Copyright ©2007 W3C®(MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark, document use and software 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.1 Example
2. Terminology and Notational Conventions
2.1 XML Namespaces
2.2 Notational Conventions
2.3 Compliance
3. MTOM Policy Assertion
3.1 Assertion Model
3.2 Assertion Syntax
3.3 Assertion Attachment
4. Security
5. References
5.1 Normative References
5.2 Informative 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:description
2 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:PolicyReference
15 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:PolicyReference 15 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 of Policy, Policy Alternative, Policy Expression and Policy 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 the
multipart/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 assertion
marked with wsp:Optional='true', it may be difficult to know which alternative
has been engaged. In such cases, if a request message is received that is an
application/soap+xml message, then the receiving endpoint SHOULD respond (if at
all) with an application/soap+xml response message unless there is some other
indicator that specifies that the response is
to be sent using MTOM encoding.
For example, when using SOAP/HTTP binding, the Accept HTTP header value of
multipart/related; type=application/xop+xml in the request message indicates that the response may be
sent using MTOM encoding.
To ensure that a response message is serialized as application/xop+xml a client
can send an application/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 the
wsp:Ignorable attribute in its [attributes] property with a value of true.
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 a wsdl:interface/wsdl11:portType; the MTOM policy assertion
specifies a concrete behavior whereas the wsdl:interface/wsdl11:portType is an abstract construct.
A policy expression containing the MTOM policy assertion MUST, if
present, be attached to either a wsdl:binding/wsdl11:binding or wsdl:endpoint/wsdl11:port.
When attached to either a wsdl:binding/wsdl11:binding or wsdl: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 a wsdl:binding/wsdl11:binding or
wsdl: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 is SOAP 1.2 HTTP binding, and the MTOM policy assertion is in scope, that binding MUST conform to section 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 on xml-dist-app@w3.org are also gratefully acknowledged.