SOAP Version 1.2 Part 2: Adjuncts

1. Introduction

SOAP Version 1.2 (SOAP) is a lightweight protocol intended for exchange of structured information between peers in a decentralized, distributed environment. The SOAP specification consists of two parts. Part 1 [1] defines the SOAP messaging framework. Part 2 (this document) defines a set of adjuncts that MAY be used with the SOAP messaging framework:

The SOAP Data Model represents application-defined data structures and values as a directed, edge-labeled graph of nodes (see 2. SOAP Data Model).
The SOAP Encoding defines a set of rules for encoding instances of data that conform to the SOAP Data Model for inclusion in SOAP messages (see 3. SOAP Encoding).
The SOAP RPC Representation defines a convention for how to use the SOAP Data Model for representing RPC calls and responses (see 4. SOAP RPC Representation).
A convention for describing features and bindings (see 5. A Convention for Describing Features and Bindings).
A request response message exchange pattern definition (see 6. SOAP-Supplied Message Exchange Patterns).
The SOAP HTTP Binding defines a binding of SOAP to HTTP [2] following the rules of the SOAP Protocol Binding Framework [1] (see 7. SOAP HTTP Binding).

Note:

In previous versions of this specification the SOAP name was an acronym. This is no longer the case.

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

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 [10]).

Table 1: Prefixes and Namespaces used in this specification
Prefix	Namespace	Notes
env	"http://www.w3.org/2001/12/soap-envelope"	Defined by Part 1 [1].
enc	"http://www.w3.org/2001/12/soap-encoding"	A normative XML Schema [4], [5] document for the "http://www.w3.org/2001/12/soap-encoding" namespace can be found at http://www.w3.org/2001/12/soap- encoding.
xs	"http://www.w3.org/2001/XMLSchema"	Defined in the W3C XML Schema specification [4], [5].
xsi	"http://www.w3.org/2001/XMLSchema-instance"	Defined in the W3C XML Schema specification [4], [5].
context	"http://www.w3.org/2001/12/soap/bindingFramework/ExchangeContext/"	See 6.2 Request-Response Message Exchange Pattern.
mep	"http://www.w3.org/2001/12/soap/mep/"	See 6.2 Request-Response Message Exchange Pattern.
fail	"http://www.w3.org/2001/12/soap/mep/FailureReasons/"	See 6.2 Request-Response Message Exchange Pattern.
reqres	"http://www.w3.org/2001/12/soap/mep/request-response/"	See 6.2 Request-Response Message Exchange Pattern.

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

This specification uses the Extended Backus-Naur Form (EBNF) as described in [8].

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

2. SOAP Data Model

The SOAP Data Model represents application-defined data as a directed edge-labeled graph of nodes. Components of this graph are described in the following sections.

The purpose of the SOAP Data Model is to provide a mapping of non-XML based data to some wire representation. It is important to note that use of the SOAP Data Model, the accompanying SOAP Encoding (see 3. SOAP Encoding), and/or the SOAP RPC Representation (see 4. SOAP RPC Representation) is OPTIONAL. Applications which already model data in XML, for example using W3C XML Schema [4],[5], may not need to use the SOAP Data Model. Due to their optionality, it is NOT a requirement to implement the SOAP Data Model, the SOAP Encoding and/or the SOAP RPC Representation as part of a SOAP node.

2.1 Graph Edges

Edges in the graph are said to originate at a graph node and terminate at a graph node. An edge that originates at a graph node is known as an outbound edge with respect to that graph node. An edge that terminates at a graph node is known as an inbound edge with respect to that graph node. An edge MAY originate and terminate at the same graph node.

The outbound edges of a given graph node MAY be distinguished by label or by position, or both. Position is a total order on such edges; thus any outbound edge MAY be identified by position.

2.1.1 Edge labels

An edge label is an XML Schema Qualified Name (see XML Schema Part 2: Datatypes [5]). Two edge labels are equal if and only if both of the following are true:

Their local name values are the same.
Either of the following is true:
1. Their namespace name values are missing.
2. Their namespace name values are present and the same.

See 2.3 Values for uses of edge labels and position to distinguish the members of encoded values, and XML Schema Part 2: Datatypes [5] for more information about comparing XML qualified names.

2.2 Graph Nodes

A graph node is either a terminal graph node or a non-terminal graph node. A non-terminal graph node has one or more outbound edges. A terminal graph node has no outbound edges and an optional lexical value. Both types of graph node have an optional unique identifier of type ID in the namespace named "http://www.w3.org/2001/XMLSchema", (see XML Schema Part2: DataTypes [5]) and an optional type name of type QName in the namespace named "http://www.w3.org/2001/XMLSchema" (see XML Schema Part2: DataTypes [5]).

2.2.1 Single and Multi reference nodes

A graph node may be single reference or multi reference. A single reference graph node has a single inbound edge. A multi reference graph node has multiple inbound edges.

2.3 Values

A simple value is represented as a terminal graph node.

A compound value is represented as a non-terminal graph node as follows:

If the labels of a non-terminal graph node's outbound edges are not unique (i.e. they can be duplicated), the non-terminal graph node is known as a "generic". Outbound edges of a generic MAY be distinguished by label and/or position, according to the needs of the application.
A non-terminal graph node whose outbound edges are distinguished solely by their labels is known as a "struct". The outbound edges of a struct MUST be labeled with distinct names (see 2.1.1 Edge labels).
A non-terminal graph node whose outbound edges are distinguished solely by position is known as an "array". The outbound edges of an array MUST NOT be labelled.

Editorial note
The Working Group solicits feedback from implementors regarding the usefulness or otherwise of 'generics'.

3. SOAP Encoding

SOAP Encoding describes how to encode instances of data that conform to the data model described in 2. SOAP Data Model. This encoding MAY be used to transmit data in SOAP header blocks and/or SOAP bodies. Other data models, alternate encodings of the SOAP Data Model as well as unencoded data MAY also be used in SOAP messages (see [1]SOAP encodingStyle Attribute for specification of alternative encoding styles and see 4. SOAP RPC Representation for restrictions on data models and encodings used to represent SOAP Remote Procedure Calls).

The serialization rules defined in this section are identified by the URI "http://www.w3.org/2001/12/soap-encoding". SOAP messages using this particular serialization SHOULD indicate that fact by using the SOAP encodingStyle attribute information item (see [1]SOAP encodingStyle Attribute).

3.1 Rules for Encoding Graphs in XML

XML allows very flexible encoding of data. SOAP Encoding defines a narrower set of rules for encoding the graphs described in 2. SOAP Data Model. This section defines the encoding at a high level, and the subsequent sub-sections describe the encoding rules in more detail. The encodings described in this section can be used in conjunction with the mapping of RPC calls and responses specified in 4. SOAP RPC Representation.

The encodings are described below from the perspective of a de-serializer. In each case, the presence of an XML serialization is presumed, and the mapping to a corresponding graph is described.

More than one encoding is typically possible for a given graph. When serializing a graph for transmission inside a SOAP message any representation that deserializes to the identical graph MAY be used; when receiving an encoded SOAP message, all representations MUST be accepted.

3.1.1 Encoding graph edges and nodes

Each graph edge is encoded as an element information item and each element information item represents a graph edge. 3.1.3 Encoding compound values describes the relationship between edge labels and the local name and namespace name properties of such element information items.

The graph node at which an edge terminates is determined by examination of the serialized XML as follows:

If the element information item representing the edge does not have a ref attribute information item (see 3.1.5.2 ref Attribute Information Item) among its attributes then that element information item is said to represent a node in the graph and the edge terminates at that node.
If the element information item representing the edge does have a ref attribute information item (see 3.1.5.2 ref Attribute Information Item) among its attributes, then the value of that attribute information item MUST be identical to the value of exactly one id attribute information item ( see 3.1.5.1 id Attribute Information Item) in the same envelope. In this case the edge terminates at the graph node represented by the element information item on which the id attribute information item appears. That element information item MUST be in the scope of an encodingStyle attribute with a value of "http://www.w3.org/2001/12/soap-encoding".

All nodes in the graph are encoded as described in 1 above. Additional inbound edges for multi reference graph nodes are encoded as described in 2 above.

