2005-03-31 diff-marked version: Web Services Addressing 1.0 - Core

<a name="_Toc77464315" id="_Toc77464315"> 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 schemas [ XML Schema Structures , XML Schema Datatypes ], 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/>). The use of @{any} indicates the presence of an attribute wildcard (<xs:anyAttribute/>).

<a name="_Toc77464316" id="_Toc77464316"> 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 ] as described in Web Services Addressing 1.0 - SOAP Binding[ WS-Addressing-SOAP ]. 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 ]. Examples in this specification use an XML 1.0 [ XML 1.0 ] representation but this is not a requirement.

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

<a name="_Toc77464318" id="_Toc77464318"> 2.1 Information Model for Endpoint References

An endpoint reference consists of the following abstract properties:

[address] : URI IRI (mandatory)

An address URI IRI for the endpoint. deleted text: This may be a network address or a logical address.

[reference parameters] : xs:any (0..unbounded).

A reference may contain a number of individual parameters which are associated with the endpoint to facilitate a particular interaction. Reference parameters are element information items that are named by QName and are required to properly interact with the endpoint. Reference parameters are also provided by the issuer of the endpoint reference and are otherwise assumed to be opaque to consuming applications. The use of reference parameters is dependent upon the protocol binding and data encoding used to interact with the endpoint. Web Services Addressing 1.0 - SOAP Binding[ WS-Addressing-SOAP ] describes the default binding for the SOAP protocol.

[selected interface] : QName (0..1) </dt> <dd> <p> A QName identifying a description of the sequences of messages that a service sends and/or receives, see Web Services Addressing 1.0 - WSDL Binding[ <cite> <a href= "#WSADDR-WSDL"> WS-Addressing-WSDL </a> </cite> ] for more details. </p> </dd> <dt class="label"> [service endpoint] : (QName, NCName (0..1)) (0..1) </dt> <dd> <p> A QName, NCName pair: the QName identifies a description of a set of endpoints at which a particular Web service is deployed; the NCName identifies one endpoint in particular. See Web Services Addressing 1.0 - WSDL Binding[ <cite> <a href= "#WSADDR-WSDL"> WS-Addressing-WSDL </a> </cite> ] for more details. </p> </dd> <dt class="label"> [policies] [metadata] : xsd:any (0..unbounded)

A reference may contain a number of policies metadata that describe describes the behavior, requirements policies and capabilities of the endpoint. Policies Metadata may be included in an endpoint reference to facilitate easier processing by the consuming application, or because the policy metadata was dynamically generated. However,

The metadata embedded policies are in each of the EPRs MAY differ, as the metadata carried by an EPR is not authoritative and may be stale or incoherent with necessarily a complete statement of the policies associated with metadata pertaining to the endpoint endpoint. Moreover, while embedded metadata is necessarily valid at the time deleted text: when the interaction occurs. 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, 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 2.4 Endpoint Reference Lifecycle or retrieval of metadata from an authoritative source, SHOULD be used.

<a name="_Toc77464319" id="_Toc77464319"> 2.2 Endpoint Reference XML Infoset Representation

This section defines an XML Infoset-based representation for an endpoint reference as both an XML type (wsa:EndpointReferenceType) and as an XML element (<wsa:EndpointReference>).

The wsa:EndpointReferenceType type is used wherever a Web service endpoint is referenced. The following describes the contents of this type:

<wsa:EndpointReference>
    <wsa:Address>xs:anyURI</wsa:Address>

    <wsa:ReferenceParameters>... </wsa:ReferenceParameters> ?


    <wsa:InterfaceName>xs:QName</wsa:InterfaceName> ?
    <wsa:ServiceName EndpointName="xs:NCName"?>xs:QName</wsa:ServiceName> ?
    <wsa:Policies> ... </wsa:Policies>?



    <wsa:Metadata> ... </wsa:Metadata>?


    <xs:any/>*
</wsa:EndpointReference>
      

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

/wsa:EndpointReference

This represents some element of type wsa:EndpointReferenceType. This example uses the predefined <wsa:EndpointReference> element, but any element of type wsa:EndpointReferenceType may be used.

/wsa:EndpointReference/wsa:Address

This REQUIRED element (of type xs:anyURI) specifies the [address] property of the endpoint reference.

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

This address may is an extensibility mechanism to allow additional attributes to be a logical address for the service endpoint. specified.

