SOAP Header Element

The specifications for a SOAP header element differ slightly between SOAP 1.1 and SOAP 1.2. The following discussion is based on SOAP 1.1.

A SOAP message consists of three elements: the top level Envelope element and two of its children (the Header element and the Body element).

The following is a SOAP message with all three of these elements.

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tns="urn:JadeWebServices/WebServiceOverHttpApp/" xmlns:s1="urn:JadeWebServices/WebServiceOverHttpApp/">
<soap:Header>
    <s1:erewhonHeader>
    <s1:priority>HIGH</s1:priority>
        </s1:erewhonHeader>
    </soap:Header>
    <soap:Body>
        <s1:getClient>
            <s1:clientName>Brian Olsen</s1:clientName>
        </s1:getClient>
    </soap:Body>
</soap:Envelope>

The Body element is where the main data in the message lives. The Header element is where any metadata that might describe the body, details of how the body should be processed, or simply extra information about the message can live. The Header element is optional, but if it exists, it must be the first child of the Envelope element. The Header element itself consists of zero or more child elements, referred to as header blocks. Each header block needs to be namespace‑qualified.

The SOAP 1.1 specifications define three attributes that can apply to header blocks: the encodingStyle attribute, the actor attribute, and the mustUnderstand attribute. All three of these attributes are optional and they can be used in addition to any other attributes that you may want to include.

The encodingStyle attribute is used to indicate how the encapsulated data is encoded. The SOAP specification includes a mechanism for encoding data that includes data type information in XML attributes. This is becoming less popular as more and more people define their headers using XML Schema.

The actor attribute is used to indicate which node should process this particular header block. A SOAP message can be passed through a sequence of nodes, and it is conceivable that a header block may apply to one node in the sequence and not to others. You might set the actor attribute to the endpoint of the node, which will process the header block so that other nodes in the sequence will know to ignore it. The absence of the actor attribute implies that the header block is targeted for the ultimate recipient of the SOAP message. Note that the actor attribute has been renamed the role attribute in the SOAP 1.2 specification.

The mustUnderstand attribute is the way that a header block indicates that it must be understood and processed in accordance with any specifications that may be defined for the specified qualified element name. If the recipient does not know how to process the header block, it must generate a MustUnderstand fault and not proceed with any further processing of the message. The mustUnderstand attribute is a Boolean value, and if it is not present, it is assumed to be false.