SOAP Version 1.2 Part 1: Messaging Framework (Second Edition)

1.1 Notational Conventions

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC 2119].

This specification uses a number of namespace prefixes throughout; they are listed in Table 1. Note that the choice of any namespace prefix is arbitrary and not semantically significant (see XML Infoset [XML InfoSet]).

Namespace names of the general form "http://example.org/..." and "http://example.com/..." represent application or context-dependent URIs (see RFC 3986 [RFC 3986]).

All parts of this specification are normative, with the exception of examples and sections explicitly marked as "Non-Normative".

1.2 Conformance

This specification describes data formats, and the rules for generating, exchanging, and processing messages using those formats. This specification does not mandate the scope of any particular implementation, although it requires that no implementation violates any mandatory requirement.

For an implementation to claim conformance with the SOAP Version 1.2 specification, it MUST correctly implement all mandatory ("MUST") requirements expressed in Part 1 of the SOAP Version 1.2 specification (this document) that pertain to the activity being performed. Note that an implementation is not mandated to implement all the mandatory requirements. For example, a special purpose implementation that never sends a SOAP header block can claim conformance provided that it correctly implements the mandatory requirements that pertain to the messages it does send.

An implementation MAY implement any number of the Adjuncts specified in SOAP 1.2 Part 2 [SOAP Part 2]. Note that no conformance is associated with the convention for describing features and bindings (see 3. SOAP Extensibility Model and 4. SOAP Protocol Binding Framework). The implementation of an Adjunct MUST implement all the pertinent mandatory requirements expressed in the specification of the Adjunct to claim conformance with the Adjunct.

SOAP Version 1.2 can be used as the basis for other technologies that provide richer or more specialized services. To claim conformance with the SOAP Version 1.2 specification, the specifications and implementations of such technologies must be consistent with the pertinent mandatory requirements expressed in Part 1 of the SOAP Version 1.2 specification (this document). Rules for conformance with such new specifications are beyond the scope of the SOAP Version 1.2 specification; it is recommended that specifications for such technologies provide the appropriate conformance rules.

SOAP Version 1.2 is designed to enable at least the usage scenarios described in SOAP 1.2 Usage Scenarios [SOAP Usage Scenarios], and possibly other scenarios. Informal descriptions showing XML representations of concrete SOAP messages used in some common scenarios are provided in SOAP 1.2 Part 0 [SOAP Part 0].

1.3 Relation to Other Specifications

A SOAP message is specified as an XML Information Set [XML InfoSet]. While all SOAP message examples in this document are shown using XML 1.0 [XML 1.0] syntax, other representations MAY be used to transmit SOAP messages between nodes (see 4. SOAP Protocol Binding Framework).

Some of the information items defined by this document (see 5. SOAP Message Construct) are identified using namespace-qualified names [Namespaces in XML]. See Table 1 for a list of the namespace names defined in this document.

SOAP does not require that XML Schema processing (assessment or validation) be performed to establish the correctness or 'schema implied' values of element and attribute information items defined by Parts 1 and 2 of this specification. The values associated with element and attribute information items defined in this specification MUST be carried explicitly in the transmitted SOAP message except where stated otherwise (see 5. SOAP Message Construct).

SOAP attribute information items have types described by XML Schema [XML Schema Part 2]. Unless otherwise stated, all lexical forms are supported for each such attribute, and lexical forms representing the same value in the XML Schema value space are considered equivalent for purposes of SOAP processing, e.g., the boolean lexical forms "1" and "true" are interchangeable. For brevity, text in this specification refers only to one lexical form for each value, e.g., "if the value of the mustUnderstand attribute information item is 'true'".

Specifications for the processing of application-defined data carried in a SOAP message but not defined by this specification MAY call for additional validation of the SOAP message in conjunction with application-level processing. In such cases, the choice of schema language and/or validation technology is at the discretion of the application.

SOAP uses XML Base [XML Base] for determining a base URI for relative URI references used as values in information items defined by this specification (see 6. Use of URIs in SOAP).

The media type "application/soap+xml" SHOULD be used for XML 1.0 serializations of the SOAP message infoset (see SOAP 1.2 Part 2 [SOAP Part 2], The "application/soap+xml" Media Type).

1.4 Example SOAP Message

The following example shows a sample notification message expressed in SOAP. The message contains two pieces of application-defined data not defined by this specification: a SOAP header block with a local name of alertcontrol and a body element with a local name of alert . In general, SOAP header blocks contain information which might be of use to SOAP intermediaries as well as the ultimate destination of the message. In this example an intermediary might prioritize the delivery of the message based on the priority and expiration information in the SOAP header block. The body contains the actual message payload, in this case the alert message.

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
 <env:Header>
  <n:alertcontrol xmlns:n="http://example.org/alertcontrol">
   <n:priority>1</n:priority>
   <n:expires>2001-06-22T14:00:00-05:00</n:expires>
  </n:alertcontrol>
 </env:Header>
 <env:Body>
  <m:alert xmlns:m="http://example.org/alert">
   <m:msg>Pick up Mary at school at 2pm</m:msg>
  </m:alert>
 </env:Body>
