MTOM Serialization Policy Assertion 1.1

Editors' Copy $date$

Latest version:
http://www.w3.org/TR/soap12-mtom-policy
Previous versions:
http://www.w3.org/TR/2007/WD-soap12-mtom-policy-20070918/
Editors:
Christopher Ferris, IBM
Yves Lafon, W3C

Abstract

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].

Status of this Document

This document is an editors' copy that has no official standing.


Short Table of Contents

1. Introduction
2. Terminology and Notational Conventions
3. MTOM Policy Assertion
4. Security
5. References
A. Appendix I – XML Schema
B. Acknowledgements (Non-Normative)


Table of Contents

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

Appendices

A. Appendix I – XML Schema
B. Acknowledgements (Non-Normative)


1. Introduction

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.

1.1 Example

The following tables list an example use of the MTOM policy assertion.

Example 1: Table 1: Example WSDL 2.0 description with 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.

Example 2: Table 2: Example WSDL 1.1 description with MTOM policy assertion.
	  		
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.

2. Terminology and Notational Conventions

Definitions of Policy, Policy Alternative, Policy Expression and Policy Subject can be found in the Web Services Policy 1.5 - Framework specification [WS-Policy].

2.1 XML Namespaces

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.

Table 1: Table 3: Prefixes and XML Namespaces used in this specification.
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.
Editorial note 
When the specification will reach a stable point, the expected namespace should be http://www.w3.org/ns/soap12-mtom-policy

2.2 Notational Conventions

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:

  • The syntax appears as an XML instance, but values in italics indicate data types instead of literal values.
  • Characters are appended to elements and attributes to indicate cardinality:
    • "?" (0 or 1)
    • "*" (0 or more)
    • "+" (1 or more)
  • The character "|" is used to indicate a choice between alternatives.
  • The characters "(" and ")" are used to indicate that contained items are to be treated as a group with respect to cardinality or choice.
  • The characters "[" and "]" are used to call out references and property names.
  • Ellipses (i.e., "…") indicate points of extensibility. Additional children and/or attributes MAY be added at the indicated extension points but MUST NOT contradict the semantics of the parent and/or owner, respectively. By default, if a receiver does not recognize an extension, the receiver SHOULD ignore the extension; exceptions to this processing rule, if any, are clearly indicated below.
  • XML namespace prefixes (see Table 3) are used to indicate the namespace of the element being defined.

2.3 Compliance

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.

3. MTOM Policy Assertion

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.

3.1 Assertion Model

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.

3.2 Assertion Syntax

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:

/wsoma:MTOM

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.

/wsoma:MTOM/@wsp:Optional="true"

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.

/wsoma:MTOM/@any

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.

3.3 Assertion Attachment

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:

  • wsdl:interface
  • wsdl:binding
  • wsdl:endpoint

WS-PolicyAttachment also defines three WSDL [WSDL1.1] policy attachment points with Endpoint Policy Subject:

  • wsdl:portType
  • wsdl:binding
  • wsdl:port

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.

4. Security

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.

5. References

5.1 Normative References

