Web Services Addressing 1.0 - SOAP Binding http://www.w3.org/TR/2005/WD-ws-addr-soap-20050331 W3C Working Draft 31 March 2005 http://www.w3.org/TR/2005/WD-ws-addr-soap-20050331 postscript PDF XML plain text http://www.w3.org/TR/2005/WD-ws-addr-soap-20050215 http://www.w3.org/TR/ws-addr-soap Martin Gudgin Microsoft Corp Marc Hadley Sun Microsystems, Inc

Web Services Addressing provides transport-neutral mechanisms to address Web services and messages. Web Services Addressing 1.0 - SOAP Binding (this document) defines the binding of the abstract properties defined in Web Services Addressing 1.0 - Core to SOAP Messages.

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 is the Last Call Working Draft of the Web Services Addressing 1.0 - SOAP Binding specification for review by W3C members and other interested parties. It has been produced by the Web Services Addressing Working Group (WG), which is part of the W3C Web Services Activity.

If the feedback is positive, the Working Group plans to submit this specification for consideration as a W3C Candidate Recommendation. Comments on this document are invited and are to be sent to the public public-ws-addressing-comments@w3.org mailing list (public archive). Comments can be sent until 11 May 2005.

A diff-marked version against the previous version of this document is available. For a detailed list of changes since the last publication of this document, please refer to appendix . Issues about this document are documented in the Last Call issues list maintained by the Working Group.

Discussion of this document takes place on the public-ws-addressing@w3.org mailing list (public archive).

This document was produced under the 5 February 2004 W3C Patent Policy. The Working Group maintains a public list of patent disclosures relevant to this document; that page also includes instructions for disclosing [and excluding] a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) with respect to this specification should disclose the information in accordance with section 6 of the W3C Patent Policy.

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.

The Web Services Addressing Working Group has decided to use XML Schema, where appropriate, to describe constructs defined in this specification. Note that this restricts use of Web Services Addressing to XML 1.0. English

Last Modified: $Date: 2005/03/31 13:30:47 $
Introduction

Web Services Addressing 1.0 - Core[] defines a set of abstract properties and an XML Infoset [] representation thereof to reference Web service endpoints and to facilitate end-to-end addressing of endpoints in messages. Web Services Addressing 1.0 - SOAP Binding (this document) defines the binding of the abstract properties defined in Web Services Addressing 1.0 - Core to SOAP Messages.

The following example illustrates the use of these mechanisms in a SOAP 1.2 message being sent from http://example.com/business/client1 to http://example.com/fabrikam/Purchasing:

Use of message addressing properties in a SOAP 1.2 message. (001) <S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope" xmlns:wsa="http://www.w3.org/2005/03/addressing"> (002) <S:Header> (003) <wsa:MessageID> (004) http://example.com/6B29FC40-CA47-1067-B31D-00DD010662DA (005) </wsa:MessageID> (006) <wsa:ReplyTo> (007) <wsa:Address>http://example.com/business/client1</wsa:Address> (008) </wsa:ReplyTo> (009) <wsa:To>http://example.com/fabrikam/Purchasing</wsa:To> (010) <wsa:Action>http://example.com/fabrikam/SubmitPO</wsa:Action> (011) </S:Header> (012) <S:Body> (013) ... (014) </S:Body> (015) </S:Envelope>

Lines (002) to (011) represent the header of the SOAP message where the mechanisms defined in the specification are used. The body is represented by lines (012) to (014).

Lines (003) to (010) contain the message addressing properties serialized as SOAP header blocks. Specifically, lines (003) to (005) specify the identifier for this message and lines (006) to (008) specify the endpoint to which replies to this message should be sent as an Endpoint Reference. Line (009) specifies the address URI of the ultimate receiver of this message. Line (010) specifies an Action IRI identifying expected semantics.

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

When describing abstract data models, this specification uses the notational convention used by XML Infoset []. Specifically, abstract property names always appear in square brackets (e.g., [some property]).

When describing concrete XML schemas [, ], this specification uses the notational convention of WS-Security []. Specifically, each member of an element's [children] or [attributes] property is described using an XPath-like notation (e.g., /x:MyHeader/x:SomeProperty/@value1). The use of {any} indicates the presence of an element wildcard (<xs:any/>). The use of @{any} indicates the presence of an attribute wildcard (<xs:anyAttribute/>).

 Namespaces

This specification uses a number of namespace prefixes throughout; they are listed in . Note that the choice of any namespace prefix is arbitrary and not semantically significant (see [ ]).

