SOAP Version 1.2 Part 1: Messaging Framework

1.1 Design Goals

Two major design goals for SOAP are simplicity and extensibility. SOAP attempts to meet these goals by omitting features often found in messaging systems and distributed object systems such as:

• distributed garbage collection;

• boxcarring or batching of messages;

• objects-by-reference (which requires distributed garbage collection);

• activation (which requires objects-by-reference).

1.2 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 [3].

The namespace prefixes "env" and "enc" used in the prose sections of this document are associated with the SOAP namespace names "http://www.w3.org/2001/09/soap-envelope" and "http://www.w3.org/2001/09/soap-encoding" respectively.

The namespace prefixes "xs" and "xsi" used in the prose sections of this document are associated with the namespace names "http://www.w3.org/2001/XMLSchema" and "http://www.w3.org/2001/XMLSchema-instance" respectively, both of which are defined in the XML Schemas specification[4],[5].

Note that the choice of any namespace prefix is arbitrary and not semantically significant.

Namespace URIs of the general form "http://example.org/..." and "http://example.com/..." represent an application-dependent or context-dependent URI[6].

This specification uses the augmented Backus-Naur Form (BNF) as described in [2].

1.3 Example of SOAP Message

The following example shows a simple notification message expressed in SOAP. The message contains the header block alertcontrol and the body block alert which are both application defined and not defined by SOAP. The header block contains the parameters priority and expires which may be of use to intermediaries as well as the ultimate destination of the message. The body block contains the actual notification message to be delivered.

<env:Envelope xmlns:env="http://www.w3.org/2001/09/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.4 SOAP Terminology

1.4.2 Data Encapsulation Concepts

SOAP message

A SOAP message is the basic unit of communication between peer SOAP nodes.

SOAP envelope

The outermost syntactic construct or structure of a SOAP message defined by SOAP within which all other syntactic elements of the message are enclosed.

SOAP block

A syntactic construct or structure used to delimit data that logically constitutes a single computational unit as seen by a SOAP node. The type of a SOAP block is identified by the fully qualified name of the outer element for the block, which consists of the namespace URI and the local name. A block encapsulated within the SOAP header is called a header block and a block encapsulated within a SOAP body is called a body block.

SOAP header

A collection of zero or more SOAP blocks which may be targeted at any SOAP receiver within the SOAP message path.

SOAP body

A collection of zero or more SOAP blocks targeted at the ultimate SOAP receiver within the SOAP message path.

SOAP fault

A special SOAP block which contains fault information generated by a SOAP node.

The following diagram illustrates how a SOAP message is composed.

2.1 SOAP Nodes

A SOAP node can be the initial SOAP sender, the ultimate SOAP receiver, or a SOAP intermediary, in which case it is both a SOAP sender and a SOAP receiver. SOAP does not provide a routing mechanism, however SOAP does recognise that a SOAP sender originates a SOAP message which is sent to an ultimate SOAP receiver, via zero or more SOAP intermediaries.

A SOAP node receiving a SOAP message MUST perform processing, generate SOAP faults, SOAP responses, and if appropriate send additional SOAP messages, as provided by the remainder of this specification.

2.2 SOAP Actors and SOAP Nodes

In processing a SOAP message, a SOAP node is said to act in the role of one or more SOAP actors, each of which is identified by a URI known as the SOAP actor name. Each SOAP node MUST act in the role of the special SOAP actor named "http://www.w3.org/2001/09/soap-envelope/actor/next", and can additionally assume the roles of zero or more other SOAP actors. A SOAP node can establish itself as the ultimate SOAP receiver by acting in the (additional) role of the anonymous SOAP actor. The roles assumed MUST be invariant during the processing of an individual SOAP message; because this specification deals only with the processing of individual SOAP messages, no statement is made regarding the possibility that a given piece of software might or might not act in varying roles when processing more than one SOAP message.

SOAP nodes MUST NOT act in the role of the special SOAP actor named "http://www.w3.org/2001/09/soap-envelope/actor/none" (see also 4.2.2 SOAP actor Attribute).

While the purpose of a SOAP actor name is to identify a SOAP node, there are no routing or message exchange semantics associated with the SOAP actor name. For example, SOAP Actors MAY be named with a URI useable to route SOAP messages to an appropriate SOAP node. Conversely, it is also appropriate to use SOAP actor 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"; such a header might be used, for example, to carry an indication to any concerned software that the containing SOAP message is idempotent, and can safely be cached and replayed.)