[RFC 2119]
Key words for use in RFCs to Indicate Requirement Levels, S. Bradner, Editor. IETF, March 1997. This RFC is available at http://www.ietf.org/rfc/rfc2119.txt.
[RFC 2387]
Hypertext Transfer Protocol -- HTTP/1.1, R. Fielding, J. Gettys, J. C. Mogul, H. Frystyk Nielsen, P. Leach, L. Masinter and T. Berners-Lee, Editors. IETF, June 1999. This RFC is available at http://www.ietf.org/rfc/rfc2616.txt.
[SOAP 1.1]
Simple Object Access Protocol (SOAP) 1.1, Don Box, David Ehnebuske, Gopal Kakivaya, Andrew Layman, Noah Mendelsohn, Henrik Nielsen, Satish Thatte, Dave Winer, Editors. DevelopMentor, IBM, Microsoft, Lotus Development Corp., UserLand Software, Inc., 8 May 2000. This version is http://www.w3.org/TR/2000/NOTE-SOAP-20000508/.
[SOAP Part 1]
SOAP Version 1.2 Part 1: Messaging Framework, Martin Gudgin, Marc Hadley, Noah Mendelsohn, Jean-Jacques Moreau, Henrik Frystyk Nielsen, Anish Karmarkar, Yves Lafon, Editors. World Wide Web Consortium, 27 April 2007. This version is http://www.w3.org/TR/2007/REC-soap12-part1-20070427/. The latest version is available at http://www.w3.org/TR/soap12-part1/.
[MTOM]
SOAP Message Transmission Optimization Mechanism, Hervé Ruellan, Noah Mendelsohn, Martin Gudgin, and Mark Nottingham, Editors. World Wide Web Consortium, 25 January 2005. This version is http://www.w3.org/TR/2005/REC-soap12-mtom-20050125/. The latest version is available at http://www.w3.org/TR/soap12-mtom/.
[XOP]
XML-binary Optimized Packaging, Mark Nottingham, Noah Mendelsohn, Martin Gudgin, and Hervé Ruellan, Editors. World Wide Web Consortium, 25 January 2005. This version is http://www.w3.org/TR/2005/REC-xop10-20050125/. The latest version is available at http://www.w3.org/TR/xop10/.
[WSDL2.0]
Web Services Description Language (WSDL) Version 2.0 Part 1: Core Language, Roberto Chinnici, Jean-Jacques Moreau, Arthur Ryman, Sanjiva Weerawarana, Editors. World Wide Web Consortium, 26 June 2007. This version is http://www.w3.org/TR/2007/REC-wsdl20-20070626/. The latest version is available at http://www.w3.org/TR/wsdl20/.
[WSDL1.1]
Web Services Description Language (WSDL) 1.1, Erik Christensen, Francisco Curbera, Greg Meredith, Sanjiva Weerawarana, Authors. Ariba, International Business Machines Corporation and Microsoft, 15March 2001. This version is http://www.w3.org/TR/2001/NOTE-wsdl-20010315. The latest version is available at http://www.w3.org/TR/wsdl.
[WS-Policy]
Web Services Policy 1.5 - Framework, Asir S Vedamuthu, David Orchard, Frederick Hirsch, et al., Editors. World Wide Web Consortium, 4 September 2007. This version is http://www.w3.org/TR/2007/REC-ws-policy-20070904/. The latest version is available at http://www.w3.org/TR/ws-policy/.
[WS-PolicyAttachment]
Web Services Policy 1.5 - Attachment, Asir S Vedamuthu, David Orchard, Frederick Hirsch, et al., Editors. World Wide Web Consortium, 4 September 2007. This version is http://www.w3.org/TR/2007/REC-ws-policy-attach-20070904/. The latest version is available at http://www.w3.org/TR/ws-policy-attach/.
[WS-Security]
Web Services Security: SOAP Message Security 1.0, Anthony Nadalin, Chris Kaler, Philip Hallam-Baker, Ronald Monzillo, Editors. OASIS Open, March 2004.
[XML Schema Part 1]
XML Schema Part 1: Structures Second Edition, David Beech, Murray Maloney, Henry S. Thompson, and Noah Mendelsohn, Editors. World Wide Web Consortium, 28 October 2004. This version is http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/ The latest version is available at http://www.w3.org/TR/xmlschema-1/.
[XML Schema Part 2]
XML Schema Part 2: Datatypes Second Edition, Ashok Malhotra and Paul V. Biron, Editors. World Wide Web Consortium, 28 October 2004. This version is http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/. The latest version is available at http://www.w3.org/TR/xmlschema-2/.
[RFC 3986]
Uniform Resource Identifiers (URI): Generic Syntax, T. Berners-Lee, R. Fielding and L. Masinter, Editors. IETF, January 2005. Obsoletes: RFC 2396, RFC 2732. This RFC is available at http://www.ietf.org/rfc/rfc3986.txt.
[Namespaces in XML]
Namespaces in XML (Second Edition), Tim Bray, Dave Hollander, Andrew Layman, and Richard Tobin, Editors. World Wide Web Consortium, 16 August 2006. This version is http://www.w3.org/TR/2006/REC-xml-names-20060816. The latest version is available at http://www.w3.org/TR/REC-xml-names.
[XML 1.0]
Extensible Markup Language (XML) 1.0 (Fourth Edition), Jean Paoli, Eve Maler, Tim Bray, et al., Editors. World Wide Web Consortium, 16 August 2006. This version is http://www.w3.org/TR/2006/REC-xml-20060816. The latest version is available at http://www.w3.org/TR/REC-xml.
[XML InfoSet]
XML Information Set (Second Edition), Richard Tobin and John Cowan, Editors. World Wide Web Consortium, 4 February 2004. This version is http://www.w3.org/TR/2004/REC-xml-infoset-20040204. The latest version is available at http://www.w3.org/TR/xml-infoset.

5.2 Informative References

[MTOMS11]
SOAP 1.1 Binding for MTOM 1.0, J. Marsh, et al., April 2006.
[XMLP Comments]
XML Protocol Comments Archive (See http://lists.w3.org/Archives/Public/xmlp-comments/.)
[XMLP Dist-App]
XML Protocol Discussion Archive (See http://lists.w3.org/Archives/Public/xml-dist-app/.)
[XMLP Charter]
XML Protocol Charter (See http://www.w3.org/2005/07/XML-Protocol-Charter.)

A. Appendix I – XML Schema

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>
	

B. Acknowledgements (Non-Normative)

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.