Prefixes and Namespaces used in this specification
Prefix Namespace
S http://www.w3.org/2003/05/soap-envelope
S11 http://schemas.xmlsoap.org/soap/envelope
wsa http://www.w3.org/2005/03/addressing
wsaw http://www.w3.org/2005/03/addressing/wsdl
xs http://www.w3.org/2001/XMLSchema

WS-Addressing is defined in terms of the XML Information Set []. WS-Addressing is conformant to the SOAP 1.2 [] processing model and is also compatible with SOAP 1.1[] for backwards compatibility. WS-Addressing may be used with WSDL [] described services as described in Web Services Addressing 1.0 - WSDL Binding[]. The examples in this specification use an XML 1.0 [] representation but this is not a requirement.

All information items defined by this specification are identified by the XML namespace URI [] "http://www.w3.org/2005/03/addressing". A normative XML Schema [, ] document can be obtained by dereferencing the XML namespace URI.

 SOAP 1.2 Addressing 1.0 Feature

This section defines the SOAP 1.2 Addressing 1.0 Feature.

Feature Name

The SOAP 1.2 Addressing 1.0 Feature is named using the following IRI:

http://www.w3.org/2005/03/addressing/feature

 Description

The SOAP 1.2 Addressing 1.0 Feature provides a SOAP-specific expression of the abstract message addressing properties defined by Web Services Addressing 1.0 - Core[].

This feature may be used with any SOAP MEP. A binding that supports this feature MUST provide a means to transmit the properties listed above with a message and to reconstitute their values on receipt of a message.

 Properties

The SOAP 1.2 Addressing 1.0 Feature defines the following properties:

Corresponds to the abstract [destination] property.

Corresponds to the abstract [source endpoint] property.

Corresponds to the abstract [reply endpoint] property.

Corresponds to the abstract [fault endpoint] property.

Corresponds to the abstract [message id] property.

Corresponds to the abstract [relationship] property.

Corresponds to the abstract [reference parameters] property.

Corresponds to the abstract [action] property.

 Interactions with Other SOAP Features

If the http://www.w3.org/2003/05/soap/features/action/Action property of the SOAP Action feature has a value, then the value of the http://www.w3.org/2005/03/addressing/feature/Action property of the SOAP 1.2 Addressing 1.0 feature MUST be identical to it.

 SOAP 1.2 Addressing 1.0 Module

The SOAP 1.2 Addressing 1.0 Module defines a set of SOAP header blocks to support the SOAP 1.2 Addressing 1.0 Feature described in . To ensure interoperability with a broad range of devices, all conformant implementations that include support for SOAP 1.2 MUST support the SOAP 1.2 Addressing 1.0 Module.

Module Name

The SOAP 1.2 Addressing 1.0 Module is identified using the following IRI:

http://www.w3.org/2005/03/addressing/module

 Description

The SOAP 1.2 Addressing 1.0 Feature (see ) defines a set of SOAP properties and their correspondence to the abstract message addressing properties defined by Web Services Addressing 1.0 - Core[]. The SOAP 1.2 Addressing 1.0 Module uses the XML Infoset representation of the abstract message addressing properties defined in Web Services Addressing 1.0 - Core.

When sending a message each property is represented using the appropriate element information item as a SOAP header block. The resulting header blocks are targetted at the ultimate recipient in the SOAP message path (note that extensions to WS-Addressing could be written to specify different targetting). describes additional processing required when binding message addressing properties to SOAP header blocks.

When receiving a message, the abstract properties are populated from their corresponding element information items in the message. Note that the message addressing properties gathered by an intermediary when receiving a SOAP message do not necessarily get replayed as MAPs when resending the message along the message path.

 Binding Message Addressing Properties

When a message is be addressed to an endpoint, the values of the SOAP 1.2 Addressing 1.0 Feature properties are mapped to the message as SOAP header blocks with the following additional modifications:

The value of the http://www.w3.org/2005/03/addressing/feature/ReferenceParameters property is added to the SOAP message header. The element information item of each [reference parameter] (including all of its [children], [attributes] and [in-scope namespaces]) is added as a SOAP header block in the new message.

Each header block added as a result of the above rule is annotated with a wsa:isReferenceParameter attribute whose value is true.

Each property that is of type IRI MUST be serialized as an absolute IRI in the SOAP message.

The following example shows how the SOAP 1.2 Addressing 1.0 Module is used to construct a message addressed to the endpoint:

