Web Services Addressing provides transport-neutral mechanisms to address Web services
and messages. Web Services Addressing Core (this document) defines a set of abstract
properties and an XML Infoset [] representation thereof to
identify Web service endpoints and to secure end-to-end identification of endpoints
in messages. This specification enables messaging systems to support message
transmission through networks that include processing nodes such as endpoint
managers, firewalls, and gateways in a transport-neutral manner.

This section describes the status of this document at the time
of its publication. Other documents may supersede this document. A
list of current W3C publications and the latest revision of this
technical report can be found in the W3C technical reports index at
http://www.w3.org/TR/.

This is the First
Public Working Draft of the Web Services Addressing - Core specification for review
by W3C members and other interested parties. It has been produced by
the Web Services
Addressing Working Group (WG), which is part of the W3C Web Services
Activity.

In this Working Draft, the Web Services Addressing Working Group
has, in keeping with its charter,
separated the WS-Addressing Member Submission into three separate
specifications: Core, SOAP Binding, and WSDL Binding. The Working
Group expects to publish an updated draft in the near future
incorporting more resolutions from its issues list.

Discussion of this document takes place on the public public public-ws-addressing@w3.org
mailing list (public
archive).
Comments on this specification should be sent to this mailing list.

This document was produced under the 5
February 2004 W3C Patent Policy. The Working Group maintains
a public
list of patent disclosures relevant to this document; that
page also includes instructions for disclosing [and excluding] a
patent. An individual who has actual knowledge of a patent which
the individual believes contains Essential Claim(s) with respect
to this specification should disclose the information in
accordance with section
6 of the W3C Patent Policy.

Per section
4 of the W3C Patent Policy, Working Group participants have
150 days from the title page date of this document to exclude
essential claims from the W3C RF licensing requirements with
respect to this document series. Exclusions are with respect to
the exclusion reference document, defined by the W3C Patent Policy
to be the latest version of a document in this series that is
published no later than 90 days after the title page date of this
document.

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.

The Web Services Addressing Working Group has decided to
use XML Schema, where appropriate, to describe constructs defined
in this specification. Note that this restricts use of Web
Services Addressing to XML 1.0.English

Last Modified: $Date: 2004/12/08 21:29:45 $

Introduction

Web Services Addressing (WS-Addressing) defines two constructs that convey
information that is typically provided by transport protocols and messaging systems:
endpoint references and message addressing properties. These constructs normalize
this underlying information into a uniform format that can be processed
independently of transport or application.

A Web service endpoint is a (referenceable) entity, processor, or resource to which
Web service messages can be targeted. Endpoint references convey the information
needed to identify/reference a Web service endpoint, and may be used in several
different ways:

To convey the information needed to access a Web service endpoint

To provide addresses for individual messages sent to and from Web services

To deal with this last usage case this specification defines a family of message
addressing properties that allows uniform addressing of messages independent of
underlying transport. These message addressing properties convey end-to-end message
characteristics including addressing for source and destination endpoints as well as
message identity.

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://business456.example/client1 to http://fabrikam123.example/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.

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 [].

When describing concrete XML schemas [, ], this specification uses the notational convention of
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/>).

Namespaces

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

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/2004/12/addressing

xs

http://www.w3.org/2001/XMLSchema

WS-Addressing may be used with SOAP [] as described
in Web Services Addressing - SOAP Binding[].
WS-Addressing may be used with WSDL [] described services
as described in Web Services Addressing - WSDL Binding[]. Examples in this specification use an XML 1.0 [] representation but this is not a requirement.

All information items defined by WS-Addressing are identified by the XML
namespace URI [] "http://www.w3.org/2004/12/addressing". A normative XML Schema
[, ] document can be
obtained by dereferencing the XML namespace URI.

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:

Dynamic generation and customization of service endpoint descriptions.

Identification 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.

Information Model for Endpoint References

An endpoint reference consists of the following abstract properties:

[address] : URI (mandatory)

An address URI that identifies the endpoint. This may be a network
address or a logical address.

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