2.3 Targeting SOAP Header Blocks

SOAP header blocks carry optional attribute information items with a local name of actor and a namespace name of http://www.w3.org/2001/09/soap-envelope (see 4.2.2 SOAP actor Attribute) that are used to target them to the appropriate SOAP node(s). SOAP header blocks with no such attribute information item and the SOAP body are implicitly targeted at the anonymous SOAP actor, implying that they are to be processed by the ultimate SOAP receiver. The specification refers to the (implicit or explicit) value of the SOAP actor attribute as the SOAP actor for the corresponding SOAP block (either a SOAP header block or a SOAP body block).

A SOAP block is said to be targeted to a SOAP node if the SOAP actor (if present) on the block matches (see [7]) a role played by the SOAP node, or in the case of a SOAP block with no actor attribute information item (including SOAP body blocks), if the SOAP node has assumed the role of the anonymous SOAP actor.

2.4 Understanding SOAP Headers

It is likely that specifications for a wide variety of header functions will be developed over time, and that each SOAP node MAY 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 conveyed by the combination of local name and namespace name of the outer-most element information item of that block.

SOAP header blocks carry optional attribute information items with a local name of mustUnderstand and a namespace name of http://www.w3.org/2001/09/soap-envelope (see 4.2.3 SOAP mustUnderstand Attribute). When the value of such an attribute information item is "true", the SOAP block is said to be mandatory. For such SOAP blocks the targeted SOAP node MUST: either process the SOAP block according to the semantics conveyed by the combination of local name and namespace name of the outer-most element information item of that block; or not process the SOAP message at all, and fail (see 4.4 SOAP Fault).

2.5 Processing SOAP Messages

This section sets out the rules by which SOAP messages are processed. Unless otherwise stated, processing must be semantically equivalent to performing the following steps separately, and in the order given. Note however that nothing in this specification should be taken to prevent the use of optimistic concurrency, roll back, or other techniques that might provide increased flexibility in processing order as long as all SOAP messages, SOAP faults and application-level side effects are equivalent to those that would be obtained by direct implementation of the following rules.

1. Generate a single SOAP MustUnderstand fault (see 4.4.2 MustUnderstand Faults) if one or more SOAP blocks targeted at the SOAP node are mandatory and are not understood by that node. If such a fault is generated, any further processing MUST NOT be done.

2. Process SOAP blocks targeted at the SOAP node, generating SOAP faults (see 4.4 SOAP Fault) if necessary. A SOAP node MUST process SOAP blocks identified as mandatory. A SOAP node MAY process or ignore SOAP blocks not so identified. In all cases where a SOAP block is processed, the SOAP node must understand the SOAP block and must do such processing in a manner fully conformant with the specification for that SOAP block. Faults, if any, must also conform to the specification for the processed SOAP block. It is possible that the processing of particular SOAP block would control or determine the order of processing for other SOAP blocks. 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 SOAP block, the order of processing is at the discretion of the SOAP node. SOAP nodes can make reference to any information in the SOAP envelope when processing a SOAP block. For example, a caching function can cache the entire SOAP message, if desired.

If the SOAP node is a SOAP intermediary, the SOAP message pattern and results of processing (e.g. no fault generated) MAY require that the SOAP message be sent further along the SOAP message path. Such relayed SOAP messages MUST contain all SOAP header blocks and the SOAP body blocks from the original SOAP message, in the original order, except that SOAP header blocks targeted at the SOAP intermediary MUST be removed (such SOAP blocks are removed regardless of whether they were processed or ignored). Additional SOAP header blocks MAY be inserted at any point in the SOAP message, and such inserted SOAP header blocks MAY be indistinguishable from one or more just removed (effectively leaving them in place, but emphasizing the need to reinterpret at each SOAP node along the SOAP message path.)

4.1 Envelope Encoding and Versioning

encodingStyle="http://www.w3.org/2001/09/soap-encoding"
encodingStyle="http://example.org/encoding/restricted http://example.org/encoding/"
encodingStyle=""

4.2 SOAP Header

SOAP provides a flexible mechanism for extending a SOAP message in a decentralized and modular way without prior knowledge between the communicating parties. Typical examples of extensions that can be implemented as SOAP header blocks are authentication, transaction management, payment, etc.

The Header element information item has:

• A local name of Header