3.1.2 Encoding simple values

The "lexical value" of a terminal graph node (simple value) is the sequence of Unicode characters identified by the character information item children of the element information item representing that node.

3.1.3 Encoding compound values

An outbound edge of a graph node is encoded as an element information item child of the element information item that represents the node (see 3.1.1 Encoding graph edges and nodes). Particular rules apply depending on what kind of compound value the graph node represents. These rules are as follows:

For a graph edge which is distinguished by label ("struct" or "generic"), the namespace name and local name properties of the element information item together determine the value of the edge label.
For a graph edge which is distinguished by position ("array" or "generic"):
- The ordinal position of the graph edge corresponds to the position of the element information item relative to its siblings
- If outbound edges are distinguished only by position ("array") then the local name and namespace name properties of the element information item are not significant.
The following rules apply to the encoding of a graph node that represents an "array":
- The element information item representing an array node MAY have among its attributes an itemType attribute information item (see 3.1.4.1 itemType Attribute Information Item).
- The element information item representing an array node MAY have among its attributes an arraySize attribute information item (see 3.1.6 arraySize Attribute Information Item).
If a graph edge does not terminate in a graph node then it can either be omitted from the serialization or it can be encoded as an element information item with an xsi:nilattribute information item whose value is "true".

3.1.4 Computing the Type Name property

The type name property of a graph node is a {namespace name, local name} pair computed as follows:

If the element information item representing the graph node has an xsi:type attribute information item among its attributes then the type name property of the graph node is the value of the xsi:type attribute information item.
Note:
This attribute is of type QName in the namespace named "http://www.w3.org/2001/XMLSchema" (see XML Schema Part 2: Datatypes [5]); its value consists of the pair {namespace name, local name}. Neither the prefix used to construct the QName nor any information relating to any definition of the type is considered to be part of the value. The SOAP graph carries only the qualified name of the type.
Otherwise if the parent element information item of the element information item representing the graph node has a soap:itemType attribute information item (see 3.1.4.1 itemType Attribute Information Item) among its attributes then the type name property of the graph node is the value of the soap:itemType attribute information item
Otherwise the value of the type name property of the graph node is unspecified.

Note:

These rules define how the type name property of a graph node in a graph is computed from a serialized encoding. This specification does not mandate validation using any particular schema language or type system. Nor does it include built in types or provide any standardized faults to reflect value/type name conflicts.

However, nothing prohibits development of additional specifications to describe the use of SOAP with particular schema languages or type systems. Such additional specifications MAY mandate validation using particular schema language, and MAY specify faults to be generated should validation fail. Such additional specifications MAY specify augmentations to the deserialized graph based on information determined from such a validation. The use by SOAP of xsi:type is intended to facilitate integration with the W3C XML Schema language (see B. Using W3C XML Schema with SOAP Encoding). Other XML based schema languages, data schemas and programmatic type systems MAY be used but only to the extent that they are compatible with the serialization described in this specification.

3.1.4.1 itemType Attribute Information Item

The itemType attribute information item has the following Infoset properties:

A local name of itemType ;
A namespace name of "http://www.w3.org/2001/12/soap-encoding".
A specified property with a value of true.

The type of the itemType attribute information item is QName in the namespace named "http://www.w3.org/2001/XMLSchema". The value of the itemType attribute information item is used to compute the type name property (see 3.1.4 Computing the Type Name property) of members of an array.

3.1.5 Unique identifiers

3.1.5.1 id Attribute Information Item

The id attribute information item has the following Infoset properties:

A local name of id ;
A namespace name which is empty
A specified property with a value of "true".

The type of the id attribute information item is ID in the namespace named "http://www.w3.org/2001/XMLSchema". The value of the id attribute information item is a unique identifier that can be referred to by a ref attribute information item (see 3.1.5.2 ref Attribute Information Item).

3.1.5.2 ref Attribute Information Item

The ref attribute information item has the following Infoset properties:

A local name of ref ;
A namespace name which is empty
A specified property with a value of true.

The type of the ref attribute information item is IDREF in the namespace named "http://www.w3.org/2001/XMLSchema". The value of the ref attribute information item is a reference to a unique identifier defined by an id attribute information item (see 3.1.5.1 id Attribute Information Item).

3.1.5.3 Constraints on id and ref attribute information items

The value of a ref attribute information item MUST also be the value of exactly one id attribute information item.

A ref attribute information item and an id attribute information item MUST NOT appear on the same element information item.

3.1.6 arraySize Attribute Information Item

The arraySize attribute information item has the following Infoset properties:

A local name of arraySize ;
A namespace name of "http://www.w3.org/2001/12/soap-encoding".
A default value of "*"

The type of the arraySize attribute information item is arraySize in the namespace named "http://www.w3.org/2001/12/soap-encoding".

The value of the arraySize attribute information item MUST conform to the following EBNF grammer

[1]	`arraySizeValue`	::=	`("" \| concreteSize) nextConcreteSize`
[2]	`nextConcreteSize`	::=	`" " concreteSize`
[3]	`concreteSize`	::=	`[0-9]+`

The array's dimensions are represented by each item in the list of sizes (unspecified size in case of the asterisk). The number of items in the list represents the number of dimensions in the array. The asterisk, if present, MUST only appear in the first position in the list.

3.2 Decoding Faults

During deserialization a SOAP receiver:

SHOULD generate an env:Sender SOAP fault with a subcode of enc:MissingID if the message violates the constraints on id and ref attribute information items (see 3.1.5.3 Constraints on id and ref attribute information items).
MAY generate an env:Sender SOAP fault with a subcode of enc:UntypedValue if the type name property of an encoded graph node is unspecified.

4. SOAP RPC Representation

One of the design goals of SOAP is to encapsulate remote procedure call (RPC) functionality using the extensibility and flexibility of XML. This section defines a uniform representation of RPC requests and responses.

The SOAP encodingStyle attribute information item (see [1]SOAP encodingStyle Attribute) is used to indicate the encoding style of the RPC representation. The encoding thus specified must support "struct" and "array" compound value constructs defined in 2.3 Values. The encoding style defined in 3. SOAP Encoding supports such constructs and is therefore suitable for use with the SOAP RPC representation.

This SOAP RPC Representation is not predicated on any SOAP protocol binding. When SOAP is bound to HTTP, an RPC invocation maps naturally to an HTTP request and an RPC response maps to an HTTP response. (see 7. SOAP HTTP Binding). However, the SOAP RPC Representation is not limited only to the SOAP HTTP Binding.

To invoke an RPC, the following information is needed:

The binding-specific address of the target SOAP node
A procedure or method name
The identities and values of any arguments to be passed to the procedure or method
Optional header data

SOAP relies on the protocol binding to provide a mechanism for carrying the URI of the target SOAP node. For HTTP the request URI indicates the resource against which the invocation is being made. Other than requiring it to be a valid URI, SOAP places no restriction on the form of an address (see RFC2396 [6] for more information on URIs).

4.1 RPC and SOAP Body

RPC invocations and responses are both carried in the SOAP Body element (see [1]SOAP Body) using the following representation.

4.1.1 RPC Invocation

An RPC invocation is modeled as a struct where parameter access is by name or as an array where parameter access is by position.

The invocation is represented by a single struct or array containing an outbound edge for each [in] or [in/out] parameter. The struct is named identically to the procedure or method name (see A. Mapping Application Defined Names to XML Names).
Each outbound edge either has a label corresponding to the name of the parameter (see A. Mapping Application Defined Names to XML Names) or a position corresponding to the position of the parameter.

Applications MAY process invocations with missing parameters but also MAY fail to process the invocation and return a fault.

4.1.2 RPC Response

An RPC response is modeled as a struct where parameter access is by name or as an array where parameter access is by position.

The response is represented by a single struct or array containing an outbound edge for the return value and each [out] or [in/out] parameter. The return value outbound edge SHOULD be the first outbound edge.
Each outbound edge has a label corresponding to the name of the parameter (see A. Mapping Application Defined Names to XML Names) or a position corresponding to the position of the parameter. The label of the return value outbound edge is "result" and it is namespace-qualified with the namespace name "http://www.w3.org/2001/12/soap-rpc". The return value outbound edge MUST be present if the return value of the procedure is non-void. The return value outbound edge MUST NOT be present if the return value of the procedure is void.
Invocation faults are handled according to the rules in 4.3 RPC Faults. If a protocol binding adds additional rules for fault expression, those MUST also be followed.

