Web Services Referral Protocol (WS-Referral)

Article
10/08/2007

October 23, 2001

Authors

Henrik Frystyk Nielsen
Erik Christensen
Steve Lucco
David Levin

Copyright Notice

The presentation, distribution or other dissemination of the information contained herein by Microsoft is not a license, either expressly or impliedly, to any intellectual property owned or controlled by Microsoft.

This document and the information contained herein is provided on an "AS IS" basis and to the maximum extent permitted by applicable law, Microsoft provides the document AS IS AND WITH ALL FAULTS, and hereby disclaims all other warranties and conditions, either express, implied or statutory, including, but not limited to, any (if any) implied warranties, duties or conditions of merchantability, of fitness for a particular purpose, of accuracy or completeness of responses, of results, of workmanlike effort, of lack of viruses, and of lack of negligence, all with regard to the document. ALSO, THERE IS NO WARRANTY OR CONDITION OF TITLE, QUIET ENJOYMENT, QUIET POSSESSION, CORRESPONDENCE TO DESCRIPTION OR NON-INFRINGEMENT WITH REGARD TO THE DOCUMENT.

IN NO EVENT WILL MICROSOFT BE LIABLE TO ANY OTHER PARTY FOR THE COST OF PROCURING SUBSTITUTE GOODS OR SERVICES, LOST PROFITS, LOSS OF USE, LOSS OF DATA, OR ANY INCIDENTAL, CONSEQUENTIAL, DIRECT, INDIRECT, OR SPECIAL DAMAGES WHETHER UNDER CONTRACT, TORT, WARRANTY, OR OTHERWISE, ARISING IN ANY WAY OUT OF THIS OR ANY OTHER AGREEMENT RELATING TO THIS DOCUMENT, WHETHER OR NOT SUCH PARTY HAD ADVANCE NOTICE OF THE POSSIBILITY OF SUCH DAMAGES.

Abstract

Web Services Referral Protocol (WS-Referral) is a SOAP-based, stateless protocol for inserting, deleting, and querying routing entries in a SOAP router. A SOAP router is a SOAP node that exposes SOAP message relaying as a Web service, either as a standalone service or in combination with other services. An example of a SOAP router is a SOAP node supporting the Web Services Routing Protocol (WS-Routing). In addition to mechanisms for inserting, deleting, and querying routing entries, WS-Referral defines an XML-based structure called a WS-Referral statement for describing a routing entry along with a set of conditions under which the statement is satisfied.

Composable Architecture

By using the SOAP extensibility model, SOAP-based specifications are designed to be composed with each other to provide a rich messaging environment. As such, WS-Referral does not itself provide for services such as message security, path description, or service discovery. These features are provided by other Web service specifications.

Status

WS-Referral and related specifications are provided as-is and for review and evaluation only. Microsoft hopes to solicit your contributions and suggestions in the near future. Microsoft Corporation makes no warrantees or representations regarding the specifications in any manner whatsoever.

1. Introduction
    1.1 Goal
2. Notational Conventions
    2.1 Compliance
3. The Web Service Referral Model
    3.1 Relationship Between SOAP, WS-Routing, and WS-Referral
    3.2 WS-Referral Terminology
    3.3 WS-Referral Statement Model
    3.4 WS-Referral Exchange Model
    3.5 Caching WS-Referral Statements
    3.6 Meta-Structures for WS-Referral Statements
4. The WS-Referral Mechanisms
    4.1 The WS-Referral Statement
        4.1.1 Endpoints
        4.1.2 Conditions
        4.1.3 Identifying a Statement
        4.1.4 Descriptive Information
    4.2 Interpreting a WS-Referral Statement
        4.2.1 Insertion of a SOAP Router Before Another Node
        4.2.2 Insertion of a SOAP Router After Another Node
        4.2.3 Removal of a SOAP Router Located Before Another Node
    4.3 WS-Referral Query Message Exchange
    4.4 WS-Referral Registration Message Exchange
    4.5 WS-Referral Header
5. The WS-Referral Specifications
    5.1 WS-Referral Statement Elements
       5.1.1 desc
       5.1.2 exact
       5.1.3 for
       5.1.4 go
       5.1.5 if
       5.1.6 invalidates
       5.1.7 prefix
       5.1.8 refAddr
       5.1.9 refId
       5.1.10 rid
       5.1.11 ttl
    5.2 WS-Referral Query
       5.2.1 WS-Referral Query Request
       5.2.2 WS-Referral Query Response
    5.3 WS-Referral Registration
       5.3.1 WS-Referral Registration Request
       5.3.2 WS-Referral Registration Response
    5.4 WS-Referral Header Elements
    5.5 Use of URIs in WS-Referral
6. Security Considerations
7. References
Appendix A. Sample WS-Routing Messages

1. Introduction

Web Services Referral Protocol(WS-Referral) is a SOAP-based [10][11], stateless protocol for inserting, deleting, and querying routing entries in a SOAP router. A SOAP router is a SOAP node that exposes SOAP message relaying as a Web service, either as a standalone service or in combination with other services.

SOAP [10][11] introduces a distributed processing model based on the concept of SOAP actors enabling a sender to indicate which parts of a message are intended for each SOAP actor along a virtual message path (see [11], Part 1 section 2.2 for a definition of SOAP actor). When processing a SOAP message, a SOAP node is said to act in the role of one or more SOAP actors, each of which is identified by a URI known as the SOAP actor name. The purpose of a SOAP actor name is to identify a SOAP node as a resource [3] on the Web.

SOAP does not, however, define any Web service routing or message exchange semantics describing an actual message path for a SOAP message. Given four SOAP nodes, A, B, C, and D, for example, a SOAP message generated by A can indicate which parts of the message are, respectively, for B, C and D. However, SOAP cannot indicate that the message is to be sent to D via B and C as intermediaries.

The Web Services Routing Protocol (WS-Routing) [12] has been designed to describe the actual message path for a given SOAP message. WS-Routing enables sending a one-way SOAP message from an initial sender to the ultimate receiver, potentially via a set of intermediaries. In addition, WS-Routing provides an optional reverse message path enabling two-way message exchange patterns like request/response, peer-to-peer conversations, and returning message acknowledgements and faults.

WS-Routing is entirely described within the SOAP envelope enabling any SOAP receiver to expose SOAP message relaying as a Web service, either in its own right or in combination with other services. However, while WS-Routing can describe a SOAP message path, it does not provide a mechanism for configuring which SOAP routers may belong to a message path. In the example above, WS-Routing does not provide a mechanism for configuring A, B, C, and D to have necessary and sufficient information about each other (see section 3).