• A namespace name of http://www.w3.org/2001/09/soap-envelope

• Zero or more namespace qualified attribute information item children.

• Zero or more namespace qualified element information item children.

All child element information items of the SOAP Header are called SOAP header blocks.

Each SOAP header block element information item:

• MUST be namespace qualified;

• MAY have an encodingStyle attribute information item

• MAY have an actor attribute information item

• MAY have a mustUnderstand attribute information item

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

4.3 SOAP Body

The SOAP Body element information item provides a simple mechanism for exchanging mandatory information intended for the ultimate SOAP receiver of a SOAP message. Example uses of SOAP Body include marshalling RPC calls and error reporting.

The Body element information item has:

• A local name of Body

• A namespace name of http://www.w3.org/2001/09/soap-envelope

• Zero or more element information item children.

All child element information items of the SOAP Body element information item are called SOAP body blocks.

Each SOAP body block element information item:

• MAY be namespace qualified.

• MAY have an encodingStyle attribute information item

SOAP defines one particular SOAP body block, the SOAP fault, which is used for reporting errors (see 4.4 SOAP Fault).

4.4 SOAP Fault

The SOAP Fault element information item is used to carry error and/or status information within a SOAP message. If present, the SOAP Fault MUST appear as a SOAP body block and MUST NOT appear more than once within a SOAP Body.

The Fault element information item has:

• A local name of Fault;

• A namespace name of http://www.w3.org/2001/09/soap-envelope;

• Two or more child element information items in order as follows:

  1. A mandatory faultcode element information item as described below;

  2. A mandatory faultstring element information item as described below;

  3. An optional faultactor element information item as described below;

  4. An optional detail element information item as described below.

The faultcode element information item has:

• A local name of faultcode

• A namespace name which is empty

The type of the faultcode element information item is QName in the http://www.w3.org/2001/XMLSchema namespace. It is intended for use by software to provide an algorithmic mechanism for identifying the fault. SOAP defines a small set of SOAP fault codes covering basic SOAP faults (see 4.4.1 SOAP Fault Codes)

The faultstring element information item has:

• A local name of faultstring;

• A namespace name which is empty.

The type of the faultstring element information item is string in the http://www.w3.org/2001/XMLSchema namespace. It is intended to provide a human readable explanation of the fault and is not intended for algorithmic processing. This element information item is similar to the 'Reason-Phrase' defined by HTTP[2] and SHOULD provide at least some information explaining the nature of the fault.

The faultactor element information item has:

• A local name of faultactor

• A namespace name which is empty

The type of the faultactor element information item is anyURI in the http://www.w3.org/2001/XMLSchema namespace. It is intended to provide information about which SOAP node on the SOAP message path caused the fault to happen (see 2 SOAP Message Exchange Model). It is similar to the SOAP actor attribute information item (see 4.2.2 SOAP actor Attribute) but instead of indicating the target of a SOAP header block, it indicates the source of the fault. The value of the faultactor element information item identifies the source of the fault. SOAP nodes that do not act as the ultimate SOAP receiver MUST include this element information item The ultimate SOAP receiver MAY include this element information item to indicate explicitly that it generated the fault.

The detail element information item has:

• A local name of detail;

• A namespace name which is empty;

• Zero or more attribute information items;

• Zero or more child element information items.

The detail element information item is intended for carrying application specific error information related to the SOAP Body. It MUST be present when the contents of the SOAP Body could not be processed successfully . It MUST NOT be used to carry error information about any SOAP header blocks. Detailed error information for SOAP header blocks MUST be carried within the SOAP header blocks themselves.

The absence of the detail element information item indicates that a SOAP Fault is not related to the processing of the SOAP Body. This can be used to find out whether the SOAP Body was at least partially processed by the ultimate SOAP receiver before the fault occurred, or not.

All child element information items of the detail element Information Item are called detail entries.

Each such element information item:

• MAY be namespace qualified;

• MAY have an encodingStyle attribute information item.

The SOAP encodingStyle attribute information item is used to indicate the encoding style used for the detail entries (see 4.1.1 SOAP encodingStyle Attribute).

Client.Authentication

<env:Envelope xmlns:env='http://www.w3.org/2001/09/soap-envelope'>
  <env:Header>
    <abc:Extension1 xmlns:abc='http://example.org/2001/06/ext'
                       env:mustUnderstand='1' />
    <def:Extension2 xmlns:def='http://example.com/stuff'
                       env:mustUnderstand='1' />
  </env:Header>
  <env:Body>
  . . .
  </env:Body>
