The SOAP Message Format (2025)

What is SOAP message?

A unit of communication in SOAP is a message. A SOAP message is an ordinary XML documentcontaining the following elements shown in the figure below.

• A required Envelope element that identifies the XML document as a SOAP message
• An optional Header element that contains the message header information; can includeany number of header blocks (simply referred to as headers); used to pass additionalprocessing or control information (e.g., authentication, information related to transactioncontrol, quality of service, and service billing and accounting-related data)
• A required Body element that contains the remote method call or response information;all immediate children of the Body element are body blocks (typically referred to simplyas bodies)
• An optional Fault element that provides information about errors that occurred whileprocessing the message

SOAP messages are encoded using XML and must not contain DTD references or XMLprocessing instructions. If a header is present in the message, it must be the firstimmediate child of the Envelope element. The Body element either directly follows theHeader element or must be the first immediate child of the Envelope element if no header ispresent.

Because the root element Envelope is uniquely identified by its namespace, it allowsprocessing tools to immediately determine whether a given XML document is a SOAP message.The main information the sender wants to transmit to the receiver should be in the body of themessage. Any additional information needed for intermediate processing or added-value services(e.g., authentication, security, transaction control, or tracing and auditing) goes into the header.This is the common approach for communication protocols. The header contains information that can be used by intermediate nodes along the SOAP message path. The payload or body is theactual message being conveyed. This is the reason why the header is optional.

Each of the SOAP elements Envelope, Header, or Body can include arbitrary number of<any> elements. Recall that the <any> element enables us to extend the XML document withelements not specified by the schema.

SOAP Message Example

An example SOAP message containing a SOAP header block and a SOAP body is given as:

<soap-env:Envelopexmlns:soap-env="http://www.w3.org/2003/05/soap-envelope"xmlns:xsd="http://www.w3.org/2001/XMLSchema"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><soap-env:Header><ac:alertcontrolxmlns:ac="http://example.org/alertcontrol" soap-env:mustUnderstand="1"><ac:priority>high</ac:priority><ac:expires>2006-22-00T14:00:00-05:00</ac:expires></ac:alertcontrol></soap-env:Header><soap-env:Body><a:notifyxmlns:a="http://example.org/alert"><a:note xsi:type="xsd:string"> 15 Reminder: meeting today at 11AM in Rm.601 </a:note></a:notify></soap-env:Body></soap-env:Envelope>

Listing 2-1: Example of a SOAP message.

The above SOAP message is a request for alert to a Web service. The request contains a text note(in the Body) and is marked (in the Header) to indicate that the message is high priority, butwill become obsolete after the given time. The details are as follows:

• Lines 1–2: Prefix soap-env, identifies SOAP-defined elements, namelyEnvelope, Header, and Body, as well as the attribute mustUnderstand (appears inLine 7).

• Line 3: Prefix xsd refers to XML Schema elements, in particular the built-in type string(appears in Line 15).

• Line 4: Prefix xsi refers to XML Schema instance type attribute, asserting the type of thenote as an XML Schema string (appears in Line 15).

• Line 7: The mustUnderstand attribute value “1” tells the Web service provider that itmust understand the semantics of the header block and that it must process the header. TheWeb service requestor demands express service delivery.

• Lines 12–18: The Body element encapsulates the service method invocation information,namely the method name notify, the method parameter note, its associated data type andits value.

SOAP message body blocks carry the information needed for the end recipient of a message. Therecipient must understand the semantics of all body blocks and must process them all. SOAP doesnot define the schema for body blocks since they are application specific. There is only oneSOAP-defined body block—the Fault element.

A SOAP message can pass through multiple nodes on its path. This includes the initial SOAPsender, zero or more SOAP intermediaries, and an ultimate SOAP receiver. SOAP intermediariesare applications that can process partsof a SOAP message as it travels fromthe sender to the receiver.

SOAP Intermediaries and Use cases

Intermediaries can both accept and forward (or relay, or route) SOAP messages. Three key use cases define the need for SOAP intermediaries:

1. crossing trust domains,
2. ensuring scalability, and
3. providing value-added services along the SOAP message path.

Crossing trust domains is acommon issue faced when implementing security in distributed systems. Corporate firewalls andvirtual private network (VPN) gateways let some requests cross the trust domain boundary anddeny access to others.

Similarly, ensuring scalability is an important requirement in distributed systems. We rarely havea simplistic scenario where the sender and receiver are directly connected by a dedicated link. Inreality, there will be several network nodes on the communication path that will be crossed bymany other concurrent communication flows. Due to the limited computing resources, theperformance of these nodes may not scale well with the increasing traffic load. To ensurescalability, the intermediate nodes need to provide flexible buffering of messages and routing based not only on message parameters, such as origin, destination, and priority, but also on thestate of the network measured by parameters such as the availability and load of its nodes as wellas network traffic information.

Lastly, we need intermediaries to provide value-added services in a distributed system. Exampleservices include authentication and authorization, security encryption, transaction management,message tracing and auditing, as well as billing and payment processing.

