WSDL - SOAP Header Definitions and Processing Rules in WSDL

1. Introduction

Web Services Description Language (WSDL) is an XML-based language used to describe the operations, messages, and communication details of a web service. It enables client applications to understand how to communicate with a web service without needing to know its internal implementation.

In SOAP-based web services, a message generally consists of an envelope, a header, and a body. The SOAP header is an optional section used to carry additional information required during message processing. While the SOAP body usually contains the main request or response data, the header carries supporting information such as authentication credentials, transaction identifiers, routing instructions, and message-processing requirements.

WSDL helps describe how SOAP messages are structured and how services communicate. SOAP header definitions are particularly useful when a service needs additional information beyond the main business data. For example, an online banking service might require a transaction identifier or security token in the SOAP header before processing a money transfer request.

2. Structure of a SOAP Header

A SOAP header appears inside the SOAP envelope and before the SOAP body. It contains one or more header blocks, each designed to carry a particular piece of information. These blocks are represented using XML elements and can be processed by the receiving service or by an intermediary involved in message delivery.

Consider an online shopping service that requires a customer authentication token and a request identifier. A SOAP message could contain these details in the header while keeping the product order information in the body.

<soap:Envelope
    xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
    xmlns:ex="http://example.com/headers">

    <soap:Header>
        <ex:RequestID>REQ-1001</ex:RequestID>
    </soap:Header>

    <soap:Body>
        <ex:PlaceOrder>
            <ex:ProductID>P101</ex:ProductID>
            <ex:Quantity>2</ex:Quantity>
        </ex:PlaceOrder>
    </soap:Body>

</soap:Envelope>

In this example, the RequestID element is placed in the SOAP header, while the product identifier and quantity are placed in the body. The receiving application can use the request identifier to track the request and the body to process the order.

A SOAP header does not automatically provide authentication, authorization, or transaction management. These functions require suitable protocols, policies, or application logic. The header simply provides a structured place to carry the information needed for those functions.

3. How WSDL Defines SOAP Headers

WSDL describes the interface of a web service, including its messages, operations, bindings, and endpoints. In WSDL 1.1, SOAP headers are commonly described using the soap:header extension within a SOAP binding operation's input or output definition. The header references a message and a part that specify the data to be carried in the header.

A simplified WSDL example is shown below.

<definitions
    xmlns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:tns="http://example.com/orders"
    targetNamespace="http://example.com/orders">

    <message name="RequestHeaderMessage">
        <part name="requestId" type="string"/>
    </message>

    <binding name="OrderServiceBinding"
             type="tns:OrderServicePortType">

        <soap:binding
            style="document"
            transport="http://schemas.xmlsoap.org/soap/http"/>

        <operation name="PlaceOrder">
            <input>
                <soap:body use="literal"/>
                <soap:header
                    message="tns:RequestHeaderMessage"
                    part="requestId"
                    use="literal"/>
            </input>
        </operation>

    </binding>
</definitions>

This example illustrates the role of soap:header: it identifies the WSDL message and message part associated with a SOAP header. The use="literal" attribute indicates that the header content follows the declared XML representation rather than SOAP encoding rules.

The example is intentionally simplified and omits other declarations, such as the complete port type, output message, service, and endpoint. In a complete WSDL document, these elements must be defined consistently. WSDL 2.0 uses a different structure and different binding mechanisms, so this WSDL 1.1 example should not be copied unchanged into a WSDL 2.0 document.

4. SOAP Header Processing Rules

SOAP header processing rules determine how a receiver interprets and handles the information included in a header. In SOAP 1.1, the actor attribute can identify the recipient responsible for a header block, while SOAP 1.2 uses the role attribute for a similar purpose. These attributes help determine whether a header is intended for the ultimate receiver or an intermediary.

The mustUnderstand attribute is particularly important. When set to 1 in SOAP 1.1 or true in SOAP 1.2, it indicates that the targeted receiver must understand and process the header block according to its defined meaning. If the receiver cannot process a mandatory header appropriately, it must not simply ignore it; the SOAP processing rules require a fault in the applicable circumstances. This mechanism helps prevent important instructions from being silently overlooked.

Header processing also depends on the namespaces and specifications associated with the header elements. A receiver must interpret a header according to its defined semantics rather than assuming that every XML element has a standard meaning. For example, a custom RequestID header has no universal processing behavior unless the service defines how it should be used. Similarly, a security-related header must follow the applicable security specification and implementation requirements.

5. Practical Applications and Benefits

SOAP header definitions are useful in enterprise applications where communication requires information beyond the main request and response data. In financial systems, headers may carry identifiers used to correlate transactions across multiple services. In enterprise integration, they may carry routing or message-priority information. Security implementations can use standardized mechanisms, such as WS-Security, to represent security-related information in SOAP headers.

Clearly defining headers in WSDL improves interoperability because client developers and code-generation tools can identify the additional message information expected by a service. It also helps testing teams verify that required header blocks are included and that receivers handle them correctly. When header definitions are documented consistently, applications developed in different programming languages can communicate more reliably.

However, SOAP headers should be designed carefully. Unnecessary headers increase complexity, and poorly documented custom headers can cause compatibility problems. Sensitive values should not be transmitted in plain text without appropriate protection, and a header should not be assumed to be secure merely because it is placed outside the SOAP body. Developers should use appropriate transport security, message-level security where required, and clear processing rules to protect service communications.

Conclusion

SOAP header definitions and processing rules are an important part of designing reliable WSDL-based web services. WSDL 1.1 provides the soap:header binding extension to describe header message parts, while SOAP specifications define how header blocks are targeted and processed. Understanding these mechanisms helps developers create interoperable services, handle additional communication metadata, and avoid errors caused by ignored or incorrectly interpreted headers. By documenting header requirements and following the relevant SOAP and security standards, organizations can build web services that are easier to integrate, test, and maintain.