</env:Envelope>

1.5 SOAP Terminology

This section describes the terms and concepts introduced in Part 1 of the SOAP Version 1.2 specification (this document).

2.1 SOAP Nodes

A SOAP node can be the initial SOAP sender, an ultimate SOAP receiver, or a SOAP intermediary. A SOAP node receiving a SOAP message MUST perform processing according to the SOAP processing model as described in this section and in the remainder of this specification. A SOAP node is identified by a URI, see 5.4.3 SOAP Node Element

2.2 SOAP Roles and SOAP Nodes

In processing a SOAP message, a SOAP node is said to act in one or more SOAP roles, each of which is identified by a URI known as the SOAP role name. The roles assumed by a node MUST be invariant during the processing of an individual SOAP message. This specification deals only with the processing of individual SOAP messages. No statement is made regarding the possibility that a given SOAP node might or might not act in varying roles when processing more than one SOAP message.

Table 2 defines three role names which have special significance in a SOAP message (see 2.6 Processing SOAP Messages).

In addition to the SOAP role names defined in Table 2, other role names MAY be used as necessary to meet the needs of SOAP applications.

While the purpose of a SOAP role name is to identify a SOAP node or nodes, there are no routing or message exchange semantics associated with the SOAP role name. For example, SOAP roles MAY be named with a URI useable to route SOAP messages to an appropriate SOAP node. Conversely, it is also appropriate to use SOAP roles with names that are related more indirectly to message routing (e.g., "http://example.org/banking/anyAccountMgr") or which are unrelated to routing (e.g., a URI meant to identify "all cache management software". For example, a SOAP header block targeted at such a role might be used to carry an indication to any concerned software that the containing SOAP message is idempotent, and can safely be cached and replayed).

With the exception of the three SOAP role names defined in Table 2, this specification does not prescribe the criteria by which a given node determines the set of roles in which it acts on a given message. For example, implementations can base this determination on factors including, but not limited to: hard coded choices in the implementation, information provided by the underlying protocol binding (e.g., the URI to which the message was physically delivered), or configuration information provided by users during system installation.

2.3 Targeting SOAP Header Blocks

A SOAP header block MAY carry a role attribute information item (see 5.2.2 SOAP role Attribute) that is used to target the header block at SOAP nodes operating in the specified role. This specification refers to the value of the SOAP role attribute information item as the SOAP role for the corresponding SOAP header block.

A SOAP header block is said to be targeted at a SOAP node if the SOAP role for the header block is the name of a role in which the SOAP node operates. SOAP header blocks targeted at the special role "http://www.w3.org/2003/05/soap-envelope/role/none" are never formally processed. Such SOAP header blocks MAY carry data that is required for processing of other SOAP header blocks. Unless removed by the action of an intermediary (see 2.7 Relaying SOAP Messages) , such blocks are relayed with the message to the ultimate receiver (see also 3.3 SOAP Modules).

2.4 Understanding SOAP Header Blocks

It is likely that specifications for a wide variety of header functions (i.e., SOAP modules) will be developed over time (see 3.3 SOAP Modules), and that some SOAP nodes might include the software necessary to implement one or more such extensions. A SOAP header block is said to be understood by a SOAP node if the software at that SOAP node has been written to fully conform to and implement the semantics specified for the XML expanded name of the outer-most element information item of that header block.

A SOAP header block MAY carry a mustUnderstand attribute information item (see 5.2.3 SOAP mustUnderstand Attribute). When the value of such an attribute information item is "true", the SOAP header block is said to be mandatory.

Mandatory SOAP header blocks are presumed to somehow modify the semantics of other SOAP header blocks or SOAP body elements. Therefore, for every mandatory SOAP header block targeted to a node, that node MUST either process the header block or not process the SOAP message at all, and instead generate a fault (see 2.6 Processing SOAP Messages and 5.4 SOAP Fault). Tagging SOAP header blocks as mandatory thus assures that such modifications will not be silently (and, presumably, erroneously) ignored by a SOAP node to which the header block is targeted.

The mustUnderstand attribute information item is not intended as a mechanism for detecting errors in routing, misidentification of nodes, failure of a node to serve in its intended role(s), etc. Any of these conditions can result in a failure to even attempt processing of a given SOAP header block from a SOAP envelope. This specification therefore does not require any fault to be generated based on the presence or value of the mustUnderstand attribute information item on a SOAP header block not targeted at the current processing node. In particular, it is not an error for an ultimate SOAP receiver to receive a message containing a mandatory SOAP header block that is targeted at a role other than the ones assumed by the ultimate SOAP receiver. This is the case, for example, when a SOAP header block has survived erroneously due to a routing or targeting error at a preceding intermediary.

2.5 Structure and Interpretation of SOAP Bodies

