SOAP Header

SOAP provides a flexible mechanism for extending a message in a decentralized and modular way without prior knowledge between the communicating parties. The Header element namespace serves as a container for extensions to SOAP. No extensions are defined by the specification, but user-defined extension services such as transaction support, locale information, authentication, digital signatures, and so forth could all be implemented by placing some information inside the Header element.

The SOAP Header element is the first immediate child element of the SOAP Envelope XML element, if it is presented.

The Header element can have any number of namespace-qualified immediate child elements that are NOT in the http://schemas.xmlsoap.org/soap/envelope/ namespace. All immediate child elements of the Header element are called header blocks. A header block is identified by its fully qualified element name, which consists of the namespace URI and the local name.

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:tns="http://schemas.xmlsoap.org/soap/envelope/"
    targetNamespace="http://schemas.xmlsoap.org/soap/envelope/">
  ....
  <xs:complexType name="Header">
    <xs:sequence>
      <xs:any namespace="##other" minOccurs="0" maxOccurs="unbounded" processContents="lax" />
    </xs:sequence>
    <xs:anyAttribute namespace="##other" processContents="lax" />
  </xs:complexType> 
  .... 
</xs:schema>

All immediate child elements of the SOAP Header element MUST be namespace-qualified (WS-I Basic Profile 1.0 requires all immediate children of Header element be namespace qualified.).

An example extension for locale information requesting that the recipient of the message send any responses localized for the specified locale; in this case, UK English.

<soap:Envelope
   xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/'>
  <soap:Header>
    <x:Locale
      xmlns:x='http://example.org/Extensions/Locale'>
     <language>en</language>
     <sublang>uk</sublang>
    </x:Locale>
  </soap:Header>
  <soap:Body>
    <!-- message payload goes here -->
  </soap:Body>
</soap:Envelope>

The header block may be annotated with the SOAP mustUnderstand attribute and/or SOAP actor attribute which indicate how to process the entry and by whom.

SOAP actor Attribute

A SOAP message travels from the originator to the ultimate destination, potentially by passing through a set of SOAP intermediaries along the message path. A SOAP intermediary is an application that is capable of both receiving and forwarding SOAP messages. Both intermediaries as well as the ultimate destination are identified by a URI.

Not all parts of a SOAP message may be intended for the ultimate destination of the SOAP message but, instead, may be intended for one or more of the intermediaries on the message path. The role of a recipient of a header element is similar to that of accepting a contract in that it cannot be extended beyond the recipient. That is, a recipient receiving a header element MUST NOT forward that header element to the next application in the SOAP message path. The recipient MAY insert a similar header element but in that case, the contract is between that application and the recipient of that header element.

The SOAP actor global attribute can be used to indicate the recipient of a header element. The value of the SOAP actor attribute is a URI. The special URI "http://schemas.xmlsoap.org/soap/actor/next" as the value of actor attribute indicates that the next SOAP application in the message path must process the header element.

SOAP 1.1 ONLY defines a single role named http://schemas.xmlsoap.org/soap/actor/next (next, for short). Every SOAP node is required to assume the next role. Hence, when a SOAP message arrives at any given SOAP node, the node must process all mandatory headers targeted at the next role, and it may choose to process optional headers also targeted at the next role. In addition to next, SOAP 1.2 defines a few more roles and applications are allowed to define custom roles as well.

The absence of the SOAP actor attributes, in the header block, indicates that the recipient is the ultimate destination of the SOAP message.

This attribute MUST appear in the SOAP message instance in order to be effective.

An example extension intended for the first intermediary in the chain

<soap:Envelope
   xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/'>
  <soap:Header>
    <x:x xmlns:x='http://example.org/Extensions/'
         soap:actor='http://schemas.xmlsoap.org/soap/actor/next'>
      <!-- extension detail goes here -->
    </x:x>
  </soap:Header>
  <soap:Body>
    <!-- message payload goes here -->
  </soap:Body>
</soap:Envelope>

SOAP mustUnderstand Attribute

The SOAP mustUnderstand global attribute can be used to indicate whether a header block is mandatory or optional for the recipient to process. The recipient of a header entry is defined by the SOAP actor attribute. The value of the mustUnderstand attribute is either "1" or "0". The absence of the SOAP mustUnderstand attribute is semantically equivalent to its presence with the value "0".

If a header element is tagged with a SOAP mustUnderstand attribute with a value of "1", the recipient of that header entry either MUST obey the semantics (as conveyed by the fully qualified name of the element) and process correctly to those semantics, or MUST fail processing the message.

The SOAP mustUnderstand attribute allows for robust evolution. Elements tagged with the SOAP mustUnderstand attribute with a value of "1" MUST be presumed to somehow modify the semantics of their parent or peer elements. Tagging elements in this manner assures that this change in semantics will not be silently (and, presumably, erroneously) ignored by those who may not fully understand it.

This attribute MUST appear in the instance in order to be effective.

SOAP 1.1.’s processing model is underspecified with respect to the processing of mandatory header blocks. Mandatory header blocks are those children of the soap:Header element bearing a soap:mustUnderstand attribute with a value of “1”. [WS-I Basic Profile 1.0]

The WS-I Basic Profile 1.0 requires that receivers generate a Fault when they encounter header blocks that they do not understand targeted at them. [WS-I Basic Profile 1.0]

The mustUnderstand attribute indicates to the recipient of a SOAP message whether processing of an extension element is mandatory. If the attribute has the value 1, then the recipient must recognize the extension element and process it accordingly. If the recipient does not recognize the element, it must report a fault. If the attribute has the value 0 (the default), then processing of the extension element is optional.

A mandatory extension as specified by the mustUnderstand attribute with a value of 1.

<soap:Envelope
   xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/'>
  <soap:Header>
    <x:x xmlns:x='http://example.org/Extensions/'
         soap:mustUnderstand='1' >
       <!-- extension detail goes here -->
    </x:x>
  </soap:Header>
  <soap:Body>
       <!-- message payload goes here -->
  </soap:Body>
</soap:Envelope>

Conformance Claim Header Block

Although the BP doesn't endorse any particular type of header block, it does specify an optional conformance header block that indicates that the SOAP message complies with the BP. The example shows how the conformance header block may appear in a SOAP message.

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope
    xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
    <soap:Header>
        <wsi:Claim conformsTo="http://ws-i.org/profiles/basic/1.0"
                      xmlns:wsi="http://ws-i.org/schemas/conformanceClaim/" />
    </soap:Header>
    <soap:Body sec:id="Body">
       <!-- Application-specific data goes here -->
    </soap:Body>
</soap:Envelope>

The WS-I Basic Profile 1.0 states that the Claim header block is not required. It also states that “absence of a conformance claim in a message must not be construed as inferring that the message does or does not conform to one or more profiles.”

A SOAP message can declare a separate Claim header for each profile it adheres to. At the time of this writing the WS-I has defined only the Basic Profile 1.0, but it's expected to release other profiles. In the future, it's possible that a SOAP message will conform to both the WS-I Basic Profile 1.0 and other, as yet undefined, profiles.