Web Services Addressing provides transport-neutral mechanisms to address Web services
and messages. Web Services Addressing 1.0 - Core (this document) defines a set of abstract
properties and an XML Infoset [
This is the second
This Working Draft reflects the current position of the Working
Group. A
Discussion of this document takes place on the
This document was produced under the
Per
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
Last Modified: $Date: 2005/02/15 20:10:04 $
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:
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.
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 the 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/02/addressing |
| xs | http://www.w3.org/2001/XMLSchema |
WS-Addressing may be used with SOAP [
All information items defined by WS-Addressing are identified by the XML
namespace URI [
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:
Dynamic generation and customization of service endpoint descriptions.
Referencing and description of specific service instances that are created as the result of stateful interactions.
Flexible and dynamic exchange of endpoint information in tightly coupled environments where communicating parties share a set of common assumptions about specific policies or protocols that are used during the interaction.
An endpoint reference consists of the following abstract properties:
An address URI for the endpoint. This may be a network address or a logical address.
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[
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[
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[
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.
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:
The following describes the attributes and elements listed in the schema overview above:
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.
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.
This OPTIONAL element contains the elements that convey the [reference parameters] of the reference.
Each child element of ReferenceParameters represents an individual [reference parameter].
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[
This OPTIONAL element (of type xs:QName) specifies the value of the
[service endpoint] property, see Web Services Addressing 1.0 - WSDL Binding[
This OPTIONAL attribute (of type xs:NCName) specifies the name of a
particular endpoint, see Web Services Addressing 1.0 - WSDL Binding[
This OPTIONAL element contains policies that are relevant to the interaction with the endpoint.
Each child element of Policies represents an individual [policy].
This is an extensibility mechanism to allow additional elements to be specified.
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[
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[
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
The [address] properties of two endpoint references are compared according to
Section 6 of [
Therefore, a consuming application should assume that different XML Schemas, WSDL definitions and policies apply to endpoint references whose addresses differ.
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.
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:
The address of the intended receiver of this message.
Reference of the endpoint where the message originated from.
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
An endpoint reference for the intended receiver for faults
related to this message. When formulating a fault message as defined in
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[
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.
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
| 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.
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:
The following describes the attributes and elements listed in the schema overview above:
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.
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.
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.
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.
This OPTIONAL element (of type wsa:EndpointReferenceType) provides the value for the [source endpoint] property.
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.
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
This REQUIRED element of type xs:anyURI conveys the [action] property. The [children] of this element convey the value of this property.
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:
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:
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)
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), Rebecca Bergersen (IONA Technologies, Inc.), Andreas Bjärlestam (ERICSSON), Ugo Corda (SeeBeyond Technology Corporation), Francisco Curbera (IBM Corporation), Glen Daniels (Sonic Software), Paul Downey (BT), Jacques Durand (Fujitsu Limited), Michael Eder (Nokia), Robert Freund (Hitachi, Ltd.), Yaron Goland (BEA Systems, Inc.), Martin Gudgin (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), Anish Karmarkar (Oracle Corporation), Paul Knight (Nortel Networks), Philippe Le Hégaret (W3C/MIT), Mark Little (Arjuna Technologies Ltd.), Jonathan Marsh (Microsoft Corporation), Jeff Mischkinsky (Oracle Corporation), Nilo Mitra (ERICSSON), Eisaku Nishiyama (Hitachi, Ltd.), Mark Nottingham (BEA Systems, Inc.), Ales Novy (Systinet Inc.), David Orchard (BEA Systems, Inc.), Mark Peel (Novell, Inc.), Harris Reynolds (webMethods, Inc.), Tony Rogers (Computer Associates), Tom Rutt (Fujitsu Limited), Rich Salz (DataPower Technology, Inc.), Davanum Srinivas (Computer Associates), Jiri Tejkl (Systinet Inc.), Greg Truty (IBM Corporation), Steve Vinoski (IONA Technologies, Inc.), Pete Wenzel (SeeBeyond Technology Corporation), Steve Winkler (SAP AG), Ümit Yalçınalp (SAP AG).
Previous members of the Working Group were: @@@.
The people who have contributed to
Placeholder for auto change log generation.
Placeholder for auto change log generation.