# The SOAP Message Format

## What is SOAP message?

A unit of communication in SOAP is a message. A SOAP message is an ordinary XML document containing 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 include any number of header blocks (simply referred to as headers); used to pass additional processing or control information (e.g., authentication, information related to transaction control, 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 simply as bodies)
• An optional Fault element that provides information about errors that occurred while processing the message

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

Because the root element Envelope is uniquely identified by its namespace, it allows processing 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 the message. 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 the actual 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 with elements 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:Envelope
xmlns: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">
<ac:priority>high</ac:priority>
<ac:expires>2006-22-00T14:00:00-05:00</ac:expires>
<soap-env:Body>
<a:notify
<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, but will become obsolete after the given time. The details are as follows:

• Lines 1–2: Prefix soap-env, identifies SOAP-defined elements, namely Envelope, Header, and Body, as well as the attribute mustUnderstand (appears in Line 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 the note as an XML Schema string (appears in Line 15).

• Line 7: The mustUnderstand attribute value “1” tells the Web service provider that it must understand the semantics of the header block and that it must process the header. The Web 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 and its value.

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

A SOAP message can pass through multiple nodes on its path. This includes the initial SOAP sender, zero or more SOAP intermediaries, and an ultimate SOAP receiver. SOAP intermediaries are applications that can process parts of a SOAP message as it travels from the 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 a common issue faced when implementing security in distributed systems. Corporate firewalls and virtual private network (VPN) gateways let some requests cross the trust domain boundary and deny access to others.

Similarly, ensuring scalability is an important requirement in distributed systems. We rarely have a simplistic scenario where the sender and receiver are directly connected by a dedicated link. In reality, there will be several network nodes on the communication path that will be crossed by many other concurrent communication flows. Due to the limited computing resources, the performance of these nodes may not scale well with the increasing traffic load. To ensure scalability, 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 the state of the network measured by parameters such as the availability and load of its nodes as well as network traffic information.

Lastly, we need intermediaries to provide value-added services in a distributed system. Example services 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 names on any complex type referencing them. The attributes are as follows:

• The mustUnderstand attribute specifies whether it is mandatory or optional that a message receiver understands and processes the content of a SOAP header block. The message 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 that should process the given header block.
• The encodingStyle attribute indicates the encoding rules used to serialize parts of a SOAP message. Although the SOAP specification allows this attribute to appear on any element 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 SOAP receiver 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 of the 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 be the ultimate receiver or an intermediary node that should provide a value-added service to this message. The SOAP specification defines three roles: none, next, and ultimateReceiver. An attribute value of http://www.w3.org/2003/05/soap-envelope/role/next identifies the next SOAP application on the message path as the role for the header block. A header without a role attribute is intended for the ultimate recipient of this message.

The encodingStyle attribute declares the mapping from an application-specific data representation to the wire format. An encoding generally defines a data type and data mapping between two parties that have different data representation. The decoding converts the wire representation of the data back to the application-specific data format. The translation step from one data representation to another, and back to the original format, is called serialization and deserialization. The terms marshaling and unmarshalling may be used as alternatives. The scope of 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 forwarded message if the header block is targeted at a role played by the SOAP intermediary, but not otherwise processed by the intermediary. This attribute type is Boolean and, if omitted, it is equivalent 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 fault message and sends it back to the message sender, i.e., in the direction opposite to the original message flow. The fault message contains a Fault element which identifies the source and cause of the error and allows error-diagnostic information to be exchanged between participants in an interaction. Fault is optional and can appear at most once within the Body element. The fault message originator can be an end host or an intermediary network node which was supposed to relay the original message. The content of the Fault element is slightly different in these two cases, 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-defined fault codes, as described below.
• The Reason element carries a human-readable explanation of the message-processing failure. It is a plain text of type string along with the attribute specifying the language the text is written in.
• The Node element names the SOAP node (end host or intermediary) on the SOAP message path 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 the fault occurred. Similar to the role attribute (described above), but instead of identifying the role 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 Body element and its sub-elements

### SOAP Generic Fault Codes

As mentioned, SOAP predefines several generic fault codes. They must be namespace qualified and 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, the node supports SOAP version 1.2, but the namespace qualification of the SOAP message Envelope element is not identical to http://www.w3.org/2003/05/soap-envelope.

• DataEncodingUnknown: A SOAP node to which a SOAP header block or SOAP body child element information item was targeted was targeted does not support the 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 a mustUnderstand attribute value “true”.

• Sender: A SOAP message was not appropriately formed or did not contain all required information. For example, the message could lack the proper authentication or payment information. Resending this identical message will again cause a failure.

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

SOAP allows custom extensions of fault codes through dot separators so that the right side of a dot separator refines the more general information given on the left side. For example, the Code element 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 message are constructed: encoding rules and communication styles . These are described in Chapter 3 and 4.