1.1 Goal

The goal of WS-Referral is to provide the mechanisms needed to enable SOAP applications to insert, delete, and query routing entries in a SOAP router through the exchange of referral information. Specifically, this specification defines the following:

An XML-based structure called a WS-Referral statement describing referral information (see section 4.1 and 4.2)
A mechanism for querying a SOAP router for WS-Referral statements (see section 4.3)
A mechanism for registering, either inserting or deleting, a WS-Referral statement at a SOAP router (see section 4.4)
A mechanism for encapsulating WS-Referral statements as a SOAP header block (see section 4.5)

Additional mechanisms have not been added by design to preserve the simplicity and broad applicability of the lightweight approach characteristic of SOAP.

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

WS-Referral is completely XML-based [5]; all elements and structures defined by WS-Referral are associated with the XML namespace URI [6] "https://schemas.xmlsoap.org/ws/2001/10/referral" and are defined by XML schema [8][9]. The WS-Referral schema can be obtained by dereferencing the WS-Referral XML Namespace URI above.

WS-Referral uses XML Namespaces [6] throughout. The term "fully qualified name" is used to denote a QName associated with its corresponding XML namespace URI.

2.1 Compliance

An implementation is not WS-Referral compliant if it fails to satisfy one or more of the MUST or REQUIRED level requirements defined in this specification.

A SOAP receiver MUST comply with this specification in order to process a WS-Referral message or a WS-Referral header successfully. A SOAP sender MUST NOT use the "https://schemas.xmlsoap.org/ws/2001/10/referral" XML Namespace identifier [6] unless it is WS-Referral compliant.

3. The Web Service Referral Model

This section describes the WS-Referral model and how it relates to WS-Routing and to SOAP itself.

3.1 Relationship Between SOAP, WS-Routing, and WS-Referral

SOAP [10][11] defines a stateless, one-way message model defined in terms of SOAP senders and SOAP receivers that can send and receive SOAP messages respectively. In addition, SOAP has the notion of intermediaries that can act as both senders and receivers. Intermediaries enable distributed processing in which services can be composed across SOAP nodes. Examples of services provided by intermediaries range from value-add services to boundaries between different trust domains and protocol environments.

SOAP does not define a mechanism for indicating the SOAP senders and receivers along the SOAP message path or the order in which the senders and receivers are composed. While certain message paths can be described using services provided by an underlying protocol to which SOAP can be bound, WS-Routing provides a generic SOAP-based mechanism for describing the entire message path from an initial sender, through zero or more intermediaries to the ultimate receiver.

WS-Routing allows for SOAP routers to be inserted statically or dynamically into the message path. But there is no requirement that the complete message path be known when a message leaves the initial SOAP sender. Nor is it a requirement that all parties in the message path know about the complete message path. Rather, it is necessary and sufficient that:

The initial sender knows about the intended receiver and the SOAP router next to itself in the message path. The term "intended receiver" is used throughout this specification to indicate the SOAP actor specified by the initial sender as the ultimate destination of the message within a message path. That is, the intended receiver is the ultimate receiver as seen from the initial sender.
An intermediary knows the next SOAP router in the message path.
The intended receiver of the message knows that it is the intended receiver and that it should act in the role of the anonymous SOAP actor.

The behavior of a SOAP router often depends on its knowledge of other SOAP routers that could belong to a message path for a given message. While WS-Routing does not provide a mechanism for inserting, deleting, or otherwise manipulating routing entries in a SOAP router, this is the purpose of WS-Referral.

WS-Referral builds on a simple model of a SOAP router being able to delegate a URI space or a part thereof to another SOAP router by manipulating its routing entries. By changing its configuration, a SOAP router can learn about other SOAP routers and as a result affect the message path of any given SOAP message passing through it. By controlling the amount of information that a given SOAP router has, it is possible to build a variety of routing configurations that can support scenarios including but not limited to:

Enabling SOAP routers to learn about firewalls and other intermediaries
Allowing progressive discovery of resources that are not directly identified by a globally unique URI
Support load-balancing and outsourcing of URI spaces

WS-Referral does not formally distinguish between authoritative and non-authoritative delegation. WS-Referral separates the problem of describing and exchanging WS-Referral statements from the issue of determining whether such statements are trustworthy or not. While it is expected that many uses of WS-Referral will involve digital signing and authentication provided by common SOAP-based security mechanisms, such trust mechanisms are not provided by this specification.

Note, that despite the references to WS-Routing, WS-Routing and WS-Referral are designed to provide orthogonal services allowing WS-Referral to be used with other message path models if so desired. Similarly, WS-Routing can be used with configuration mechanisms other than WS-Referral.

3.2 WS-Referral Terminology

This specification defines the following set of terms, which are used throughout this document:

WS-Referral statement
A WS-Referral statement is the basic structure for describing delegation information. A WS-Referral statement is a document structure with no direct action or operations associated. Such actions are defined by WS-Referral requests.
WS-Referral request
WS-Referral defines a set of actions such as register and query operations that can be performed on WS-Referral statements. Each of these actions, known as a WS-Referral request, is expressed as a SOAP body block within a SOAP message.
WS-Referral response
A WS-Referral request may result in a WS-Referral response which indicates the result of the request. If a response is positive then the response data is expressed as a SOAP body block within a SOAP message. If a response is a fault, it is expressed as part of a SOAP Fault.
WS-Referral message
A SOAP message containing either a WS-Referral request or a WS-Referral response.
WS-Referral query
A WS-Referral query is a WS-Referral request that is used to request one or more WS-Referral statements
WS-Referral query response
A WS-Referral query response is a WS-Referral response that contains the result of a WS-Referral query
WS-Referral registration
A WS-Referral registration is a WS-Referral request that is used to request that a WS-Referral statement is inserted or deleted by a SOAP router
WS-Referral registration response
A WS-Referral registration response is a WS-Referral response that contains the result of a WS-Referral registration
WS-Referral header
A SOAP header block containing one or more WS-Referral statements

3.3 Referral Statement Model

A WS-Referral statement is the basic structure for describing a delegation that can be exchanged between SOAP routers. WS-Referral statements are built around a simple, extensible structure allowing for an open-ended set of constraints that can be added through extension. Each statement contains five parts

A set of SOAP actors for which a statement is intended
A set of conditions that have to be met for a statement to be satisfied
Descriptive information about the statement, the sender of the statement, the intended receiver of the statement, or a combination thereof
A WS-Referral statement identifier
A set of SOAP routers that a statement is referring to as part of the delegation

