Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 36 ยท XML and SOAP Messages

The SOAP Envelope, Header and Body

Learn the structure of a SOAP message: Envelope, optional Header blocks, mandatory Body, attributes such as mustUnderstand and role, and validate a message in code.

Every SOAP message has the same skeleton, whatever the service does. Learn it once and every message in the world becomes readable: an Envelope that wraps everything, an optional Header with metadata, and a mandatory Body with the actual request or response.

flowchart TD
    E["Envelope (root, names the SOAP version)"] --> H["Header (optional)<br/>security, routing, transaction, trace blocks"]
    E --> B["Body (required)<br/>operation call, response or Fault"]
    H --> H1["block 1"]
    H --> H2["block 2"]
    B --> B1["operation element<br/>with parameters"]

The Header, when present, comes before the Body. Each header block is a separate element.

The Envelope

The root element is Envelope, in the SOAP 1.1 or SOAP 1.2 namespace. It contains at most one Header followed by exactly one Body. Nothing else is allowed directly inside it in SOAP 1.2 (SOAP 1.1 formally allowed extra trailing elements, but it is not used). The Envelope is also where you declare the namespaces the message needs.

XML
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
               xmlns:acct="urn:example:accounts">
  <soap:Header>
    <acct:TraceId soap:mustUnderstand="false">c1f8-77a0</acct:TraceId>
  </soap:Header>
  <soap:Body>
    <acct:GetBalance>
      <acct:accountNumber>12345678</acct:accountNumber>
    </acct:GetBalance>
  </soap:Body>
</soap:Envelope>

The Header

The Header carries information about the message: who is calling, how to route it, which transaction it belongs to. It is a container of header blocks, each a namespaced element defined by some specification or by you. Business data does not belong here.

Header blocks may carry these attributes in the SOAP namespace:

Attribute Meaning
mustUnderstand 1/true means: the target node must process this block or fail. 1.1 writes 1/0; 1.2 allows true/false/1/0.
role (1.2) or actor (1.1) Which node the block is for. Default: the ultimate receiver.
relay (1.2) Forward the block even if the intermediary did not process it.

Typical blocks: wsse:Security (credentials, signatures), wsa:To/wsa:Action/wsa:MessageID (addressing), wsrm:Sequence (reliable messaging), and your own correlation id. A service that does not understand a mustUnderstand="1" block must return a MustUnderstand fault.

The Body

The Body holds the payload. For a request it normally contains one element named after the operation, with one child element per parameter. For a response, one element, conventionally OperationNameResponse. When something goes wrong, the Body contains a single Fault instead. That is all the SOAP standard says; the rest is your schema.

Building envelopes

Building the envelope by hand is fine for learning. This function takes a header list and a body and writes both SOAP versions, so you can compare them side by side.

Node.js An envelope builder for 1.1 and 1.2

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice how the same logical message differs only in the namespace, the mustUnderstand values and the actor/role attribute name.

Checking a message's structure

A receiving node performs structural checks before it dispatches the operation. The following validator mirrors the rules: root must be Envelope in a known namespace, an optional Header first, then exactly one Body, nothing else.

Node.js Validating the envelope structure

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Real frameworks do these checks for you and return the correct Fault (VersionMismatch, MustUnderstand, Sender). You still need to know the rules, because the fault text tells you which one you broke.

Body or Header: where does it go?

A simple test: does the receiver's business logic need this value to do its job? Then it goes in the Body. Is it about how the message is handled (who sent it, how it is secured, which hop it targets, which conversation it belongs to)? Then it is a Header block. Keeping the two separate lets a gateway sign, route and audit messages without understanding the business content.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which parts of a SOAP envelope are mandatory?

    The Envelope must contain exactly one Body. The Header is optional.
  2. 2. What happens if a node must process a block marked mustUnderstand and does not understand it?

    mustUnderstand makes a block mandatory for its target; failing to understand it is a fault.
  3. 3. Where should a trace id used only by monitoring tools be placed?

    Metadata about message handling belongs in header blocks, leaving the Body for business data.
  4. 4. Which attribute name addresses a header block to a specific node in SOAP 1.2?

    SOAP 1.1 uses actor; SOAP 1.2 renamed it role.
  5. 5. In what order do Header and Body appear?

    The optional Header must come first, followed by the Body.

Summary

  • A SOAP message is an Envelope with an optional Header and a required Body, in that order.
  • Header blocks carry metadata for nodes along the path; the Body carries business data or a Fault.
  • mustUnderstand, role/actor and relay control how header blocks are processed.
  • The envelope namespace gives the SOAP version; structural errors produce specific faults.

Next: SOAP Faults