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 is the
This document has been reviewed by W3C Members, by software developers, and by other W3C groups and interested parties, and is endorsed by the Director as a W3C Recommendation. It is a stable document and may be used as reference material or cited from another document. W3C's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment. This enhances the functionality and interoperability of the Web.
The Working Group made the following editorial changes to the
Proposed Recommendation in response to comments: normative and
informative references are now more clearly distinguished, and some
typographical errors were fixed. An
Please report errors in this document to the public
This document was produced by a group operating under the
Last Modified: $Date: 2006/05/05 16:06:14 $
Web Services Addressing 1.0 - Core[
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:
Lines (02) to (09) represent the header of the SOAP message where the mechanisms defined in the specification are used. The body is represented by lines (10) to (12).
Lines (03) to (08) contain the message addressing properties serialized as SOAP header blocks. Specifically, line (03) specifies the identifier for this message and lines (04) to (06) specify the endpoint to which replies to this message should be sent as an Endpoint Reference. Line (07) specifies the address URI of the ultimate receiver of this message. Line (08) specifies an action URI identifying expected semantics.
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 [
When describing concrete XML schemas [
This specification uses a number of namespace prefixes throughout; they are listed in
| Prefix | Namespace |
|---|---|
| S | http://www.w3.org/2003/05/soap-envelope |
| S11 | http://schemas.xmlsoap.org/soap/envelope |
| wsa | http://www.w3.org/2005/08/addressing |
| wsaw | http://www.w3.org/2006/02/addressing/wsdl |
| xs | http://www.w3.org/2001/XMLSchema |
WS-Addressing is defined in terms of the XML Information Set [
All information items defined by this specification are identified by the XML namespace
URI [
This section defines the SOAP 1.2 Addressing 1.0 Feature.
The SOAP 1.2 Addressing 1.0 Feature is named using the following URI:
http://www.w3.org/2005/08/addressing/feature
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 below with a message and to reconstitute their values on receipt of a message.
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 [action] property.
Corresponds to the abstract [message id] property.
Corresponds to the abstract [relationship] property.
Corresponds to the abstract [reference parameters] property.
If the http://www.w3.org/2003/05/soap/features/action/Action property of the SOAP Action
feature[
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
The SOAP 1.2 Addressing 1.0 Module is identified using the following URI:
http://www.w3.org/2005/08/addressing/module
The SOAP 1.2 Addressing 1.0 Feature (see
When sending a message each property is represented using the appropriate element
information item as a SOAP header block. By default, the resulting header blocks are
targeted at the ultimate recipient in the SOAP message path (note that extensions to
WS-Addressing could be written to specify different targetting).
When receiving a message, the abstract properties are populated from their corresponding
element information items in the message. A message MUST NOT contain more than one wsa:To,
wsa:ReplyTo, wsa:FaultTo, wsa:Action, or wsa:MessageID header targeted at a recipient;
headers with an incorrect cardinality MUST NOT be used to populate the corresponding
abstract properties. A
recipient MUST generate a wsa:InvalidAddressingHeader (see
The SOAP processing model dictates that message addressing properties targeted at an intermediary do not normally get relayed as message addressing properties when the message is forwarded along the message path. The specification for a SOAP header used as a reference parameter or use of the soap:relay attribute can override this default behavior.
The SOAP 1.2 Addressing 1.0 Module defines the following additional XML Infoset items:
This REQUIRED attribute (of type xs:boolean) signifies whether the message
addressing header is a reference parameter, see section
When a message is to be addressed to an endpoint, the XML Infoset representation of each message addressing property that has been assigned a value is inserted into the message as a SOAP header block subject to the following additional constraints:
The value, if any, of the [reference parameters] property is added to the SOAP message header: the element information item of each of the [reference parameters] (including all of its [children], [attributes] and [in-scope namespaces]) is added as a SOAP header block in the new message.
The insertion of SOAP headers into a message implies particular semantics. Since
the reference parameter mechanism does not restrict the content of the generated
headers, EPR suppliers should exercise appropriate caution to ensure their reference
parameters do not cause unintended or erroneous semantics in the resultant SOAP
message. For example, using a reference parameter to send a WS-Security[
Each header block added as a result of the above rule is annotated with a
wsa:IsReferenceParameter attribute (see
Integrity validation of [reference parameters] needs to take into account the addition of wsa:IsReferenceParameter attributes and the corresponding introduction of the WS-Addressing namespace to the [in-scope namespaces]
The value of each message addressing property that is of type IRI MUST be serialized as an absolute IRI in the corresponding SOAP header block. No additional %-escaping is performed.
Each optional element or attribute that has a value equal to the defined default value for that element or attribute MAY be omitted.
The following example shows how the SOAP 1.2 Addressing 1.0 Module is used to construct a message addressed to the endpoint:
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:
Some underlying protocols may support native properties similar to the Message Addressing Properties. For example, the reply-to: email header is similar to the [reply endpoint] Message Addressing Property. Authors and implementors of bindings should not assume any particular correspondence between native properties and Message Addressing Properties. For example, if an email message represents only one hop in a multi-hop path, then the reply-to: header is likely to differ from the [reply endpoint] address.
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
The SOAP 1.1 Addressing 1.0 Extension is identified using the following URI:
http://www.w3.org/2005/08/addressing/module
The SOAP 1.2 Addressing 1.0 Feature (see
Use of the SOAPAction HTTP request header field is required when using the SOAP 1.1
HTTP binding. The field-value of the SOAPAction HTTP request header MUST either be
the value of the [action] property enclosed in quotation marks, or the empty value
"". The latter case supports the ability to obscure the [action] property through
SOAP-level security mechanisms, without requiring otherwise unnecessary
transport-level security. Any other value for SOAPAction results in an Invalid
Message Addressing Property fault (see
In the following text, the term 'response endpoint' refers to the [reply endpoint] and [fault endpoint] message addressing properties collectively.
A value of "http://www.w3.org/2005/08/addressing/anonymous" for
the [destination] property implies no additional semantics beyond those resulting from the
rules defined below and as described
in Web Services Addressing 1.0 - Core[
When "http://www.w3.org/2005/08/addressing/anonymous" is specified for the response endpoint then there is no change to the SOAP 1.1/ HTTP binding.
When "http://www.w3.org/2005/08/addressing/anonymous" is specified for the response
endpoint and the message is the http://www.w3.org/2003/05/soap/mep/InboundMessage
property of a SOAP request-response MEP [
When "http://www.w3.org/2005/08/addressing/anonymous" is not specified for the response
endpoint, then the message SHOULD be part of a binding that supports not returning a
SOAP envelope in the HTTP response (e.g. see [
When "http://www.w3.org/2005/08/addressing/anonymous" is not specified for the response
endpoint, then any response SHOULD NOT be the
http://www.w3.org/2003/05/soap/mep/OutboundMessage property of the same instance of the SOAP
request-response MEP [
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 generated fault messages. Fault messages are
correlated as replies using the [relationship] property as defined in
Web Services Addressing 1.0 - Core[
The [action] property below designates WS-Addressing fault messages:
This action SHOULD NOT be used as an action value in messages other than those carrying WS-Addressing faults.
SOAP modules, extensions and applications SHOULD define custom [action] values for the faults they describe but MAY designate use of the following [action] value instead:
The above [action] value SHOULD be used for SOAP defined faults including version mismatch, must understand, and data encoding unknown.
Each of the predefined faults listed below is defined by specifying values for the following abstract properties:
[Code] The fault code, use of the specified fault code is REQUIRED.
[Subcode] The fault subcode, use of the specified fault subcode is REQUIRED.
[Subsubcode] A more specific fault subcode that may be used to further qualify the value of the [Subcode] property, use of a specified fault subcode is OPTIONAL.
[Reason] The English language reason element, use of the specified fault code is RECOMMENDED but alternate text MAY be used.
[Details] The detail elements, use of the specified detail elements is REQUIRED. If absent, no detail elements are defined for the fault.
The fault properties bind to a SOAP 1.2 fault as follows:
The value of the [Code] property is bound as the value of the SOAP faults S:Fault/S:Code/S:Value element information item.
The value of the [Subcode] property is bound as the value of the SOAP faults S:Fault/S:Code/S:Subcode/S:Value element information item.
The value of the [Subsubcode] property is bound as the value of the SOAP faults S:Fault/S:Code/S:Subcode/S:/Subcode/S:Value element information item.
The value of the [Reason] property is bound as the value of the SOAP faults S:Fault/S:Reason/S:Text element information item.
The value of the [Details] property is bound as child elements of the SOAP faults S:Fault/S:Detail element information item.
The SOAP 1.1 fault is slightly less expressive than the SOAP 1.2 fault and maps only [Subcode], [Reason] and [Detail]. These the properties bind to a SOAP 1.1 fault as follows:
The value of the [Subsubcode] or, if that is not specified, the value of the [Subcode] property is bound as the value of the SOAP faults S11:Fault/faultcode element.
The value of the [Reason] property is bound as the value of the SOAP faults S11:Fault/faultstring element.
The SOAP 1.1 fault detail is only for use with faults related to the body of a message and is therefore not used for SOAP 1.1 faults related to processing of addressing headers. Instead the value of the [Details] property is bound as the value of a new wsa:FaultDetail SOAP header block. The following describes the wsa:FaultDetail element:
Zero or more of the elements defined in
Optional extensibility attributes including SOAP role and mustUnderstand.
The following subsections define a set of elements used to convey additional information
in the faults described in
The following describes the <wsa:ProblemHeaderQName> element:
A QName representing the name of the root element of the problem header block.
Optional extensibility attributes that do not affect processing.
The following describes the <wsa:ProblemIRI> element:
The IRI that caused the problem.
Optional extensibility attributes that do not affect processing.
The following describes the <wsa:ProblemAction> element:
An optional element that provides the [action] that caused the problem.
An optional element that provides the SOAPAction IRI that caused the problem.
Optional extensibility elements that do not affect processing.
Optional extensibility attributes that do not affect processing.
The following describes the <wsa:RetryAfter> element:
This element (whose content is of type xs:unsignedLong) is a suggested minimum duration in milliseconds to wait before retransmitting the message. Omission of this element indicates that a retry is never likely to succeed.
Optional extensibility attributes that do not affect processing.
A header representing a WS-Addressing 1.0 Message Addressing Property is invalid and 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.
[Code] a QName representing the value S:Sender
[Subcode] a QName representing the value wsa:InvalidAddressingHeader
[Reason] the string: "A header representing a Message Addressing Property is not valid and the message cannot be processed"
[Details] either a <wsa:ProblemHeader> element that conveys a copy of the offending header or a <wsa:ProblemHeaderQName> element that conveys the QName of the root element of the offending header.
The invalid addressing header fault can be further narrowed in scope by use of the additional [Subsubcode]s specified in the following subsections. Use of these [Subsubcode] values is OPTIONAL.
Specifies that an [address] was invalid.
Specifies that the invalid header was expected to be an EPR but was not valid.
Specifies that there was a greater than expected number of the specified header.
Specifies that the invalid header was expected to be an EPR but did not contain an [address].
Specifies that the invalid header conveyed a [message id] that was a duplicate of one already received.
Specifies that the [action] and SOAPAction for the message did not match, [Details] MAY contain a <wsa:ProblemAction> element in addition to the <wsa:ProblemHeader> element or <wsa:ProblemHeaderQName> element.
Specifies that the only address supported is the anonymous address.
Specifies that the anonymous address is not supported, and that only a non-anonymous address will be accepted.
A required header representing a Message Addressing Property is absent.
[Code] a QName representing the value S:Sender
[Subcode] a QName representing the value wsa:MessageAddressingHeaderRequired
[Reason] the string: "A required header representing a Message Addressing Property is not present"
[Details] a <wsa:ProblemHeaderQName> element that conveys the QName of the message addressing header that was missing.
The endpoint identified by the value of [destination] property cannot be reached.
[Code] a QName representing the value S:Sender
[Subcode] a QName representing the value wsa:DestinationUnreachable
[Reason] the string: "No route can be determined to reach [destination]"
[Details] an optional <wsa:ProblemIRI> element that conveys the [address] of the [destination].
Implementation of this fault is optional.
The [action] property in the message is not supported at this endpoint.
[Code] a QName representing the value S:Sender
[Subcode] a QName representing the value wsa:ActionNotSupported
[Reason] the string: "The [action] cannot be processed at the receiver"
[Details] a <wsa:ProblemAction> element with a REQUIRED <wsa:Action> child element
Implementation of this fault is optional.
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] a QName representing the value S:Receiver
[Subcode] a QName representing the value wsa:EndpointUnavailable
[Reason] the string "The endpoint is unable to process the message at this time"
[Details] an optional <wsa:RetryAfter> element and an optional <wsa:ProblemIRI> element that conveys the [address] of the [destination].
Implementation of this fault is optional.
No assumptions are made herein of the application level security requirement, the organization of the application, implementation of senders or receivers, or of the ways that other protocols may make use of WS-Addressing, and what security mechanisms they may employ. A holistic approach to security which considers all components of the application, other protocols utilized, the way that these protocols compose with WS-Security, and the use of other methods or additional techniques is highly recommended.
As discussed in Web Services Addressing 1.0 - Core[
SOAP headers are a powerful extension mechanism and therefore great care should be taken before honoring a [reply endpoint] or [fault endpoint] to avoid inadvertent participation in the activities of malicious SOAP message senders.
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[
Messages that use wsa:ReplyTo or wsa:FaultTo headers whose [address] is not the predefined anonymous URI should include claims that allow a receiver to confirm that the EPR was issued by a principle with authority to represent the [address] of the EPR.
When receiving a SOAP message, certain SOAP headers may have resulted from the serialization of an EPR's [reference parameters] property. A SOAP message receiver should perform additional security and sanity checks to prevent unintended actions.
There are many mechanisms that could be used to supply proof that a message sender has
authority to represent the [address] of EPRs supplied within the message. Typically such
mechanisms require the inclusion of a WS-Security[
For example, a message could include a WS-Security[
The wsa:isReferenceParameter attribute is only meaningful on SOAP headers. Message processors should consider its appearance elsewhere in a SOAP message as a possible attack.
Message processors should consider elements from the soap11, soap12 and wsa namespaces appearing as reference parameters in an EPR as a possible attack.
There are known XML ID and re-structuring attacks which should be considered by message
processors, see [
To avoid breaking signatures, intermediaries MUST NOT change the XML representation of
WS-Addressing headers when relaying those 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
A SOAP 1.2 message conforms to the SOAP 1.2 Addressing 1.0 Module when it contains headers
from the wsa namespace, and follows all the constraints on message addressing properties
defined by Web Services Addressing 1.0 - Core[
A SOAP 1.1 message conforms to the SOAP 1.1 Addressing 1.0 Extension when it contains
headers from the wsa namespace, and follows all the constraints on message addressing
properties defined by Web Services Addressing 1.0 - Core[
An endpoint which conforms to this specification understands and accepts SOAP messages
containing headers in the wsa namespace targeted to it, generates reply or fault messages it
may send in response according to the rules outlined in this specification and in
Web Services Addressing 1.0 - Core[
Web Services Addressing 1.0 - WSDL Binding[
Endpoints MAY accept and respond to messages which contain no WSA headers.
If a receiver processes a message containing a wsa:Action header, this SOAP binding is engaged, and the rules of this specification are in force.
This document is the work of the
Members of the Working Group are (at the time of writing, and by alphabetical order): Abbie Barbir (Nortel Networks), Andreas Bjärlestam (ERICSSON), Dave Chappell (Sonic Software), Eran Chinthaka (WSO2), Francisco Curbera (IBM Corporation), Glen Daniels (Sonic Software), Vikas Deolaliker (Sonoa Systems, Inc.), Paul Downey (BT), Jacques Durand (Fujitsu Limited), Robert Freund (Hitachi, Ltd.), Marc Goodner (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), David Illsley (IBM Corporation), Anish Karmarkar (Oracle Corporation), Paul Knight (Nortel Networks), Philippe Le Hégaret (W3C/MIT), Amelia Lewis (TIBCO Software, Inc.), Bozhong Lin (IONA Technologies, Inc.), Mark Little (JBoss Inc.), Jonathan Marsh (Microsoft Corporation), Jeff Mischkinsky (Oracle Corporation), Nilo Mitra (ERICSSON), Eisaku Nishiyama (Hitachi, Ltd.), Ales Novy (Systinet Inc.), David Orchard (BEA Systems, Inc.), Gilbert Pilz (BEA Systems, Inc.), Alain Regnier (Ricoh Company, Ltd.), Tony Rogers (Computer Associates), Tom Rutt (Fujitsu Limited), Davanum Srinivas (WSO2), Jiri Tejkl (Systinet Inc.), Mike Vernal (Microsoft Corporation), Steve Vinoski (IONA Technologies, Inc.), Katy Warr (IBM Corporation), Pete Wenzel (Sun Microsystems, Inc.), Steve Winkler (SAP AG), Ümit Yalçinalp (SAP AG), Prasad Yendluri (webMethods, Inc.).
Previous members of the Working Group were: Lisa Bahler (SAIC - Telcordia Technologies), Rebecca Bergersen (IONA Technologies, Inc.), Ugo Corda (Sun Microsystems, Inc.), Michael Eder (Nokia), Yaron Goland (BEA Systems, Inc.), Marc Goodner (SAP AG), Martin Gudgin (Microsoft Corporation), Mark Nottingham (BEA Systems, Inc.), Mark Peel (Novell, Inc.), Harris Reynolds (webMethods, Inc.), Rich Salz (IBM Corporation), Davanum Srinivas (Computer Associates), Greg Truty (IBM Corporation).
The people who have contributed to