SOAP Message Global Attributes

SOAP defines three global attributes that are intended to be usable via qualified attribute nameson any complex type referencing them. The attributes are as follows:

• The mustUnderstand attribute specifies whether it is mandatory or optional that amessage receiver understands and processes the content of a SOAP header block. Themessage receiver to which this attribute refers to is named by the role attribute.
• The role attribute is exclusively related to header blocks. It names the application thatshould process the given header block.
• The encodingStyle attribute indicates the encoding rules used to serialize parts of aSOAP message. Although the SOAP specification allows this attribute to appear on anyelement of the message (including header blocks), it mostly applies to body blocks.
• The relay attribute is used to indicate whether a SOAP header block targeted at a SOAPreceiver must be relayed if not processed.

The mustUnderstand attribute can have values ‘1’ or ‘0’ (or, ‘true’ or ‘false’).Value ‘1’ indicates that the target role of this SOAP message must understand the semantics ofthe header block and process it. If this attribute is missing, this is equivalent to having value ‘0’.This value indicates that the target role may, but does not have to, process the header block.

The role attribute carries an URI value that names the recipient of a header block. This can bethe ultimate receiver or an intermediary node that should provide a value-added service to thismessage. The SOAP specification defines three roles: none, next, and ultimateReceiver. Anattribute value of http://www.w3.org/2003/05/soap-envelope/role/nextidentifies the next SOAP application on the message path as the role for the header block. Aheader without a role attribute is intended for the ultimate recipient of this message.

The encodingStyle attribute declares the mapping from an application-specific datarepresentation to the wire format. An encoding generally defines a data type and data mappingbetween two parties that have different data representation. The decoding converts the wirerepresentation of the data back to the application-specific data format. The translation step fromone data representation to another, and back to the original format, is called serialization anddeserialization. The terms marshaling and unmarshalling may be used as alternatives. The scopeof the encodingStyle attribute is that of its owner element and that element’s descendants,excluding the scope of the encodingStyle attribute on a nested element.

The relay attribute indicates whether a header block should be relayed in the forwardedmessage if the header block is targeted at a role played by the SOAP intermediary, but nototherwise processed by the intermediary. This attribute type is Boolean and, if omitted, it isequivalent as if included with a value of “false.”

Error Handling in SOAP: The Fault Body Block

If a network node encounters problems while processing a SOAP message, it generates a faultmessage and sends it back to the message sender, i.e., in the direction opposite to the originalmessage flow. The fault message contains a Fault element which identifies the source andcause of the error and allows error-diagnostic information to be exchanged between participantsin an interaction. Fault is optional and can appear at most once within the Body element. Thefault message originator can be an end host or an intermediary network node which was supposedto relay the original message. The content of the Fault element is slightly different in these twocases, as will be seen below.

A Fault element consists of the following nested elements

• The Code element specifies the failure type. Fault codes are identified via namespace-qualified names. SOAP predefines several generic fault codes and allows custom-definedfault codes, as described below.
• The Reason element carries a human-readable explanation of the message-processingfailure. It is a plain text of type string along with the attribute specifying the language thetext is written in.
• The Node element names the SOAP node (end host or intermediary) on the SOAP messagepath that caused the fault to happen. This node is the originator of the fault message.
• The Role element identifies the role the originating node was operating in at the point thefault occurred. Similar to the role attribute (described above), but instead of identifying therole of the recipient of a header block, it gives the role of the fault originator.
• The Detail element carries application-specific error information related to the Bodyelement and its sub-elements

SOAP Generic Fault Codes

As mentioned, SOAP predefines several generic fault codes. They must be namespace qualifiedand appear in a Code element. These are:

• VersionMismatch: The SOAP node received a message whose version is not supported,which is determined by the Envelope namespace. For example, thenode supports SOAP version 1.2, but the namespace qualification ofthe SOAP message Envelope element is not identical tohttp://www.w3.org/2003/05/soap-envelope.

• DataEncodingUnknown: A SOAP node to which a SOAP header block or SOAP body childelement information item was targeted was targeted does not supportthe data encoding indicated by the encodingStyle attribute.

• MustUnderstand: A SOAP node to which a header block was targeted could not process the header block, and the block contained amustUnderstand attribute value “true”.

• Sender: A SOAP message was not appropriately formed or did not contain allrequired information. For example, the message could lack the properauthentication or payment information. Resending this identicalmessage will again cause a failure.

• Receiver: A SOAP message could not be processed due to reasons not relatedto the message format or content. For example, processing couldinclude communicating with an upstream SOAP node, which did notrespond. Resending this identical message might succeed at somelater point in time.

SOAP allows custom extensions of fault codes through dot separators so that the right side of adot separator refines the more general information given on the left side. For example, the Codeelement conveying a sender authentication error would contain Sender.Authentication.SOAP does not require any further structure within the content placed in header or body blocks.Nonetheless, there are two aspects that influence how the header and body of a SOAP messageare constructed: encoding rules and communication styles . These are described in Chapter 3 and 4.

Licenses and Attributions