Web Services Addressing 1.0 - SOAP Binding

1.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 [IETF RFC 2119].

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

When describing concrete XML information items, this specification uses the notational convention of WS-Security [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/> in XML Schema 1.0 for XML 1.0 serialization). The use of @{any} indicates the presence of an attribute wildcard (<xs:anyAttribute/> in XML Schema 1.0 for an XML 1.0 serialization).

1.2 Namespaces

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

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

All information items defined by this specification are identified by the XML namespace URI [XML Namespaces] http://www.w3.org/@@@@/@@/addressing. A normative XML Schema [XML Schema Structures, XML Schema Datatypes] document for XML 1.0 serialization can be obtained by dereferencing the XML namespace URI.

2.1 Feature Name

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

• http://www.w3.org/@@@@/@@/addressing/feature

2.2 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[WS-Addressing-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.

2.3 Properties

The SOAP 1.2 Addressing 1.0 Feature defines the following properties:

http://www.w3.org/@@@@/@@/addressing/feature/Destination

Corresponds to the abstract [destination] property.

http://www.w3.org/@@@@/@@/addressing/feature/SourceEndpoint

Corresponds to the abstract [source endpoint] property.

http://www.w3.org/@@@@/@@/addressing/feature/ReplyEndpoint

Corresponds to the abstract [reply endpoint] property.

http://www.w3.org/@@@@/@@/addressing/feature/FaultEndpoint

Corresponds to the abstract [fault endpoint] property.

http://www.w3.org/@@@@/@@/addressing/feature/Action

Corresponds to the abstract [action] property.

http://www.w3.org/@@@@/@@/addressing/feature/MessageID

Corresponds to the abstract [message id] property.

http://www.w3.org/@@@@/@@/addressing/feature/Relationship

Corresponds to the abstract [relationship] property.

http://www.w3.org/@@@@/@@/addressing/feature/ReferenceParameters

Corresponds to the abstract [reference parameters] property.

2.4 Interactions with Other SOAP Features

If the http://www.w3.org/2003/05/soap/features/action/Action property of the SOAP Action feature[SOAP 1.2 Part 2: Adjuncts] has a value, then the value of the http://www.w3.org/@@@@/@@/addressing/feature/Action property of the SOAP 1.2 Addressing 1.0 feature MUST be identical to it. Failure to have an identical value results in an Invalid Addressing Header fault (see 5.3 Invalid Addressing Header.

3.1 Module Name

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

• http://www.w3.org/@@@@/@@/addressing/module

3.2 Description

The SOAP 1.2 Addressing 1.0 Feature (see 2. SOAP 1.2 Addressing 1.0 Feature) defines a set of SOAP properties and their correspondence to the abstract message addressing properties defined by Web Services Addressing 1.0 - Core[WS-Addressing-Core]. The SOAP 1.2 Addressing 1.0 Module defines SOAP headers corresponding to 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. 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). 3.4 Binding Message Addressing Properties 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. A message MUST NOT contain more than one wsa:To, wsa:ReplyTo, wsa:FaultTo, wsa:Action, or wsa:MessageID header targeted at a recipient. A recipient MUST generate a wsa:InvalidAddressingHeader (see 5.3 Invalid Addressing Header) fault if such a message is received.

3.3 Additional Infoset Items

The SOAP 1.2 Addressing 1.0 Module defines the following additional XML Infoset items:

/[reference parameters]/@wsa:IsReferenceParameter

This REQUIRED attribute (of type xs:boolean) signifies whether the message addressing header is a reference parameter, see section 3.4 Binding Message Addressing Properties for more details on its use.

3.4 Binding Message Addressing Properties

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.

  Note:

  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[WS-Security] header would be ill-advised (since other parts of the SOAP infrastructure will often control this header, and there must be at most one of them per message).

• Each header block added as a result of the above rule is annotated with a wsa:IsReferenceParameter attribute (see 3.3 Additional Infoset Items) whose value is a valid xs:boolean representaion of "true". Any existing wsa:IsReferenceParameter attribute on the header block is replaced.

  Note:

  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:

<wsa:EndpointReference
     xmlns:wsa="http://www.w3.org/@@@@/@@/addressing"
     xmlns:wsaw="http://www.w3.org/@@@@/@@/addressing/wsdl"
     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:

<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope"
         xmlns:wsa="http://www.w3.org/@@@@/@@/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>

4.1 Extension Name

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

• http://www.w3.org/@@@@/@@/addressing/module