A reference may contain a number of individual properties that are
required to identify the entity or resource being conveyed.
Reference identification properties are element information items
that are named by QName and are required to properly dispatch
messages at the endpoint. Reference properties are provided by the
issuer of the endpoint reference and are otherwise assumed to be
opaque to consuming applications. The interpretation of these
properties (as the use of the endpoint reference in general) is
dependent upon the protocol binding and data encoding used to
interact with the endpoint. Web Services Addressing - SOAP
Binding[] defines the default binding
for the SOAP protocol. Consuming applications SHOULD assume that
endpoints represented by endpoint references with different
[reference properties] may accept different sets of messages or
follow a different set of policies, and consequently may have
different associated metadata (WSDL, XML Schema, and policies ). The
relationship between reference properties and endpoint policies is
further explained in

[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 - SOAP Binding[] describes the default binding for the SOAP
protocol. Unlike [reference properties], the [reference parameters]
of two endpoint references may differ without an implication that
different XML Schema, WSDL or policies apply to the endpoints.

[selected port type] : QName (0..1)

The QName of the primary portType of the endpoint being conveyed, see
Web Services Addressing - WSDL Binding
for more details.

[service-port] : (QName, NCName (0..1)) (0..1)

The QName identifying the WSDL service element that contains the
definition of the endpoint being conveyed, see Web Services
Addressing - WSDL Binding 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.

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:

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 or identifier for the service endpoint.

/wsa:EndpointReference/wsa:ReferenceProperties/

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

/wsa:EndpointReference/wsa:ReferenceProperties/{any}

Each child element of ReferenceProperties represents an individual
[reference property].

/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:PortType

This OPTIONAL element (of type xs:Qname) specifies the value of the
[selected port type] property of the endpoint reference, see Web
Services Addressing - WSDL Binding for
more details..

/wsa:EndpointReference/wsa:ServiceName

This OPTIONAL element (of type xs:QName) specifies the
<wsdl:service> definition that contains a WSDL
description of the endpoint being referenced, see Web Services
Addressing - WSDL Binding for more details..

/wsa:EndpointReference/wsa:ServiceName/@PortName

This OPTIONAL attribute (of type xs:NCName) specifies the name of the
<wsdl:port> definition that corresponds to the
endpoint being referenced, see Web Services Addressing - WSDL
Binding 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.

The following shows an example endpoint reference. This element references the
port of type "fabrikam:InventoryPortType" at the URI "http://www.fabrikam123.example/acct".

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 rules clarify the relation between the behaviors of the endpoints
represented by two endpoint references with the same [address] and the same
[reference properties].

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 metadata applicable to the two references are the same.

In particular, the policies applicable to the two endpoints are the same
regardless of the values of any embedded [policies]. Embedded policies
are not authoritative and may be stale or incoherent with the policies
associated with the endpoint.

The [address] properties of two endpoint references are compared according to
Section 6 of []. The [reference properties] of two
endpoint references are equal if:

they contain the same number of individual properties;

for each reference property in one endpoint reference there exists an
equivalent reference property in the other. One [reference property] is
equivalent to another [reference property] if their byte streams per
Exclusive XML Canonicalization are equal.

This section defines the information model and syntax of message addressing properties.

Message addressing properties enable the identification and location of the endpoints
involved in an interaction. 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 can be either an application message, a fault, or
any other message.

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 that identifies 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 .
If the [reply endpoint] is absent, the contents of the [source endpoint]
may be used to formulate a message to the source. This property MAY be
absent if the message has no meaningful reply. If this property is
present, the [message id] property is REQUIRED.

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

An endpoint reference that identifies the intended receiver for faults
related to this message. When formulating a fault message as defined in
, the sender MUST use the contents of
the [fault endpoint] of the message being replied to to formulate the
fault message. If the [fault endpoint] is absent, the sender MAY use the
contents of the [reply endpoint] to formulate the fault message. If both
the [fault endpoint] and [reply endpoint] are absent, the sender MAY use
the contents of the [source endpoint] to formulate the fault message.
This property may be absent if the sender cannot receive fault messages
(e.g., is a one-way application 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 - WSDL
Binding 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] : (QName, 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 QName. 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/2004/12/addressing

This specification has one predefined relationship type as shown in
.

Description of the QName used in [relationship]

QName

Description

wsa:Reply

Indicates that this is a reply to the message identified by
the URI.

A reply message MUST contain a [relationship] property consisting of
wsa:Reply 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 identify the target processing location
and the verb or intent of the message.

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/2004/12/addressing

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.

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:

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,
QName) 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:QName) conveys the relationship
type as a QName. When absent, the implied value of this attribute is wsa: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.