An ultimate SOAP receiver MUST correctly process the immediate children of the SOAP body (see 5.3 SOAP Body). However, with the exception of SOAP faults (see 5.4 SOAP Fault), Part 1 of this specification (this document) mandates no particular structure or interpretation of these elements, and provides no standard means for specifying the processing to be done.

2.6 Processing SOAP Messages

This section sets out the rules by which SOAP messages are processed. Nothing in this specification prevents the use of optimistic concurrency, roll back, or other techniques that might provide increased flexibility in processing order. Unless otherwise stated, processing of all generated SOAP messages, SOAP faults and application-level side effects MUST be semantically equivalent to performing the following steps separately, and in the order given.

1. Determine the set of roles in which the node is to act. The contents of the SOAP envelope, including any SOAP header blocks and the SOAP body, MAY be inspected in making such determination.

2. Identify all header blocks targeted at the node that are mandatory.

3. If one or more of the SOAP header blocks identified in the preceding step are not understood by the node then generate a single SOAP fault with the Value of Code set to "env:MustUnderstand" (see 5.4.8 SOAP mustUnderstand Faults). If such a fault is generated, any further processing MUST NOT be done. Faults relating to the contents of the SOAP body MUST NOT be generated in this step.

   Note:

   Throughout this document, the term "Value of Code " is used as a shorthand for "value of the Value child element information item of the Code element information item" (see 5.4.1 SOAP Code Element).

4. Process all mandatory SOAP header blocks targeted at the node and, in the case of an ultimate SOAP receiver, the SOAP body. A SOAP node MAY also choose to process non-mandatory SOAP header blocks targeted at it.

5. In the case of a SOAP intermediary, and where the SOAP message exchange pattern and results of processing (e.g., no fault generated) require that the SOAP message be sent further along the SOAP message path, relay the message as described in section 2.7 Relaying SOAP Messages.

In all cases where a SOAP header block is processed, the SOAP node MUST understand the SOAP header block and MUST do such processing in a manner fully conformant with the specification for that header block. The successful processing of one header block does not guarantee successful processing of another block with the same XML expanded name within the same message: the specification for the header block determines the circumstances in which such processing would result in a fault. An ultimate SOAP receiver MUST process the SOAP body, in a manner consistent with 2.5 Structure and Interpretation of SOAP Bodies.

Failure is indicated by the generation of a fault (see 5.4 SOAP Fault). SOAP message processing MAY result in the generation of a SOAP fault; more than one SOAP fault MUST NOT be generated when processing a SOAP message.

A message may contain or result in multiple errors during processing. Except where the order of detection is specifically indicated (as in 2.4 Understanding SOAP Header Blocks), a SOAP node is at liberty to reflect any single fault from the set of possible faults prescribed for the errors encountered. The selection of a fault need not be predicated on the application of the "MUST", "SHOULD" or "MAY" keywords to the generation of the fault, with the exception that if one or more of the prescribed faults is qualified with the "MUST" keyword, then any one fault from the set of possible faults MUST be generated.

SOAP nodes MAY make reference to any information in the SOAP envelope when processing a SOAP body or SOAP header block. For example, a caching function can cache the entire SOAP message, if desired.

The processing of one or more SOAP header blocks MAY control or determine the order of processing for other SOAP header blocks and/or the SOAP body. For example, one could create a SOAP header block to force processing of other SOAP header blocks in lexical order. In the absence of such a controlling SOAP header block, the order of header and body processing is at the discretion of the SOAP node. Header blocks MAY be processed in arbitrary order. Header block processing MAY precede, MAY be interleaved with, or MAY follow processing of the SOAP body. For example, processing of a "begin transaction" header block would typically precede body processing, a "logging" function might run concurrently with body processing and a "commit transaction" header block might be honored following completion of all other work.

2.7 Relaying SOAP Messages

As mentioned earlier in this section, it is assumed that a SOAP message originates at an initial SOAP sender and is sent to an ultimate SOAP receiver via zero or more SOAP intermediaries. While SOAP does not itself define any routing or forwarding semantics, it is anticipated that such functionality can be described as one or more SOAP features (see 3. SOAP Extensibility Model). The purpose of this section is to describe how message forwarding interacts with the SOAP distributed processing model.

SOAP defines two different types of intermediaries: forwarding intermediaries and active intermediaries. These two types of intermediary are described in this section.

2.8 SOAP Versioning Model

The version of a SOAP message is identified by the XML expanded name of the child element information item of the document information item. A SOAP Version 1.2 message has a child element information item of the document information item with a [local name] of Envelope and a [namespace name] of "http://www.w3.org/2003/05/soap-envelope" (see 5.1 SOAP Envelope).

A SOAP node determines whether it supports the version of a SOAP message on a per message basis. In this context "support" means understanding the semantics of that version of a SOAP envelope. The versioning model is directed only at the SOAP Envelope element information item. It does not address versioning of SOAP header blocks, encodings, protocol bindings, or anything else.

A SOAP node MAY support multiple envelope versions. However, when processing a message, a SOAP node MUST use the semantics defined by the version of that message.