A SOAP actor is said to match a WS-Referral statement if the SOAP actor name matches any of the SOAP actors for which this statement is intended according to the URI matching rules described in section 5.5.

WS-Referral conditions are structured elements that can be used to indicate rules and constraints for how to interpret a WS-Referral statement. A WS-Referral statement is said to be satisfied if all conditions are fulfilled. A condition is said to be fulfilled if the condition is met in a manner that is fully conformant with the semantics conveyed by that condition.

While WS-Referral statements can be exchanged in a number of ways (see section 4) a WS-Referral statement has to be accepted by a SOAP router in order to be actively used. A satisfied WS-Referral statement is said to be accepted by a SOAP router if that router either implicitly or explicitly has indicated that it is willing to use the statement. While it is expected that many cases of accepting WS-Referral statements will involve digital signing and authentication provided by common SOAP-based security mechanisms, such trust mechanisms are out of scope of this specification.

In addition to conditions, a WS-Referral statement can contain descriptive information called an information entry. An information entry is a structured element that does not affect the evaluation of whether a statement is satisfied but can contain additional information about the sender of the statement, the receiver, the statement itself, or a combination thereof.

While each WS-Referral statement can be interpreted independently, statements are often related to other statements as part of caching schemes or other meta-structures (see section 3.5 and 3.6). In order to facilitate such meta-structures, each WS-Referral statement contains an identifier that enables SOAP routers to refer to a specific representation or instance of a WS-Referral statement. When a WS-Referral statement is modified, the identifier changes as well.

Finally, a WS-Referral statement indicates the set of SOAP routers referred to by that statement. The semantics of the referred SOAP routers is that if a SOAP message with a given message path indicated using the Web Services Routing Protocol for example, contains a SOAP actor that matches a satisfied and accepted WS-Referral statement, then the SOAP router can reconfigure that message path to go via one of the referred SOAP routers (see section 4.2).

3.4 WS-Referral Exchange Model

WS-Referral defines two modes of operation for exchanging WS-Referral statements: The first is based on a request/response style exchange of WS-Referral messages where a SOAP router sends a WS-Referral request to another SOAP router which replies with a WS-Referral response. This mode of operation is used for actions that require active participation by the receiver such as querying WS-Referral statements (see section 4.3) or explicitly delegating URI spaces described by WS-Referral statements (see section 4.4).

This specification does not define any message correlation mechanism for correlating WS-Referral requests with WS-Referral responses. Such correlation is expected to be provided by either the underlying protocol to which SOAP is bound or by a SOAP-based mechanism as defined by the Web Services Routing Protocol, for example.

The second mode of operation is a one-way style exchange of WS-Referral statements which the receiver may or may not be interested in. Such statements SHOULD be carried within a WS-Referral header (see section 4.5). This mode of operation can be used to propagate cached information and provide routing configuration hints among participating SOAP routers.

Regardless of how WS-Referral statements are exchanged, they follow the same model described in section 3.3.

3.5 Caching WS-Referral Statements

It is anticipated that many WS-Referral statements are going to be quasi-static in nature which allows for the use of caches to optimize performance and minimize the overall impact on the network. WS-Referral does not provide a comprehensive caching model although it does provide a simple model based on the following concepts:

A time-to-live period which can be associated with a WS-Referral statement
An explicit invalidation mechanism that can be used to render already cached WS-Referral statements invalid

While outside the scope of this specification, emphasis has been put on not prohibiting other or supplementary caching strategies from being defined for WS-Referral statements in the future.

3.6 Meta-Structures for WS-Referral Statements

WS-Referral does not define any meta-structures that could be applied to describe sets of WS-Referral statements. Such meta-structures could for example be used to categorize and group statements in order to perform efficient replication or mirroring, or to make assertions about groups of WS-Referral statements in general. While it is not a goal for this specification to specify any meta-structures, it is anticipated that it is possible to build such structures in an independent and orthogonal manner.

4. The WS-Referral Mechanisms

This section introduces the structure of a WS-Referral statement and the mechanisms used for exchanging such statements in SOAP.

4.1 The WS-Referral Statement

The model behind a WS-Referral statement is described in section 3.3. In this section we describe the mechanisms used in a WS-Referral statement.

4.1.1 Endpoints

WS-Referral defines the following elements for describing the endpoints contained in a WS-Referral statement:

for
Identifies the set of SOAP actors for which the referral statement is intended, so that it is possible to determine whether a given SOAP actor matches a statement (see section 3.3 and 5.1.3)
go
Identifies the set of SOAP routers that a SOAP message with a message path that matches a satisfied and accepted WS-Referral statement is referred to (see section 3.3 and 5.1.4).

4.1.2 Conditions

WS-Referral provides an open-ended mechanism for describing the conditions under which a WS-Referral statement is satisfied:

if
Contains the set of conditions expressed as structured elements that must be fulfilled in order for a WS-Referral statement to be satisfied (see section 3.3 and 5.1.5)

This specification defines two basic conditions—other conditions are expected to be defined through extension:

ttl
The "ttl" condition provides a simple mechanism to indicate the time-to-live of a WS-Referral statement after which the statement is no longer satisfied (see section 3.5 and 5.1.11)
invalidates
The "invalidates" condition can be used to indicate one or more WS-Referral statements that this statement invalidates (see section 3.5 and 5.1.6)

4.1.3 Identifying a Statement

Unique identification of a specific representation of a WS-Referral statement is important in order to enable mechanisms for creating caching models, distribution schemes, and other items. Identification of a representation of a WS-Referral statement is not intended as a cryptographic hash; rather it is intended as a mechanism for a SOAP router to be able to refer to WS-Referral statements. WS-Referral defines the following element for identifying a representation of a WS-Referral statement:

refId
The value of the "refId" element is a unique identifier in the form of a URI that identifies THIS representation of a WS-Referral statement (see section 5.1.9)

4.1.4 Descriptive Information

It is anticipated that many statements will be associated with information about the statements themselves, the sending party, or the receiver of the statement. While such information is not essential in order to evaluate whether a statement is satisfied, it may aid the receiver of a statement in handling that statement. WS-Referral defines a mechanism for incorporating such information directly into a statement using the following element:

desc
Contains any descriptive information that may be used by the receiver if appropriate. Descriptive information does not have an impact on whether a WS-Referral statement is satisfied or not (see section 3.3 and 5.1.1)

This specification defines one piece of descriptive information—other pieces are expected to be defined through extension:

refAddr
Contains the address of the referral statement from which a representation of the statement may be obtained using an HTTP GET request, for example (see section 5.1.8)

4.2 Interpreting a WS-Referral Statement