/wsa:EndpointReference/wsa:ReferenceParameters/ /wsa:EndpointReference/wsa:ReferenceParameters

This OPTIONAL element contains the elements that convey the [reference parameters] of the reference.

/wsa:EndpointReference/wsa:ReferenceParameters/{any} </dt> <dd> <p> Each child element of ReferenceParameters represents an individual [reference parameter]. </p> </dd> <dt class="label"> /wsa:EndpointReference/wsa:InterfaceName /wsa:EndpointReference/wsa:ReferenceParameters/@{any}

This OPTIONAL element (of type xs:Qname) specifies the value of the [selected interface] property of the endpoint reference, see Web Services Addressing 1.0 - WSDL Binding[ <cite> <a href= "#WSADDR-WSDL"> WS-Addressing-WSDL </a> </cite> ] for more details.. is an extensibility mechanism to allow additional attributes to be specified.

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

This OPTIONAL Each element (of type xs:QName) specifies the value information item of the [service endpoint] property, see Web Services Addressing 1.0 - WSDL Binding[ <cite> <a href= "#WSADDR-WSDL"> WS-Addressing-WSDL </a> </cite> ] for more details.. </p> </dd> <dt class="label"> /wsa:EndpointReference/wsa:ServiceName/@EndpointName </dt> <dd> <p> This OPTIONAL attribute (of type xs:NCName) specifies the name found in [reference parameters] (including all of a particular endpoint, see Web Services Addressing 1.0 - WSDL Binding[ <cite> <a href="#WSADDR-WSDL"> WS-Addressing-WSDL </a> </cite> ] for more details. its [children], [attributes] and [in-scope namespaces]) is represented as is.

/wsa:EndpointReference/wsa:Policies /wsa:EndpointReference/wsa:Metadata

This OPTIONAL element contains policies metadata that are is relevant to the interaction with the endpoint.

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

Each child element of Policies Metadata represents an individual [policy]. </p> </dd> <dt class="label"> /wsa:EndpointReference/{any} </dt> <dd> <p> This is an extensibility mechanism to allow additional elements to be specified. piece of metadata.

/wsa:EndpointReference/@{any} /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 [selected interface] and [service endpoint] properties. 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 deleted text: [selected interface] "fabrikam:Inventory" at the endpoint URI "http://example.com/www.fabrikam/acct". Note the use of at the WSDL[ <cite> <a href="#WSDL20"> WSDL 2.0 </a> </cite> ] wsdlLocation attribute. IRI "http://example.com/www.fabrikam/acct".

<wsa:EndpointReference
     xmlns:wsa="http://www.w3.org/2005/02/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:EndpointReference xmlns:wsa="http://www.w3.org/2005/03/addressing">


   <wsa:Address>http://example.com/fabrikam/acct</wsa:Address>
deleted text: 

   <wsa:InterfaceName>fabrikam:Inventory</wsa:InterfaceName>


</wsa:EndpointReference>
      

2.3 Endpoint Reference Comparison

During the course of Web services interactions applications may receive multiple endpoint references describing the endpoints it needs to interact with. Different copies of an endpoint reference may also be received over time. </p> <p> The following rule clarifies the relation between the behaviors This specification provides no concept of deleted text: the endpoints represented by two endpoint references with the same [address]; </p> <ul> <li> <p> The two endpoints accept the same sets of messages, and follow and require the same set of policies. That is, the XML Schema, WSDL, and policy identity and other metadata applicable therefore does not provide any mechanism to the two references are the same. </p> </li> </ul> <p> However, the metadata embedded in each determine equality or inequality of deleted text: the EPRs MAY differ, as the metadata carried by an EPR is and does 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. </p> <p> To deal with conflicts between specify the embedded metadata consequences of two EPRs, or between embedded metadata and metadata obtained from a different source, their equality or to ascertain the current validity of embedded metadata, mechanisms inequality. However, note that are outside of the scope of this specification, such as EPR life cycle information [see <a href= "#eprlifecycle"> <b> 2.4 Endpoint Reference Lifecycle </b> </a> ] or retrieval of metadata from an authoritative source, SHOULD be used. </p> <p> The [address] properties of two endpoint references are compared according it is possible for other specifications to Section 6 of [ <cite> <a href="#RFC2396"> RFC 3986 </a> </cite> ]. </p> <p> Therefore, provide a consuming application should assume comparison function that different XML Schemas, WSDL definitions and policies apply to endpoint references whose addresses differ. 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 recogonised or understood.