4.2 Description

The SOAP 1.2 Addressing 1.0 Feature (see 2. SOAP 1.2 Addressing 1.0 Feature) defines a set of SOAP properties and their correspondence to the abstract message addressing properties defined by Web Services Addressing 1.0 - Core[WS-Addressing-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 3. SOAP 1.2 Addressing 1.0 Module with the following exceptions:

SOAP Action

Use of the SOAPAction HTTP header is required when using the SOAP 1.1 HTTP binding. The value of the SOAPAction HTTP header MUST either be identical to the value of the wsa:Action header, or be empty. The latter case supports the ability to obscure the wsa:Action header through SOAP-level security mechanisms, without requiring otherwise unnecessary transport-level security. Failure to have an identical value, or an empty value for SOAPAction, results in an Invalid Message Addressing Property fault (see 5.3 Invalid Addressing Header.

5.1 SOAP 1.2 Fault Binding

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

[Code]

The value of the [Code] property is bound as the value of the SOAP faults S:Fault/S:Code/S:Value element information item.

[Subcode]

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.

[Reason]

The value of the [Reason] property is bound as the value of the SOAP faults S:Fault/S:Reason/S:Text element information item.

[Detail]

The value of the [Detail] property is bound as child of the SOAP faults S:Fault/S:Detail element information item.

<S:Envelope>
  <S:Header>
    <wsa:Action>http://www.w3.org/@@@@/@@/addressing/fault</wsa:Action>
    <!-- Headers elided for brevity.  -->
  </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>
      

5.2 SOAP 1.1 Fault Binding

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:

[Subcode]

The value of the [Subcode] property is bound as the value of the SOAP faults S11:Fault/faultcode element.

[Reason]

The value of the [Reason] property is bound as the value of the SOAP faults S11:Fault/faultstring element.

[Detail]

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 [Detail] property is bound as the value of a new wsa:FaultDetail SOAP header block. The following describes the wsa:FaultDetail element:

/wsa:FaultDetail

One of wsa:ActionNotSupported, wsa:InvalidAddressingHeader, wsa:MessageAddressingHeaderRequired, wsa:RetryAfter or {any} (xs:any for an XML 1.0 serialization).

/wsa:FaultDetail/@{any}

Optional extensibility attributes including SOAP role and mustUnderstand.

<S11:Envelope>
  <S11:Header>
    <wsa:Action>http://www.w3.org/@@@@/@@/addressing/fault</wsa:Action>
    <wsa:FaultDetail>[Detail]</wsa:FaultDetail>
    <!-- Other headers elided for brevity.  -->
  </S11:Header>
  <S11:Body>
    <S11:Fault>
      <faultcode>[Subcode]</faultcode>
      <faultstring xml:lang="en">[Reason]</faultstring>
    </S11:Fault>
  </S11:Body>
</S11:Envelope>
      

5.3 Invalid Addressing Header

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"

[Detail] a <wsa:InvalidAddressingHeader> element

The following describes the <wsa:InvalidAddressingHeader> element:

/wsa:InvalidAddressingHeader

A QName representing the name of the root element of the invalid header block

/wsa:InvalidAddressingHeader/@{any}

Optional extensibility attributes that do not affect processing.

5.4 Message Addressing Header Required

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"

[Detail] a <wsa:MessageAddressingHeaderRequired> element

The following describes the <wsa:MessageAddressingHeaderRequired> element:

/wsa:MessageAddressingHeaderRequired

A QName representing the name of the missing header element

/wsa:MessageAddressingHeaderRequired/@{any}

Optional extensibility attributes that do not affect processing.

5.5 Destination Unreachable

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

[Detail] (empty)

5.6 Action Not Supported

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"

[Detail] a <wsa:ActionNotSupported> element

The following describes the <wsa:ActionNotSupported> element:

/wsa:ActionNotSupported

The value of the wsa:Action header block

/wsa:ActionNotSupported/@{any}

Optional extensibility attributes that do not affect processing.

5.7 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] 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"

[Detail] a <wsa:RetryAfter> element

The following describes the <wsa:RetryAfter> element:

/wsa:RetryAfter

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.

/wsa:RetryAfter/@{any}

Optional extensibility attributes that do not affect processing.

6.1 Additional Considerations for SOAP Intermediaries

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 "http://www.w3.org/@@@@/@@/addressing/reply", an intermediary MUST NOT remove it; similarly, if there is no RelationshipType attribute, an intermediary MUST NOT add one.