The structure of a WS-Referral statement which is based on the model defined in section 3.3 can loosely be described as a "for ... if ... then go via ..." language construct as follows:

for any SOAP actor name matching the
  set of SOAP actors listed in the
  for element

if the set of conditions listed in the
  if element is met and hence the
  statement is satisfied

then go via one of the SOAP routers
  listed in the go element

An example of a WS-Referral statement is illustrated in Example 1:

Example 1 Sample WS-Referral statement

<r:ref xmlns:r="https://schemas.xmlsoap.org/ws/2001/10/referral">
  <r:for>
    <r:exact>soap://example.org/some.doc</r:exact>
    <r:prefix>soap://example.org/topics/icebergs</r:prefix>
  </r:for>
  <r:if>
    <r:ttl>43200000</r:ttl>
  </r:if>
  <r:go>
    <r:via>soap://example.com/mirror</r:via>
  </r:go>
  <r:refId>uuid:09233523-345b-4351-b623-5dsf35sgs5d6</r:refId>
  <r:desc>
    <r:refAddr>https://example.com/references/2001/10/1234.xml</r:refAddr>
  </r:desc>
</r:ref>

A verbal description of the interpretation of the WS-Referral statement in Example 1 is as follows:

For any SOAP actor name matching the SOAP actor "soap://example.org/some.doc" or SOAP actors starting with "soap://example.org/topics/icebergs", if this referral is less than 12 hours (43,200,000 milliseconds) old then go via "soap://example.com/mirror".

In the remainder of this section, the effect of accepting WS-Referral statements on SOAP router configurations is illustrated through a set of scenarios. The scenarios illustrate three common operations for configuring SOAP routers:

Insertion of a SOAP router before another router
Insertion of a SOAP router after another router
Removal of a SOAP router

The scenarios are based on a simple configuration of two SOAP routers named A and B organized into the message path illustrated in Figure 1. As WS-Referral statements can be applied iteratively, it is possible to repeat the configuration operations if appropriate.

Figure 1 Sample message path used for illustrating insertion and removal of SOAP routers through the exchange of WS-Referral statements

The scenarios illustrate how WS-Referral statements are interpreted, not how they may be exchanged between SOAP routers. Sections 4.3, 4.4, and 4.5 describe various mechanisms for exchanging WS-Referral statements.

4.2.1 Insertion of a SOAP Node Before Another Node

In this scenario, SOAP router A accepts the WS-Referral statement shown in Example 2 introducing C in the message path configuration for messages from A to go via when communicating with B. This type of delegation can be used in cases where an intermediary is needed in order to facilitate communications between two SOAP routers.

Example 2 Sample WS-Referral statement interpreted by A

<r:ref xmlns:r="https://schemas.xmlsoap.org/ws/2001/10/referral">
  <r:for>
    <r:prefix>soap://b.org</r:prefix>
  </r:for>
  <r:if/>
  <r:go>
    <r:via>soap://c.org</r:via>
  </r:go>
  <r:refId>mid:1234@some.host.org</r:refId>
</r:ref>

As a result of the accepted WS-Referral statement, the next time SOAP router A sends a message to B, it sends the message to B via C as illustrated in Figure 2.

Figure 2 Example of A sending a message to B via C

The intended destination of the message is still B although the message path has been augmented by the insertion of C between A and B. (See Appendix A for examples of how this is reflected in the WS-Routing message path.)

4.2.2 Insertion of a SOAP Node After Another Node

In this scenario, SOAP router B accepts the WS-Referral statement shown in Example 3 showing that C is delegated a part of B's URI space so that messages intended for B are forwarded to C. While in section 4.2.1, C was inserted before B, C is now inserted after B. This type of delegation can be used to facilitate progressive discovery where A may not know that B has delegated a part of its URI space to C. Note, that this WS-Referral statement is interpreted using the exact same rules described above regardless that B is itself participating in the delegation.

Example 3 Sample WS-Referral statement interpreted by B

<r:ref xmlns:r="https://schemas.xmlsoap.org/ws/2001/10/referral">
  <r:for>
    <r:prefix>soap://b.org/some/part</r:prefix>
  </r:for>
  <r:if/>
  <r:go>
    <r:via>soap://c.org/my/application</r:via>
  </r:go>
  <r:refId>mid:2345@some.host.org</r:refId>
</r:ref>

If SOAP router B accepts the WS-Referral statement, the next time it receives a message intended for a SOAP actor matching the WS-Referral statement, it forwards that message to C as illustrated in Figure 3. The intended destination of the message is still the SOAP actor name "soap://b.org/some/part" although the message path has been augmented by the insertion of C. (See Appendix A for examples of how this is reflected in the WS-Routing message path.)

Figure 3 Example of A sending a message to B which forwards the message to C

4.2.3 Removal of a SOAP router

This scenario shows an example of how a WS-Referral statement can be used to invalidate another WS-Referral statement which can be used to shorten a message path configuration by removing a SOAP router. SOAP router B interprets the WS-Referral statement shown in Example 4 showing that C no longer is delegated a part of B's URI space and that the previous WS-Referral statement is invalidated.

Example 4 Sample WS-Referral statement intended to invalidate the WS-Referral statement shown in Example 3

<r:ref xmlns:r="https://schemas.xmlsoap.org/ws/2001/10/referral">
  <r:for>
    <r:prefix>soap://b.org/some/part</r:prefix>
  </r:for>
  <r:if>
    <r:invalidates>
      <r:rid>mid:2345@some.host.org</r:rid>
    </r:invalidates>
  </r:if>
  <r:go/>
  <r:refId>mid:3456@some.host.org</r:refId>
</r:ref>

4.3 WS-Referral Query Message Exchange

A SOAP router can explicitly request one or more WS-Referral statements from another SOAP router by sending a WS-Referral query. This can for example be used to request new or to update inadequate routing information in order to reach a given SOAP router in a message path. The result of a WS-Referral query is returned to the sender in form of a WS-Referral query response as illustrated in Figure 4.

Figure 4 Time diagram of a WS-Referral query message exchange

In the general case, a WS-Referral query is a query over a virtual, distributed database of referral information based on an open-ended set of query parameters. While this specification only defines a simple form of querying based on the set of URIs for which referral information is requested, it is anticipated that a WS-Referral query can be extended to support actual query semantics through extension.

4.3.1 WS-Referral Query

A WS-Referral query defines the following elements (see section 5.2.1):

query
The fully qualified name of the "query" element in a SOAP body identifies that message as a WS-Referral query
for
Identifies the set of SOAP actors for which referral information is requested

Example 5 Sample WS-Referral query sent from A to B