An RPC response MUST NOT contain both a result and a fault, because a result indicates success and a fault indicates failure.

4.1.3 SOAP Encoding Restriction

When using SOAP encoding (see 3. SOAP Encoding) in conjunction with the RPC convention described here, the SOAP Body MUST contain only a single child element information item, that child being the serialized RPC invocation or response struct or array. I.e. when using the SOAP encoding for serializing RPC invocations and responses, the encoding is constrained to produce a single tree of element information items.

4.2 RPC and SOAP Header

Additional information relevant to the encoding of an RPC invocation but not part of the formal procedure or method signature MAY be expressed in a SOAP envelope carrying an RPC invocation or response. Such additional information MUST be expressed as SOAP header blocks.

4.3 RPC Faults

The SOAP RPC Representation introduces additional SOAP fault subcode values to be used in conjunction with the fault codes described in [1]SOAP Fault Codes. The namespace name for these SOAP fault subcode values is "http://www.w3.org/2001/12/soap-rpc" and the namespace prefix rpc: is used in this section to indicate association with this namespace. A schema document for this namespace can be found at http://www.w3.org/2001/12/soap-rpc .

Errors arising during RPC invocations are reported according to the following rules (in decreasing order of precedence):

A fault with a Value of "env:Receiver" for Code SHOULD be generated when the receiver cannot handle the message because of some temporary condition, e.g. when it is out of memory.
A fault with a Value of "env:DataEncodingUnknown" for Code SHOULD be generated when the arguments are encoded in a data encoding unknown to the receiver.
A fault with a Value of "env:Sender" for Code and a Value of "rpc:ProcedureNotPresent" for Subcode MUST be generated when the receiver does not support the procedure or method specified.
A fault with a Value of "env:Sender" for Code and a Value of "rpc:BadArguments" for Subcode MUST be generated when the receiver cannot parse the arguments or when there is a mismatch between what the receiver expects and what the sender has sent.
Other faults arising in an extension or from the application SHOULD be generated as described in [1]SOAP Fault Codes.

In all cases the values of the Detail and Reason element information items are implementation defined. Details of their use MAY be specified by an external document.

5. A Convention for Describing Features and Bindings

This section describes a convention describing Features (including MEPs) and Bindings in terms of properties and property values. The convention is sufficient to describe the distributed states of Feature and Binding specifications as mandated by the Binding Framework (see [1]SOAP Protocol Binding Framework) and it is used to describe a Request-Response MEP 6.2 Request-Response Message Exchange Pattern and the SOAP HTTP Binding 7. SOAP HTTP Binding elsewhere in this document. Along with the convention itself, an informal model is defined that describes how properties propagate through a SOAP system. Note that this model is intended to be illustrative only, and is not meant to imply any constraints on the structure or layering of any particular SOAP implementation.

5.1 Model and Properties

In general, a SOAP message is the information that one SOAP node wishes to exchange with another SOAP node according to a particular set of features, including a MEP. In addition, there may be information essential to exchanging a message that is not part of the message itself. Such information is sometimes called message meta-data. In the model, the message, any message meta-data, and the various information items that enable features are represented as abstractions called properties.

5.1.1 Properties

Under the convention, properties are represented as follows:

Properties are named with XML qualified names (QNames). For example, myNS:RetryCount where RetryCount is the name of the property, and myNS is a prefix mapped to a namespace.
Property values are typed, and the type of a property-value is defined by an XML Schema simple datatype in the specification which introduces the property. For example, the type of RetryCount is xsi:int .

5.1.2 Property Scope

Properties within a SOAP node can differ in terms of their scope and the origins of their values. Some properties are scoped per message-exchange, while others have a wider significance. For example, the scope of a SOAP message property is per message-exchange, but the scope of a User Identity property may extend beyond the exchange of a single message. The values of some properties arise directly from the operations of the SOAP node and message exchanges, while others arise in implementation specific ways due to the local environment. As shown in the figure below, we make the distinction between per message-exchange and more widely scoped properties by assigning them to different containers called Message Exchange Context and Environment respectively. All properties, regardless of their scope, are shared by SOAP and a particular Binding.

Model describing properties shared between SOAP and Binding

The values of properties in Environment may depend upon local circumstances (as depicted by the external arrow from Environment in the figure above). More specifically, the properties in the example could be influenced by an Operating System User ID on whose behalf a message exchange is being executed. The mapping of information in a particular implementation to such properties is outside the scope of the binding framework although the abstract representation of such information as properties is not.

5.1.3 Properties and Features

A feature may be expressed through multiple properties and a single property may enable more than one feature. For example, the properties called User ID and Password may be used to enable a feature called Authentication. As a second example, a single property called Message ID could be used to enable one feature called Transaction and a second feature called Message Correlation.

6. SOAP-Supplied Message Exchange Patterns

6.1 Property Conventions for Message Exchange Patterns

Table 2 describes the properties (in accordance with the property naming conventions defined in this document) that support the description of message exchange patterns (MEPs). Other properties may be involved in the specification of particular MEPs, but the properties in this table are generally applicable to all MEPs.

Table 2: Property definitions supporting the description of MEPs
Property Name	Property Description
`context:ExchangePatternName`	A URI that names the MEP in operation.
`context:FailureReason`	A URI value that denotes a pattern specific, binding independent reason for the failure of a message exchange. Underlying protocol binding specifications may define properties to convey more binding specific details of the failure.

6.2 Request-Response Message Exchange Pattern

This section defines the message exchange pattern (MEP) called "Request-Response". The description is an abstract presentation of the operation of this MEP. It is not intended to describe a real implementation or to suggest how a real implementation should be structured.

6.2.1 Message Exchange Pattern Name

This message exchange pattern is identified by the URI:

"http://www.w3.org/2001/12/soap/mep/request-response/"

Protocol binding specifications may use this URI to declare their support for the MEP and its associated semantics.

6.2.2 Description

The Request-Response MEP defines a pattern for the exchange of two messages between two adjacent SOAP nodes along a SOAP message path. One message is exchanged in each direction between a requesting SOAP node and a responding SOAP node.

In the normal operation of a message exchange conforming to the Request-Response MEP, a request message is first transferred from the requesting SOAP node to the responding SOAP node. Following the successful processing of the request message by the responding SOAP node, a response message is transferred from the responding SOAP node to the requesting SOAP node.

Abnormal operation during a Request-Response message exchange may be caused by a failure to transfer the request message, a failure at the responding SOAP node to process the request message, or a failure to transfer the response message. Such failures MAY be silent at either or both of the requesting and responding SOAP nodes involved. Also, during abnormal operation each SOAP node involved in the message exchange MAY differ in its determination of the successful completion of the message exchange.

The scope of a Request-Response MEP is limited to the exchange of a request message and a response message between one requesting and one responding SOAP node. This pattern does not mandate any correlation between multiple requests nor specific timing for multiple requests. Implementations MAY choose to support multiple ongoing requests (and associated response processing) at the same time.

6.2.3 State Machine Description

The Request-Response MEP defines a set of properties described in Table 3.

Table 3: Property definitions for Request-Response MEP
Property Name	Property Description
`reqres:Role`	A URI denoting the pattern specific role of the local SOAP node participating in the message exchange.
`reqres:State`	A URI denoting the current state of the message exchange. This value is managed by the binding instance and may be inspected by other entities monitoring the progress of the message exchange.
`reqres:OutboundMessage`	An abstract structure that represents the current outbound message in the message exchange. This abstracts both SOAP Envelope and any other information structures that are transferred along with the envelope.
`reqres:InboundMessage`	An abstract structure that represents the current inbound message in the message exchange. This abstracts both SOAP Envelope and any other information structures that are transferred along with the envelope.
`reqres:ImmediateDestination`	A URI denoting the immediate destination of an outbound message.
`reqres:ImmediateSender`	A URI denoting the immediate sender of an inbound message.

