W3C

Web Services SOAP Assertions (WS-SOAPAssertions)

W3C Working Draft 5 August 2010 Candidate Recommendation 28 April 2011

This version:
http://www.w3.org/TR/2010/WD-ws-soap-assertions-20100805 http://www.w3.org/TR/2011/CR-ws-soap-assertions-20110428
Latest version:
http://www.w3.org/TR/ws-soap-assertions
Previous version:
http://www.w3.org/TR/2010/WD-ws-soap-assertions-20100713 http://www.w3.org/TR/2010/WD-ws-soap-assertions-20100805
Editors:
Doug Davis, IBM
Ashok Malhotra, Oracle
Katy Warr, IBM
Wu Chou, Avaya

Copyright © 2010 2011 W3C ® ( MIT , ERCIM , Keio ), All Rights Reserved. W3C liability , trademark and document use rules apply.

Abstract

This specification defines two WS-Policy assertions that can be used to advertise the requirement to use a certain version of SOAP in message exchanges.

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

This document is second During the Candidate Recommendation phase, the Last Call Working Draft Group will test multiple specifications in a serie of tests defined in the Web Services SOAP Assertions (WS-SOAPAssertions) specification; It is intended to WSRA scenario document. Tests results will be published and maintained as a W3C Recommendation after review and refinement. compiled in the Implementation Report

There are no features declared at risk. The Web Services Resource Access Working Group (WSRA WG) believes to have addressed all issues brought forth through previous Working Draft iterations, including during the first review period ends on 20 May 2011 .Changes since Last Call period (See are described in a diff document .

Publication as a Candidate Recommendation does not imply endorsement by the [changelog] ). The Working Group encourages feedback about W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document. The Last Call period extends through 17 September 2010. document as other than work in progress.

It has been produced by the Web Services Resource Access Working Group (WG), which is part of the W3C Web Services Activity . The working Group home page provides additional information on this and the related specifications produced by this working group.

Please provide comments on report errors in this document to the public public-ws-resource-access-comments@w3.org mailing list ( public archive ).

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress. This document was produced by a group operating under the 5 February 2004 W3C Patent Policy . W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy .

Table of Contents

1 Composable Architecture
2 Introduction
   2.1 Requirements
3 Notations
   3.1 Notational Conventions
   3.2 Considerations on the Use of Extensibility Points
   3.3 Compliance
   3.4 XML Namespaces
4 SOAP Assertions
   4.1 SOAP11 Assertion
   4.2 SOAP12 Assertion
5 Examples
6 Acknowledgements
7 References
   7.1 Normative References

Appendices

A XML Schema
B Change Log

1 Composable Architecture

By using the XML, SOAP [SOAP11] , [SOAP12] , and WSDL [WSDL11] extensibility models, 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.

2 Introduction

Using the Web Service Policy - Framework [WS-Policy] and Web Services Policy - Attachment [WS-PolicyAttachment] specifications, an endpoint can indicate support for a variety of features. Two endpoints can then determine if they share compatible features through the policy intersection algorithm defined by the WS-Policy framework. This allows for a programmatic way to locate interoperable endpoints.

However, one key aspect of the message exchanges is whether either endpoint requires the use of SOAP 1.1 [SOAP11] or SOAP 1.2 [SOAP12] . While this information might be obtainable through examination of a WSDL [WSDL11] document, or implied through some out of band knowledge, there is no way to make this determination during the application of the policy intersection algorithm. This specification defines two new policy assertions that allows for this critical piece of information to be available during normal policy processing.

2.1 Requirements

This specification intends to meet the following requirement:

  • Provide a set of policy assertions to indicate the requirement to use a certain version of SOAP.

3 Notations

This section specifies the notations and namespaces used in this specification.

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

  • XML namespace prefixes (see Table 3-1 ) are used to indicate the namespace of the element being defined.

This specification can be used in terms of XML Information Set (Infoset) [XML Infoset] , even though the specification uses XML 1.0 terminology. Valid Infoset for this specification is the one serializable in XML 1.0, hence the use of XML 1.0.

3.2 Considerations on the Use of Extensibility Points

The elements defined in this specification MAY be extended at the points indicated by their outlines and schema. Implementations MAY add child elements and/or attributes at the indicated extension points but MUST NOT contradict the semantics of the parent and/or owner, respectively.

Extension elements and attributes MUST NOT use the Web Services Metadata Exchange namespace URI.

3.3 Compliance

An implementation is not compliant with this specification if it fails to satisfy one or more of the MUST or REQUIRED level requirements defined herein. A SOAP Node MUST NOT use the XML namespace identifier for this specification (listed in 3.4 XML Namespaces ) within SOAP Envelopes unless it is compliant with this specification.

Normative text within this specification takes precedence over the XML Schema and WSDL descriptions, which in turn take precedence over outlines, which in turn take precedence over examples.