If a SOAP node receives a message whose version is not supported it MUST generate a fault (see 5.4 SOAP Fault) with a Value of Code set to "env:VersionMismatch". Any other malformation of the message construct MUST result in the generation of a fault with a Value of Code set to "env:Sender".

Appendix A. Version Transition From SOAP/1.1 to SOAP Version 1.2 defines a mechanism for transitioning from SOAP/1.1 to SOAP Version 1.2 using the Upgrade element information item (see 5.4.7 VersionMismatch Faults).

3.1 SOAP Features

A SOAP feature is an extension of the SOAP messaging framework. Although SOAP poses no constraints on the potential scope of such features, example features may include "reliability", "security", "correlation", "routing", and message exchange patterns (MEPs) such as request/response, one-way, and peer-to-peer conversations.

The SOAP extensibility model provides two mechanisms through which features can be expressed: the SOAP Processing Model and the SOAP Protocol Binding Framework (see 2. SOAP Processing Model and 4. SOAP Protocol Binding Framework). The former describes the behavior of a single SOAP node with respect to the processing of an individual message. The latter mediates the act of sending and receiving SOAP messages by a SOAP node via an underlying protocol.

The SOAP Processing Model enables SOAP nodes that include the mechanisms necessary to implement one or more features to express such features within the SOAP envelope as SOAP header blocks (see 2.4 Understanding SOAP Header Blocks). Such header blocks can be intended for any SOAP node or nodes along a SOAP message path (see 2.3 Targeting SOAP Header Blocks). The combined syntax and semantics of SOAP header blocks are known as a SOAP module, and are specified according to the rules in 3.3 SOAP Modules.

In contrast, a SOAP protocol binding operates between two adjacent SOAP nodes along a SOAP message path. There is no requirement that the same underlying protocol is used for all hops along a SOAP message path. In some cases, underlying protocols are equipped, either directly or through extension, with mechanisms for providing certain features. The SOAP Protocol Binding Framework provides a scheme for describing these features and how they relate to SOAP nodes through a binding specification (see 4. SOAP Protocol Binding Framework).

Certain features might require end-to-end as opposed to hop-by-hop processing semantics. Although the SOAP Protocol Binding Framework allows end-to-end features to be expressed outside the SOAP envelope, no standard mechanism is provided for the processing by intermediaries of the resulting messages. A binding specification that expresses such features external to the SOAP envelope needs to define its own processing rules for those externally expressed features. A SOAP node is expected to conform to these processing rules (for example, describing what information is passed along with the SOAP message as it leaves the intermediary). The processing of SOAP envelopes in accordance with the SOAP Processing Model (see 2. SOAP Processing Model) MUST NOT be overridden by binding specifications.

It is recommended that, where practical, end-to-end features be expressed as SOAP header blocks, so that the rules defined by the SOAP Processing Model can be employed.

3.2 SOAP Message Exchange Patterns (MEPs)

A Message Exchange Pattern (MEP) is a template that establishes a pattern for the exchange of messages between SOAP nodes. MEPs are a type of feature, and unless otherwise stated, references in this specification to the term "feature" apply also to MEPs. The request-response MEP specified in SOAP 1.2 Part 2 [SOAP Part 2] illustrates the specification of a MEP feature.

The specification of a message exchange pattern MUST:

• As mandated by 3.1.1 Requirements on Features, provide a URI to name the MEP.

• Describe the life cycle of a message exchange conforming to the pattern.

• Describe the temporal/causal relationships, if any, of multiple messages exchanged in conformance with the pattern (e.g., responses follow requests and are sent to the originator of the request.)

• Describe the normal and abnormal termination of a message exchange conforming to the pattern.

Underlying protocol binding specifications can declare their support for one or more named MEPs.

MEPs are SOAP features, so an MEP specification MUST conform to the requirements for SOAP feature specifications (see 3.1.1 Requirements on Features). An MEP specification MUST also include:

1. Any requirements to generate additional messages (such as responses to requests in a request/response MEP).

2. Rules for the delivery or other disposition of SOAP faults generated during the operation of the MEP.

3.3 SOAP Modules

The term "SOAP module" refers to the specification of the syntax and semantics of one or more SOAP header blocks. A SOAP module realizes zero or more SOAP features. A module specification adheres to the following rules. It:

1. MUST identify itself with a URI. This enables the module to be unambiguously referenced in description languages or during negotiation.

2. MUST declare the features provided by a module (see 3.1 SOAP Features).

3. MUST clearly and completely specify the content and semantics of the SOAP header blocks used to implement the behavior in question, including if appropriate any modifications to the SOAP processing model. The SOAP extensibility model does not limit the extent to which SOAP can be extended. Nor does it prevent extensions from modifying the SOAP processing model from that described in 2. SOAP Processing Model