To initiate a message exchange conforming to the Request-Response MEP, the requesting SOAP node instantiates a local message exchange context. Table 4 describes how the context is initialized.

Table 4: Instantiation of a Message Exchange Context for a requesting SOAP node
Property Name	Property Value
`context:ExchangePatternName`	"http://www.w3.org/2001/12/soap/mep/request-response/"
`context:FailureReason`	None
`reqres:Role`	RequestingSOAPNode
`reqres:State`	Init
`reqres:OutboundMessage`	An abstraction of the request message
`reqres:ImmediateDestination`	An identifier (URI) that denotes the responding SOAP node

There may be other properties related to the operation of the message exchange context instance. Such properties are initialized according to their own feature specifications.

Once the message exchange context is initialized, control of the context is passed to a (conforming) local binding instance.

The diagram below shows the logical state transitions at the requesting and responding SOAP nodes during the lifetime of the message exchange. At each SOAP node, the local binding instance updates (logically) the value of the reqres:State property to reflect the current state of the message exchange. The state names are relative URIs, relative to a Base URI value carried in the reqres:Role property of the local message exchange context.

Request-Response MEP State Transition Diagram.

When the local binding instance at the responding SOAP node starts to receive an inbound request message, it (logically) instantiates a message exchange context. Table 5 describes the properties that the binding initializes as part of the context's instantiation.

Table 5: Instantiation of Message Exchange Context for an inbound request message
Property Name	Property Value
`context:ExchangePatternName`	"http://www.w3.org/2001/12/soap/mep/request-response/" Initialized as early as possible during the life cycle of the message exchange.
`context:FailureReason`	None
`reqres:Role`	RespondingSOAPNode Initialized as early as possible during the life cycle the message exchange.
`reqres:State`	Init

When the requesting and responding SOAP nodes transition between states, the local binding instance (logically) updates a number of properties. Table 6 and Table 7 describe these updates for the requesting and the responding SOAP nodes, respectively.

Table 6: Requesting SOAP Node State Transitions
CurrentState	Transition Condition	NextState	Action
Init	Unconditional	Requesting	Initiate transmission of request message abstracted in `reqres:OutboundMessage` .
Requesting	Message transmission failure	Fail	Set `context:FailureReason` to "transmissionFailure"
Requesting	Start receiving response message	Sending+Receiving	Set `reqres:ImmediateSender` to denote the sender of the response message (may differ from the values in `reqres:ImmediateDestination` ). Start making an abstraction of the response message available in `reqres:InboundMessgae` .
Sending+Receiving	Message exchange failure	Fail	Set `context:FailureReason` to "exchangeFailure"
Sending+Receiving	Completed sending request message. Completed receiving response message.	Success

Table 7: Responding SOAP Node State Transitions
CurrentState	Transition Condition	NextState	Action
Init	Start receiving request message	Receiving	Set `reqres:ImmediateSender` to denote the sender of the request message (if determinable). Start making an abstraction of the request message available in `reqres:InboundMessgae` . Pass control of message exchange context to SOAP processor.
Receiving	Message reception failure	Fail	Set `context:FailureReason` to "receptionFailure".
Receiving	Start of response message available in `reqres:OutboundMessage`	Receiving+Sending	Initiate transmission of response message abstracted in `reqres:OutboundMessage` .
Receiving+Sending	Message exchange failure	Fail	Set `context:FailureReason` to "exchangeFailure".
Receiving+Sending	Completed receiving request message. Completed sending response message.	Success

Bindings that implement this MEP MAY provide for streaming of SOAP responses. That is, responding SOAP nodes MAY begin transmission of a SOAP response while a SOAP request is still being received and processed. When SOAP nodes implement bindings that support streaming, the following rules apply:

All the rules in [1]Binding Framework regarding streaming of individual SOAP messages MUST be obeyed for both request and response SOAP messages.
When using streaming SOAP bindings, requesting SOAP nodes MUST avoid deadlock by accepting and if necessary processing SOAP response information while the SOAP request is being transmitted.
Note:
Depending on the implementation used and the size of the messages involved, this rule MAY require that SOAP applications stream application-level response processing in parallel with request generation.
A requesting SOAP node MAY enter the Fail state, and thus abort transmission of the outbound SOAP request, based on information contained in an incoming streamed SOAP response.

6.2.4 Fault Handling

During the operation of the Request-Response MEP, the participating SOAP nodes may generate SOAP faults.

If a SOAP fault is generated by the responding SOAP node while it is in the Receiving state, the SOAP fault is made available in reqres:OutboundMessage and the state machine transitions to the Receiving+Sending state.

This MEP makes no claims about the disposition or handling of SOAP faults generated by the requesting SOAP node during any processing of the response message that follows the Success state in the requesting SOAP node's state transition table (see Table 6).

7. SOAP HTTP Binding

7.1 Introduction

The SOAP HTTP Binding provides a binding of SOAP to HTTP. The binding conforms to the SOAP Protocol Binding Framework (see [1]SOAP Protocol Binding Framework) and uses abstract properties as a descriptive tool for defining the functionality of certain features.

The SOAP Protocol Binding Framework (see [1]SOAP Protocol Binding Framework), the Message Exchange Pattern Specifications (see [1]SOAP Message Exchange Patterns) and Feature Specifications (see 5. A Convention for Describing Features and Bindings) each describe the properties they expect to be present in a message exchange context when control of that context passes between a local SOAP node and a binding instance.

Properties are named with XML qualified names. Property values are determined by the Schema type of the property, as defined in the specification which introduces the property.

Conforming implementations of this binding:

MUST be capable of sending and receiving messages serialized using media type "application/soap+xml" whose proper use and parameters are described in [12].
MAY send requests and responses using other media types providing that such media types provide for at least the transfer of SOAP XML Infoset.
MAY, when sending requests, provide an HTTP Accept header. This header:
- SHOULD indicate an ability to accept at minimum "application/soap+xml".
- MAY additionally indicate willingness to accept other media types that satisfy 2 above.

Note:

The SOAP HTTP Binding is optional and SOAP nodes are NOT required to implement it. The SOAP version 1.2 specification does not preclude specifications of other bindings to HTTP or bindings to other protocols. A SOAP node that correctly and completely implements the SOAP HTTP Binding may to be said to "conform to the SOAP 1.2 HTTP Binding."

7.2 Binding Name

The binding is identified with the URI:

"http://www.w3.org/2001/12/soap/bindings/HTTP/"

7.3 Supported Message Exchange Patterns

An implementation of the SOAP HTTP Binding MUST support the following message exchange pattern (MEP):

"http://www.w3.org/2001/12/soap/mep/request-response/" (see 6.2 Request-Response Message Exchange Pattern)

7.4 Request-Response MEP Operation

For binding instances conforming to this specification:

A SOAP node instantiated at an HTTP client may assume the role (i.e. the property reqres:Role ) of "RequestingSOAPNode".
A SOAP node instantiated at an HTTP server may assume the role (ie. the property reqres:Role ) of "RespondingSOAPNode".

The remainder of this section describes the MEP state machine and its relation to the HTTP protocol. In the state tables below, the states are defined as values of the property reqres:State (see 6.2 Request-Response Message Exchange Pattern), and are of type reqres:StateType (an enumeration over xs:string ).

Failure reasons that are specified in the tables represent values of the property context:FailureReason and their values are XML qualified names. If an implementation enters the "Fail" state, the context:FailureReason property will contain the value specified for the particular transition.

7.4.1 Behavior of Requesting SOAP Node

The overall flow of the behavior of a requesting SOAP node follows the state machine description contained in 6.2 Request-Response Message Exchange Pattern. This binding supports streaming and, as a result, requesting SOAP nodes MUST avoid deadlock by accepting and if necessary processing SOAP response information while the SOAP request is being transmitted (see 6.2.3 State Machine Description). The following subsections describe each state in detail.

7.4.1.1 Init

Table 8 and Table 9 describe the requesting SOAP node's Init state and the values of the HTTP request fields.

Table 8: State Description: Init
Transitions	Event/Condition	NextState	Failure Reason
Statename	Init
Description	Formulate and start sending HTTP request (see next table)
Preconditions	See 6.2.3 State Machine Description
Postconditions	None
Transitions	Unconditional	Requesting	N/A