Example endpoint reference. <wsa:EndpointReference xmlns:wsa="http://www.w3.org/2005/03/addressing" xmlns:fabrikam="http://example.com/fabrikam" xmlns:wsdli="http://www.w3.org/2004/08/wsdl-instance" wsdli:wsdlLocation="http://example.com/fabrikam http://example.com/fabrikam/fabrikam.wsdl"> <wsa:Address>http://example.com/fabrikam/acct</wsa:Address> <wsa:Metadata> <wsaw:InterfaceName>fabrikam:Inventory</wsaw:InterfaceName> <wsa:Metadata> <wsa:ReferenceParameters> <fabrikam:CustomerKey>123456789</fabrikam:CustomerKey> <fabrikam:ShoppingCart>ABCDEFG</fabrikam:ShoppingCart> </wsa:ReferenceParameters> </wsa:EndpointReference>

The address value is copied in the "To" header block and the "CustomerKey" and "ShoppingCart" elements are copied literally as a header blocks in a SOAP message addressed to this endpoint. The resulting SOAP message would look as follows:

Example endpoint reference mapped to SOAP message header blocks. <S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope" xmlns:wsa="http://www.w3.org/2005/03/addressing" xmlns:fabrikam="http://example.com/fabrikam"> <S:Header> ... <wsa:To>http://example.com/fabrikam/acct</wsa:To> <wsa:Action>...</wsa:Action> <fabrikam:CustomerKey wsa:isReferenceParameter='true'>123456789</fabrikam:CustomerKey> <fabrikam:ShoppingCart wsa:isReferenceParameter='true'>ABCDEFG</fabrikam:ShoppingCart> ... </S:Header> <S:Body> ... </S:Body> </S:Envelope> SOAP 1.1 Addressing 1.0 Extension

The SOAP 1.1 Addressing 1.0 Extension defines a set of SOAP header blocks to support the SOAP 1.2 Addressing 1.0 Feature described in . To ensure interoperability with a broad range of devices, all conformant implementations that include support for SOAP 1.1 MUST support the SOAP 1.1 Addressing 1.0 Extension. This SOAP 1.1 extension is provided for backwards compatibility only.

Extension Name

The SOAP 1.1 Addressing 1.0 Extension is identified using the following IRI:

http://www.w3.org/2005/03/addressing/module

 Description

The SOAP 1.2 Addressing 1.0 Feature (see ) defines a set of SOAP properties and their correspondence to the abstract message addressing properties defined by Web Services Addressing 1.0 - Core[]. The SOAP 1.1 Addressing 1.0 Extension uses the XML Infoset representation of the abstract message addressing properties defined in Web Services Addressing 1.0 - Core and binds each element information item to a SOAP header block. The SOAP 1.1 Addressing 1.0 Extension operates as described in with the following exceptions:

Use of the SOAPAction HTTP header is required when using the SOAP 1.1 HTTP binding. The value of the SOAPAction HTTP header SHOULD be identical to the value of the http://www.w3.org/2005/03/addressing/feature/Action property of the Web Services Addressing 1.0 feature.

 Faults

The faults defined in this section are generated if the condition stated in the preamble in each subsection is met.

Endpoints compliant with this specification MUST include the required message addressing properties serialized as SOAP headers in all fault messages. Fault messages are correlated as replies using the [relationship] property as defined in Section 3. The [action] property below designates WS-Addressing fault messages:

http://www.w3.org/2005/03/addressing/fault

The definitions of faults use the following properties:

[Code] The fault code.

[Subcode] The fault subcode.

[Reason] The English language reason element.

[Detail] The detail element. If absent, no detail element is defined for the fault.

The properties above bind to a SOAP 1.2 fault as follows:

Binding of fault properties to SOAP 1.2 messages. <S:Envelope> <S:Header> <wsa:Action> http://www.w3.org/2005/03/addressing/fault </wsa:Action> <!-- Headers elided for clarity. --> </S:Header> <S:Body> <S:Fault> <S:Code> <S:Value>[Code]</S:Value> <S:Subcode> <S:Value>[Subcode]</S:Value> </S:Subcode> </S:Code> <S:Reason> <S:Text xml:lang="en">[Reason]</S:Text> </S:Reason> <S:Detail> [Detail] </S:Detail> </S:Fault> </S:Body> </S:Envelope>

The SOAP 1.1 fault is less expressive and map only [Subcode] and [Reason]. These the properties bind to a SOAP 1.1 fault as follows:

Binding of fault properties to SOAP 1.1 messages. <S11:Envelope> <S11:Body> <S11:Fault> <faultcode>[Subcode]</faultcode> <faultstring xml:lang="en">[Reason]</faultstring> </S11:Fault> </S11:Body> </S11:Envelope> Invalid Message Addressing Property