Implementations are expected to support both UTF-8 and UTF-16 as described in XML 1.0.

Implementations of this specification MUST conform to the corrected version of WSDL as defined by the 'WSDL Correction' sections of WS-I Basic Profile 1.2 [BP12] and WS-I Basic Profile 2.0 [BP20] .

3.4 XML Namespaces

The XML namespace URI that MUST be used by implementations of this specification is:

http://www.w3.org/2010/08/ws-sas


http://www.w3.org/2011/03/ws-sas

Table 3-1 lists XML namespaces that are used in this specification. The choice of any namespace prefix is arbitrary and not semantically significant.

Table 3-1: Prefixes and XML namespaces used in this specification
Prefix XML Namespaces Specification(s)
s (Either SOAP 1.1 or 1.2) (Either SOAP 1.1 or 1.2)
s11 http://schemas.xmlsoap.org/soap/envelope/ [SOAP11]
s12 http://www.w3.org/2003/05/soap-envelope [SOAP12]
wsa http://www.w3.org/2005/08/addressing [WS-Addressing]
wsp http://www.w3.org/ns/ws-policy [WS-Policy]
wssa http://www.w3.org/2010/08/ws-sas http://www.w3.org/2011/03/ws-sas This specification
xs http://www.w3.org/2001/XMLSchema [XMLSchema - Part 1]

The working group intends to update the value of the Web Services Metadata Exchange namespace URI each time a new version of this document is published until such time that the document reaches Candidate Recommendation status. Once it has reached Candidate Recommendation status, the working group intends to maintain the value of the Web Services Metadata Exchange namespace URI that was assigned in the Candidate Recommendation unless significant changes are made that impact the implementation or break post-CR implementations of the specification. Also see http://www.w3.org/2001/tag/doc/namespaceState.html and http://www.w3.org/2005/07/13-nsuri .

4 SOAP Assertions

An endpoint MAY indicate that it requires the use of a certain version of SOAP by using the following policy assertions with its policy alternatives.

4.1 SOAP11 Assertion

The normative outline of this assertion is:

<wssa:SOAP11
...>
...
<wssa:SOAP11>

The following describes additional, normative constraints on the outline listed above:

/wssa:SOAP11

This policy assertion has Endpoint Policy Subject. When present in a policy alternative, it indicates that the SOAP 1.1 protocol MUST be used when communicating with this endpoint.

4.2 SOAP12 Assertion

The normative outline of this assertion is:

<wssa:SOAP12
...>
...
<wssa:SOAP12>

The following describes additional, normative constraints on the outline listed above:

/wssa:SOAP12

This policy assertion has Endpoint Policy Subject. When present in a policy alternative, it indicates that the SOAP 1.2 protocol MUST be used when communicating with this endpoint.

5 Examples

The following example shows a sample policy expression that indicates SOAP 1.1 is required:

<wsp:Policy>
  <wssa:SOAP11/>
</wsp:Policy>

The following example shows a sample policy expression that indicates either SOAP 1.1 or SOAP 1.2 can be used:

<wsp:Policy>
  <wsp:ExactlyOne>
    <wssa:SOAP11/>
    <wssa:SOAP12/>
  </wsp:ExactlyOne>
</wsp:Policy>

The following example shows a WS-Addressing [WS-Addressing] endpoint reference that indicates SOAP 1.2 is required for all messages sent to the endpoint:

<wsa:EndpointReference>
  <wsa:Address> ... </wsa:Address>
  <wsp:Policy>
    <wssa:SOAP12/>
  </wsp:Policy>
<wsa:EndpointReference>

6 Acknowledgements

This specification has been developed as a result of joint work with many individuals and teams, including: Alessio Soldano (Red Hat), Ashok Malhotra (Oracle Corp.), Asir Vedamuthu (Microsoft Corp.), Bob Freund (Hitachi, Ltd.), Bob Natale (MITRE Corp.), David Snelling (Fujitsu, Ltd.), Doug Davis (IBM), Fred Maciel (Hitachi, Ltd.), Geoff Bullen (Microsoft Corp.), Gilbert Pilz (Oracle Corp.), Greg Carpenter (Microsoft Corp.), Jeff Mischkinsky (Oracle Corp.), Katy Warr (IBM), Li Li (Avaya Communications), Mark Little (Red Hat), Martin Chapman (Oracle Corp.), Paul Fremantle (WSO2), Paul Nolan (IBM), Prasad Yendluri (Software AG), Ram Jeyaraman (Microsoft Corp.), Sreedhara Narayanaswamy (CA), Sumeet Vij (Software AG), Tom Rutt (Fujitsu, Ltd.), Vikas Varma (Software AG), Wu Chou (Avaya Communications), Yves Lafon (W3C/ERCIM).

7 References

