Web Services Addressing 1.0 - Core

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 the 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 Information Item'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 XML 1.0 serialization). In addition, where pseudo-schemas are provided for a component, they use BNF-style conventions for attributes and elements: "?" denotes optionality (i.e. zero or one occurrences), "*" denotes zero or more occurrences, "+" one or more occurrences, "[" and "]" are used to form groups, and "|" represents choice. Attributes are conventionally assigned a value which corresponds to their type, as defined in the normative schema. Elements with simple content are conventionally assigned a value which corresponds to the type of their content, as defined in the normative schema.

When defining the cardinality of endpoint reference properties and message addressing properties, this specification uses the following notation: (n..m), where n is the minimum allowed number of ocurrances of the property and m is the maximum allowed number of occurances. When n has the same value as m then exactly that number of ocurrances of the property must be present in the associated endpoint reference or message.

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 may be used with SOAP [SOAP 1.2 Part 1: Messaging Framework, SOAP 1.1] as described in Web Services Addressing 1.0 - SOAP Binding[WS-Addressing-SOAP]. WS-Addressing may be used with WSDL [WSDL 2.0, WSDL 1.1] described services as described in Web Services Addressing 1.0 - WSDL Binding[WS-Addressing-WSDL]. 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 Information Model for Endpoint References

An endpoint reference consists of the following abstract properties:

[address] : IRI (1..1)

An absolute IRI representing the address of the endpoint. This specification introduces two predefined [address] values as shown in Table 2-1.

Table 2-1. Predefined [address] values

URI	Description
"http://www.w3.org/@@@@/@@/addressing/anonymous"	Due to the range of network technologies currently in wide-spread use (e.g., NAT, DHCP, firewalls), many deployments cannot assign a meaningful global IRI to a given endpoint. This URI is used to allow such endpoints to send and receive messages. Messages sent to EPRs whose [address] is this value MUST rely on some out-of-band mechanism for delivery (e.g. using a pre-existing transport connection) from a prior interaction.
"http://www.w3.org/@@@@/@@/addressing/none"	Messages sent to EPRs whose [address] is this value MUST be discarded (i.e. not sent). This URI is typically used in EPRs that designate a reply or fault endpoint (see section 3.1 Abstract Property Definitions) to indicate that no reply or fault message should be sent.

[reference parameters] : {any} (xs:any for an XML 1.0 serialization) (0..unbounded).

A reference may contain a number of individual parameters that are associated with the endpoint to facilitate a particular interaction. Reference parameters are namespace-qualified element information items that are required to properly interact with the endpoint. Reference parameters are provided by the issuer of the endpoint reference and are assumed to be opaque to other users of an endpoint refernce. The binding of reference parameters to messages depends upon the protocol binding used to interact with the endpoint - Web Services Addressing 1.0 - SOAP Binding[WS-Addressing-SOAP] describes the default binding for the SOAP protocol.

[metadata] : {any} (xs:any for an XML 1.0 serialization) (0..unbounded)

A reference may contain metadata that describes the behavior, policies and capabilities of the endpoint. Metadata may be included in an endpoint reference to facilitate easier processing by a user of an endpoint reference, or because the metadata was dynamically generated.

The metadata embedded in an EPR is not necessarily a complete statement of the metadata pertaining to the endpoint. Moreover, while embedded metadata is necessarily valid at the time the EPR is initially created it may become stale at a later point in time.

To deal with conflicts between the embedded metadata of two EPRs that have the same [address], or between embedded metadata and metadata obtained from a different source, or to ascertain the current validity of embedded metadata, mechanisms that are outside of the scope of this specification, such as EPR life cycle information (see 2.4 Endpoint Reference Lifecycle) or retrieval of metadata from an authoritative source, SHOULD be used.

2.2 Endpoint Reference XML Infoset Representation

This section defines an XML Infoset-based representation for an endpoint reference as both an XML element (<wsa:EndpointReference>) and as an XML type (wsa:EndpointReferenceType) for XML 1.0 serialization which MAY be used wherever a Web service endpoint is referenced in an XML 1.0 document. For brevity simple XML terms are used, e.g. 'element' instead of 'element information item' - this is not intended to constrain use of the constructs defined in this section to textual XML representations.

<wsa:EndpointReference>
    <wsa:Address>IRI</wsa:Address>
    <wsa:ReferenceParameters>{any}*</wsa:ReferenceParameters> ?
    <wsa:Metadata>{any}*</wsa:Metadata>?