A message information property cannot be processed.

[Code] S:Sender

[Subcode] wsa:InvalidMessageAddressingProperty

[Reason] A message addressing property is not valid and the message cannot be processed. The validity failure can be either structural or semantic, e.g. a [destination] that is not an IRI or a [relationship] to a [message id] that was never issued.

[Detail] [invalid property]

 Message Addressing Property Required

A required message addressing property is absent.

[Code] S:Sender

[Subcode] wsa:MessageAddressingPropertyRequired

[Reason] A required message addressing property is not present.

[Detail] [Missing Property QName]

 Destination Unreachable

No endpoint can be found capable of acting in the role of the [destination] property.

[Code] S:Sender

[Subcode] wsa:DestinationUnreachable

[Reason] No route can be determined to reach [destination].

[Detail] empty

 Action Not Supported

The [action] property in the message is not supported at this endpoint.

The contents of this fault are as follows:

[Code] S:Sender

[Subcode] wsa:ActionNotSupported

[Reason] The [action] cannot be processed at the receiver.

[Detail] [action]

 Endpoint Unavailable

The endpoint is unable to process the message at this time either due to some transient issue or a permanent failure.

The endpoint may optionally include a RetryAfter parameter in the detail. The source should not retransmit the message until this duration has passed.

[Code] S:Receiver

[Subcode] wsa:EndpointUnavailable

[Reason] The endpoint is unable to process the message at this time.

[Detail] <wsa:RetryAfter ...>[xs:NonNegativeInteger]</wsa:RetryAfter>

The following describes the attributes and elements listed above:

This element (of type xs:nonNegativeInteger) is a suggested minimum duration in milliseconds to wait before retransmitting the message. If this element is omitted from the detail, the value is infinite.

M Hadley The WG seeks feedback on the choice of nonNegativeInteger for this element. Other types considered included unsignedLong, unsignedInt and duration.

Optional extensibility attributes that do not affect processing.

 Security Considerations

WS-Addressing message addressing properties serialized as SOAP headers (wsa:To, wsa:Action et al.) including those headers present as a result of the [reference parameters] property SHOULD be integrity protected as explained in Web Services Addressing 1.0 - Core[].

When receiving a SOAP message, certain SOAP headers may be resulting from the serialization of an EPR's [reference parameters] property. The SOAP message receiver MAY perform additional security and sanity checks to prevent unintended actions.

Additional Considerations for SOAP Intermediaries

To avoid breaking signatures, intermediaries MUST NOT change the XML representation of WS-Addressing headers. Specifically, 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 RelationshipType attribute is present with a value of http://www.w3.org/2005/03/addressing/reply, an intermediary MUST NOT remove it; similarly, if there is no RelationshipType attribute, an intermediary MUST NOT add one.