4. MAY utilize the property conventions defined in SOAP 1.2 Part 2 [SOAP Part 2], section A Convention for Describing Features and Bindings, in describing the functionality that the module provides. If these conventions are followed, the module specification MUST clearly describe the relationship between the abstract properties and their representations in the SOAP envelope. Note that it is possible to write a feature specification purely in terms of abstract properties, and then write a separate module specification which implements that feature, mapping the properties defined in the feature specification to SOAP header blocks in the SOAP module.

5. MUST clearly specify any known interactions with or changes to the interpretation of the SOAP body. Furthermore, it MUST clearly specify any known interactions with or changes to the interpretation of other SOAP features and SOAP modules. For example, we can imagine a module which encrypts and removes the SOAP body, inserting instead a SOAP header block containing a checksum and an indication of the encryption mechanism used. The specification for such a module would indicate that the decryption algorithm on the receiving side is to be run prior to any other modules which rely on the contents of the SOAP body.

4.1 Goals of the Binding Framework

The goals of the binding framework are:

1. To set out the requirements and concepts that are common to all binding specifications.

2. To facilitate homogeneous description in situations where multiple bindings support common features, promoting reuse across bindings.

3. To facilitate consistency in the specification of optional features.

Two or more bindings can offer a given optional feature, such as reliable delivery, using different means. One binding might exploit an underlying protocol that directly facilitates the feature (e.g., the protocol is reliable), and the other binding might provide the necessary logic itself (e.g., reliability is achieved via logging and retransmission). In such cases, the feature can be made available to applications in a consistent manner, regardless of which binding is used.

4.2 Binding Framework

The creation, transmission, and processing of a SOAP message, possibly through one or more intermediaries, is specified in terms of a distributed state machine. The state consists of information known to a SOAP node at a given point in time, including but not limited to the contents of messages being assembled for transmission or received for processing. The state at each node can be updated either by local processing, or by information received from an adjacent node.

Section 2. SOAP Processing Model of this specification describes the processing that is common to all SOAP nodes when receiving a message. The purpose of a binding specification is to augment those core SOAP rules with additional processing that is particular to the binding, and to specify the manner in which the underlying protocol is used to transmit information between adjacent nodes in the message path.

The distributed state machine that manages the transmission of a given SOAP message through its message path is the combination of the core SOAP processing (see 2. SOAP Processing Model) operating at each node, in conjunction with the binding specifications connecting each pair of nodes. A binding specification MUST enable one or more MEPs.

In cases where multiple features are supported by a binding specification, the specifications for those features MUST provide any information necessary for their successful use in combination. Similarly, any dependencies of one feature on another (i.e., if successful use of one feature depends on use or non-use of another) MUST be specified. This binding framework does not provide any explicit mechanism for controlling the use of such interdependent features.

The binding framework provides no fixed means of naming or typing the information comprising the state at a given node. Individual feature and binding specifications are free to adopt their own conventions for specifying state. Note, however, that consistency across bindings and features is likely to be enhanced in situations where multiple feature specifications adopt consistent conventions for representing state. For example, multiple features might benefit from a consistent specification for an authentication credential, a transaction ID, etc. The HTTP binding in SOAP 1.2 Part 2 [SOAP Part 2] illustrates one such convention.

As described in 5. SOAP Message Construct, each SOAP message is specified as an XML infoset that consists of a document information item with exactly one child: the SOAP Envelope element information item. Therefore, the minimum responsibility of a binding in transmitting a message is to specify the means by which the SOAP message infoset is transferred to and reconstituted by the binding at the receiving SOAP node and to specify the manner in which the transmission of the envelope is effected using the facilities of the underlying protocol.

5. SOAP Message Construct provides that all SOAP envelopes are serializable using an XML 1.0 serialization, so XML 1.0 or later versions of XML MAY be used by bindings as the "on the wire" representation of the XML Infoset. However, the binding framework does not require that every binding use an XML serialization for transmission; compressed, encrypted, fragmented representations and so on can be used if appropriate. A binding, if using an XML serialization of the XML infoset, MAY mandate that a particular character encoding or set of encodings be used.

A binding, if using a XML serialization, must list the versions of XML used to serialize the infoset, or if it delegates this to other means (like media type description). To preserve interoperability, the list of supported XML versions should be exhaustive.

Bindings MAY provide for streaming when processing messages. That is, SOAP nodes MAY begin processing a received SOAP message as soon as the necessary information is available. SOAP processing is specified in terms of SOAP message infosets (see 5. SOAP Message Construct). Although streaming SOAP receivers will acquire such XML infosets incrementally, SOAP processing MUST yield results identical to those that would have been achieved if the entire SOAP envelope were available prior to the start of processing. For example, as provided in 2.6 Processing SOAP Messages, identification of targeted SOAP header blocks, and checking of all mustUnderstand attributes is to be done before successful processing can proceed. Depending on the representation used for the XML infoset, and the order in which it is transmitted, this rule might limit the degree to which streaming can be achieved.

Bindings MAY depend on state that is modeled as being outside of the SOAP message infoset (e.g., retry counts), and MAY transmit such information to adjacent nodes. For example, some bindings take a message delivery address (typically a URI) that is not within the envelope.