<S:Envelope xmlns:S="https://www.w3.org/2001/09/soap-envelope">
  <S:Header>
    <m:path xmlns:m="https://schemas.xmlsoap.org/rp/">
      <m:action>https://schemas.xmlsoap.org/ws/2001/10/referral#query</m:action>
      <m:to>soap://b.org</m:to>
      <m:rev>
        <m:via/>
      </m:rev>
      <m:id>mid:1000@a.org</m:id>
    </m:path>
  </S:Header>
  <S:Body>
    <r:query xmlns:r="https://schemas.xmlsoap.org/ws/2001/10/referral">
      <r:for>
        <r:prefix>soap://example.org/topics/icebergs</r:prefix>
      </r:for>
    </r:query>
  </S:Body>
</S:Envelope>

4.3.2 WS-Referral Query Response

The result of a WS-Referral query is returned in a WS-Referral query response in the form of WS-Referral statements that matches the query (if any). A WS-Referral query response defines the following elements (see section 5.2.2):

queryResponse
The fully qualified name of the "queryResponse" element in a SOAP body identifies that message as a WS-Referral query response
ref
Zero or more WS-Referral statements matching the query

Example 6 Sample WS-Referral query response sent from B to A.

<S:Envelope xmlns:S="https://www.w3.org/2001/09/soap-envelope">
  <S:Header>
    <m:path xmlns:m="https://schemas.xmlsoap.org/rp/">
      <m:action>https://schemas.xmlsoap.org/ws/2001/10/referral#queryResponse</m:action>
      <m:to>soap://a.org</m:to>
      <m:id>mid:2000@b.org</m:id>
      <m:relatesTo>mid:1000@a.org</m:relatesTo>
    </m:path>
  </S:Header>
  <S:Body>
    <r:queryResponse xmlns:r="https://schemas.xmlsoap.org/ws/2001/10/referral">
      <r:ref>
        <!-- statement left out for illustrative reasons -->
      </r:ref>
      <r:ref>
        <!-- statement left out for illustrative reasons -->
      </r:ref>
    </r:queryResponse>
  </S:Body>
</S:Envelope>

4.4 WS-Referral Registration Message Exchange

A SOAP router can explicitly request that a WS-Referral statement be accepted or rejected by another SOAP router by sending a WS-Referral registration. This can for example be used to explicitly request that a SOAP router delegates a piece of its URI space to the requesting SOAP router. The result of a WS-Referral registration is returned to the sender in form of a WS-Referral registration response as illustrated in Figure 5.

Figure 5 Time diagram of a WS-Referral registration message exchange

Although WS-Referral statements MAY refer to each other, a WS-Referral registration is independent of any other registration (see section 3.5).

4.4.1 WS-Referral Registration

A WS-Referral registration defines the following elements (see section 5.3.1):

register
The fully qualified name of the "register" element in a SOAP body identifies that message as a WS-Referral registration response
ref
Contains the WS-Referral statement that is to be registered

Example 7 Sample WS-Referral registration sent from C to B

<S:Envelope xmlns:S="https://www.w3.org/2001/09/soap-envelope">
  <S:Header>
    <m:path xmlns:m="https://schemas.xmlsoap.org/rp/">
      <m:action>https://schemas.xmlsoap.org/ws/2001/10/referral#register</m:action>
      <m:to>soap://b.org</m:to>
      <m:rev>
        <m:via/>
      </m:rev>
      <m:id>mid:3000@c.org</m:id>
    </m:path>
  </S:Header>
  <S:Body>
    <r:register xmlns:r="https://schemas.xmlsoap.org/ws/2001/10/referral">
      <r:ref>
        <!-- statement left out for illustrative reasons -->
      </r:ref>
    </r:register>
  </S:Body>
</S:Envelope>

4.4.2 WS-Referral Registration Response

The result of a WS-Referral registration is returned in a WS-Referral registration response either as a simple positive acknowledgement that the registration succeeded, or as part of a SOAP Fault message indicating that the registration did not succeed. A positive WS-Referral registration response defines the following elements (see section 5.3.2):

registerResponse
The fully qualified name of the "registerResponse" element in a SOAP body identifies that message as a positive WS-Referral registration response

Example 8 Sample positive WS-Referral registration response sent from B to C

<S:Envelope xmlns:S="https://www.w3.org/2001/09/soap-envelope">
  <S:Header>
    <m:path xmlns:m="https://schemas.xmlsoap.org/rp/">
      <m:action>https://schemas.xmlsoap.org/ws/2001/10/referral#registrationResponse</m:action>
      <m:to>soap://a.org</m:to>
      <m:id>mid:2001@b.org</m:id>
      <m:relatesTo>mid:3000@c.org</m:relatesTo>
    </m:path>
  </S:Header>
  <S:Body>
    <r:registrationResponse xmlns:r="https://schemas.xmlsoap.org/ws/2001/10/referral"/>
  </S:Body>
</S:Envelope>

The result of a failed WS-Referral registration is carried within a SOAP Fault message identified by the "registrationFault" SOAP fault code (see section 5.3.2).

Example 9 Sample fault WS-Referral registration response sent from B to C indicating a max accepted time-to-live of 10 hours

<S:Envelope xmlns:S="https://www.w3.org/2001/09/soap-envelope">
  <S:Header>
    <m:path xmlns:m="https://schemas.xmlsoap.org/rp/">
      <m:action>https://schemas.xmlsoap.org/ws/2001/10/referral#registrationResponse</m:action>
      <m:to>soap://a.org</m:to>
      <m:id>mid:2002@b.org</m:id>
      <m:relatesTo>mid:1000@a.org</m:relatesTo>
    </m:path>
  </S:Header>
  <S:Body>
    <S:Fault xmlns:r="https://schemas.xmlsoap.org/ws/2001/10/referral">
      <faultcode>r:registrationFault</faultcode>
      <faultstring>Registration Fault</faultstring>
      <detail>
        <r:maxTtl>36000000</r:maxTtl>
      </detail>
    </S:Fault>
  </S:Body>
</S:Envelope>

4.5 WS-Referral Header

In some cases, a SOAP router may want to send WS-Referral statements to other SOAP routers without being part of an explicit WS-Referral registration or WS-Referral query. Such statements MAY be sent as part of a WS-Referral header which potentially may be piggybacked on other SOAP messages if appropriate (see section 3.4). A WS-Referral header defines the following element:

referrals
The fully qualified name of the "referrals" element identifies a WS-Referral header within a SOAP header (see section 5.4)

Example 10 Sample WS-Referral Header