7.1 Normative References

BP12
WS-I Profile, Basic Profile Version 1.2 , R. Chumbley, et al, Editors. Web Services Interoperability Organization (WS-I), 9 November 2010. Available at http://ws-i.org/profiles/BasicProfile-1.2-2010-11-09.html .
BP20
WS-I Profile, Basic Profile Version 2.0 , R. Chumbley, et al, Editors. Web Services Interoperability Organization (WS-I), 9 November 2010. Available at http://ws-i.org/profiles/BasicProfile-2.0-2010-11-09.html .
RFC 2119
Key words for use in RFCs to Indicate Requirement Levels , S. Bradner, Author. Internet Engineering Task Force, March 1997. (See http://www.ietf.org/rfc/rfc2119.txt.) Available at http://www.ietf.org/rfc/rfc2119.txt .
SOAP11
W3C Note, "Simple Object Access Protocol (SOAP) 1.1" , D. Box, et al, Editors. World Wide Web Consortium (W3C), 8 May 2000. (See http://www.w3.org/TR/2000/NOTE-SOAP-20000508/.) Available at http://www.w3.org/TR/2000/NOTE-SOAP-20000508/ .
SOAP12
W3C Recommendation, "SOAP Version 1.2 Part 1: Messaging Framework" , M. Gudgin, M. Hadley, N. Mendelsohn, J-J. Moreau, H. Frystyk Nielson, Editors. World Wide Web Consortium (W3C), 27 April 2007. (See http://www.w3.org/TR/soap12-part1/.) Available at http://www.w3.org/TR/soap12-part1/ .
WS-Addressing
W3C Recommendation, "Web Services Addressing 1.0 (WS-Addressing)" , M. Gudgin, M. Hadley, T. Rogers, Editors. World Wide Web Consortium (W3C), 9 May 2006. (See http://www.w3.org/TR/ws-addr-core.) Available at http://www.w3.org/TR/ws-addr-core .
WS-Policy
W3C Recommendation, "Web Services Policy (WS-Policy) 1.5 - Framework" , A. Vedamuthu, et al., Editors. World Wide Web Consortium (W3C), 4 September 2007. (See http://www.w3.org/TR/ws-policy/.) Available at http://www.w3.org/TR/ws-policy/ .
WS-PolicyAttachment
W3C Recommendation, "Web Services Policy (WS-Policy) 1.5 - Attachment" , A. Vedamuthu, et al., Editors. World Wide Web Consortium (W3C), 4 September 2007. (See http://www.w3.org/TR/ws-policy-attach/.) Available at http://www.w3.org/TR/ws-policy-attach/ .
WSDL11
W3C Note, "Web Services Description Language (WSDL) 1.1" , E. Christensen, et al., Editors. World Wide Web Consortium (W3C), 15 March 2001 (See http://www.w3.org/TR/2001/NOTE-wsdl-20010315.) Available at http://www.w3.org/TR/2001/NOTE-wsdl-20010315 .
XML Infoset
W3C Recommendation, "XML Information Set (Second Edition)" , J. Cowan, R. Tobin, Editors. World Wide Web Consortium (W3C), 4 February 2004. (See http://www.w3.org/TR/xml-infoset.) Available at http://www.w3.org/TR/xml-infoset .
XMLSchema - Part 1
W3C Recommendation, "XML Schema Part 1: Structures (Second Edition)" , H. Thompson, et al., Editors. World Wide Web Consortium (W3C), 28 October 2004. (See http://www.w3.org/TR/xmlschema-1/.) Available at http://www.w3.org/TR/xmlschema-1/ .
XMLSchema - Part 2
W3C Recommendation, "XML Schema Part 2: Datatypes (Second Edition)" , P. Biron, A. Malhotra, Editors. World Wide Web Consortium (W3C), 28 October 2004. (See http://www.w3.org/TR/xmlschema-2/.) A XML Schema A normative copy of the XML Schema [XMLSchema - Part 1] , [XMLSchema - Part 2] description for this specification can be retrieved from the following address: http://www.w3.org/2010/08/ws-sas/soapassertions.xsd A non-normative copy of the XML schema is listed below for convenience. <xs:schema targetNamespace='http://www.w3.org/2010/08/ws-sas' xmlns:tns='http://www.w3.org/2010/08/ws-sas' xmlns:xs='http://www.w3.org/2001/XMLSchema' elementFormDefault='qualified' blockDefault='#all' > <xs:complexType name='emptyElementType'> <xs:sequence> <xs:any namespace='##other' minOccurs='0' maxOccurs='unbounded'/> </xs:sequence> <xs:anyAttribute namespace='##other' processContents='lax'/> </xs:complexType> Bir <xs:element name='SOAP11' type='tns:emptyElementType'/> <xs:element name='SOAP12' type='tns:emptyElementType'