Table 9: HTTP Request Fields
Field	Value
HTTP Method	POST (the use of other HTTP methods is undefined in this binding).
Request URI	The value of the URI carried in the `reqres:ImmediateDestination` property of the message exchange context.
Content-Type header	The media type of the request body, see 7.1 Introduction for a description of permissible media types.
Accept header (optional)	List of media types that are acceptable in response to the request message.
Additional Headers	Generated in accordance with the rules for the binding specific expression of any optional features in use for this message exchange.
HTTP entity body	SOAP message serialized according to the rules for carrying SOAP messages in the media type given by the Content-Type header. Rules for carrying SOAP messages in media type "application/soap+xml" are given in [12].

7.4.1.2 Requesting

Table 10 describes the requesting SOAP node's Requesting state.

Table 10: State Description: Requesting
Transitions	Event/Condition	NextState	Failure Reason
Statename	Requesting
Description	Sending request message and waiting for start of response message.
Preconditions	None
Postconditions	Property `reqres:ImmediateSender` instantiated with a URI value that denotes the sender of the HTTP response (if known) HTTP headers significant to features expressed outside the SOAP envelope processed in accordance with the relevant feature specification.
	HTTP Response Status Line and HTTP Headers received	(see status code table below)	(see status code table below)
	Message exchange failure	Fail	"fail:transmissionFailure"

Table 11 details the transitions that take place when a requesting SOAP node reveives an HTTP status line and response headers.

Table 11: HTTP status code dependent transitions
Status Code	Reason phrase	Significance/Action		NextState
2xx	Successful
200	OK	The response message follows in HTTP response entity body. Start making an abstraction of the response message available in `reqres:InboundMessage` .		Sending+Receiving
202	Accepted	The request message has been received and processed. The entity body of the HTTP response MAY contain a response message. Start making an abstraction of the response message available in `reqres:InboundMessage`		Sending+Receiving
204	No Content	The request message has been received and processed. The HTTP response MUST NOT contain an entity body. The message exchange is regarded as having completed successfully.		Sending+Receiving
		Instantiated Property	Value
		`reqres:InboundMessage`	"Empty" SOAP Envelope.
3xx	Redirection	The requested resource has moved and the HTTP request SHOULD be retried using the URI carried in the associated Location header as the new value for the `reqres:ImmediateDestination` property.		Init
4xx	Client Error
400	Bad Request	Indicates a problem with the received HTTP request message. The problem may bea malformed XML in the request message envelope. This operation SHOULD NOT be repeated with the same message content. The message exchange is regarded as having completed unsuccessfully.		Fail
		Instantiated Property	Value
		`context:FailureReason`	"fail:BadRequest"
401	Unauthorized	Indicates that the HTTP request requires authorization.		Requesting
		Instantiated Property	Value
		`context:FailureReason`	"fail:AuthenticationFailure"
		If the simple authentication feature is unavailable or the operation of simple authentication ultimately fails, then the message exchange is regarded as having completed unsuccessfully.		Fail
		Instantiated Property	Value
		`context:FailureReason`	"fail:AuthenticationFailure"
405	Method not allowed	Indicates that the peer HTTP server does not support the requested HTTP method at the given request URI. The message exchange is regarded as having completed unsuccessfully.		Fail
		Instantiated Property	Value
		`context:FailureReason`	"fail:BindingMismatch"
415	Unsupported Media Type	Indicates that the peer HTTP server does not support Content-type used to encode the request message. The message exchange is regarded as having completed unsuccessfully.		Fail
		Instantiated Property	Value
		`context:FailureReason`	"fail:BindingMismatch"
5xx	Server Error
500	Internal Server Error	Indicates that the response message contained in the following HTTP response entity body may contain an SOAP fault. Other internal server errors may be the cause of this status code. The local binding instance continues to receive the incoming message.		Sending+Receiving
		Instantiated Property	Value
		`context:FailureReason`	fail:ServerFault

Note:

There may be elements in the HTTP infrastructure configured to modify HTTP response entity bodies for 4xx and 5xx status code responses. For example, some HTTP origin servers have such a feature as a configuration option. This behavior may interfere with the use of 4xx and 5xx status code responses carrying SOAP fault messages in HTTP and it is recommended that such behavior is disabled for resources accepting SOAP/HTTP requests. If the rewriting behavior cannot be disabled, SOAP/HTTP cannot be used in such configurations.

7.4.1.3 Sending+Receiving

Table 12 describes the requesting SOAP node's Sending+Receiving state.

Table 12: State Description: Sending+Receiving
Transitions	Event/Condition	NextState	Failure Reason
Statename	Sending+Receiving
Description	Completing the transmission of a request message and the reception of a response message. The response message is assumed to be a SOAP envelope serialized according the rules for carrying SOAP messages in the media type given in the Content-Type header.
Preconditions	None
Postconditions	On transitions to Success, the property `reqres:InboundMessage` is instantiated with the Infoset representation of the serialized envelope in the response body.

	Request message transmission and response message reception completed and a well formed response message received	Success	N/A
	Reception Failure (broken connections etc.)	Fail	"fail:ReceptionFailure"
	Packaging Failure (including mismatched Content-Type)	Fail	"fail:PackagingFailure"
	Malformed response message, e.g. malformed XML, message contains a DTD, invalid SOAP Envelope	Fail	"fail:BadResponseMessage"

7.4.1.4 Success and Fail

Succes and Fail are the terminal states of a Request-Response MEP. Control over the message exchange context returns to the local SOAP node.

7.4.2 Behavior of Responding SOAP Node

The overall flow of the behavior of a requesting SOAP node follows the state machine description contained in 6.2 Request-Response Message Exchange Pattern. The following subsections describe each state in detail.

7.4.2.1 Init

Table 13 and Table 14 describe the responding SOAP node's Init state and the faults it generates respectively.

Table 13: State Description: Init
Transitions	Event/Condition	NextState	Action
Statename	Init
Description	Waiting for the start of an inbound request message
Preconditions	Reception of an HTTP POST request at an HTTP endpoint bound to the local SOAP node, see 6.2.3 State Machine Description.
Postconditions	See below
	Receive the beginning of an HTTP POST request containing well formed request message.	Receiving	Instantiate or replace the property `reqres:ImmediateSender` with a URI value that denotes the sender of the HTTP request (if known) Start making an abstraction of the request message available in `reqres:InboundMessage` . Any HTTP headers that are significant to features expressed outside the SOAP envelope are processed in accordance with the relevant feature specification. This change of state represents a transfer of control of the inbound message exchange context to the local SOAP node.
	Receive HTTP POST request containing malformed request message	Fail	The message is considered to have been intended for the local SOAP node. It is considered to be malformed becuase it is not well formed XML, contains a serialized DTD, and/or contains an invalid SOAP envelope. The local SOAP node generates a SOAP fault message in accordance with the following table and sends it in the corresponding HTTP response message, accompanied by a status code value appropriate to the particular fault. The message exchange context may be destroyed or considered not to have been created.

Table 14: Binding Generated Faults
Problem with Message	HTTP Status Code	HTTP Reason Phrase (informative)	SOAP Fault
Malformed Request Message	400	Bad request	None
Unsupported message encapsulation method	415	Unsupported Media	None

7.4.2.2 Receiving

Table 15 describes the responding SOAP node's Receiving state.

Table 15: State Description: Receiving
Transitions	Event/Condition	NextState	Action or Failure Reason
Statename	Receiving
Description	Continue receiving the request message and wait for the start of a response message to be available in the message exchange context.
Preconditions	None
Postconditions	See below
	The start of an abstraction of a response message becomes available in `reqres:OutboundMessage` indicating that the local SOAP processor has generating a response message.	Receiving+Sending	Formulate and start sending the response message, `reqres:OutboundMessage` may contain a SOAP fault.
	Message reception failure	Fail	"fail:receptionFailure"

Table 16 and Table 17 describe the HTTP response headers generated by the responding SOAP node.