5.1 SOAP Envelope

The SOAP Envelope element information item has:

• A [local name] of Envelope .

• A [namespace name] of "http://www.w3.org/2003/05/soap-envelope".

• Zero or more namespace-qualified attribute information items amongst its [attributes] property.

• One or two element information items in its [children] property in order as follows:

  1. An optional Header element information item (see 5.2 SOAP Header).

  2. A mandatory Body element information item (see 5.3 SOAP Body).

"http://www.w3.org/2003/05/soap-encoding"
"http://example.org/encoding/"
"http://www.w3.org/2003/05/soap-envelope/encoding/none"

5.2 SOAP Header

The SOAP Header element information item provides a mechanism for extending a SOAP message in a decentralized and modular way (see 3. SOAP Extensibility Model and 2.4 Understanding SOAP Header Blocks).

The Header element information item has:

• A [local name] of Header .

• A [namespace name] of "http://www.w3.org/2003/05/soap-envelope".

• Zero or more namespace-qualified attribute information items in its [attributes] property.

• Zero or more namespace-qualified element information items in its [children] property.

Each child element information item of the SOAP Header is called a SOAP header block.

<env:Header xmlns:env="http://www.w3.org/2003/05/soap-envelope" >
 <t:Transaction xmlns:t="http://example.org/2001/06/tx" 
                env:mustUnderstand="true" >
   5
 </t:Transaction>
</env:Header>

5.3 SOAP Body

A SOAP body provides a mechanism for transmitting information to an ultimate SOAP receiver (see 2.5 Structure and Interpretation of SOAP Bodies).

The Body element information item has:

• A [local name] of Body .

• A [namespace name] of "http://www.w3.org/2003/05/soap-envelope".

• Zero or more namespace-qualified attribute information items in its [attributes] property.

• Zero or more namespace-qualified element information items in its [children] property.

The Body element information item MAY have any number of character information item children. The character code of such character information items MUST be amongst the white space characters as defined by XML 1.0 [XML 1.0]. These are considered significant.

5.4 SOAP Fault

A SOAP fault is used to carry error information within a SOAP message.

The Fault element information item has:

• A [local name] of Fault .

• A [namespace name] of "http://www.w3.org/2003/05/soap-envelope".

• Two or more child element information items in its [children] property in order as follows:

  1. A mandatory Code element information item (see 5.4.1 SOAP Code Element).

  2. A mandatory Reason element information item (see 5.4.2 SOAP Reason Element).

  3. An optional Node element information item (see 5.4.3 SOAP Node Element).

  4. An optional Role element information item (see 5.4.4 SOAP Role Element).

  5. An optional Detail element information item (see 5.4.5 SOAP Detail Element).

To be recognized as carrying SOAP error information, a SOAP message MUST contain a single SOAP Fault element information item as the only child element information item of the SOAP Body .

When generating a fault, SOAP senders MUST NOT include additional element information items in the SOAP Body . A message whose Body contains a Fault plus additional element information items has no SOAP-defined semantics.

A SOAP Fault element information item MAY appear within a SOAP header block, or as a descendant of a child element information item of the SOAP Body ; in such cases, the element has no SOAP-defined semantics.

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"
              xmlns:m="http://www.example.org/timeouts"
              xmlns:xml="http://www.w3.org/XML/1998/namespace">
 <env:Body>
  <env:Fault>
   <env:Code>
     <env:Value>env:Sender</env:Value>
     <env:Subcode>
      <env:Value>m:MessageTimeout</env:Value>
     </env:Subcode>
   </env:Code>
   <env:Reason>
     <env:Text xml:lang="en">Sender Timeout</env:Text>
   </env:Reason>
   <env:Detail>
     <m:MaxTime>P5M</m:MaxTime>
   </env:Detail>    
  </env:Fault>
 </env:Body>
</env:Envelope>

<?xml version="1.0" ?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"
              xmlns:xml="http://www.w3.org/XML/1998/namespace">
 <env:Header>
  <env:Upgrade>
   <env:SupportedEnvelope qname="ns1:Envelope" 
             xmlns:ns1="http://www.w3.org/2003/05/soap-envelope"/>
   <env:SupportedEnvelope qname="ns2:Envelope" 
             xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/"/>
  </env:Upgrade>
 </env:Header>
 <env:Body>
  <env:Fault>
   <env:Code><env:Value>env:VersionMismatch</env:Value></env:Code>
    <env:Reason>
      <env:Text xml:lang="en">Version Mismatch</env:Text>
    </env:Reason>
   </env:Fault>
 </env:Body>
</env:Envelope>

<?xml version="1.0" ?>
<env:Envelope xmlns:env='http://www.w3.org/2003/05/soap-envelope'>
  <env:Header>
    <abc:Extension1 xmlns:abc='http://example.org/2001/06/ext'
       env:mustUnderstand='true'/>
    <def:Extension2 xmlns:def='http://example.com/stuff'
       env:mustUnderstand='true' />
  </env:Header>
  <env:Body>
    . . .
  </env:Body>