</wsa:EndpointReference>

The following describes the attributes and elements listed in the schema overview above:

/wsa:EndpointReference

This represents an Endpoint Reference. This example uses the predefined <wsa:EndpointReference> element, but any element of the same type (of the wsa:EndpointReferenceType for an XML 1.0 serialization) may be used.

/wsa:EndpointReference/wsa:Address

This REQUIRED element, whose content is an IRI (of type xs:anyURI for an XML 1.0 serialization), specifies the [address] property of the endpoint reference.

/wsa:EndpointReference/wsa:Address/@{any}

This is an extensibility mechanism to allow additional attributes to be specified.

/wsa:EndpointReference/wsa:ReferenceParameters

This OPTIONAL element may contain elements from any namespace. Such elements form the [reference parameters] of the reference.

/wsa:EndpointReference/wsa:ReferenceParameters/@{any}

This is an extensibility mechanism to allow additional attributes to be specified.

/wsa:EndpointReference/wsa:ReferenceParameters/{any}

Each element information item found in [reference parameters] (including all of that elements [children], [attributes] and [in-scope namespaces]) is represented as is.

/wsa:EndpointReference/wsa:Metadata

This OPTIONAL element may contain elements from any namespace. Such elements form the metadata that is relevant to the interaction with the endpoint.

/wsa:EndpointReference/wsa:Metadata/{any}

Each child element of Metadata represents an individual piece of metadata.

/wsa:EndpointReference/wsa:Metadata/{@any}

This is an extensibility mechanism to allow additional attributes to be specified. Some examples in this specification show use of this extensibility point to include a wsdlLocation[WSDL 2.0] attribute to provide a hint for the location of a WSDL description of the service deployed at the endpoint.

/wsa:EndpointReference/{any}

This is an extensibility mechanism to allow additional elements to be specified.

/wsa:EndpointReference/@{any}

This is an extensibility mechanism to allow additional attributes to be specified.

The following shows an example endpoint reference. This element references the the endpoint at the URI "http://example.com/fabrikam/acct".

<wsa:EndpointReference xmlns:wsa="http://www.w3.org/@@@@/@@/addressing">
   <wsa:Address>http://example.com/fabrikam/acct</wsa:Address>
</wsa:EndpointReference>
      

2.3 Endpoint Reference Comparison

This specification provides no concept of endpoint identity and therefore does not provide any mechanism to determine equality or inequality of EPRs and does not specify the consequences of their equality or inequality. However, note that it is possible for other specifications to provide a comparison function that is applicable within a limited scope.

2.4 Endpoint Reference Lifecycle

This specification does not define a lifecycle model for endpoint references and does not address the question of time-to-live for endpoint references. Other specifications that build on or use WS-Addressing may define a lifecycle model for endpoint references created according to that specification.

2.5 Endpoint Reference Extensibility

As noted in 2.2 Endpoint Reference XML Infoset Representation endpoint references are extensible. When extension attributes or elements appear as part of an endpoint reference, the processing model for such extensions is defined by the specification for those extensions. Software that processes endpoint references can safely ignore any such extensions that it does not recognise or understand.

Extension elements and attributes MAY add additional properties to an endpoint reference in addition to those specified in 2.1 Information Model for Endpoint References. Endpoint reference extensions MAY modify the value of one or more existing properties of an endpoint reference. Extensions MAY modify the rules for binding endpoint reference properties to message addressing properties, or otherwise indicate that a different binding be used.

Note that this ability to modify existing properties and binding behavior, when coupled with the fact that software can ignore unknown or unrecognised extensions, may result in a difference in behaviour depending on whether such an extended endpoint reference is processed by software that understands the extension(s). When designing endpoint reference extensions designers should consider whether they desire standard processing per this specification in cases where their extension is not recognized or understood.

3.1 Abstract Property Definitions

Message addressing properties collectively augment a message with the following abstract properties to support one-way, request-response, and other interaction patterns:

[destination] : IRI (1..1)

An absolute IRI representing the address of the intended receiver of this message.

[source endpoint] : endpoint reference (0..1)

Reference to the endpoint from which the message originated.

[reply endpoint] : endpoint reference (0..1)

An endpoint reference for the intended receiver for replies to this message.

[fault endpoint] : endpoint reference (0..1)

An endpoint reference for the intended receiver for faults related to this message.