Table 16: HTTP Response Headers
Header	Value
Status line	Set according to the next table
Content-Type header	The media type of the response body, see 7.1 Introduction for a description of permissible media types.
Additional Headers	Generated in accordance with the rules for the binding specific expression of any optional features in use for this message exchange.
HTTP Entity Body	SOAP message serialized according to the rules for carrying SOAP messages in the media type given by the Content-Type header. Rules for carrying SOAP messages in `application/soap+xml` are given in [12].

Table 17: SOAP Fault to HTTP Status Mapping
SOAP Fault	HTTP Status Code	HTTP Reason Phrase (informative)
env:VersionMismatch	500	Internal server error
env:MustUnderstand	500	Internal server error
env:Sender	400	Bad request
env:Receiver	500	Internal server error

7.4.2.3 Receiving+Sending

Table 18 describes the responding SOAP node's Responding state.

Table 18: State Description: Receiving+Sending
Transitions	Event/Condition	NextState	Action or Failure Reason
Statename	Receiving+Sending
Description	Completing request message reception and response message transmission.
Preconditions	None
Postconditions	See below
	Response message reception and request message transmission complete.	Success
	Message exchange failure	Fail	"fail:exchangeFailure".

7.4.2.4 Success and Fail

Success and Fail are the terminal states for a Request-Response MEP. From the point-of-view of the local node this message exchange has completed.

7.5 Security Considerations

The SOAP HTTP Binding (see 7. SOAP HTTP Binding) can be considered as an extension of the HTTP application protocol. As such, all of the security considerations identified and described in section 15 of the HTTP specification[2] apply to the SOAP HTTP Binding in addition to those described in [1] "Security Considerations". Implementors of the SOAP HTTP Binding should carefully review this material.

8. References

8.1 Normative References

