X SOAP Correlation Extension

The SOAP Correlation Extension defines two SOAP blocks with a prescribed set of processing semantics that enable correlation of messages and their response(s) exchanged between SOAP processing nodes. This extension has been provided to enable the request/response message exchange pattern, and potentially other MEPs, to be effected in situations where the underlying transport or transfer application protocol does not provide for implicit correlation of messages.

It is not the intent of the W3C XMLP WG to define a canonical/normative correlation mechanism for SOAP. Other correlation extensions MAY be devised and used.

X.1 CorrelationId Block

The first of these SOAP blocks is the CorrelationId block. This is a SOAP header block that consists of an element information item that has the following properties:

local name: CorrelationId
namespace name: http://www.w3.org/2001/07/soap-correlation
parent: the Header element information item [need reference target in spec]

The in-scope namespaces property MUST contain a namespace information item that has a namespace name property of "http://www.w3.org/2001/06/soap-envelope".

In addition to these specified properties, the following attribute information items MUST be present in the
attributes property:

actor attribute information item:

local name: actor
namespace name: http://www.w3.org/2001/06/soap-envelope
specified: true
attribute type: CDATA
normalized value: http://www.w3.org/2001/06/soap-envelope/actor/next

mustUnderstand attribute information item:

local name: mustUnderstand
namespace name: http://www.w3.org/2001/06/soap-envelope
specified: true
attribute type: CDATA
normalized value: true

An attribute information item with the following properties SHOULD be included in the attributes property:

local name: source
namespace name: http://www.w3.org/2001/06/soap-correlation
specified: true
attribute type: CDATA

This attribute information item, if present, SHALL have a normalized value property that is an identifier chosen by the SOAP processing node or application that originates the CorrelationId block.

Zero or more additional attribute information items MAY be present in the attributes property with the constraint that they have a namespace name property that is not "http://www.w3.org/2001/07/soap-correlation".

The children property SHALL consist of one or more character information items. The set of character information items represents some token or value that the originator of the CorrelationId block understands and will use to match against an equivalent set of character information items in a CorrelationRef block in some other message that it receives.

X.2 CorrelationRef Block

The second of these SOAP blocks is the CorrelationRef block. This is a SOAP header block that consists of an element information item that has the following properties:

local name: CorrelationRef
namespace name: http://www.w3.org/2001/07/soap-correlation
parent: the Header element information item [need reference target in spec]

The in-scope namespaces property MUST contain a namespace information item that has a namespace name property of "http://www.w3.org/2001/06/soap-envelope".

In addition to these specified properties, the following attribute information item MAY be present in the
attributes property:

attribute information item:

local name: actor
namespace name: http://www.w3.org/2001/06/soap-envelope
specified: true
attribute type: CDATA

The normalized value property of the actor attribute information item is determined by the processing semantics described below in section X.3.

The children property SHALL consist of one or more character information items.

X.3 Processing Semantics

A SOAP message MAY include zero or more CorrelationId blocks.

A SOAP node that is the ultimate receiver of a SOAP message containing a CorrelationId block as defined in section X.1 SHALL include a CorrelationRef block, as defined in section X.2, in any SOAP message that is considered a response to the original message received, including a SOAP Fault. The CorrelationRef element information item included in the SOAP response message SHALL contain exactly the same set of character information items in the CorrelationId element information item of the original message. If the CorrelationId element information item contains a source attribute information item, then an actor attribute information item SHALL be added to the CorrelationRef element information item's attributes property that has a normalized value property that is the same as that of the source attribute information item of the CorrelationId element information item.

An intermediary SOAP processing node receiving a SOAP message that includes the CorrelationId block, as described above, MUST include an equivalent CorrelationId block in the SOAP message that is forwarded to the next SOAP processing node in the message path. In the event that a SOAP Fault is generated by the intermediary SOAP processing node, it SHALL include a CorrelationRef element information item, as described above, in the SOAP Fault message that has exactly the same set of character information items as the corresponding CorrelationId element information item. If the CorrelationId element information item contains a source attribute information item, then an actor attribute information item SHALL be added to the CorrelationRef element information item's attributes property that has a normalized value property that is the same as that of the source attribute information item of the CorrelationId element information item.

An intermediary SOAP processing node MAY insert its own CorrelationId block into a SOAP message that is to be forwarded along its message path. An intermediary SOAP processing node adding its own CorrelationId block MUST include the source attribute information item with a normalized value property that corresponds to the actor URI by which it is known.

X.4 Example

SOAP request message with CorrelationId block

<s:Envelope xmlns:s="http://www.w3.org/2001/06/soap-envelope/">
<s:Header>
    <c:CorrelationId xmlns:c="http://www.w3.org/2001/07/soap-correlation/"
        s:actor="next" s:mustUnderstand="true" c:source="urn:x-me-myself-i">
    12345
    </c:CorrelationId>
</s:Header>
<s:Body>
    <x:Foo xmlns:x="...">...</x:Foo>
</s:Body>
</s:Envelope>

SOAP response message with CorrelationRef block

<s:Envelope xmlns:s="http://www.w3.org/2001/06/soap-envelope">
<s:Header>
    <c:CorrelationRef xmlns:c="http://www.w3.org/2001/07/soap-correlation"
       s:actor="urn:x-me-myself-i">
    12345
    </c:CorrelationRef>
</s:Header>
<s:Body>
    <x:Bar xmlns:x="...">...</x:Bar>
</s:Body>
</s:Envelope>

X.5 Correlation Extension Schema Definition

<?xml version = "1.0" encoding = "UTF-8"?>
<schema xmlns = "http://www.w3.org/2001/XMLSchema"
targetNamespace = "http://www.w3.org/2001/07/soap-correlation"
xmlns:tns = "http://www.w3.org/2001/07/soap-correlation"
xmlns:soap = "http://www.w3.org/2001/06/soap-envelope"
version = "0.01"
elementFormDefault = "qualified">
<import namespace = "http://www.w3.org/2001/06/soap-envelope"
    schemaLocation = "http://www.w3.org/2001/06/soap-envelope"/>
<element name = "CorrelationId">
<complexType>
   <simpleContent>
    <extension base = "string">
     <attribute ref = "soap:mustUnderstand"/>
     <attribute ref = "soap:actor"/>
     <attribute name = "source" type = "anyURI" minOccurs="0"/>
     <anyAttribute namespace = "##other" processContents = "lax" minOccurs="0" maxOccurs="unbounded"/>
    </extension>
   </simpleContent>
</complexType>
</element>
<element name = "CorrelationRef">
<complexType>
   <simpleContent>
    <extension base = "string">
     <attribute ref = "soap:actor" minOccurs="0"/>
     <anyAttribute namespace = "##other" processContents = "lax" minOccurs="0" maxOccurs="unbounded"/>
    </extension>
   </simpleContent>
</complexType>
</element>
</schema>