<a name="_Toc77464323" id="_Toc77464323"> 3.1 XML Infoset Representation of Message Addressing Properties

Message addressing properties provide end-to-end characteristics of a message that can be easily secured as a unit. These properties are immutable and not intended to be modified along a message path.

The following describes the XML Infoset representation of message addressing properties:

<wsa:MessageID> xs:anyURI </wsa:MessageID>
<wsa:RelatesTo RelationshipType="..."?>xs:anyURI</wsa:RelatesTo>
<wsa:To>xs:anyURI</wsa:To>
<wsa:Action>xs:anyURI</wsa:Action>
<wsa:From>endpoint-reference</wsa:From>
<wsa:ReplyTo>endpoint-reference</wsa:ReplyTo>
<wsa:FaultTo>endpoint-reference</wsa:FaultTo>

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

/wsa:MessageID

This OPTIONAL element (of type xs:anyURI) conveys the [message id] property. This element MUST be present if wsa:ReplyTo or wsa:FaultTo is present.

/wsa:RelatesTo

This OPTIONAL (repeating) element information item contributes one abstract [relationship] property value, in the form of a (URI, URI) (IRI, IRI) pair. The [children] property of this element (which is of type xs:anyURI) conveys the [message id] of the related message. This element MUST be present if the message is a reply.

/wsa:RelatesTo/@RelationshipType

This OPTIONAL attribute (of type xs:anyURI) conveys the relationship type as a URI. an IRI. When absent, the implied value of this attribute is <code> http://www.w3.org/2005/02/addressing/reply </code>. "http://www.w3.org/2005/03/addressing/reply".

/wsa:ReplyTo

This OPTIONAL element (of type wsa:EndpointReferenceType) provides the value for the [reply endpoint] property. This element MUST be present if a reply is expected. If this element is present, wsa:MessageID MUST be present.

/wsa:From

This OPTIONAL element (of type wsa:EndpointReferenceType) provides the value for the [source endpoint] property.

/wsa:FaultTo

This OPTIONAL element (of type wsa:EndpointReferenceType) provides the value for the [fault endpoint] property. If this element is present, wsa:MessageID MUST be present.

/wsa:To

This OPTIONAL element (of type xs:anyURI) 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/2005/02/addressing/role/anonymous". "http://www.w3.org/2005/03/addressing/role/anonymous". Otherwise the [children] of this element convey the value of this property.

/wsa:Action

This REQUIRED element of type xs:anyURI conveys the [action] property. The [children] of this element convey the value of this property.

/[reference parameters]*

Each element information item of found in [reference parameters] (including all of its [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.

3.2 Formulating a Reply Message

The reply to a WS-Addressing compliant request message MUST be compliant to WS-Addressing and be is constructed according to the rules defined following rules:

1. Select the appropriate EPR:

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

   • Otherwise, if the reply is a fault message and the incoming 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 incoming message's [reply endpoint] message addressing property. Otherwise, if the [reply endpoint] property is empty, the behavior of the recipient of the incoming message is unconstrained by this specification.

2. Populate the reply message's message addressing properties:

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

   • [relationship]: a new pair of IRIs is added to this value as follows; the relationship type is the predefined reply IRI "http://www.w3.org/2005/03/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 section. property

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

The following example illustrates a request message using containing message information 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/2005/02/addressing">



  xmlns:wsa="http://www.w3.org/2005/03/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 S:mustUnderstand="1">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] The URI mailto:fabrikam@example.com [destination]: "mailto:fabrikam@example.com"

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

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

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

The following example illustrates a reply message using message information header blocks in a SOAP 1.2 to the above message:

<S:Envelope
  xmlns:S="http://www.w3.org/2003/05/soap-envelope" 


  xmlns:wsa="http://www.w3.org/2005/02/addressing">



  xmlns:wsa="http://www.w3.org/2005/03/addressing">


  <S:Header>
    <wsa:MessageID>
      http://example.com/someotheruniquestring
    </wsa:MessageID>
    <wsa:RelatesTo>
      http://example.com/someuniquestring
    </wsa:RelatesTo>
    <wsa:To S:mustUnderstand="1">
      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 [destination]: "http://example.com/business/client1"

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

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

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