[1]: W3C Working Draft "SOAP Version 1.2 Part 1: Messaging Framework", Martin Gudgin, Marc Hadley, Jean-Jacques Moreau, Henrik Frystyk Nielsen, @@@@2002 (See soap12-part1.html.)
[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 Recommendation "XML Linking Language (XLink) Version 1.0", Steve DeRose, Eve Maler, David Orchard, 27 June 2001. (See http://www.w3.org/TR/2001/REC-xlink-20010627/.)
[10]: W3C Recommendation "XML Information Set", John Cowan, Richard Tobin, 24 October 2001. (See http://www.w3.org/TR/2001/REC-xml-infoset-20011024/.)
[11]: IETF "RFC 3023: XML Media Types", M. Murata, S. St. Laurent, D. Kohn, July 1998. (See http://www.ietf.org/rfc/rfc3023.txt.)
[12]: IETF "INTERNET DRAFT: The 'application/soap+xml' media type", M. Baker, M. Nottingham, January 14, 2002. (Work in progress). (See http://www.ietf.org/internet-drafts/draft-baker-soap-media-reg-00.txt.)

8.2 Informative References

[13]: XML Protocol Comments Archive (See http://lists.w3.org/Archives/Public/xmlp-comments/.)
[14]: XML Protocol Discussion Archive (See http://lists.w3.org/Archives/Public/xml-dist-app/.)
[15]: XML Protocol Charter (See http://www.w3.org/2000/09/XML-Protocol-Charter.)
[16]: IETF "RFC2045: Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies", N. Freed, N. Borenstein, November 1996. (See http://www.ietf.org/rfc/rfc2045.txt.)
[17]: IETF "RFC 2026: The Internet Standards Process -- Revision 3", section 4.2.3, S. Bradner, October 1996. (See http://www.ietf.org/rfc/rfc2026.txt.)

A. Mapping Application Defined Names to XML Names

Hex Digits

[4] hexDigit ::= [0-9A-F]

A.1 Rules for mapping application defined names to XML Names

XML Name has two parts: Prefix and LocalPart. Let Prefix be computed per the rules and constraints specified in Namespaces in XML [7].
Let TAG be a name in an application. TAG is a sequence of characters of the application. Let N be the number of characters in TAG. Let T₁, T₂, ... , T_N be the characters of TAG, in order from left to right.
Let M be the implementation-defined mapping of the characters of the application to characters of Unicode.
For each i between 1 (one) and N, let M_i be M(T_i).
For each i between 1 (one) and N, let X_i be the Unicode character string defined by the following rules.
Case:
1. If T_i has no mapping to Unicode (i.e. M(T_i) is undefined), then X_i is implementation-defined
2. If i<=N-1, T_i is "_" (underscore), and T_i+1 is "x" (lowercase letter x), then let X_i be "_x005F_".
3. If i=1, N>=3, T₁ is either "x" (lowercase letter x) or "X" (uppercase letter X), T₂ is either "m" (lowercase letter m) or "M" (uppercase letter M), and T₃ is either "l" (lowercase letter l) or "L" (uppercase letter L), then let X_i be "_xFFFF_"T₁
4. If T_i is not a valid XML NCName character or if i=1 (one) and T₁ is not a valid first character of an XML NCName, then:
  Let U₁, U₂, ... , U₈ be the eight hex digits [PROD: 4] such that T_i is "U+"U₁U₂ ... U₈ in the UCS-4 encoding.
  Case:
  1. If U₁=0, U₂=0, U₃=0, and U₄=0, then let X_i="_x"U₅U₆U₇U₈"_".
    This case implies that T_i has a UCS-2 encoding, which is U+U₅U₆U₇U₈.
  2. Otherwise, let X_i be "_x"U₁U₂U₃U₄U₅U₆U₇U₈"_".
5. Otherwise, let X_i be M_i. That is, any character in TAG that is a valid character in an XML NCName is simply copied.
Let LocalPart be the character string concatenation of X₁, X₂, ... , X_N in order from left to right.
Let XML Name be the QName per Namespaces in XML [7]

A.2 Examples

Hello world -> Hello_x0020_world
Hello_xorld -> Hello_x005F_xorld
Helloworld_ -> Helloworld_

          x -> x
        xml -> _xFFFF_xml
       -xml -> _x002D_xml
       x-ml -> x-ml

B. Using W3C XML Schema with SOAP Encoding (Non-Normative)

As noted in 3.1.4 Computing the Type Name property SOAP graph nodes are labeled with type names, but validation of encoded SOAP messages MUST NOT be required by conforming processors. These sections describe techniques that can be used when validation with W3C XML schemas is desired for use by SOAP applications. Any errors or faults resulting from such validation are beyond those covered by the normative recommendation; from the perspective of SOAP, such faults are considered to be application-level failures.

B.1 Validating using the minimum schema

Although W3C XML schemas are conventionally exchanged in the form of schema documents (see [4]), the schema recommendation is build on an abstract definition of schemas, to which all processors must conform. The schema recommendation provides that all such schemas include definitions for a core set of built in types, such as integers, dates, and so on (see [4], Built-in Simple Type Definition). Thus, it is possible to discuss validation of a SOAP message against such a minimal schema, which is the one that would result from providing no additional definitions or declarations (i.e. no schema document) to a schema processor.

The minimal schema provides that any well formed XML document will validate, except that where an xsi:type is provided, the type named must be built in, and the corresponding element must be valid per that type. Thus, validation of a SOAP 1.2 message using a minimal schema approximates the behavior of the built-in types of SOAP 1.1.

B.2 Validating using the SOAP Encoding schema

Validation against the minimal schema (see B.1 Validating using the minimum schema) will not succed where encoded graph nodes have multiple inbound edges. The SOAP Encoding of such graphs MAY be validated against the SOAP Encoding schema. In order for the encoding to validate, edge labels, and hence element namespace names and local names, must match those defined in the SOAP Encoding schema. Validation of the encoded graph against the SOAP Encoding schema would result in the type name property of the nodes in the graph being assigned the relevant type name.

B.3 Validating using more specific schemas

It may be that schemas could be constructed to describe the encoding of certain graphs. Validation of the encoded graph against such a schema would result in the type name property of the graph nodes being assigned the relevant type name.

C. SOAP HTTP Binding Examples (Non-Normative)

C.1 Sample Encoding of Call Requests

Example 2: SOAP HTTP Request Using POST

POST /StockQuote HTTP/1.1
Content-Type: application/soap+xml; charset="utf-8"
Content-Length: nnnn

<?xml version="1.0" ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/12/soap-envelope" >
 . . .
</env:Envelope>

Example 3: SOAP message using SOAP Encoding in HTTP POST with a mandatory header

POST /StockQuote HTTP/1.1
Host: www.example.org
Content-Type: application/soap+xml; charset="utf-8"
Content-Length: nnnn

<?xml version="1.0" ?>
<env:Envelope
     xmlns:env="http://www.w3.org/2001/12/soap-envelope" >
 <env:Header>
  <t:Transaction
     xmlns:t="http://example.org/2001/06/tx"
     env:encodingStyle="http://www.w3.org/2001/12/soap-encoding"
     env:mustUnderstand="true" >
     5
  </t:Transaction>
 </env:Header>
 <env:Body >
  <m:GetLastTradePrice
     env:encodingStyle="http://www.w3.org/2001/12/soap-encoding"
     xmlns:m="http://example.org/2001/06/quotes" >
   <m:symbol>DEF</m:symbol>
  </m:GetLastTradePrice>
 </env:Body>
</env:Envelope>

Example 4: SOAP message using SOAP Encoding in HTTP POST with multiple request parameters

POST /StockQuote HTTP/1.1
Host: www.example.org
Content-Type: application/soap+xml; charset="utf-8"
Content-Length: nnnn

<?xml version="1.0" ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/12/soap-envelope" >
 <env:Body>
  <m:GetLastTradePriceDetailed
     env:encodingStyle="http://www.w3.org/2001/12/soap-encoding"
     xmlns:m="http://example.org/2001/06/quotes" >
   <Symbol>DEF</Symbol>
   <Company>DEF Corp</Company>
   <Price>34.1</Price>
  </m:GetLastTradePriceDetailed>
 </env:Body>
</env:Envelope>

C.2 Sample Encoding of Response

Example 5: SOAP HTTP Response

HTTP/1.1 200 OK
Content-Type: application/soap+xml; charset="utf-8"
Content-Length: nnnn

<?xml version="1.0" ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/12/soap-envelope" >
 . . .
</env:Envelope>

Example 6: SOAP message using SOAP Encoding in HTTP response including a mandatory header

HTTP/1.1 200 OK
Content-Type: application/soap+xml; charset="utf-8"
Content-Length: nnnn

<?xml version="1.0" ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/12/soap-envelope" >
 <env:Header>
  <t:Transaction 
     xmlns:t="http://example.org/2001/06/tx"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xmlns:xs="http://www.w3.org/2001/XMLSchema"
     xsi:type="xs:int"
     env:encodingStyle="http://www.w3.org/2001/12/soap-encoding"
     env:mustUnderstand="true" >
     5
  </t:Transaction>
 </env:Header>
 <env:Body>
  <m:GetLastTradePriceResponse
     env:encodingStyle="http://www.w3.org/2001/12/soap-encoding"
     xmlns:m="http://example.org/2001/06/quotes" >
   <Price>34.5</Price>
  </m:GetLastTradePriceResponse>
 </env:Body>
</env:Envelope>

Example 7: Similar to previous example but using a struct for the body and omitting the mandatory header

HTTP/1.1 200 OK
Content-Type: application/soap+xml; charset="utf-8"
Content-Length: nnnn

<?xml version="1.0" ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/12/soap-envelope" >
 <env:Body>
  <m:GetLastTradePriceResponse
     env:encodingStyle="http://www.w3.org/2001/12/soap-encoding"
     xmlns:m="http://example.org/2001/06/quotes" >
   <PriceAndVolume>
    <LastTradePrice>34.5</LastTradePrice>
    <DayVolume>10000</DayVolume>
   </PriceAndVolume>
  </m:GetLastTradePriceResponse>
 </env:Body>
</env:Envelope>

Example 8: Must understand fault in HTTP response

HTTP/1.1 500 Internal Server Error
Content-Type: application/soap+xml; charset="utf-8"
Content-Length: nnnn

<?xml version="1.0" ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/12/soap-envelope">
 <env:Body>
  <env:Fault>
   <env:Code><env:Value>env:MustUnderstand</env:Value></env:Code>
   <env:Reason>SOAP Must Understand Error</env:Reason>
  </env:Fault>
 </env:Body>
</env:Envelope>

Example 9: SOAP fault, resulting from failure to handle the SOAP body, in HTTP response

HTTP/1.1 500 Internal Server Error
Content-Type: application/soap+xml; charset="utf-8"
Content-Length: nnnn

<?xml version="1.0" ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/12/soap-envelope" >
 <env:Body>
  <env:Fault xmlns:e="http://example.org/2001/06/faults" >
   <env:Code>
    <env:Value>env:Server</env:Value>
    <env:Subcode>
     <env:Value>e:OutOfMemory</env:Value>
    </env:Subcode>
   </env:Code>
   <env:Reason>Server Error</env:Reason>
   <env:Detail>
    <e:myfaultdetails>
     <message>My application didn't work</message>
    </e:myfaultdetails>
   </env:Detail>
  </env:Fault>
 </env:Body>
</env:Envelope>

D. Acknowledgements (Non-Normative)

This document is the work of the W3C XML Protocol Working Group.

Members of the Working Group are (at the time of writing, and by alphabetical order): Yasser al Safadi (Philips Research), Vidur Apparao (Netscape), Don Box (DevelopMentor), Charles Campbell (Informix Software), Michael Champion (Software AG), Dave Cleary (webMethods), Ugo Corda (Xerox), Paul Cotton (Microsoft Corporation), Ron Daniel (Interwoven), Glen Daniels (Allaire), Doug Davis (IBM), Ray Denenberg (Library of Congress), Paul Denning (MITRE Corporation), Frank DeRose (TIBCO Software, Inc.), Colleen Evans (Progress Software), James Falek (TIBCO Software, Inc.), David Fallside (IBM), Chris Ferris (Sun Microsystems), Daniela Florescu (Propel), Dietmar Gaertner (Software AG), Rich Greenfield (Library of Congress), Martin Gudgin (DevelopMentor), Hugo Haas (W3C), Marc Hadley (Sun Microsystems), Mark Hale (Interwoven), Randy Hall (Intel), Gerd Hoelzing (SAP AG), Oisin Hurley (IONA Technologies), Yin-Leng Husband (Compaq), John Ibbotson (IBM), Ryuji Inoue (Matsushita Electric Industrial Co., Ltd.), Scott Isaacson (Novell, Inc.), Kazunori Iwasa (Fujitsu Software Corporation), Murali Janakiraman (Rogue Wave), Mario Jeckle (Daimler-Chrysler Research and Technology), Eric Jenkins (Engenia Software), Mark Jones (AT&T), Anish Karmarkar (Oracle), Jeffrey Kay (Engenia Software), Richard Koo (Vitria Technology Inc.), Jacek Kopecky (IDOOX s.r.o.), Yves Lafon (W3C), Tony Lee (Vitria Technology Inc.), Michah Lerner (AT&T), Henry Lowe (OMG), Richard Martin (Active Data Exchange), Noah Mendelsohn (Lotus Development), Jeff Mischkinsky (Oracle), Nilo Mitra (Ericsson Research Canada), Jean-Jacques Moreau (Canon), Highland Mary Mountain (Intel), Masahiko Narita (Fujitsu Software Corporation), Mark Needleman (Data Research Associates), Eric Newcomer (IONA Technologies), Henrik Frystyk Nielsen (Microsoft Corporation), Mark Nottingham (Akamai Technologies), David Orchard (BEA Systems), Kevin Perkins (Compaq), Jags Ramnaryan (BEA Systems), Andreas Riegg (Daimler-Chrysler Research and Technology), Herve Ruellan (Canon), Marwan Sabbouh (MITRE Corporation), Shane Sesta (Active Data Exchange), Miroslav Simek (IDOOX s.r.o.), Simeon Simeonov (Allaire), Nick Smilonich (Unisys), Soumitro Tagore (Informix Software), Lynne Thompson (Unisys), Patrick Thompson (Rogue Wave), Asir Vedamuthu (webMethods) Ray Whitmer (Netscape), Volker Wiechers (SAP AG), Stuart Williams (Hewlett-Packard), Amr Yassin (Philips Research) and Jin Yu (Martsoft Corp.).

Previous members were: Eric Fedok (Active Data Exchange), Susan Yee (Active Data Exchange), Dan Frantz (BEA Systems), Alex Ceponkus (Bowstreet), James Tauber (Bowstreet), Rekha Nagarajan (Calico Commerce), Mary Holstege (Calico Commerce), Krishna Sankar (Cisco Systems), David Burdett (Commerce One), Murray Maloney (Commerce One), Jay Kasi (Commerce One), Yan Xu (DataChannel), Brian Eisenberg (DataChannel), Mike Dierken (DataChannel), Michael Freeman (Engenia Software), Bjoern Heckel (Epicentric), Dean Moses (Epicentric), Julian Kumar (Epicentric), Miles Chaston (Epicentric), Alan Kropp (Epicentric), Scott Golubock (Epicentric), Michael Freeman (Engenia Software), Jim Hughes (Fujitsu Limited), Dick Brooks (Group 8760), David Ezell (Hewlett Packard), Fransisco Cubera (IBM), David Orchard (Jamcracker), Alex Milowski (Lexica), Steve Hole (MessagingDirect Ltd.), John-Paul Sicotte (MessagingDirect Ltd.), Vilhelm Rosenqvist (NCR), Lew Shannon (NCR), Art Nevarez (Novell, Inc.), David Clay (Oracle), Jim Trezzo (Oracle), David Cleary (Progress Software), Andrew Eisenberg (Progress Software), Peter Lecuyer (Progress Software), Ed Mooney (Sun Microsystems), Mark Baker (Sun Microsystems), Anne Thomas Manes (Sun Microsystems), George Scott (Tradia Inc.), Erin Hoffmann (Tradia Inc.), Conleth O'Connell (Vignette), Waqar Sadiq (Vitria Technology Inc.), Randy Waldrop (WebMethods), Bill Anderson (Xerox), Tom Breuel (Xerox), Matthew MacKenzie (XMLGlobal Technologies), David Webber (XMLGlobal Technologies), John Evdemon (XMLSolutions) and Kevin Mitchell (XMLSolutions).

The people who have contributed to discussions on xml-dist-app@w3.org are also gratefully acknowledged.

E. Part 2 Change Log (Non-Normative)

E.1 SOAP Specification Changes

Date	Author	Description
20020509	MJH	Added RPC root resolution.
20020509	MJH	Added bib refs to spec cross refs. Fixed some xspecrefs that were empty and so didn't show up in the html. Removed pt1 section numbers from cross references since these are not autogenerated and would be a maintenance headache.
20020506	JJM	Removed double-spaces.
20020506	JJM	Divided the long list in "SOAP RPC and Body" into two separate lists.
20020506	JJM	Fixed a few typos.
20020503	HFN	Changed "faulthint" to "faultreason".
20020503	HFN	Made the order of properties listed in ReqRes MEP tables and removed "local abort" as per "http://lists.w3.org/Archives/Member/w3c-xml-protocol-wg/2002May/0005.html". Also fixed the prefix given that some properties have moved from context to reqres.
20020503	HFN	Removed the sentence "This URI is often abbreviated to the term "request-response" throughout this specification." as we have already said that the MEP is called "Request-Response". Also, have casing consistent in using the name (was often "request-response").
20020503	HFN	Removed the notion that MEP properties are relative URIs - they are just URIs.
20020503	MJH	Added table cross-references.
20020503	MJH	Added streaming edits to state tables in MEP and HTTP binding.
20020503	JJM	Added a couple of missing "SOAP" to streaming stuff.
20020503	JJM	Added back streaming stuff (with proper XML formatting), after CVS hick-up.
20020502	JJM	Added missing <att>
20020502	MJG	Clarified arraySize BNF
20020502	MJH	Incorporated readability changes into abstract.
20020502	MJH	Incorporated readability changes into section 7.
20020502	MJH	Decapitalised requesting, responding, request, response, message, node and path.
20020502	MJH	Incorporated readability changes into sections 5 and 6.
20020502	MJH	Incorporated readability changes into Section 1.
20020501	HFN	Change SOAP Node to SOAP node
20020501	HFN	Incorporated changes referring first ednote in mail thread in http://lists.w3.org/Archives/Member/w3c-xml-protocol-wg/2002May/0005.html
20020501	HFN	Changed "Message Exchange" and other permutations to "MEP"
20020501	MJH	Fixed dangling xref.
20020430	MJG	Incorporated readability changes into Section 4.
20020430	MJG	Incorporated readability changes into Section 3.
20020430	MJG	Incorporated readability changes into Section 2.
20020426	JJM	Updated member list.
20020426	MJH	Removed SOAPAction section - moved to application/soap+xml ID.
20020425	MJG	Removed notion of local/global scoping from SOAP Encoding per http://lists.w3.org/Archives/Public/xmlp-comments/2002Apr/0024.html
20020425	MJG	Updated on Appendix B1
20020425	MJG	Started on Appendices B2 and B3
20020425	MJH	Completed HTTP status code mapping table (#196).
20020425	MJH	Added resolution for issue #192.
20020425	JJM	Started incorporating resolution for issue #196.
20020424	MJH	Added issue 197 resolution.
20020411	MJH	Fixed responding table in HTTP section.
20020411	MJH	Removed pt1 TOC from intro and cleaned up abstract.
20020410	MJG	Added an id to a div
20020410

SOAP Version 1.2 Part 2: Adjuncts

Editors' Copy May 14 2002

Abstract

Status of this Document

Short Table of Contents

Table of Contents

Appendices

1. Introduction

1.1 Notational Conventions

2. SOAP Data Model

2.1 Graph Edges

2.1.1 Edge labels

2.2 Graph Nodes

2.2.1 Single and Multi reference nodes

2.3 Values

3. SOAP Encoding

3.1 Rules for Encoding Graphs in XML

3.1.1 Encoding graph edges and nodes

3.1.2 Encoding simple values

3.1.3 Encoding compound values

3.1.4 Computing the Type Name property

3.1.4.1 itemType Attribute Information Item

3.1.5 Unique identifiers

3.1.5.1 id Attribute Information Item

3.1.5.2 ref Attribute Information Item

3.1.5.3 Constraints on id and ref attribute information items

3.1.6 arraySize Attribute Information Item

3.2 Decoding Faults

4. SOAP RPC Representation

4.1 RPC and SOAP Body

4.1.1 RPC Invocation

4.1.2 RPC Response

4.1.3 SOAP Encoding Restriction

4.2 RPC and SOAP Header

4.3 RPC Faults

5. A Convention for Describing Features and Bindings

5.1 Model and Properties

5.1.1 Properties

5.1.2 Property Scope

5.1.3 Properties and Features

6. SOAP-Supplied Message Exchange Patterns

6.1 Property Conventions for Message Exchange Patterns

6.2 Request-Response Message Exchange Pattern

6.2.1 Message Exchange Pattern Name

6.2.2 Description

6.2.3 State Machine Description

6.2.4 Fault Handling

7. SOAP HTTP Binding

7.1 Introduction

7.2 Binding Name

7.3 Supported Message Exchange Patterns

7.4 Request-Response MEP Operation

7.4.1 Behavior of Requesting SOAP Node

7.4.1.1 Init

7.4.1.2 Requesting

7.4.1.3 Sending+Receiving

7.4.1.4 Success and Fail

7.4.2 Behavior of Responding SOAP Node

7.4.2.1 Init

7.4.2.2 Receiving

7.4.2.3 Receiving+Sending

7.4.2.4 Success and Fail

7.5 Security Considerations

8. References

8.1 Normative References

8.2 Informative References

A. Mapping Application Defined Names to XML Names

Hex Digits

A.1 Rules for mapping application defined names to XML Names

A.2 Examples

B. Using W3C XML Schema with SOAP Encoding (Non-Normative)

B.1 Validating using the minimum schema

B.2 Validating using the SOAP Encoding schema

B.3 Validating using more specific schemas

C. SOAP HTTP Binding Examples (Non-Normative)

C.1 Sample Encoding of Call Requests

C.2 Sample Encoding of Response

D. Acknowledgements (Non-Normative)

E. Part 2 Change Log (Non-Normative)

E.1 SOAP Specification Changes