Copyright ©2007W3C®(MIT,ERCIM,Keio), All Rights Reserved. W3Cliability,trademark,document use andsoftware licensing rules apply.
This specification describes a domain-specific policy assertion that indicates endpoint support of the optimized MIME multipart/related serialization of SOAP messages defined in section 3 of the SOAP Message Transmission Optimization Mechanism[MTOM] specification. This policy assertion can be specified within a policy alternative as defined in Web Services Policy 1.5 - Framework[WS-Policy] and attached to a WSDL description as defined in Web Services Policy 1.5 - Attachment[WS-PolicyAttachment].
This document is an editors' copy that has no official standing.
1.Introduction
2.Terminology and Notational Conventions
3.MTOM Policy Assertion
4.Security
5.References
A.Appendix I – XML Schema
B.Acknowledgements (Non-Normative)
1.Introduction
1.1Example
2.Terminology and Notational Conventions
2.1XML Namespaces
2.2Notational Conventions
2.3Compliance
3.MTOM Policy Assertion
3.1Assertion Model
3.2Assertion Syntax
3.3Assertion Attachment
4.Security
5.References
5.1Normative References
5.2Informative References
A.Appendix I – XML Schema
B.Acknowledgements (Non-Normative)
This specification describes a domain-specific policy assertion for the SOAP Message Transmission Optimization Mechanism W3C Recommentation[MTOM] that can be specified within a policy alternative as defined in Web Services Policy 1.5 - Framework[WS-Policy]. For backwards compatibility, the policy assertion can also be used in conjunction with the SOAP 1.1 Binding for MTOM 1.0[MTOMS11] Member Submission.
The following tables list an example use of the MTOM policy assertion.
1 <wsdl:description2 targetNamespace="http://tns.example.com/"3 xmlns:tns="http://tns.example.com/"4 xmlns:wsdl="http://www.w3.org/ns/wsdl"5 xmlns:wsp="http://www.w3.org/ns/ws-policy"6 xmlns:wsoma="http://www.w3.org/2007/08/soap12-mtom-policy"7 xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" >8 <wsp:Policy wsu:Id="MyPolicy" >9 <wsoma:MTOM />10 <!-- omitted assertions --> 11 </wsp:Policy>12 <!-- omitted elements -->13 <wsdl:binding name="MyBinding" type="tns:MyInterface" >14 <wsp:PolicyReference15 URI="#MyPolicy"16 wsdl:required="true" />17 <!-- omitted elements -->18 </wsdl:binding>19 </wsdl:description>
Lines (8-11) in are a policy expression that includes an MTOM policy assertion (Line 9) to indicate that the SOAP Message Transmission Optimization Mechanism[MTOM] may be used.
Lines (13-18) are a WSDL 2.0[WSDL2.0] binding. Lines (14-16) indicate that the policy in Lines (8-11) applies to this binding, specifically indicating that MTOM encodings must be accepted over all the messages in the binding. Line (16) indicates policy is a required extension.
1 <wsdl:definitions 2 targetNamespace="example.com"3 xmlns:tns="example.com"4 xmlns:wsdl11="http://schemas.xmlsoap.org/wsdl/"5 xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"6 xmlns:wsoma="http://www.w3.org/2007/08/soap12-mtom-policy"7 xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" > 8 <wsp:Policy wsu:Id="MyPolicy" >9 <wsoma:MTOM />10 <!-- omitted assertions --> 11 </wsp:Policy> 12 <!-- omitted elements --> 13 <wsdl:binding name="MyBinding" type="tns:MyPortType" >14 <wsp:PolicyReference15 URI="#MyPolicy"16 wsdl11:required="true" />17 <!-- omitted elements -->18 </wsdl:binding>19 </wsdl:definitions>
Lines (8-11) in are a policy expression that includes an MTOM policy assertion (Line 9) to indicate that the SOAP Message Transmission Optimization Mechanism[MTOM] may be used.
Lines (13-18) are a WSDL 1.1[WSDL1.1] binding. Lines (14-16) indicate that the policy in Lines (8-11) applies to this binding, specifically indicating that MTOM encodings must be accepted over all the messages in the binding. Line (16) indicates policy is a required extension.
Definitions ofPolicy,Policy Alternative,Policy Expression andPolicy Subject can be found in the Web Services Policy 1.5 - Framework specification[WS-Policy].
The XML Namespace URI that MUST be used by implementations of this specification is:
http://www.w3.org/2007/08/soap12-mtom-policy
Table 3 lists XML namespaces that are used in this specification. The choice of any namespace prefix is arbitrary and not semantically significant.
| Prefix | Namespace | Notes | ||||
|---|---|---|---|---|---|---|
| wsdl | "http://www.w3.org/ns/wsdl" | [WSDL2.0]. | ||||
| wsdl11 | "http://schemas.xmlsoap.org/wsdl/" | [WSDL1.1]. | ||||
| wsp | "http://www.w3.org/ns/ws-policy" | [WS-Policy]. | ||||
| wsoma | "http://www.w3.org/2007/08/soap12-mtom-policy" | This specification.
| ||||
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119[RFC 2119].
This specification uses the following syntax to define pseudo schemas for messages:
An endpoint MAY implement more than one of the roles defined herein. An endpoint is not compliant with this specification if it fails to satisfy one or more of the MUST or REQUIRED level requirements defined herein for the roles it implements.
Normative text within this specification takes precedence over pseudo schemas, which in turn take precedence over the XML Schema[XMLSchema1][XMLSchema2] and WSDL[WSDL1.1] descriptions, which in turn take precedence over examples.
The Web Services Policy 1.5 - Framework[WS-Policy] and Web Services 1.5 - Attachment[WS-PolicyAttachment] specifications collectively define a framework, model and grammar for expressing the requirements and general characteristics of entities in an XML Web services-based system. To enable an endpoint to describe its ability to use the SOAP Message Transmission Optimization Mechanism[MTOM], or MTOM with SOAP 1.1[MTOMS11], this specification defines a single policy assertion that leverages the Web Services Policy framework and attachment model for WSDL.
The MTOM policy assertion defines a behavior in which an endpoint requires and generates messages serialized as specified in section 3 of the SOAP Message Transmission Optimization Mechanism[MTOM], or MTOM with SOAP 1.1[MTOMS11] specifications.
The normative pseudo schema for the MTOM policy assertion is:
<wsoma:MTOM wsp:Optional? .../>
The following describes additional constraints on the pseudo schema listed above:
A policy assertion that specifies that MTOM[MTOM] MUST be used in messages sent to the Web service. It also specifies that responses from the Web service MUST be optimized using MTOM[MTOM], i.e. that the messages must be sent using themultipart/related; type=application/xop+xml mime type.
Per Web Services Policy[WS-Policy], this is compact notation for two policy alternatives, one with and one without the assertion. This indicates that the behavior indicated by the assertion is optional, specifically that non-MTOM-encoded exchanges are also supported by the endpoint.
When an endpoint reflects a compact policy expression with the MTOM assertionmarked withwsp:Optional='true', it may be difficult to know which alternativehas been engaged. In such cases, if a request message is received that is anapplication/soap+xml message, then the receiving endpoint SHOULD respond (if atall) with anapplication/soap+xml response message unless there is some otherindicator that specifies that the response isto be sent using MTOM encoding.
For example, when using SOAP/HTTP binding, theAccept HTTP header value ofmultipart/related; type=application/xop+xml in the request message indicates that the response may besent using MTOM encoding.
To ensure that a response message is serialized asapplication/xop+xml a clientcan send anapplication/xop+xml request message.
This is an extensibility mechanism to allow additional attributes to be added to the element.
The MTOM policy assertion element information item MUST NOT include thewsp:Ignorable attribute in its [attributes] property with a value oftrue.
Because the MTOM policy assertion indicates behavior over all messages in a binding, the assertion has Endpoint Policy Subject[WS-PolicyAttachment].
WS-PolicyAttachment defines three WSDL 2.0[WSDL2.0] policy attachment points with Endpoint Policy Subject:
WS-PolicyAttachment also defines three WSDL[WSDL1.1] policy attachment points with Endpoint Policy Subject:
A policy expression containing the MTOM policy assertion MUST NOT be attached to awsdl:interface/wsdl11:portType; the MTOM policy assertion specifies a concrete behavior whereas thewsdl:interface/wsdl11:portType is an abstract construct.
A policy expression containing the MTOM policy assertion MUST, if present, be attached to either awsdl:binding/wsdl11:binding orwsdl:endpoint/wsdl11:port.
When attached to either awsdl:binding/wsdl11:binding orwsdl:endpoint/wsdl11:port representing a SOAP 1.2 binding, the assertion indicates that the mechanism described in SOAP Message Transmission Optimization Mechanism[MTOM] applies for the designated endpoint. When attached to either awsdl:binding/wsdl11:binding orwsdl:endpoint/wsdl11:port representing a SOAP 1.1 binding, the assertion indicates that the mechanism described in MTOM with SOAP 1.1[MTOMS11] applies for the designated endpoint.
When the binding used for a service isSOAP 1.2 HTTP binding, and the MTOM policy assertion is in scope, that binding MUST conform tosection 4 of the SOAP Message Transmission Optimization Mechanism[MTOM] specification.
It is strongly RECOMMENDED that policies and assertions be signed to prevent tampering.
It is RECOMMENDED that policies SHOULD NOT be accepted unless they are signed and have an associated security token to specify the signer has proper claims for the given policy. That is, a relying party shouldn't rely on a policy unless the policy is signed and presented with sufficient claims to pass the relying parties acceptance criteria.
It should be noted that the mechanisms described in this document could be secured as part of a SOAP message using WS-Security[WS-Security] or embedded within other objects using object-specific security mechanisms.
To avoid breaking signatures, intermediates MUST NOT change the XML representations defined herein. Specifically, intermediaries MUST NOT rewrite XML namespace prefix mappings. Similarly, intermediaries MUST NOT remove XML content that explicitly indicates otherwise-implied content, and intermediaries MUST NOT insert XML content to make implied values explicit. For instance, if a @wsp:Optional attribute is present with a value of "false" an intermediary MUST NOT remove it; similarly, if there is no @wsp:Optional attribute, an intermediary MUST NOT add one.
A normative copy of the XML Schema[XMLSchema1][XMLSchema2] description for this specification can be retrieved from the following address:
http://www.w3.org/2007/08/soap12-mtom-policy.xsd
A non-normative copy of the XML Schema description is listed below for convenience.
<xs:schema targetNamespace="http://www.w3.org/2007/08/soap12-mtom-policy" xmlns:tns="http://www.w3.org/2007/08/soap12-mtom-policy" xmlns:wsp="http://www.w3.org/ns/ws-policy" xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified" > <xs:import namespace="http://www.w3.org/ns/ws-policy" schemaLocation="http://www.w3.org/2007/02/ws-policy.xsd" /> <xs:element name="MTOM" type="tns:MTOMType" /> <xs:complexType name="MTOMType" > <xs:attribute ref="wsp:Optional" /> <xs:anyAttribute namespace="##other" processContents="lax" /> </xs:complexType></xs:schema>
This document is the work of the W3C XML Protocol Working Group.
Participants in the Working Group are (at the time of writing, and by alphabetical order): Glen Daniels (Progress Software),Chris Ferris (IBM Corporation),Anish Karmarkar (Oracle Corporation),Doug Kohlert (Sun Microsystems, Inc.),Yves Lafon (W3C),Jonathan Marsh (WSO2),Jeff Mischkinsky (Oracle Corporation),Pete Wenzel (Sun Microsystems, Inc.).
The people who have contributed to discussions onxml-dist-app@w3.orgare also gratefully acknowledged.