</env:Envelope>

<?xml version="1.0" ?>
<env:Envelope xmlns:env='http://www.w3.org/2003/05/soap-envelope'
              xmlns:xml='http://www.w3.org/XML/1998/namespace'>
 <env:Header>
  <env:NotUnderstood qname='abc:Extension1'
                   xmlns:abc='http://example.org/2001/06/ext' />
  <env:NotUnderstood qname='def:Extension2'
                   xmlns:def='http://example.com/stuff' />
 </env:Header>
 <env:Body>
  <env:Fault>
   <env:Code><env:Value>env:MustUnderstand</env:Value></env:Code>
   <env:Reason>
     <env:Text xml:lang='en'>One or more mandatory 
       SOAP header blocks not understood
     </env:Text>
   </env:Reason>
  </env:Fault>
 </env:Body>
</env:Envelope>

7.1 SOAP Nodes

SOAP can carry application-defined data as SOAP header blocks or as SOAP body contents. Processing a SOAP header block might include dealing with side effects such as state changes, logging of information, or the generation of additional messages. It is strongly recommended that, for any deployment scenario, only carefully specified SOAP header blocks with well understood security implications of any side effects be processed by a SOAP node.

Similarly, processing the SOAP body might imply the occurrence of side effects that could, if not properly understood, have severe consequences for the receiving SOAP node. It is strongly recommended that only well-defined body contents with known security implications be processed.

Security considerations, however, are not just limited to recognizing the immediate child elements of a SOAP header block and the SOAP body. Implementors need to pay special attention to the security implications of all data carried within a SOAP message that can cause the remote execution of any actions in the receiver's environment. This includes not only data expressed as XML infoset properties but data that might be encoded as property values including binary data or parameters, for example URI query strings. Before accepting data of any type, an application ought to be aware of the particular security implications associated with that data within the context it is being used.

SOAP implementors need to be careful to ensure that if processing of the various parts of a SOAP message is provided through modular software architecture, that each module is aware of the overall security context. For example, the SOAP body ought not to be processed without knowing the context in which it was received.

7.2 SOAP Intermediaries

SOAP inherently provides a distributed processing model that might involve a SOAP message passing through multiple SOAP nodes (see 2. SOAP Processing Model). SOAP intermediaries are by definition men in the middle, and represent an opportunity for man-in-the-middle attacks. Security breaches on systems that run SOAP intermediaries can result in serious security and privacy problems. A compromised SOAP intermediary, or an intermediary implemented or configured without regard to security and privacy considerations, might be used in the commission of a wide range of potential attacks.

In analyzing the security implications of potential SOAP-related security problems, it is important to realize that the scope of security mechanisms provided by the underlying protocol might not be the same scope as the whole message path of the SOAP message. There is no requirement in SOAP that all hops between participating SOAP nodes use the same underlying protocol and even if this were the case, the very use of SOAP intermediaries is likely to reach beyond the scope of transport-level security.

7.3 Underlying Protocol Bindings

The effects on security of not implementing a MUST or SHOULD, or doing something the specification says MUST NOT or SHOULD NOT be done can be very subtle. Binding specification authors ought to describe, in detail, the security implications of not following recommendations or requirements as most implementors will not have had the benefit of the experience and discussion that produced the specification (see 4. SOAP Protocol Binding Framework).

In addition, a binding specification might not address or provide countermeasures for all aspects of the inherent security risks. The binding specification authors ought to identify any such risks as might remain and indicate where further countermeasures would be needed above and beyond those provided for in the binding specification.

Authors of binding specifications need to be aware that SOAP extension modules expressed as SOAP header blocks could affect the underlying protocol in unforeseen ways. A SOAP message carried over a particular protocol binding might result in seemingly conflicting features. An example of this is a SOAP message carried over HTTP, using the HTTP basic authentication mechanism in combination with a SOAP-based authentication mechanism. It is strongly recommended that a binding specification describes any such interactions between the extensions and the underlying protocols.

8.1 Normative References

[SOAP Part 2]

SOAP Version 1.2 Part 2: Adjuncts (Second Edition), Martin Gudgin, Marc Hadley, Noah Mendelsohn, Jean-Jacques Moreau, Henrik Frystyk Nielsen, Anish Karmarkar, Yves Lafon, Editors. World Wide Web Consortium, 27 April 2007. This version is http://www.w3.org/TR/2007/REC-soap12-part2-20070427. The latest version is available at http://www.w3.org/TR/soap12-part2/.

[RFC 2616]

Hypertext Transfer Protocol -- HTTP/1.1, R. Fielding, J. Gettys, J. C. Mogul, H. Frystyk Nielsen, P. Leach, L. Masinter and T. Berners-Lee, Editors. IETF, June 1999. This RFC is available at http://www.ietf.org/rfc/rfc2616.txt.

[RFC 2119]

