1. Introduction
Web Services Addressing (WS-Addressing) defines two constructs,
message addressing properties and endpoint references, that
normalize the information typically provided by transport protocols
and messaging systems in a way that is independent of any
particular transport or messaging system.
A Web service endpoint is a (referenceable) entity, processor,
or resource to which Web service messages can be addressed.
Endpoint references convey the information needed to address a Web
service endpoint.
This specification defines a family of message addressing
properties that convey end-to-end message characteristics including
references for source and destination endpoints and message
identity that allows uniform addressing of messages independent of
the underlying transport.
Both of these constructs are designed to be extensible and
re-usable so that other specifications can build on and leverage
endpoint references and message information headers.
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:
Example
1-1. 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/02/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 information 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 URI
identifying expected semantics.
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/>).
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 ]).
Table 1-1. 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/02/addressing |
| xs |
http://www.w3.org/2001/XMLSchema |
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 are identified by
the XML namespace URI [XML
Namespaces] "http://www.w3.org/2005/02/addressing". A
normative XML Schema [XML Schema
Structures, XML Schema
Datatypes] document can be obtained by dereferencing the
XML namespace URI.
2. Endpoint
References
This section defines the information model and syntax of an
endpoint reference.
This specification introduces the endpoint reference, a
construct designed to support the following usage scenarios:
2.1 Information
Model for Endpoint References
An endpoint reference consists of the following abstract
properties:
- [address] : URI (mandatory)
-
An address URI for the endpoint. 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)
-
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[WS-Addressing-WSDL] for more details.
- [service endpoint] : (QName, NCName (0..1))
(0..1)
-
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[WS-Addressing-WSDL] for more details.
- [policies] : xsd:any (0..unbounded)
-
A reference may contain a number of policies that describe the
behavior, requirements and capabilities of the endpoint. Policies
may be included in an endpoint to facilitate easier processing by
the consuming application, or because the policy was dynamically
generated. However, embedded policies are not authoritative and may
be stale or incoherent with the policies associated with the
endpoint at the time when the interaction occurs.
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:
Example
2-1. Structure of the wsa:EndpointReference element.
<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>?
<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. This address may be a
logical address for the service endpoint.
-
/wsa:EndpointReference/wsa:ReferenceParameters/
-
This OPTIONAL element contains the elements that convey the
[reference parameters] of the reference.
-
/wsa:EndpointReference/wsa:ReferenceParameters/{any}
-
Each child element of ReferenceParameters represents an
individual [reference parameter].
- /wsa:EndpointReference/wsa:InterfaceName
-
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[WS-Addressing-WSDL] for more
details..
- /wsa:EndpointReference/wsa:ServiceName
-
This OPTIONAL element (of type xs:QName) specifies the value of
the [service endpoint] property, see Web Services Addressing 1.0 -
WSDL Binding[WS-Addressing-WSDL] for more
details..
-
/wsa:EndpointReference/wsa:ServiceName/@EndpointName
-
This OPTIONAL attribute (of type xs:NCName) specifies the name
of a particular endpoint, see Web Services Addressing 1.0 - WSDL
Binding[WS-Addressing-WSDL]
for more details.
- /wsa:EndpointReference/wsa:Policies
-
This OPTIONAL element contains policies that are relevant to the
interaction with the endpoint.
- /wsa:EndpointReference/wsa:Policies/{any}
-
Each child element of Policies represents an individual
[policy].
- /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. 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.
The following shows an example endpoint reference. This element
references the [selected interface] "fabrikam:Inventory" at the
endpoint URI "http://example.com/www.fabrikam/acct". Note the use
of the WSDL[WSDL 2.0]
wsdlLocation attribute.
Example
2-2. Example endpoint reference.
<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:Address>http://example.com/fabrikam/acct</wsa:Address>
<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.
The following rule clarifies the relation between the behaviors
of the endpoints represented by two endpoint references with the
same [address];
-
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 and other metadata applicable to the two
references are the same.
However, the metadata embedded in each of the EPRs MAY differ,
as the metadata carried by 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, 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.
The [address] properties of two endpoint references are compared
according to Section 6 of [RFC
3986].
Therefore, a consuming application should assume that different
XML Schemas, WSDL definitions and policies apply to endpoint
references whose addresses differ.
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.
3. Message
Addressing Properties
This section defines the information model and syntax of message
addressing properties.
Message addressing properties provide references for the
endpoints involved in an interaction. The use of these properties
to support specific interaction is in general defined by both the
semantics of the properties themselves and the implicit or explicit
contract that governs the message exchange. If explicitly
available, this contract can take different forms including but not
being limited to WSDL MEPs and interfaces; business processes and
e-commerce specifications, among others, can also be used to define
explicit contracts between the parties. The basic interaction
pattern from which all others are composed is "one way". In this
pattern a source sends a message to a destination without any
further definition of the interaction. "Request Reply" is a common
interaction pattern that consists of an initial message sent by a
source endpoint (the request) and a subsequent message sent from
the destination of the request back to the source (the reply). A
reply in this case can be either an application message, a fault,
or any other message. Note, however, that reply messages may be
sent as part of other message exchanges as well, and are not
restricted to the usual single Request, single Reply pattern, or to
a particular WSDL MEP. The contract between the interacting parties
may specify that multiple or even a variable number or replies be
delivered.
Message addressing properties collectively augment a message
with the following abstract properties to support one way, request
reply, and any other interaction pattern:
- [destination] : URI (mandatory)
-
The address of the intended receiver of this message.
- [source endpoint] : endpoint reference
(0..1)
-
Reference of the endpoint where the message originated from.
- [reply endpoint] : endpoint reference (0..1)
-
An endpoint reference for the intended receiver for replies to
this message. If a reply is expected, a message MUST contain a
[reply endpoint]. The sender MUST use the contents of the [reply
endpoint] to formulate the reply message as defined in 3.2 Formulating a Reply Message. If this
property is present, the [message id] property is REQUIRED.
- [fault endpoint] : endpoint reference (0..1)
-
An endpoint reference for the intended receiver for faults
related to this message. When formulating a fault message as
defined in 3.2 Formulating a Reply
Message, the sender MUST use the contents of the [fault
endpoint], when present, of the message being replied to to
formulate the fault message. If this property is present, the
[message id] property is REQUIRED.
- [action] : URI (mandatory)
-
An identifier that uniquely (and opaquely) identifies the
semantics implied by this message.
It is RECOMMENDED that value of the [action] property is a URI
identifying an input, output, or fault message within a WSDL 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. Finally, if in addition to
the [action] property, a SOAP Action URI is encoded in a request,
the URI of the SOAP Action MUST be the same as the one specified by
the [action] property.
- [message id] : URI (0..1)
-
A URI that uniquely identifies this message in time and space.
No two messages with a distinct application intent may share a
[message id] property. A message MAY be retransmitted for any
purpose including communications failure and MAY use the same
[message id] property. The value of this property is an opaque URI
whose interpretation beyond equivalence is not defined in this
specification. If a reply is expected, this property MUST be
present.
- [relationship] : (URI, URI) (0..unbounded)
-
A pair of values that indicate how this message relates to
another message. The type of the relationship is identified by a
URI. The related message is identified by a URI that corresponds to
the related message's [message id] property. The message identifier
URI may refer to a specific message, or be the following well-known
URI that means "unspecified message":
http://www.w3.org/2005/02/addressing/id/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/2005/02/addressing/reply |
Indicates that this is a reply to the
message identified by the URI. |
A reply message MUST contain a [relationship] property
consisting of the predefined reply URI and the message id property
of the request message.
The dispatching of incoming messages is based on two message
properties: the mandatory "destination" and "action" fields
indicate the target processing location and the verb or intent of
the message respectively.
Due to the range of network technologies currently in
wide-spread use (e.g., NAT, DHCP, firewalls), many deployments
cannot assign a meaningful global URI to a given endpoint. To allow
these "anonymous" endpoints to initiate message exchange patterns
and receive replies, WS-Addressing defines the following well-known
URI for use by endpoints that cannot have a stable, resolvable URI:
http://www.w3.org/2005/02/addressing/role/anonymous
Requests whose [reply endpoint], [source endpoint] and/or [fault
endpoint] use this address MUST provide some out-of-band mechanism
for delivering replies or faults (e.g. returning the reply on the
same transport connection). This mechanism may be a simple
request/reply transport protocol (e.g., HTTP GET or POST). This URI
MAY be used as the [destination] for reply messages and SHOULD NOT
be used as the [destination] in other circumstances.
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:
Example
3-1. 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) 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. When absent, the implied value of this
attribute is
http://www.w3.org/2005/02/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". 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.
3.2 Formulating a
Reply Message
The reply to a WS-Addressing compliant request message MUST be
compliant to WS-Addressing and be constructed according to the
rules defined in this section.
The following example illustrates a request message using
message information header blocks in a SOAP 1.2 message:
Example
3-2. Example request message.
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope"
xmlns:wsa="http://www.w3.org/2005/02/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
[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 message using message
information header blocks in a SOAP 1.2 message:
Example
3-3. Example response message.
<S:Envelope
xmlns:S="http://www.w3.org/2003/05/soap-envelope"
xmlns:wsa="http://www.w3.org/2005/02/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
[action] http://example.com/fabrikam/mail/DeleteAck
[message id] http://example.com/someotheruniquestring
[relationship] (wsa:Reply,
http://example.com/someuniquestring)