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 WS-Policy Framework [WS-Policy] and attached to a WSDL description as
defined in WS-PolicyAttachment [WS-PolicyAttachment].
Status of this document
This section describes the status of this document at the time of its
publication. Other documents may supersede this document. A list of current
W3C publications and the latest revision of this technical report can be
found in the W3C technical reports index
at http://www.w3.org/TR/.
WS-MTOMPolicy is provided as-is and for review and evaluation only. IBM
and Microsoft make no warrantees or representations regarding the
specifications in any manner whatsoever.
By publishing this document, W3C acknowledges that the Submitting Members have made
a formal Submission request to W3C for discussion. Publication of this
document by W3C indicates no endorsement of its content by W3C, nor that W3C
has, is, or will be allocating any resources to the issues addressed by it.
This document is not the product of a chartered W3C group, but is published
as potential input to the W3C
Process. A W3C
Team Comment has been published in conjunction with this Member
Submission. Publication of acknowledged Member Submissions at the W3C site is
one of the benefits of W3C Membership.
Please consult the requirements associated with Member Submissions of section
3.3 of the W3C Patent Policy. Please consult the complete list of acknowledged W3C Member
Submissions.
Composable Architecture
The Web service specifications (WS-*) are designed to be composed with
each other to provide a rich set of tools for the Web services environment.
This specification relies on other Web service specifications to provide
secure, reliable, and/or transacted message delivery and to express Web
service metadata.
1. Introduction
This specification describes a domain-specific policy assertion for the
SOAP Message Transmission Optimization Mechanism [MTOM] that can be specified within a policy alternative as
defined in WS-Policy Framework [WS-Policy].
1.1 Requirements
This specification intends to meet the following requirements:
- Indicate that messages are encoded as described in section 3 of the
SOAP Message Transmission Optimization Mechanism [MTOM] using MIME multipart/related [RFC2387] and XML-binary Optimized
Packaging [XOP].
- Indicate the use of MTOM independent of transport.
- Provide attribute extensibility for more sophisticated and/or currently
unanticipated scenarios.
- Support a variety of encoding formats including both SOAP
1.1 [SOAP 1.1] and SOAP 1.2 [SOAP 1.2] Envelopes.
1.2 Example
Table 1 lists an example use of the Optimized Mime
Serialization policy assertion.
Table 1: Example WSDL 1.1 description with MTOM policy
assertion.
1 <wsdl:definitions
2 targetNamespace="example.com"
3 xmlns:tns="example.com"
4 xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
5 xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
6 xmlns:wsoma="http://schemas.xmlsoap.org/ws/2004/09/policy/optimizedmimeserialization"
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:OptimizedMimeSerialization />
10 <!-- omitted assertions -->
11 </wsp:Policy>
12 <!-- omitted elements -->
13 <wsdl:binding name="MyBinding" type="tns:MyPortType" >
14 <wsp:PolicyReference
15 URI="#MyPolicy"
16 wsdl:required="true" />
17 <!-- omitted elements -->
18 </wsdl:binding>
19 </wsdl:definitions>
Lines (8-11) in are a policy expression that includes an Optimized Mime
Serialization policy assertion (Line 9) to indicate that the SOAP
Message Transmission Optimization Mechanism [MTOM]
may be used.
Lines (13-18) are a WSDL [WSDL 1.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 Notation
2.1 Terminology
- Policy
- A collection of policy alternatives; typically one alternative is
selected.
- Policy Alternative
- A collection of policy assertions; typically all assertions in an
alternative are honored.
- Policy Assertion
- An individual, domain-specific requirement, capability, or other
property of a behavior.
- Policy Expression
- An XML Infoset representation of a policy, either in a normal form or
in an equivalent compact form.
- Policy Subject
- An entity (e.g., an endpoint, message, resource, interaction) with
which a policy can be associated.
2.2 XML Namespaces
The XML Namespace URI that MUST be used by implementations of this
specification is:
http://schemas.xmlsoap.org/ws/2004/09/policy/optimizedmimeserialization
Table 2 lists XML namespaces that are used in this
specification. The choice of any namespace prefix is arbitrary and not
semantically significant.
Table 2: Prefixes and XML Namespaces used in this
specification.
| Prefix |
XML Namespace |
Specification(s) |
| wsdl |
http://schemas.xmlsoap.org/wsdl/ |
[WSDL 1.1] |
| wsp |
http://schemas.xmlsoap.org/ws/2004/09/policy |
[WS-Policy, WS-PolicyAttachment] |
| wsoma |
http://schemas.xmlsoap.org/ws/2004/09/policy/optimizedmimeserialization |
This specification |
2.3 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 outlines 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 2) are used to
indicate the namespace of the element being defined.
2.4 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 outlines,
which in turn take precedence over the XML Schema [XML
Schema Part 1, Part 2] and WSDL [WSDL 1.1] descriptions, which in turn take precedence over
examples.
3. Optimized Mime
Serialization Policy Assertion
The WS-Policy Framework [WS-Policy] and
WS-PolicyAttachment [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 WS-Policy framework and attachment model for
WSDL.
3.1 Assertion Model
The Optimized Mime Serialization 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 outline for the Optimized Mime Serialization policy
assertion is:
<wsoma:OptimizedMimeSerialization ... />
The following describes additional constraints on the outline listed
above:
- /wsoma:OptimizedMimeSerialization
- 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
application/xop+xml mime type.
- /wsoma:OptimizedMimeSerialization/@wsp:Optional="true"
- Per WS-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.
- /wsoma:OptimizedMimeSerialization/@any
- This is an extensibility mechanism to allow additional attributes to
be added to the element.
3.3 Assertion Attachment
Because the Optimized Mime Serialization policy assertion indicates
behavior over all messages in a binding, the assertion has Endpoint Policy
Subject [WS-PolicyAttachment].
WS-PolicyAttachment defines three WSDL [WSDL 1.1]
policy attachment points with Endpoint Policy Subject:
wsdl:portTypewsdl:bindingwsdl:port
A policy expression containing the Optimized Mime Serialization policy
assertion MUST NOT be attached to a wsdl:portType; the
Optimized Mime Serialization policy assertion specifies a concrete
behavior whereas the wsdl:portType is an abstract
construct.
A policy expression containing the Optimized Mime Serialization policy
assertion MUST, if present be attached to either a
wsdl:binding or wsdl:port.
When attached to either a wsdl:binding or wsdl: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 or wsdl: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.
4. Security
It is strongly RECOMMENDED that policies and assertions be signed to
prevent tampering.
It is RECOMMENED 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 2004] 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. Acknowledgements
This specification has been developed as a result of joint work with many
individuals and teams, including: Francisco Curbera (IBM), Colleen Evans
(Microsoft), Carlos Figueira (Microsoft), Maryann Hondo (IBM), Natasha
Jethanandani (Microsoft), Ram Jeyaraman (Microsoft), Anthony Nadalin (IBM),
Eugene Osovetsky (Microsoft), Arthur Ryman (IBM), Christopher Sharp (IBM),
Greg Truty (IBM).
6. References
- RFC 2119
- S. Bradner, "Key words for use in RFCs to Indicate Requirement
Levels," RFC 2119, Harvard University, March 1997. (See http://www.ietf.org/rfc/rfc2119.txt.)
- RFC 2387
- E. Levinson, "The MIME Multipart/Related Content-type,"
RFC 2387, August 1998. (See http://www.ietf.org/rfc/rfc2387.txt.)
- SOAP 1.1
- D. Box, et al, "Simple Object Access Protocol (SOAP)
1.1," May 2000. (See http://www.w3.org/TR/2000/NOTE-SOAP-20000508/.)
- SOAP 1.2
- M. Gudgin, et al, "SOAP Version 1.2 Part 1: Messaging
Framework," June 2003. (See http://www.w3.org/TR/2003/REC-soap12-part1-20030624/.)
- MTOM
- M. Gudgin, et al, "SOAP Message Transmission Optimization
Mechanism," January 2005. (See http://www.w3.org/TR/2005/REC-soap12-mtom-20050125/.)
- MTOMS11
- J. Marsh, et al, "MTOM with SOAP 1.1," April 2006. (See
http://www.w3.org/submissions/soap11mtom10/.)
- XOP
- M. Gudgin, et al, "XML-binary Optimized Packaging,"
January 2005. (See http://www.w3.org/TR/2005/REC-xop10-20050125/.)
- WSDL 1.1
- E. Christensen, et al, "Web Services Description Language
(WSDL) 1.1," March 2001. (See http://www.w3.org/TR/2001/NOTE-wsdl-20010315.)
- WS-Policy
- S. Bajaj, et al, "Web Services Policy Framework
(WS-Policy)," 25 April 2006. (See http://www.w3.org/submissions/WS-Policy/.)
- WS-PolicyAttachment
- S. Bajaj, et al, "Web Services Policy Attachment
(WS-PolicyAttachment)," 25 April 2006. (See http://www.w3.org/submissions/WS-PolicyAttachment/.)
- WS-Security 2004
- A. Nadalin, et al, "Web Services Security: SOAP Message
Security 1.0," March 2004. (See http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf.)
- XML Schema, Part 1
- H. Thompson, et al, "XML Schema Part 1: Structures,"
October 2004. (See http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/.)
- XML Schema, Part 2
- P. Biron, et al, "XML Schema Part 2: Datatypes," October
2004. (See http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/.)
Appendix I – XML Schema
A normative copy of the XML Schema [XML Schema Part
1, Part 2] description for this specification
can be retrieved from the following address:
http://schemas.xmlsoap.org/ws/2004/09/policy/optimizedmimeserialization/optimizedmimeserialization-policy.xsd
A non-normative copy of the XML Schema description is listed below for
convenience.
<xs:schema
targetNamespace="http://schemas.xmlsoap.org/ws/2004/09/policy/optimizedmimeserialization"
xmlns:tns="http://schemas.xmlsoap.org/ws/2004/09/policy/optimizedmimeserialization"
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified"
attributeFormDefault="unqualified" >
<xs:import
namespace="http://schemas.xmlsoap.org/ws/2004/09/policy"
schemaLocation="http://schemas.xmlsoap.org/ws/2004/09/policy/ws-policy.xsd" />
<xs:element
name="OptimizedMimeSerialization"
type="tns:OptimizedMimeSerializationType" />
<xs:complexType name="OptimizedMimeSerializationType" >
<xs:attribute ref="wsp:Optional" />
<xs:anyAttribute namespace="##any" processContents="lax" />
</xs:complexType>
</xs:schema>