<S:Envelope xmlns:S="https://www.w3.org/2001/09/soap-envelope">
  <S:Header>
    <r:referrals xmlns:r="https://schemas.xmlsoap.org/ws/2001/10/referral">
      <r:ref>
        <!-- statement left out for illustrative reasons -->
      </r:ref>
      <r:ref>
        <!-- statement left out for illustrative reasons -->
      </r:ref>
    </r:referrals>
  </S:Header>
  <S:Body>
    ...
  </S:Body>
</S:Envelope>

5. The WS-Referral Specifications

5.1 WS-Referral Statement Elements

This section defines the elements of a WS-Referral statement (see section 4.1 and 4.2).

5.1.1 desc

The "desc" element is an OPTIONAL element that MAY contain an ordered list of information entries that MAY be used by the receiver of a WS-Referral statement. While such information does not affect the evaluation of whether a statement is satisfied (see section 3.3), it may provide useful additional information.

Information entries are structured elements. Each immediate child element of the "desc" element is known as an information entry and is identified by the fully qualified name of the outermost element of that entry. The "desc" element allows for an open-ended set of information entries; this specification defines one:

The "refAddr" information entry can be used to indicate the address from which a representation of the WS-Referral statement may be obtained (see section 5.1.8)

It is anticipated that over time many statements will be associated with information about the statements themselves, the sending party, or the receiver of the statement and that such information will be specified and deployed through extension.

5.1.2 exact

The "exact" element is used to indicate a SOAP actor for which an exact match is needed (see section 5.5). The "exact" element is used in the "for" element to indicate a SOAP actor for which this WS-Referral statement is intended (see section 5.1.3). The value of the "exact" element is an absolute URI (see section 5.5).

5.1.3 for

A WS-Referral statement MUST contain a "for" element that indicates the set of SOAP actors for which this WS-Referral statement is intended (see section 3.3). A SOAP actor matches a WS-Referral statement if the SOAP actor name matches any of the SOAP actors listed in the "for" element. The "for" element defines two ways for listing the SOAP actors that can be matched against depending on the matching algorithm used (see section 5.5):

The "exact" element can be used to indicate SOAP actors for which an exact match is needed (see section 5.1.2)
The "prefix" element can be used to indicate SOAP actors for which a prefix match is needed (see section 5.1.7)

If no URIs are listed then no SOAP actor can be said to match that WS-Referral statement.

5.1.4 go

The "go" element is used to indicate the set of SOAP routers referred to by a given WS-Referral statement (see section 3.3 and 4.2). The element MUST be present in a WS-Referral message.

If a SOAP message with a given message path includes a SOAP actor (indicated using WS-Routing for example) with a SOAP actor name that matches a satisfied and accepted WS-Referral statement, then the SOAP router SHOULD reconfigure the message path to go via one of the SOAP routers referred to by the statement.

The "go" element consists of a list of "via" elements containing the referred SOAP routers. If the element contains no "via" elements then no SOAP router is to be inserted in the message path. If it contains more than one "via" element then the SOAP router interpreting the statement MAY choose any of the SOAP routers listed. There is no inherent preferred order associated with "via" elements.

5.1.5 if

A WS-Referral statement MUST contain an "if" element which MAY contain an ordered list of conditions that can impose constraints on how the statement is evaluated. A WS-Referral statement is satisfied if all conditions are fulfilled (see section 3.3). If the "if" element is empty then that WS-Referral statement is automatically said to be satisfied.

Conditions are structured elements. Each immediate child element of the "if" element is known as a condition and is identified by the fully qualified name of the outermost element of that condition. The "if" element allows for an open-ended set of conditions; this specification defines two:

The "ttl" condition can be used to indicate the time-to-live of the WS-Referral statement (see section 5.1.11 and 5.3.2)
The "invalidates" condition can be used to indicate a set of WS-Referral statements that this statement invalidates (see section 5.1.6 and 5.3.2)

It is anticipated that over time many types of conditions will be specified and deployed through extension. In order to be able to evaluate whether a WS-Referral statement is satisfied, it is important that a condition specification clearly defines how it can be fulfilled as well as any fault states that may be conveyed within a WS-Referral registration response, for example.

5.1.6 invalidates

The "invalidates" element defines a condition that MAY be used to indicate the "refId" value (see section 5.1.9) of one or more WS-Referral statements that THIS statement invalidates (see section 3.3 and 5.1.5). An invalidated WS-Referral statement MUST NOT be evaluated as satisfied.

The "invalidates" element consists of a list of "rid" elements (see section 5.1.10) whose values are to be matched against the set of "refId" values of WS-Referral statements already cached on that SOAP router.

The value of the "refId" element for THIS WS-Referral statement MUST NOT be used within the "invalidates" element. If this is the case then that WS-Referral statement MUST NOT be evaluated as satisfied. That is, it is not possible to invalidate THIS statement using the "invalidates" element.

The "invalidates" condition is fulfilled if all WS-Referral statements with "refId" values that match the value of a "rid" element are invalidated. If at the time of interpreting the WS-Referral statement, a SOAP router does not have a WS-Referral statement with a "refId" value that matches the value of a "rid" element then that "rid" element is ignored, and does not cause the condition to fail.

WS-Referral response faults associated with the "invalidates" condition are described in section 5.3.2.

5.1.7 prefix

The "prefix" element is used to indicate a set of SOAP actors for which a prefix match is needed (see section 5.5). The "prefix" element is used in the "for" element to indicate a set of SOAP actors for which this WS-Referral statement is intended (see section 5.1.3). The value of the "prefix" element is a URI-prefix that follows the syntax of an absolute URI (see section 5.5).

5.1.8 refAddr

The "refAddr" element defines a descriptive information entry (see section 5.1.1) that MAY be used to indicate the address of the referral statement from which a representation of the statement can be obtained using a HTTP GET request, for example. This is different from "refId" which identifies a particular representation of a WS-Referral statement.

The value of a "refAddr" element is an absolute URI (see section 5.5).

5.1.9 refId

The "refId" element MUST be used to identify THIS representation of a WS-Referral statement. The "refId" value can be used as a mechanism for SOAP routers to be able to refer to specific representations of a WS-Referral statement (see section 5.1.6).

Two WS-Referral statements that are logically equivalent SHOULD have the same refId value; two WS-Referral statements that are logically different MUST NOT have the same refId value.

A WS-Referral condition or information entry (see section 3.3) MAY define specific logical equivalence rules for the contents carried in that condition or information entry; these specific logical equivalence rules MAY be based on an understanding of the semantics of the statements, and hence identify as equivalent statements whose lexical forms differ substantially. In all cases, however, a writer of statements MUST ensure that any two statements having identical canonical forms based on the canonicalization method (see [13]) are logically equivalent.