Key words for use in RFCs to Indicate Requirement Levels, S. Bradner, Editor. IETF, March 1997. This RFC is available at http://www.ietf.org/rfc/rfc2119.txt.

[XML Schema Part 1]

XML Schema Part 1: Structures Second Edition, David Beech, Murray Maloney, Henry S. Thompson, and Noah Mendelsohn, Editors. World Wide Web Consortium, 28 October 2004. This version is http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/ The latest version is available at http://www.w3.org/TR/xmlschema-1/.

[XML Schema Part 2]

XML Schema Part 2: Datatypes Second Edition, Ashok Malhotra and Paul V. Biron, Editors. World Wide Web Consortium, 28 October 2004. This version is http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/. The latest version is available at http://www.w3.org/TR/xmlschema-2/.

[RFC 3986]

Uniform Resource Identifiers (URI): Generic Syntax, T. Berners-Lee, R. Fielding and L. Masinter, Editors. IETF, January 2005. Obsoletes: RFC 2396, RFC 2732. This RFC is available at http://www.ietf.org/rfc/rfc3986.txt.

[Namespaces in XML]

Namespaces in XML (Second Edition), Tim Bray, Dave Hollander, Andrew Layman, and Richard Tobin, Editors. World Wide Web Consortium, 16 August 2006. This version is http://www.w3.org/TR/2006/REC-xml-names-20060816. The latest version is available at http://www.w3.org/TR/REC-xml-names.

[XML 1.0]

Extensible Markup Language (XML) 1.0 (Fourth Edition), Jean Paoli, Eve Maler, Tim Bray, et. al., Editors. World Wide Web Consortium, 16 August 2006. This version is http://www.w3.org/TR/2006/REC-xml-20060816. The latest version is available at http://www.w3.org/TR/REC-xml.

[XML InfoSet]

XML Information Set (Second Edition), Richard Tobin and John Cowan, Editors. World Wide Web Consortium, 04 February 2004. This version is http://www.w3.org/TR/2004/REC-xml-infoset-20040204. The latest version is available at http://www.w3.org/TR/xml-infoset.

[XML Base]

XML Base, Jonathan Marsh, Editor. World Wide Web Consortium, 27 June 2001. This version is http://www.w3.org/TR/2001/REC-xmlbase-20010627/. The latest version is available at http://www.w3.org/TR/xmlbase/.

8.2 Informative References

[SOAP Part 0]

SOAP Version 1.2 Part 0: Primer (Second Edition), Nilo Mitra, Yves Lafon, Editors. World Wide Web Consortium, 27 April 2007. This version is http://www.w3.org/TR/2007/REC-soap12-part0-20070427. The latest version is available at http://www.w3.org/TR/soap12-part0/.

[XMLP Comments]

XML Protocol Comments Archive (See http://lists.w3.org/Archives/Public/xmlp-comments/.)

[XMLP Dist-App]

XML Protocol Discussion Archive (See http://lists.w3.org/Archives/Public/xml-dist-app/.)

[XMLP Charter]

XML Protocol Charter (See http://www.w3.org/2005/07/XML-Protocol-Charter.)

[XMLP Requirements]

XML Protocol (XMLP) Requirements, Vidur Apparao, Alex Ceponkus, Paul Cotton, David Ezell, David Fallside, Martin Gudgin, Oisin Hurley, John Ibbotson, R. Alexander Milowski, Kevin Mitchell, Jean-Jacques Moreau, Eric Newcomer, Henrik Frystyk Nielsen, Mark Nottingham, Waqar Sadiq, Stuart Williams, Amr Yassin, Editors. World Wide Web Consortium, 28 July 2003. This version is http://www.w3.org/TR/2003/NOTE-xmlp-reqs-20030728/. The latest version is available at http://www.w3.org/TR/xmlp-reqs.

[SOAP Usage Scenarios]

SOAP Version 1.2 Usage Scenarios, John Ibbotson, Editor. World Wide Web Consortium, 30 July 2003. This version is http://www.w3.org/TR/2003/NOTE-xmlp-scenarios-20030730/. The latest version is available at http://www.w3.org/TR/xmlp-scenarios.

[SOAP 1.1]

Simple Object Access Protocol (SOAP) 1.1, Don Box, David Ehnebuske, Gopal Kakivaya, Andrew Layman, Noah Mendelsohn, Henrik Nielsen, Satish Thatte, Dave Winer, Editors. DevelopMentor, IBM, Microsoft, Lotus Development Corp., UserLand Software, Inc., 30 July 2003. This version is http://www.w3.org/TR/2000/NOTE-SOAP-20000508/.

[RFC 3987]

Internationalized Resource Identifiers (IRIs) , M. Duerst, Editors. IETF, January 2005. This RFC is available at http://www.ietf.org/rfc/rfc3987.txt.

[RFC 1900]

Renumbering Needs Work, B. Carpenter, Y. Rekhter, Editors. Editor. IETF, February 1996. This RFC is available at http://www.ietf.org/rfc/rfc1900.txt.