SOAP Version 1.2 (SOAP) is a lightweight protocol intended for exchanging structured information in a decentralized, distributed environment. It uses XML technologies to define an extensible messaging framework providing a message construct that can be exchanged over a variety of underlying protocols. The framework has been designed to be independent of any particular programming model and other implementation specific semantics.
Two major design goals for SOAP are simplicity and extensibility (see XMLP Requirements [XMLP Requirements]). SOAP attempts to meet these goals by omitting, from the messaging framework, features that are often found in distributed systems. Such features include but are not limited to "reliability", "security", "correlation", "routing", and "Message Exchange Patterns" (MEPs). While it is anticipated that many features will be defined, this specification provides specifics only for two MEPs. Other features are left to be defined as extensions by other specifications.
The SOAP Version 1.2 specification consists of three parts. Part 1 of the SOAP Version 1.2 specification (this document) defines the SOAP messaging framework consisting of:
The SOAP processing model defining the rules for processing a SOAP message (see 2. SOAP Processing Model).
The SOAP Extensibility model defining the concepts of SOAP features and SOAP modules (see 3. SOAP Extensibility Model).
The SOAP underlying protocol binding framework describing the rules for defining a binding to an underlying protocol that can be used for exchanging SOAP messages between SOAP nodes (see 4. SOAP Protocol Binding Framework).
The SOAP message construct defining the structure of a SOAP message (see 5. SOAP Message Construct).
The SOAP 1.2 Primer [SOAP Part 0] is a non-normative document intended to provide an easily understandable tutorial on the features of the SOAP Version 1.2 specifications.
SOAP 1.2 Part 2 [SOAP Part 2] describes a set of adjuncts that can be used in connection with the SOAP messaging framework.
Note:
In previous versions of this specification the SOAP name was an acronym. This is no longer the case.
The ability to use SOAP in a particular environment will vary depending on the actual constraints, choice of tools, processing model, or nature of the messages being exchanged. SOAP has been designed to have a relatively small number of dependencies on other XML specifications, none of which are perceived as having prohibitive processing requirements. Also, limiting use of SOAP to small messages instead of arbitrarily-sized messages and supporting only a few specific message types instead of implementing generalized processing could significantly lower processing requirements.
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>
This section describes the terms and concepts introduced in Part 1 of the SOAP Version 1.2 specification (this document).
The formal set of conventions governing the format and processing rules of a SOAP message. These conventions include the interactions among SOAP nodes generating and accepting SOAP messages for the purpose of exchanging information along a SOAP message path.
The embodiment of the processing logic necessary to transmit, receive, process and/or relay a SOAP message, according to the set of conventions defined by this recommendation. A SOAP node is responsible for enforcing the rules that govern the exchange of SOAP messages (see 2. SOAP Processing Model). It accesses the services provided by the underlying protocols through one or more SOAP bindings.
A SOAP receiver's expected function in processing a message. A SOAP receiver can act in multiple roles.
The formal set of rules for carrying a SOAP message within or on top of another protocol (underlying protocol) for the purpose of exchange (see 4. SOAP Protocol Binding Framework). Examples of SOAP bindings include carrying a SOAP message within an HTTP entity-body, or over a TCP stream.
An extension of the SOAP messaging framework (see 3. SOAP Extensibility Model). Examples of features include "reliability", "security", "correlation", "routing", and "Message Exchange Patterns" (MEPs).
A SOAP Module is a specification that contains the combined syntax and semantics of SOAP header blocks specified according to the rules in 3.3 SOAP Modules. A SOAP module realizes zero or more SOAP features.
A template for the exchange of SOAP messages between SOAP nodes enabled by one or more underlying SOAP protocol bindings (see 4. SOAP Protocol Binding Framework). A SOAP MEP is an example of a SOAP feature (see 3.2 SOAP Message Exchange Patterns (MEPs)).
An entity, typically software, that produces, consumes or otherwise acts upon SOAP messages in a manner conforming to the SOAP processing model (see 2. SOAP Processing Model).
The basic unit of communication between SOAP nodes.
The outermost element information item of a SOAP message.
A collection of zero or more SOAP header blocks each of which might be targeted at any SOAP receiver within the SOAP message path.
An element information item used to delimit data that logically constitutes a single computational unit within the SOAP header. The type of a SOAP header block is identified by the XML expanded name of the header block element information item.
A collection of zero or more element information items targeted at an ultimate SOAP receiver in the SOAP message path (see 5.3 SOAP Body).
A SOAP element information item which contains fault information generated by a SOAP node.
A SOAP node that transmits a SOAP message.
A SOAP node that accepts a SOAP message.
The set of SOAP nodes through which a single SOAP message passes. This includes the initial SOAP sender, zero or more SOAP intermediaries, and an ultimate SOAP receiver.
The SOAP sender that originates a SOAP message at the starting point of a SOAP message path.
A SOAP intermediary is both a SOAP receiver and a SOAP sender and is targetable from within a SOAP message. It processes the SOAP header blocks targeted at it and acts to forward a SOAP message towards an ultimate SOAP receiver.
The SOAP receiver that is a final destination of a SOAP message. It is responsible for processing the contents of the SOAP body and any SOAP header blocks targeted at it. In some circumstances, a SOAP message might not reach an ultimate SOAP receiver, for example because of a problem at a SOAP intermediary. An ultimate SOAP receiver cannot also be a SOAP intermediary for the same SOAP message (see 2. SOAP Processing Model).
SOAP provides a distributed processing model that assumes a SOAP message originates at an initial SOAP sender and is sent to an ultimate SOAP receiver via zero or more SOAP intermediaries. Note that the SOAP distributed processing model can support many MEPs including but not limited to one-way messages, request/response interactions, and peer-to-peer conversations (see 3.2 SOAP Message Exchange Patterns (MEPs) for a description of the relationship between SOAP message exchange patterns and the SOAP extensibility model).
This section defines the SOAP distributed processing model. The SOAP processing model specifies how a SOAP receiver processes a SOAP message. It applies to a single message only, in isolation from any other SOAP message. The SOAP processing model itself does not maintain any state or perform any correlation or coordination between messages, even, for example, when used in combination with a SOAP feature which involves sending multiple SOAP messages in sequence, each subsequent message depending on the response to the previous message. It is the responsibility of each such feature to define any combined processing.
Section 3. SOAP Extensibility Model describes how SOAP can be extended and how SOAP extensions might interact with the SOAP processing model and the SOAP protocol binding framework. Section 4. SOAP Protocol Binding Framework defines a framework for describing the rules for how SOAP messages can be exchanged over a variety of underlying protocols.
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
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).
| Short-name | Name | Description |
|---|---|---|
next |
"http://www.w3.org/2003/05/soap-envelope/role/next" | Each SOAP intermediary and the ultimate SOAP receiver MUST act in this role. |
none |
"http://www.w3.org/2003/05/soap-envelope/role/none" | SOAP nodes MUST NOT act in this role. |
ultimateReceiver |
"http://www.w3.org/2003/05/soap-envelope/role/ultimateReceiver" | The ultimate receiver MUST act in this role. |
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.
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).
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.
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.
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.
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.
Identify all header blocks targeted at the node that are mandatory.
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).
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.
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.
Note:
The above rules apply to processing at a single
node. SOAP extensions can be designed to ensure that
SOAP header blocks are processed in an appropriate
order, as the message moves along the message path towards the
ultimate SOAP receiver. Specifically, such extensions might
specify that a fault with a Value of Code
set to "env:Sender" is
generated if some SOAP header blocks have inadvertently
survived past some intended point in the message path. Such
extensions might depend on the presence or value of the
mustUnderstand attribute information
item in the surviving SOAP header blocks when determining whether
an error has occurred.
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.
The relaying of SOAP header blocks targeted at an intermediary SOAP node depends on whether the SOAP header blocks are processed or not by that node. A SOAP header block is said to be reinserted if the processing of that header block determines that the header block is to be reinserted in the forwarded message. The specification for a SOAP header block may call for the header block to 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. Such header blocks are said to be relayable.
A SOAP header block MAY carry a relay attribute information
item (see 5.2.4 SOAP relay Attribute). When the value of
such an attribute information item is "true", the header
block is said to be relayable. The forwarding of relayable
header blocks is described in section 2.7.2 SOAP Forwarding Intermediaries.
The relay attribute information item has no effect on SOAP
header blocks targeted at a role other than one assumed by
a SOAP intermediary.
The relay attribute information item has no effect
on the SOAP processing model when
the header block also carries a mustUnderstand attribute
information item with a value of "true".
The relay attribute information item has no effect
on the processing of SOAP messages by the SOAP ultimate receiver.
Table 3 summarizes the forwarding behavior of a SOAP node for a given header block. Each row contains a different combination of the value of the header block's role attribute information item, whether the SOAP node is acting in that role and whether the header block has been understood and processed, and shows whether the header block will be forwarded or removed.
| Role | Header block | ||
|---|---|---|---|
| Short-name | Assumed | Understood & Processed | Forwarded |
next |
Yes | Yes | No, unless reinserted |
| No | No, unless relay ="true" |
||
| user-defined | Yes | Yes | No, unless reinserted |
| No | No, unless relay ="true" |
||
| No | n/a | Yes | |
ultimateReceiver |
Yes | Yes | n/a |
| No | n/a | ||
none |
No | n/a | Yes |
The semantics of one or more SOAP header blocks in a SOAP message, or the SOAP MEP used, MAY require that the SOAP message be forwarded to another SOAP node on behalf of the initiator of the inbound SOAP message. In this case, the processing SOAP node acts in the role of a SOAP forwarding intermediary.
Forwarding SOAP intermediaries MUST process the message according to the SOAP processing model defined in 2.6 Processing SOAP Messages. In addition, when generating a SOAP message for the purpose of forwarding, they MUST:
Remove all processed SOAP header blocks.
Remove all non-relayable SOAP header blocks that were targeted at the forwarding node but ignored during processing.
Retain all relayable SOAP header blocks that were targeted at the forwarding node but ignored during processing.
Forwarding SOAP intermediaries MUST also obey the specification for the SOAP forwarding features being used. The specification for each such a feature MUST describe the required semantics, including the rules describing how the forwarded message is constructed. Such rules MAY describe placement of inserted or reinserted SOAP header blocks. Inserted SOAP header blocks might be indistinguishable from one or more of the header blocks removed by the intermediary. Processing is defined here in terms of re-inserting header blocks (rather than leaving them in place) to emphasize the need to process them at each SOAP node along the SOAP message path.
SOAP enables exchange of SOAP messages using a variety of underlying protocols. The formal set of rules for carrying a SOAP message within or on top of another protocol (underlying protocol) for the purpose of exchange is called a binding. The SOAP Protocol Binding Framework provides general rules for the specification of protocol bindings; the framework also describes the relationship between bindings and SOAP nodes that implement those bindings. The HTTP binding in SOAP 1.2 Part 2 [SOAP Part 2] illustrates the specification of a binding. Additional bindings can be created by specifications that conform to the binding framework introduced in this chapter.
A SOAP binding specification:
Declares the features provided by a binding.
Describes how the services of the underlying protocol are used to transmit SOAP message infosets.
Describes how the services of the underlying protocol are used to honor the contract formed by the features supported by that binding.
Describes the handling of all potential failures that can be anticipated within the binding.
Defines the requirements for building a conformant implementation of the binding being specified.
A binding does not provide a separate processing model and does not constitute a SOAP node by itself. Rather a SOAP binding is an integral part of a SOAP node (see 2. SOAP Processing Model).
The goals of the binding framework are:
To set out the requirements and concepts that are common to all binding specifications.
To facilitate homogeneous description in situations where multiple bindings support common features, promoting reuse across bindings.
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.
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.