Two WS-Referral statements MUST be recognized as logically equivalent if they have identical canonical forms based on the canonicalization method (see [13]). Note that XML comments are NOT considered significant in the XML canonicalization method. The effect of the rule described by this paragraph is that statements which are identical except for trivial lexical differences such as whitespace will always be recognized as equivalent, but except for such canonicalization, these rules permit one to consider lexically-distinct statements as non-equivalent (more exactly, not known to be equivalent).

If a SOAP router receives a WS-Referral statement with a "refId" value that matches the refId of an already accepted WS-Referral statement, then that SOAP router MUST discard the incoming WS-Referral statement as a duplicate. If the WS-Referral statement is part of a WS-Referral registration then a SOAP Fault MUST be generated (see section 5.3.2).

Examples of "refId" element values are:

uuid:84b9f5d0-33fb-4a81-b02b-5b760641c1d6
mid:C10F7F15B07@bar.net

The uniqueness of the WS-Referral statement identifier is guaranteed by the generator of the statement. It is STRONGLY RECOMMENDED that the identifier be as unique over space and time as possible.

5.1.10 rid

The "rid" element is used to indicate a "refId" value for which an exact match is needed (see section 5.5). The "rid" element is used in the "invalidates" element to indicate that an already cached WS-Referral with a matching "refId" value is to be invalidated (see section 5.1.6). The value of the "rid" element is an absolute URI (see section 5.5).

5.1.11 ttl

The "ttl" element defines a duration, relative to the creation time of the message, after which the referral MUST be considered stale (see section 3.5 and 5.1.5), subject to clock-synchronization as noted below. Because WS-Referral statements often are likely to be quasi-static in nature, it is STRONGLY RECOMMENDED that the "ttl" condition be used whenever possible.

The value of the "ttl" element is an unsignedLong with a unit of milliseconds. The "ttl" condition is fulfilled if the WS-Referral statement is not stale. A stale WS-Referral statement MUST NOT be evaluated as satisfied. WS-Referral response faults associated with the "ttl" condition are described in section 5.3.2.

Because clocks may not be perfectly synchronized, readers of a "ttl" element will need to use mechanisms out of the scope of this specification to either bring clocks into synchronization and/or estimate the extent of clock skew and/or transmission delay. Readers and writers of WS-Referral statements SHOULD NOT assume that statements become stale with any greater degree of clock synchronization than has been achieved by those processes.

5.2 WS-Referral Query

This section defines the elements of a WS-Referral query and a WS-Referral query response (see section 4.3). A WS-Referral query sent from initial sender A to intended receiver B MUST be followed by a WS-Referral query response sent from B to A. A SOAP router MUST NOT send a WS-Referral query response UNLESS it is in response to a WS-Referral query. A SOAP router receiving a WS-Referral query response that cannot be correlated with a WS-Referral query that it generated, MUST discard that message.

5.2.1 WS-Referral Query Request

A WS-Referral query is delimited by the "query" element which is the outermost element of a WS-Referral query carried as a SOAP body block. In the general case, a WS-Referral query is a query over a virtual, distributed database of referral information based on an open-ended set of query parameters. WS-Referral provides an open content model that allows for the addition of query mechanisms as part of a WS-Referral query.

The only mechanism defined by this specification consists of providing a list of SOAP actors that the requestor is interested in WS-Referral statements for. The list of SOAP actors are carried within the "for" element defined in section 5.1.3.

If used with the Web Services Routing Protocol, the value of the "action" element defined by WS-Routing for a WS-Referral query request MUST be

https://schemas.xmlsoap.org/ws/2001/10/referral#query

5.2.2 WS-Referral Query Response

A WS-Referral query response is delimited by the "queryResponse" element which is the outermost element of a WS-Referral query response carried as a SOAP body block. The "queryResponse" element contains the zero or more WS-Referral statements that match the query.

If used with the Web Services Routing Protocol, the value of the "action" element defined by WS-Routing for a WS-Referral query response MUST be

https://schemas.xmlsoap.org/ws/2001/10/referral#queryResponse

5.3 WS-Referral Registration

This section defines the elements of a WS-Referral registration and a WS-Referral registration response (see section 4.4). A WS-Referral registration sent from initial sender A to intended receiver B MUST be followed by a WS-Referral registration response sent from B to A. A SOAP router MUST NOT send a WS-Referral registration response UNLESS it is in response to a WS-Referral registration. If a SOAP router receives a WS-Referral registration response that cannot be correlated with a WS-Referral registration that it generated, it MUST discard that message.

5.3.1 WS-Referral Registration Request

A WS-Referral registration is delimited by the "register" element which is the outermost element of a WS-Referral registration carried as a SOAP body block. A WS-Referral registration contains a WS-Referral statement that either can be accepted or rejected by the receiver (see section 5.1).

If used with the Web Services Routing Protocol, the value of the "action" element defined by WS-Routing for a WS-Referral registration request MUST be

https://schemas.xmlsoap.org/ws/2001/10/referral#registration

5.3.2 WS-Referral Registration Response

There are two types of WS-Referral registration responses: a positive response and a fault response. A positive response is delimited by the "registrationResponse" element which is the outermost element of a positive WS-Referral registration response carried as a SOAP body block. Although the "registrationResponse" element provides an open content model, this specification defines no other parts of the "registrationResponse" element.

The result of a failed WS-Referral registration is carried within a SOAP Fault message identified by the fully qualified "registrationFault" SOAP fault code. It is suggested, but not required, to use the SOAP fault string "Registration Failed" with the "registrationFault" fault code. It is STRONGLY RECOMMENDED that the SOAP Fault detail element be used to provide detailed information about the fault condition. This specification defines the following fault information intended to be carried in a SOAP Fault "detail" element:

Table 1 WS-Referral SOAP Fault detail elements

Element Name	Meaning
duplicate	The requested SOAP router already has an accepted and satisfied WS-Referral statement with that "refId" value.
notInvalidated	The SOAP router refused to invalidate the accepted and satisfied WS-Referral statements requested by the "invalidates" condition. The requested SOAP router MAY indicate the offending "refId" values as part of the "notInvalidated" element.
maxTtl	The SOAP router refused to accept a WS-Referral statement with a "ttl" value greater than the value included in the "maxTtl" element. The value is expressed as a number with a unit of milliseconds (see section 5.1.11)

If no SOAP detail element is provided as part of the SOAP Fault message then no additional information is provided about the registration fault condition.