</env:Envelope>

<env:Envelope xmlns:env='http://www.w3.org/2001/09/soap-envelope'
                      xmlns:f='http://www.w3.org/2001/09/soap-faults' >
  <env:Header>
    <f:Misunderstood qname='abc:Extension1'
                                xmlns:abc='http://example.org/2001/06/ext' />
    <f:Misunderstood qname='def:Extension2'
                                xmlns:def='http://example.com/stuff' />
  </env:Header>
  <env:Body>
    <env:Fault>
      <faultcode>env:MustUnderstand</faultcode>
      <faultstring>One or more mandatory headers not understood</faultstring>
    </env:Fault>
  </env:Body>
</env:Envelope>

5.1 Binding to Application-Specific Protocols

Some underlying protocols may be designed for a particular purpose or application profile. SOAP bindings to such protocols MAY use the same endpoint identification (e.g., TCP port number) as the underlying protocol, in order to reuse the existing infrastructure associated that protocol.

However, the use of well-known ports by SOAP may incur additional, unintended handling by intermediaries and underlying implementations. For example, HTTP is commonly thought of as a 'Web browsing' protocol, and network administrators may place certain restrictions upon its use, or may interpose services such as filtering, content modification, routing, etc. Often, these services are interposed using port number as a heuristic.

As a result, binding definitions for underlying protocols with well-known default ports or application profiles SHOULD document potential (harmful?) interactions with commonly deployed infrastructure at those default ports or in-conformance with default application profiles. Binding definitions SHOULD also illustrate the use of the binding on a non-default port as a means of avoiding unintended interaction with such services.

5.2 Security Considerations

6.1 Normative References

1

W3C Working Draft "SOAP Version 1.2 Part 2: Adjuncts", Martin Gudgin, Marc Hadley, Jean-Jacques Moreau, Henrik Frystyk Nielsen, 2 October 2001 (See http://www.w3.org/TR/2001/WD-soap12-part2-20011002/.)

2

IETF "RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1", R. Fielding, J. Gettys, J. C. Mogul, H. Frystyk, T. Berners-Lee, January 1997. (See http://www.ietf.org/rfc/rfc2616.txt.)

3

IETF "RFC 2119: Key words for use in RFCs to Indicate Requirement Levels", S. Bradner, March 1997. (See http://www.ietf.org/rfc/rfc2119.txt.)

4

W3C Recommendation "XML Schema Part 1: Structures", Henry S. Thompson, David Beech, Murray Maloney, Noah Mendelsohn, 2 May 2001. (See http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/.)

5

W3C Recommendation "XML Schema Part 2: Datatypes", Paul V. Biron, Ashok Malhotra, 2 May 2001. (See http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/.)

6

IETF "RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax", T. Berners-Lee, R. Fielding, L. Masinter, August 1998. (See http://www.ietf.org/rfc/rfc2396.txt.)

7

W3C Recommendation "Namespaces in XML", Tim Bray, Dave Hollander, Andrew Layman, 14 January 1999. (See http://www.w3.org/TR/1999/REC-xml-names-19990114/.)

8

W3C Recommendation "Extensible Markup Language (XML) 1.0 (Second Edition)", Tim Bray, Jean Paoli, C. M. Sperberg-McQueen, Eve Maler, 6 October 2000. (See http://www.w3.org/TR/2000/REC-xml-20001006.)

9

W3C Proposed Recommendation "XML Linking Language (XLink) Version 1.0", Steve DeRose, Eve Maler, David Orchard, 20 December 2000. (See http://www.w3.org/TR/2000/PR-xlink-20001220/.)

10

W3C Proposed Recommendation "XML Information Set", John Cowan, Richard Tobin, 10 August 2001. (See http://www.w3.org/TR/2001/PR-xml-infoset-20010810/.)

6.2 Informative References

11

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

12

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

13

XML Protocol Charter (See http://www.w3.org/2000/09/XML-Protocol-Charter.)

14

W3C Note "Simple Object Access Protocol (SOAP) 1.1", Don Box, David Ehnebuske, Gopal Kakivaya, Andrew Layman, Noah Mendelsohn, Henrik Nielsen, Satish Thatte, Dave Winer, 8 May 2000. (See http://www.w3.org/TR/SOAP/.)