[action] : IRI (1..1)

An absolute IRI that uniquely identifies the semantics implied by this message.

It is RECOMMENDED that the value of the [action] property is an IRI identifying an input, output, or fault message within a WSDL interface or port type. An action may be explicitly or implicitly associated with the corresponding WSDL definition. Web Services Addressing 1.0 - WSDL Binding[WS-Addressing-WSDL] describes the mechanisms of association.

[message id] : IRI (0..1)

An absolute IRI that uniquely identifies the message. When present, it is the responsibility of the sender to ensure that each message is uniquely identified. The behavior of a receiver when receiving a message that contains the same [message id] as a previously received message is unconstrained by this specification.

[relationship] : (IRI, IRI) (0..unbounded)

A pair of values that indicate how this message relates to another message. The type of the relationship is identified by an absolute IRI. The related message is identified by an absolute IRI that corresponds to the related message's [message id] property. The message identifier IRI may refer to a specific message, or be the following pre-defined URI that means "unspecified message": "http://www.w3.org/@@@@/@@/addressing/unspecified"

This specification has one predefined relationship type as shown in Table 3-1.

Table 3-1. Predefined [relationship] values

URI	Description
"http://www.w3.org/@@@@/@@/addressing/reply"	Indicates that this is a reply to the message identified by the [message id] IRI.

[reference parameters] : {any} (xs:any for an XML 1.0 serialization) (0..unbounded).

Corresponds to the value of the [reference parameters] property of the endpoint reference to which the message is addressed.

The [destination] and [action] properties indicate the target processing location and the verb or intent of the message respectively. The values of these properties can be used to facilitate the dispatch of messages.

A binding of WS_Addressing message addressing properties MUST reflect the property cardinality shown above. Web Services Addressing 1.0 - SOAP Binding[WS-Addressing-SOAP] defines such a binding for the SOAP [SOAP 1.2 Part 1: Messaging Framework, SOAP 1.1] protocol.

3.2 XML Infoset Representation of Message Addressing Properties

The following shows the XML Infoset representation of the message addressing properties defined in 3.1 Abstract Property Definitions:

<wsa:To>IRI</wsa:To>
<wsa:From>Endpoint Reference</wsa:From>
<wsa:ReplyTo>Endpoint Reference</wsa:ReplyTo>
<wsa:FaultTo>Endpoint Reference</wsa:FaultTo>
<wsa:Action>IRI</wsa:Action>
<wsa:MessageID>IRI</wsa:MessageID>
<wsa:RelatesTo RelationshipType="IRI"?>IRI</wsa:RelatesTo>
<wsa:ReferenceParameters>{any}*</wsa:ReferenceParameters>
                    

The following describes the attributes and elements listed in the schema overview above:

/wsa:To

This OPTIONAL element, whose content is an IRI (of type xs:anyURI for an XML 1.0 serialization), provides the value for the [destination] property. If this element is NOT present then the value of the [destination] property is "http://www.w3.org/@@@@/@@/addressing/anonymous".

/wsa:From

This OPTIONAL element, an Endpoint Reference as defined in 2.2 Endpoint Reference XML Infoset Representation (of type wsa:EndpointReferenceType for an XML 1.0 serialization), provides the value for the [source endpoint] property.

/wsa:ReplyTo

This OPTIONAL element, an Endpoint Reference as defined in 2.2 Endpoint Reference XML Infoset Representation (of type wsa:EndpointReferenceType for an XML 1.0 serialization), provides the value for the [reply endpoint] property. If this element is NOT present then the value of the [address] property of the [reply endpoint] EPR is "http://www.w3.org/@@@@/@@/addressing/anonymous".

/wsa:FaultTo

This OPTIONAL element, an Endpoint Reference as defined in 2.2 Endpoint Reference XML Infoset Representation (of type wsa:EndpointReferenceType for an XML 1.0 serialization), provides the value for the [fault endpoint] property.

/wsa:Action

This REQUIRED element, whose content is an IRI (of type xs:anyURI for an XML 1.0 serialization), conveys the value of the [action] property.

/wsa:MessageID

This OPTIONAL element, whose content is an IRI (of type xs:anyURI for an XML 1.0 serialization), conveys the [message id] property.

/wsa:RelatesTo

This OPTIONAL (repeating) element information item contributes one abstract [relationship] property value, in the form of an (IRI, IRI) pair. The content of this element (of type xs:anyURI for an XML 1.0 serialization) conveys the [message id] of the related message.