Regardless of whether the response is positive or a fault, if used with the Web Services Routing Protocol, the value of the "action" element defined by WS-Routing for a WS-Referral registration request MUST be

https://schemas.xmlsoap.org/ws/2001/10/referral#registrationResponse

5.4 WS-Referral Header Elements

This section defines the elements of a WS-Referral header (see section 4.5).

5.4.1 Referrals

A WS-Referral header is delimited by the "referrals" element which is the outermost element of a WS-Referral header carried as a SOAP header block. The "referrals" element contains zero or more WS-Referral statements as defined in section 5.1.

5.5 Use of URIs in WS-Referral

Similar to WS-Routing, WS-Referral uses URIs [3] for all identifiers without exception. To WS-Referral, a URI is simply a formatted string that identifies—via name, location, or any other characteristic—a resource on the Web.

All URIs used in WS-Referral MUST be absolute. The use of IP addresses in URIs SHOULD be avoided whenever possible (see RFC 1900). However, when used, the literal format for IPv6 addresses in URIs as described by RFC 2732 [14] SHOULD be supported.

A URI match is defined as one of two URI matching operations:

A URI is said to be an exact match if it can be shown to be equivalent with the URI that it is matched against
A URI-prefix is said to be a prefix match if it can be shown to be equivalent with a prefix of the URI that it is matched against. An exact match is a valid prefix match. A URI-prefix MUST contain at least a URI scheme followed by a ":" (see [3]).

WS-Referral does not define any equivalence rules for URIs in general as these are defined by the individual URI schemes and by RFC 2396. However, because of inconsistencies with respect to some URI equivalence rules in many current URI parsers, it is STRONGLY RECOMMENDED that generators of WS-Referral statements only rely on the most rudimentary equivalence rules defined by RFC 2396.

WS-Referral does not place any a priori limit on the length of a URI. Any WS-Referral receiver MUST be able to handle the length of any URI that it publishes and all WS-Referral implementations SHOULD be able to deal with URIs of at least 8k in length.

6. Security Considerations

Many security concerns are associated with accepting a WS-Referral statement whether through implicit or explicit registration. It is STRONGLY RECOMMENDED that any SOAP router accepting WS-Referral statements require strong authentication and message integrity as part of the registration procedure.

SOAP routers replying to WS-Referral queries SHOULD be aware that any information provided in the form of WS-Referral statements MAY unintentionally provide information about how that SOAP router is configured. It is STRONGLY RECOMMENDED that WS-Referral statements included in a WS-Referral query response NOT be associated with the actual configuration of that SOAP router UNLESS the appropriate trust between the requester and the requested SOAP router has been established.

Similarly, including WS-Referral statements as part of a WS-Referral header MAY unintentionally provide information about how that SOAP router is configured. As for WS-Referral query responses, it is STRONGLY RECOMMENDED that WS-Referral statements included in a WS-Referral header NOT be associated with the actual configuration of that SOAP router UNLESS the appropriate trust has been established with the receiving SOAP routers.

7. References

[1] P. Mockapetris, "DOMAIN NAMES - IMPLEMENTATION and SPECIFICATION" RFC 883, ISI, November 1983

[2] S. Bradner, "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119, Harvard University, March 1997

[3] T. Berners-Lee, R. Fielding, L. Masinter, "Uniform Resource Identifiers (URI): Generic Syntax", RFC 2396, MIT/LCS, U.C. Irvine, Xerox Corporation, August 1998.

[4] R. Fielding, J. Gettys, J. C. Mogul, H. Frystyk, T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, U.C. Irvine, DEC W3C/MIT, DEC, W3C/MIT, W3C/MIT, January 1997

[5] W3C Recommendation "Extensible Markup Language (XML) 1.0 (Second Edition)", 6 October 2000

[6] W3C Recommendation "Namespaces in XML", 14 January 1999

[7] W3C Recommendation "XML Base", 27 June 2001

[8] W3C Recommendation "XML Schema Part 1: Structures", 2 May 2001

[9] W3C Recommendation "XML Schema Part 2: Datatypes", 2 May 2001

[10] W3C Note "Simple Object Access Protocol (SOAP) 1.1"

[11] W3C Working Draft "SOAP Version 1.2 (Part 1 and Part 2)", October 2 2001. This is work in progress.

[12] H. Nielsen, S. Thatte, "Web Services Routing Protocol", Microsoft, October 2001

[13] W3C Recommendation "Canonical XML Version 1.0" 15 March 2001

[14] R. Hinden, B. Carpenter, L. Masinter, "Format for Literal IPv6 Addresses in URL's", RFC 2732, Nokia, IBM, AT&T, December 1999

Appendix A. Sample WS-Routing Messages

Given the sample message path illustrated in Figure 1, a corresponding WS-Routing message may look like this:

Example A.1 Sample WS-Routing message for message from A to B

<S:Envelope xmlns:S="https://www.w3.org/2001/09/soap-envelope">
  <S:Header>
    <m:path xmlns:m="https://schemas.xmlsoap.org/rp/">
      <m:action>https://www.notification.org/update</m:action>
      <m:to>soap://b.org</m:to>
      <m:from>soap://a.org</m:from>
      <m:id>mid:1000@a.org</m:id>
    </m:path>
  </S:Header>
  <S:Body>
    ...
  </S:Body>
</S:Envelope>

If A accepts the WS-Referral statement illustrated in Example 2, the next message that A sends to B may look like this when it leaves A:

Example A.2 Sample WS-Routing message for message from A to B given WS-Referral statement in Figure 2 accepted by A

<S:Envelope xmlns:S="https://www.w3.org/2001/09/soap-envelope">
  <S:Header>
    <m:path xmlns:m="https://schemas.xmlsoap.org/rp/">
      <m:action>https://www.notification.org/update</m:action>
      <m:to>soap://b.org</m:to>
      <m:fwd>
        <m:via>soap://c.org</m:via>
      </m:fwd>
      <m:from>soap://a.org</m:from>
      <m:id>mid:1001@a.org</m:id>
    </m:path>
  </S:Header>
  <S:Body>
    ...
  </S:Body>
</S:Envelope>

If B accepts the WS-Referral statement illustrated in Example 3, the next message that A sends to B looks exactly like illustrated in Example A.1 because A doesn't know about the WS-Referral statement accepted by B. When the message arrives at B, B knows that it has outsourced that part of the namespace to C and therefore forwards the message to C. The WS-Routing header used for the message forwarded from B to C looks exactly as the message illustrated in Example A.2.

That is, the resulting message path configuration is the same—the only difference is who knows about the configuration: In the first example, node A knows about the configuration whereas in the second example, B knows about the configuration.