References Web Services Addressing 1.0 - Core, M. Gudgin, M. Hadley, Editors. Web Services Addressing 1.0 - WSDL Binding, M. Gudgin, M. Hadley, Editors. Web Services Description Language 2.0, R. Chinnici, M. Gudgin, J. J. Moreau, J. Schlimmer, S. Weerawarana, Editors. World Wide Web Consortium, 3 August 2004. This version of the WSDL 2.0 specification is http://www.w3.org/TR/2004/WD-wsdl20-20040803. The latest version of WSDL 2.0 is available at http://www.w3.org/TR/wsdl20. Key words for use in RFCs to Indicate Requirement Levels, S. Bradner, Author. Internet Engineering Task Force, June 1999. Available at http://www.ietf.org/rfc/rfc2119.txt. M. Duerst, M. Suignard, "Internationalized Resource Identifiers (IRIs)", January 2005. Extensible Markup Language (XML) 1.0 (Third Edition), T. Bray, J. Paoli, C. M. Sperberg-McQueen, and E. Maler, Editors. World Wide Web Consortium, 4 February 2004. This version of the XML 1.0 Recommendation is http://www.w3.org/TR/2004/REC-xml-20040204. The latest version of XML 1.0 is available at http://www.w3.org/TR/REC-xml. Namespaces in XML, T. Bray, D. Hollander, and A. Layman, Editors. World Wide Web Consortium, 14 January 1999. This version of the XML Information Set Recommendation is http://www.w3.org/TR/1999/REC-xml-names-19990114. The latest version of Namespaces in XML is available at http://www.w3.org/TR/REC-xml-names. XML Information Set, J. Cowan and R. Tobin, Editors. World Wide Web Consortium, 24 October 2001. This version of the XML Information Set Recommendation is http://www.w3.org/TR/2001/REC-xml-infoset-20011024. The latest version of XML Information Set is available at http://www.w3.org/TR/xml-infoset. XML Schema Part 1: Structures Second Edition, H. Thompson, D. Beech, M. Maloney, and N. Mendelsohn, Editors. World Wide Web Consortium, 28 October 2004. This version of the XML Schema Part 1 Recommendation is http://www.w3.org/TR/2004/REC-xmlschema-1-20041028. The latest version of XML Schema Part 1 is available at http://www.w3.org/TR/xmlschema-1. XML Schema Part 2: Datatypes Second Edition, P. Byron and A. Malhotra, Editors. World Wide Web Consortium, 28 October 2004. This version of the XML Schema Part 2 Recommendation is http://www.w3.org/TR/2004/REC-xmlschema-2-20041028. The latest version of XML Schema Part 2 is available at http://www.w3.org/TR/xmlschema-2. SOAP Version 1.2 Part 1: Messaging Framework, M. Gudgin, M. Hadley, N. Mendelsohn, J-J. Moreau, H. Frystyk Nielsen, Editors. World Wide Web Consortium, 24 June 2003. This version of the "SOAP Version 1.2 Part 1: Messaging Framework" Recommendation is http://www.w3.org/TR/2003/REC-soap12-part1-20030624/. The latest version of "SOAP Version 1.2 Part 1: Messaging Framework" is available at http://www.w3.org/TR/soap12-part1/. SOAP Version 1.2 Part 2: Adjuncts, M. Gudgin, M. Hadley, N. Mendelsohn, J-J. Moreau, H. Frystyk Nielsen, Editors. World Wide Web Consortium, 24 June 2003. This version of the "SOAP Version 1.2 Part 2: Adjuncts" Recommendation is http://www.w3.org/TR/2003/REC-soap12-part2-20030624/. The latest version of "SOAP Version 1.2 Part 2: Adjuncts" is available at http://www.w3.org/TR/soap12-part2/. Don Box, et al, Simple Object Access Protocol (SOAP) 1.1, May 2000. OASIS, Web Services Security: SOAP Message Security, March 2004. Acknowledgements

This document is the work of the W3C Web Service Addressing Working Group.

Members of the Working Group are (at the time of writing, and by alphabetical order): Abbie Barbir (Nortel Networks), Rebecca Bergersen (IONA Technologies, Inc.), Andreas Bjärlestam (ERICSSON), Ugo Corda (SeeBeyond Technology Corporation), Francisco Curbera (IBM Corporation), Glen Daniels (Sonic Software), Paul Downey (BT), Jacques Durand (Fujitsu Limited), Michael Eder (Nokia), Robert Freund (Hitachi, Ltd.), Yaron Goland (BEA Systems, Inc.), Martin Gudgin (Microsoft Corporation), Arun Gupta (Sun Microsystems, Inc.), Hugo Haas (W3C/ERCIM), Marc Hadley (Sun Microsystems, Inc.), David Hull (TIBCO Software, Inc.), Yin-Leng Husband (HP), Anish Karmarkar (Oracle Corporation), Paul Knight (Nortel Networks), Philippe Le Hégaret (W3C/MIT), Mark Little (Arjuna Technologies Ltd.), Jonathan Marsh (Microsoft Corporation), Jeff Mischkinsky (Oracle Corporation), Nilo Mitra (ERICSSON), Eisaku Nishiyama (Hitachi, Ltd.), Mark Nottingham (BEA Systems, Inc.), Ales Novy (Systinet Inc.), David Orchard (BEA Systems, Inc.), Mark Peel (Novell, Inc.), Tony Rogers (Computer Associates), Tom Rutt (Fujitsu Limited), Rich Salz (DataPower Technology, Inc.), Davanum Srinivas (Computer Associates), Jiri Tejkl (Systinet Inc.), Greg Truty (IBM Corporation), Steve Vinoski (IONA Technologies, Inc.), Pete Wenzel (SeeBeyond Technology Corporation), Steve Winkler (SAP AG), Ümit Yalçınalp (SAP AG), Prasad Yendluri (webMethods, Inc.).

Previous members of the Working Group were: Lisa Bahler (SAIC - Telcordia Technologies), Marc Goodner (SAP AG), Harris Reynolds (webMethods, Inc.).

The people who have contributed to discussions on public-ws-addressing@w3.org are also gratefully acknowledged.

 Change Log Changes Since Second Working Draft

Placeholder for auto change log generation.

 Changes Since First Working Draft

Placeholder for auto change log generation.

 Changes Since Submission

Placeholder for auto change log generation.