/wsa:RelatesTo/@RelationshipType

This OPTIONAL attribute, whose content is an IRI (of type xs:anyURI for an XML 1.0 serialization), conveys the relationship type. When absent, the implied value of this attribute is "http://www.w3.org/@@@@/@@/addressing/reply".

/[reference parameters]*

Each element information item found in [reference parameters] (including all of that elements [children], [attributes] and [in-scope namespaces]) is represented as is.

Note that each of the element information items described above allows attribute wildcards for future extensibility. A message processor may safely ignore any extension attribute it does not recognize.

3.3 Formulating a Reply Message

This section specifies the WS-Addressing-specific rules for creating a reply or fault message related to another message.

1. Select the appropriate EPR:

   • If the reply is a normal message, select the EPR from the related message's [reply endpoint] message addressing property. If none is present, the processor MUST fault.

     Note:

     When using the XML Infoset representation, in the absence of a wsa:ReplyTo element the value of the [reply endpoint] message addressing property defaults to an EPR with an [address] property of "http://www.w3.org/@@@@/@@/addressing/anonymous" - see section 3.2 XML Infoset Representation of Message Addressing Properties.

   • Otherwise, if the reply is a fault message and the related message's [fault endpoint] message addressing property is not empty, select the EPR from that property. If the [fault endpoint] property is empty, select the EPR from the related message's [reply endpoint] message addressing property. Otherwise, if the [reply endpoint] property is empty, the behavior of the recipient of the related message is unconstrained by this specification.

   • In either of the above cases, if the related message lacks a [message id] property, the processor MUST fault.

2. If the selected EPR's [address] property is "http://www.w3.org/@@@@/@@/addressing/none" the reply message is discarded, if not then populate the reply message's message addressing properties:

   • [destination]: this property takes the value of the selected EPR's [address] property.

   • [relationship]: this property MUST include a pair of IRIs as follows; the relationship type is the predefined reply URI "http://www.w3.org/@@@@/@@/addressing/reply" and the related message's identifier is the [message id] property value from the message being replied to; other relationships MAY be expressed in this property

   • [reference parameters]: this property takes the value of the selected EPR's [reference parameters] property

The following example illustrates a message containing message addressing properties serialized as header blocks in a SOAP 1.2 message:

<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope"
  xmlns:wsa="http://www.w3.org/@@@@/@@/addressing">
  <S:Header> 
  <wsa:MessageID>http://example.com/someuniquestring</wsa:MessageID>
    <wsa:ReplyTo>
      <wsa:Address>http://example.com/business/client1</wsa:Address>
    </wsa:ReplyTo>
    <wsa:To>mailto:fabrikam@example.com</wsa:To>
    <wsa:Action>http://example.com/fabrikam/mail/Delete</wsa:Action>
  </S:Header>
  <S:Body>
    <f:Delete xmlns:f="http://example.com/fabrikam">     
       <maxCount>42</maxCount>
    </f:Delete>
  </S:Body>
</S:Envelope>
      

This message would have the following property values:

• [destination]: "mailto:fabrikam@example.com"

• [reply endpoint]: The endpoint with [address] "http://example.com/business/client1"

• [action]: "http://example.com/fabrikam/mail/Delete"

• [message id]: "http://example.com/someuniquestring"

The following example illustrates a reply to the above message:

<S:Envelope
  xmlns:S="http://www.w3.org/2003/05/soap-envelope" 
  xmlns:wsa="http://www.w3.org/@@@@/@@/addressing">
  <S:Header>
    <wsa:MessageID>http://example.com/someotheruniquestring</wsa:MessageID>
    <wsa:RelatesTo>http://example.com/someuniquestring</wsa:RelatesTo>
    <wsa:To>http://example.com/business/client1</wsa:To>
    <wsa:Action>http://example.com/fabrikam/mail/DeleteAck</wsa:Action>
  </S:Header>
  <S:Body>
    <f:DeleteAck xmlns:f="http://example.com/fabrikam"/>
  </S:Body>
</S:Envelope>
      

This message would have the following property values:

• [destination]: "http://example.com/business/client1"

• [action]: "http://example.com/fabrikam/mail/DeleteAck"

• [message id]: "http://example.com/someotheruniquestring"

• [relationship]: ("http://www.w3.org/@@@@/@@/addressing/reply", "http://example.com/someuniquestring")