W3C

DRAFT Rewrite of SOAP Version 1.2 Part 2: Adjuncts

$Date: 2005/12/21 15:02:31 $

This version:
/
Latest version:
http://www.w3.org/TR//
Previous version:
http://www.w3.org/TR/2003/REC-soap12-part2-20030624/
Editors:
Martin Gudgin, Microsoft
Marc Hadley, Sun Microsystems
Noah Mendelsohn, IBM
Jean-Jacques Moreau, Canon
Henrik Frystyk Nielsen, Microsoft

Abstract

SOAP Version 1.2 is a lightweight protocol intended for exchanging structured information in a decentralized, distributed environment. SOAP Version 1.2 Part 2: Adjuncts defines a set of adjuncts that may be used with SOAP Version 1.2 Part 1: Messaging Framework. This specification depends on SOAP Version 1.2 Part 1: Messaging Framework [SOAP Part 1].

Status of this Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. The latest status of this document series is maintained at the W3C.

Table of Contents

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 Mapping between XML and the SOAP Data Model
        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.1.7 nodeType Attribute Information Item
    3.2 Decoding Faults
4 SOAP RPC Representation
    4.1 Use of RPC on the World Wide Web
        4.1.1 Identification of RPC Resources
        4.1.2 Distinguishing Resource Retrievals from other RPCs
    4.2 RPC and SOAP Body
        4.2.1 RPC Invocation
        4.2.2 RPC Response
        4.2.3 SOAP Encoding Restriction
    4.3 RPC and SOAP Header
    4.4 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.2.1 Message Exchange Context
            5.1.2.2 Environment Context
        5.1.3 Properties and Features
6 SOAP-Supplied Message Exchange Patterns and Features
    6.1 SOAP Request-Response Message Exchange Pattern
        6.1.1 SOAP Feature Name
        6.1.2 Description
        6.1.3 Property Description
        6.1.4 Fault Handling
    6.2 SOAP Web Method Feature
        6.2.1 SOAP Feature Name
        6.2.2 Description
        6.2.3 SOAP Web Method Feature Properties
    6.3 SOAP Action Figure
        6.3.1 SOAP Feature Name
        6.3.2 Description
        6.3.3 SOAP Action Figure State Machine
7 SOAP HTTP Binding
    7.1 Introduction
        7.1.1 Optionality
        7.1.2 Use of HTTP
        7.1.3 Interoperability with non-SOAP HTTP Implementations
        7.1.4 HTTP Media-Type
    7.2 Binding Name
    7.3 Supported Message Exchange Patterns
    7.4 Supported Features
    7.5 MEP Operation
        7.5.1 Behavior of Requesting SOAP Node
            7.5.1.1 Init
            7.5.1.2 Requesting
            7.5.1.3 Sending+Receiving
            7.5.1.4 Success and Fail
        7.5.2 Behavior of Responding SOAP Node
            7.5.2.1 Init
            7.5.2.2 Receiving
            7.5.2.3 Receiving+Sending
            7.5.2.4 Success and Fail
    7.6 Security Considerations
8 References
    8.1 Normative References
    8.2 Informative References

Appendices

A The application/soap+xml Media Type
B Mapping Application-Defined Names to XML Names
    B.1 Rules for Mapping Application-Defined Names to XML Names
    B.2 Examples
C Using W3C XML Schema with SOAP Encoding (Non-Normative)
    C.1 Validating Using the Minimum Schema
    C.2 Validating Using the SOAP Encoding Schema
    C.3 Validating Using More Specific Schemas
D Acknowledgements (Non-Normative)


1 Introduction

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

  1. The SOAP Data Model represents application-defined data structures and values as a directed, edge-labeled graph of nodes (see 2 SOAP Data Model).

  2. 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).

  3. 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).

  4. The section for describing features and bindings defines a convention for describing features and binding in terms of properties and property values (see 5 A Convention for Describing Features and Bindings).

  5. The section on SOAP-Supplied Message Exchange Patterns and Features defines a request response message exchange pattern (see 6 SOAP-Supplied Message Exchange Patterns and Features).

  6. The SOAP Web Method feature defines a feature for control of methods used on the World Wide Web (see 6.2 SOAP Web Method Feature).

  7. The SOAP HTTP Binding defines a binding of SOAP to HTTP (see [RFC 2616]) following the rules of the SOAP Protocol Binding Framework, [SOAP Part 1] (see 7 SOAP HTTP Binding).

SOAP 1.2 Part 0 [SOAP Part 0] is a non-normative document intended to provide an easily understandable tutorial on the features of the SOAP Version 1.2 specifications.

SOAP 1.2 Part 1 [SOAP Part 1] defines the SOAP messaging framework.

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 RFC 2119 [RFC 2119].

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

Prefixes and Namespaces used in this specification
PrefixNamespaceNotes
env"http://www.w3.org/2003/05/soap-envelope"Defined by SOAP 1.2 Part 1 [SOAP Part 1].
enc"http://www.w3.org/2003/05/soap-encoding"A normative XML Schema [XML Schema Part 1], [XML Schema Part 2] document for the "http://www.w3.org/2003/05/soap-encoding" namespace can be found at http://www.w3.org/2003/05/soap-encoding.
rpc"http://www.w3.org/2003/05/soap-rpc"A normative XML Schema [XML Schema Part 1], [XML Schema Part 2] document for the "http://www.w3.org/2003/05/soap-rpc" namespace can be found at http://www.w3.org/2003/05/soap-rpc.
xs"http://www.w3.org/2001/XMLSchema"Defined in the W3C XML Schema specification [XML Schema Part 1], [XML Schema Part 2].
xsi"http://www.w3.org/2001/XMLSchema-instance"Defined in the W3C XML Schema specification [XML Schema Part 1], [XML Schema Part 2].

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

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

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 structures and values 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 may not need to use the SOAP Data Model. Due to their optional nature, 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.

3 SOAP Encoding

SOAP Encoding provides a means of encoding 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 SOAP 1.2 Part 1 [SOAP Part 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 (RPC)).

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

3.1 Mapping between XML and the SOAP Data Model

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 requests 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, a representation that deserializes to the identical graph MUST be used; when multiple such representations are possible, any of them 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:

  1. If the element information item representing the edge does not have a refattribute 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. In such cases the element information item represents both a graph edge and a graph node

  2. If the element information item representing the edge does have a refattribute 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 idattribute 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 idattribute information item appears. That element information item MUST be in the scope of an encodingStyle attribute with a value of "http://www.w3.org/2003/05/soap-encoding" (see SOAP 1.2 Part 1 [SOAP Part 1], SOAP encodingStyle Attribute).

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.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:

  1. For a graph edge which is distinguished by label, the [local name] and [namespace name] properties of the child element information item together determine the value of the edge label.

  2. For a graph edge which is distinguished by position:

    • The ordinal position of the graph edge corresponds to the position of the child element information item relative to its siblings

    • The [local name] and [namespace name] properties of the child element information item are not significant.

  3. The element information item representing a compound value node MAY have among its attributes a nodeTypeattribute information item (see 3.1.7 nodeType Attribute Information Item).

  4. The following rules apply to the encoding of a graph node that represents an "array":

  5. 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:

  1. If the element information item representing the graph node has an xsi:typeattribute information item among its attributes then the type name property of the graph node is the value of the xsi:typeattribute information item.

    Note:

    This attribute is of type xs:QName (see XML Schema [XML Schema Part 2]); 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.

  2. Otherwise if the parent element information item of the element information item representing the graph node has an enc:itemTypeattribute 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 enc:itemTypeattribute information item

  3. 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 Encoding with particular schema languages or type systems. Such additional specifications MAY mandate validation using particular schema language, and MAY specify faults to be generated if validation fails. Such additional specifications MAY specify augmentations to the deserialized graph based on information determined from such a validation. The use by SOAP Encoding of xsi:type is intended to facilitate integration with the W3C XML Schema language (see C 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.2 Decoding Faults

During deserialization a SOAP receiver:

4 SOAP RPC Representation

One of the design goals of SOAP is to facilitate the exchange of messages that map conveniently to definitions and invocations of methods and procedures in commonly used programming languages. For that purpose, this section defines a uniform representation of remote procedure call (RPC) requests and responses. It does not define actual mappings to any particular programming language. The representation is entirely platform-independent and considerable effort has been made to encourage usage that is consistent with the Web in general.

As mentioned in section 2 SOAP Data Model, use and implementation of the SOAP RPC Representation is OPTIONAL.

The SOAP encodingStyle attribute information item (see SOAP 1.2 Part 1 [SOAP Part 1]SOAP encodingStyle Attribute) is used to indicate the encoding style of the RPC representation. The encoding thus specified MUST support the 2 SOAP Data Model. 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 to the SOAP HTTP Binding.

To invoke an RPC, the following information is needed:

SOAP RPC 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 identifier (see RFC 2396 [RFC 2396] for more information on URIs). The section 4.1.1 Identification of RPC Resources further discusses the use of URIs for identifying RPC resources.

The SOAP RPC Representation employs the 6.1 SOAP Request-Response Message Exchange Pattern and ???. Use of the SOAP RPC Representation with other MEPs MAY be possible, but is beyond the scope of this specification.

4.1 Use of RPC on the World Wide Web

The following guidelines SHOULD be followed when deploying SOAP RPC applications on the World Wide Web.

4.1.2 Distinguishing Resource Retrievals from other RPCs

The World Wide Web depends on mechanisms that optimize commonly performed information retrieval tasks. Specifically, protocols such as HTTP [RFC 2616] provide a GET method which is used to perform safe retrievals, i.e., to perform retrievals that are idempotent, free of side effects, and for which security considerations do not preclude the use of cached results or URI-based resource identification.

Certain procedure or method calls represent requests for information retrieval. For example, the call:

getQuantityInStock(PartNumber="123")

might be used to retrieve the quantity established in the example above.

The following conventions can be employed to implement SOAP retrievals and other RPCs on the Web:

  • The conventions described in 4.1.1 Identification of RPC Resources are used to identify the resource with a URI.

  • In cases where all the arguments have been represented in the URI, no SOAP header blocks are to be transmitted and the operation is a safe retrieval, the 6.2 SOAP Web Method Feature and the ??? are used. Accordingly, no SOAP envelope is transmitted for the request, and the http://www.w3.org/2003/05/soap/features/web-method/Method property is set to "GET". The results of the retrieval are a SOAP RPC response as described in 4.2.2 RPC Response

  • In cases where the operation to be performed is not a retrieval, when SOAP header blocks are to be transmitted (a digital signature, for example), or when a retrieval is not safe, the 6.2 SOAP Web Method Feature and the 6.1 SOAP Request-Response Message Exchange Pattern are used. The request envelope is encoded as described in 4.2.1 RPC Invocation, and the results are as described in 4.2.2 RPC Response. The http://www.w3.org/2003/05/soap/features/web-method/Method property is set to "POST".

The SOAP RPC Representation does not define any other value for the http://www.w3.org/2003/05/soap/features/web-method/Method.

4.2 RPC and SOAP Body

RPC invocations (except for safe retrievals: see 4.1.2 Distinguishing Resource Retrievals from other RPCs) and responses are both carried in the SOAP Body element (see SOAP 1.2 Part 1 [SOAP Part 1]SOAP Body) using the following representation:

4.2.1 RPC Invocation

An RPC invocation is modeled as follows:

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

4.2.2 RPC Response

An RPC response is modeled as follows:

4.2.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.

4.4 RPC Faults

The SOAP RPC Representation introduces additional SOAP fault subcode values to be used in conjunction with the fault codes described in SOAP 1.2 Part 1 [SOAP Part 1]SOAP Fault Codes.

Errors arising during RPC invocations are reported according to the following rules:

  1. A fault with a Value of Code set to "env:Receiver" SHOULD be generated when the receiver cannot handle the message because of some temporary condition, e.g. when it is out of memory.

    Note:

    Throughout this document, the term "Value of Code" is used as a shorthand for "value of the Value child element information item of the Codeelement information item" (see SOAP 1.2 Part 1 [SOAP Part 1], SOAP Code Element ).

  2. A fault with a Value of Code set to "env:DataEncodingUnknown" SHOULD be generated when the arguments are encoded in a data encoding unknown to the receiver.

  3. A fault with a Value of Code set to "env:Sender" and a Value of Subcode set to "rpc:ProcedureNotPresent" MAY be generated when the receiver does not support the procedure or method specified.

    Note:

    Throughout this document, the term "Value of Subcode" is used as a shorthand for "value of the Value child element information item of the Subcodeelement information item" (see SOAP 1.2 Part 1 [SOAP Part 1], SOAP Subcode element).

  4. A fault with a Value of Code set to "env:Sender" and a Value of Subcode set to "rpc:BadArguments" MUST be generated when the receiver cannot parse the arguments or when there is a mismatch in number and/or type of the arguments between what the receiver expects and what was sent.

  5. Other faults arising in an extension or from the application SHOULD be generated as described in SOAP 1.2 Part 1 [SOAP Part 1]SOAP Fault Codes.

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

Note:

Senders might receive different faults from those listed above in response to an RPC invocation if the receiver does not support the (optional) RPC convention described here.

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 SOAP 1.2 Part 1 [SOAP Part 1]SOAP Protocol Binding Framework) and it is used to describe a Request-Response MEP (see 6.1 SOAP Request-Response Message Exchange Pattern), the SOAP Web Method feature (see 6.2 SOAP Web Method Feature) and the SOAP HTTP Binding (see 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 metadata. In the model, the message, any message metadata, and the various information items that enable features are represented as abstractions called properties.

5.1.2 Property Scope

Properties within a SOAP node differ in terms of their scope and the origins of their values. As shown in the figure below, we make the distinction between per-message-exchange properties and more widely scoped properties by assigning them to different containers called Message Exchange Context and Environment Context respectively. All properties, regardless of their scope, are shared by a SOAP node and a particular Binding.

Model describing properties shared between SOAP and Binding

6 SOAP-Supplied Message Exchange Patterns and Features

6.1 SOAP 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.1.2 Description

The SOAP Request-Response MEP defines a pattern for the exchange of a message acting as a request optionally followed by a message acting as a response. The messages may or may not carry SOAP envelopes. In the absence of failure in the underlying protocol, this MEP consists of one request message and one optional response message:

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

Abnormal operation during a Request-Response message exchange might be caused by a failure to transfer the request message, a failure at the responding node to process the request message, or a failure to transfer the response message. Such failures might be silent at either or both of the requesting and responding nodes involved, or might result in the generation of a SOAP or binding-specific fault (see 6.1.4 Fault Handling). Also, during abnormal operation each node involved in the message exchange might 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 an optional response message between one requesting and one responding 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.1.3 Property Description

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

Property definitions for Request-Response MEP
Property NameProperty DescriptionProperty Type
http://www.w3.org/2003/05/soap/mep/OutboundMessageAn abstract structure that represents the current outbound message in the message exchange. This abstracts both any SOAP Envelope and any other information structures that are transferred along with the envelope.Not specified
http://www.w3.org/2003/05/soap/mep/InboundMessageAn abstract structure that represents the current inbound message in the message exchange. This abstracts both any SOAP Envelope and any other information structures that are transferred along with the envelope.Not specified
http://www.w3.org/2003/05/soap/mep/ImmediateDestinationThe identifier of the immediate destination of an outbound message.xs:anyURI
http://www.w3.org/2003/05/soap/mep/ImmediateSenderThe identifier of the immediate sender of an inbound message.xs:anyURI
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/FailureReasonA 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. xs:anyURI
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/State

The identifier of the 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. At a terminal state, it contains either Success or Fail

xs:anyURI

To initiate a message exchange conforming to the Request-Response MEP, the requesting node instantiates a local message exchange context. Once the message exchange context is initialized, control of the context is passed to a (conforming) local binding instance.

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 request is still being received and processed. When SOAP nodes implement bindings that support streaming, the following rules apply:

  • All the rules in SOAP 1.2 Part 1 [SOAP Part 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 nodes MUST avoid deadlock by accepting and if necessary processing SOAP response information while the 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 node MAY fail, and thus abort transmission of the outbound request, based on information contained in an incoming streamed SOAP response.

6.2 SOAP Web Method Feature

This section defines the "SOAP Web Method Feature".

6.2.2 Description

Underlying protocols designed for use on the World Wide Web provide for manipulation of resources using a small set of Web methods such as GET, PUT, POST, and DELETE. These methods are formally defined in the HTTP specification [RFC 2616], but other underlying protocols might also support them. Bindings to HTTP or such other protocols SHOULD use the SOAP Web Method feature to give applications control over the Web methods to be used when sending a SOAP message.

Bindings supporting this feature SHOULD use the appropriate embodiment of that method if provided by the underlying protocol; for example, the HTTP binding provided with this specification represents the "GET" Web method as an HTTP GET request, and the "POST" method as an HTTP POST request (see 7 SOAP HTTP Binding). Bindings supporting this feature SHOULD provide to the receiving node indication of the Web method used for transmission.

The SOAP Web Method feature MAY be implemented by bindings to underlying transports that have no preferred embodiment of particular Web methods (e.g. do not distinguish GET from POST). Such bindings SHOULD provide to the receiving node indication of the Web method used for transmission, but need take no other action in support of the feature.

6.2.3 SOAP Web Method Feature Properties

The SOAP Web Method feature defines a single property, which is described in ???.

Property definition for the SOAP Web Method feature
Property NameProperty DescriptionProperty Type
http://www.w3.org/2003/05/soap/features/web-method/MethodOne of "GET", "POST", "PUT", "DELETE" (or others which may subsequently be added to the repertoire of Web methods.)Not specified

This specification provides for the use of the SOAP Web Method feature in conjunction with the 6.1 SOAP Request-Response Message Exchange Pattern message exchange pattern. This feature MAY be used with other MEPs if and only if provided for in the specifications of those MEPs.

A node sending a request message MUST provide a value for the http://www.w3.org/2003/05/soap/features/web-method/Method property. A protocol binding supporting this feature SHOULD set the value of the http://www.w3.org/2003/05/soap/features/web-method/Method property at the receiving node to match that provided by the sender; the means of transmission for the method property is binding-specific.

A responding node SHOULD respond in a manner consistent with the Web method requested (e.g. a "GET" should result in retrieval of a representation of the identified resource) or SHOULD fault in an application-specific manner if the Web method cannot be supported.

Bindings implementing this feature MUST employ a Message Exchange Pattern with semantics that are compatible with the Web method selected. For example, the SOAP Request Response Message Exchange Pattern (see ???) is compatible with GET.

6.3 SOAP Action Figure

This section defines the "SOAP Action Feature".

6.3.2 Description

Many SOAP 1.2 underlying protocol bindings will likely utilize the "application/soap+xml" media type (described in A The application/soap+xml Media Type) to transmit XML serializations of SOAP messages. The media type specifies an optional action parameter, which can be used to optimize dispatch or routing, among other things. The Action Feature specifies well-known URIs to indicate support for the action parameter in bindings which use MIME, and also to refer to value of the parameter itself.

6.3.3 SOAP Action Figure State Machine

The SOAP Action feature defines a single property, which is described in ???. The value of this property MUST be an absolute URI[RFC 2396] and MUST NOT be empty.

Property definition for the SOAP Action feature
Property NameProperty Type

http://www.w3.org/2003/05/soap/features/action/Action

xsd:anyURI

If the http://www.w3.org/2003/05/soap/features/action/Action property has a value at a SOAP sender utilizing a binding supporting this feature, the sender MUST use the property value as the value of the action parameter in the media type designator.

Conversely, if a value arrives in the action parameter of the media type designator at a SOAP receiver, the receiver MUST make that value available as the value of the http://www.w3.org/2003/05/soap/features/action/Action property.

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 SOAP 1.2 Part 1 [SOAP Part 1]SOAP Protocol Binding Framework) and supports the message exchange patterns and features described in 6 SOAP-Supplied Message Exchange Patterns and Features.

7.1.2 Use of HTTP

The SOAP HTTP binding defines a base URI according to the rules in HTTP/1.1 [RFC 2616]. I.e., the base URI is the HTTP Request-URI or the value of the HTTP Content-Location header field.

This binding of SOAP to HTTP is intended to make appropriate use of HTTP as an application protocol. For example, successful responses are sent with status code 200, and failures are indicated as 4XX or 5XX. This binding is not intended to fully exploit the features of HTTP, but rather to use HTTP specifically for the purpose of communicating with other SOAP nodes implementing the same binding. Therefore, this HTTP binding for SOAP does not specify the use and/or meaning of all possible HTTP methods, header fields and status responses. It specifies only those which are pertinent to the 6.1 SOAP Request-Response Message Exchange Pattern or which are likely to be introduced by HTTP mechanisms (such as proxies) acting between the SOAP nodes.

Certain optional features provided by this binding depend on capabilities provided by HTTP/1.1, for example content negotiation. Implementations SHOULD thus use HTTP/1.1 [RFC 2616] (or later compatible versions that share the same major version number). Implementations MAY also be deployed using HTTP/1.0, although in this case certain optional binding features may not be provided.

Note:

SOAP HTTP Binding implementations need to account for the fact that HTTP/1.0 intermediaries (which may or may not also be SOAP intermediaries) may alter the representation of SOAP messages, even in situations where both the initial SOAP sender and ultimate SOAP receiver use HTTP/1.1.

7.1.4 HTTP Media-Type

Conforming implementations of this binding:

  1. MUST be capable of sending and receiving messages serialized using media type "application/soap+xml" whose proper use and parameters are described in A The application/soap+xml Media Type.

  2. MAY send requests and responses using other media types providing that such media types provide for at least the transfer of SOAP XML Infoset.

  3. MAY, when sending requests, provide an HTTP Accept header field. This header field:

    • SHOULD indicate an ability to accept at minimum "application/soap+xml".

    • MAY additionally indicate willingness to accept other media types that satisfy 2 above.

7.5 MEP Operation

This section describes the MEP properties and their relation to the HTTP protocol.

7.5.1 Behavior of Requesting SOAP Node

The overall flow of the behavior of a requesting SOAP node follows property transmission consistent with 6.1 SOAP Request-Response Message Exchange Pattern. The state machine starts at Init, proceeds to Requesting, then either Sending+Receiving or Fail, then either Success or Fail. This binding supports streaming and, as a result, requesting nodes MUST avoid deadlock by accepting and if necessary processing response information while the request is being transmitted (see 6.1.3 Property Description). The following subsections describe each state in detail.

7.5.1.1 Init

In the "Init" state, a HTTP request is formulated according to ??? and transmission of the request is initiated.

HTTP Request Fields
FieldValue
HTTP MethodAccording to the http://www.w3.org/2003/05/soap/features/web-method/Method property.
Request URIThe value of the URI carried in the http://www.w3.org/2003/05/soap/mep/ImmediateDestination property of the message exchange context.

Content-Type header field

The media type of the request entity body, if present; otherwise, omitted (see 7.1 Introduction for a description of permissible media types). If the SOAP envelope infoset in the http://www.w3.org/2003/05/soap/mep/OutboundMessage property is null, then the Content-Type header field MAY be omitted.

action parameter

According to the value of the http://www.w3.org/2003/05/soap/features/action/Action property.

Accept header field (optional)

List of media types that are acceptable in response to the request message.

Additional header fields

Generated in accordance with the rules for the binding-specific expression of any optional features in use for this message exchange. For example, a Content-Encoding header field (see HTTP [RFC 2616], section 14.11) may be used to express an optional compression feature.

HTTP entity body

A message serialized according to the rules for carrying the message in HTTP. If a SOAP envelope, then serialized according to SOAP messages in the media type given by the Content-Type header field. Rules for carrying SOAP messages in media type "application/soap+xml" are given in A The application/soap+xml Media Type. If the SOAP envelope infoset in the http://www.w3.org/2003/05/soap/mep/OutboundMessage property is null, the entity body is omitted

7.5.1.2 Requesting

In the "Requesting" state, sending of the request continues while waiting for the start of the response message. ??? details the transitions that take place when a requesting node receives an HTTP status line and response header fields. For some status codes there is a choice of possible next state. In cases where "Fail" is one of the choices, the transition is dependent on whether a SOAP message is present in the HTTP response. If a SOAP message is present, the next state is "Sending+Receiving", otherwise the next state is "Fail".

HTTP status code dependent transitions
Status CodeReason phraseSignificance/ActionNextState
2xxSuccessful
200OK

The response message follows in the HTTP response entity body. Start making an abstraction of the response message available in http://www.w3.org/2003/05/soap/mep/InboundMessage.

"Sending+Receiving"
202AcceptedThe request has completed succesfully. The HTTP response entity body will be empty. "Success"
301, 302, 307Redirect

The requested resource has moved. In the case of unsafe HTTP method, like POST or PUT, explicit confirmation is required before proceeding as follow.

In the case of a safe method, like GET, or if the redirection has been approved, the HTTP request SHOULD be retried using the URI carried in the associated Location header field as the new value for the http://www.w3.org/2003/05/soap/mep/ImmediateDestination property.

"Init" or "Fail"
303See Other

The requested resource has moved and the HTTP request SHOULD be retried using the URI carried in the associated Location header field as the new value for the http://www.w3.org/2003/05/soap/mep/ImmediateDestination property. The value of http://www.w3.org/2003/05/soap/features/web-method/Method is changed to ""GET"", the value of http://www.w3.org/2003/05/soap/mep/OutboundMessage is set to "null". [Note: Status code 303 MUST NOT be sent unless the request SOAP envelope has been processed according to the SOAP processing model and the SOAP response is to be made available by retrieval from the URI provided with the 303.]

"Init"
4xxClient Error
400Bad Request

Indicates a problem with the received HTTP request message.

"Sending+Receiving" or "Fail"

401Unauthorized

Indicates that the HTTP request requires authorization.

The message exchange is regarded as having completed unsuccessfully.

"Requesting" or "Fail"
405Method 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"
415Unsupported Media Type

Indicates that the peer HTTP server does not support the Content-type used to encode the request message. The message exchange is regarded as having completed unsuccessfully.

"Fail"
5xxServer Error
500Internal Server Error

Indicates a server problem or a problem with the received request

"Sending+Receiving" or "Fail"

??? refers to some but not all of the existing HTTP/1.1 [RFC 2616] status codes. In addition to these status codes, HTTP provides an open-ended mechanism for supporting status codes defined by HTTP extensions (see RFC 2817 [RFC 2817] for a registration mechanism for new status codes). HTTP status codes are divided into status code classes as described in HTTP [RFC 2616], section 6.1.1. The SOAP HTTP binding follows the rules of any HTTP application which means that an implementation of the SOAP HTTP binding must understand the class of any status code, as indicated by the first digit, and treat any unrecognized response as being equivalent to the x00 status code of that class, with the exception that an unrecognized response must not be cached.

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 be disabled for resources accepting SOAP/HTTP requests. If the rewriting behavior cannot be disabled, SOAP/HTTP cannot be used in such configurations.

7.5.2 Behavior of Responding SOAP Node

The overall flow of the behavior of a responding SOAP node follows property transmission consistent with either 6.1 SOAP Request-Response Message Exchange Pattern. The state machine starts at Init, proceeds to Receiving, then either Receiving+Sending or Fail, then either Success or Fail. The following subsections describe each state in detail.

7.5.2.1 Init

In the "Init" state, the binding waits for the start of an inbound request message. ??? describes the errors that a responding SOAP node might generate while in the "Init" state. In this state no message has been received, therefore the SOAP node cannot generate a SOAP fault.

Errors generated in the Init state
Problem with MessageHTTP Status CodeHTTP Reason Phrase (informative)
Malformed Request Message400Bad request
HTTP Method is neither POST nor GET405Method Not Allowed
Unsupported message encapsulation method415Unsupported Media
7.5.2.2 Receiving

In the "Receiving" state, the binding receives the request and any associated message and waits for the start of a response message to be available. ??? describes the HTTP response header fields generated by the responding SOAP node. ??? describes the HTTP status codes associated with SOAP faults that can be generated by the responding SOAP node.

HTTP Response Headers Fields
FieldValue
Status line

200, 202, or set according to ??? if a SOAP fault was generated.

Content-Type header field

The media type of the response body, see 7.1 Introduction for a description of permissible media types.

Additional header fields

Generated in accordance with the rules for the binding-specific expression of any optional features in use for this message exchange. For example, a Content-Encoding header field (see HTTP [RFC 2616], section 14.11) may be used to express an optional compression feature.

HTTP Entity Body

An optional SOAP message serialized according to the rules for carrying SOAP messages in the media type given by the Content-Type header field. Rules for carrying SOAP messages in "application/soap+xml" are given in A The application/soap+xml Media Type.

SOAP Fault to HTTP Status Mapping
SOAP FaultHTTP Status CodeHTTP Reason Phrase (informative)
env:VersionMismatch500Internal server error
env:MustUnderstand500Internal server error
env:Sender400Bad request
env:Receiver500Internal server error
env:DataEncodingUnknown500Internal server error
7.5.2.3 Receiving+Sending

In the "Receiving+Sending" state (6.1 SOAP Request-Response Message Exchange Pattern only) the binding completes receiving of the request message and transmission of the response message.

7.6 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 [RFC 2616] apply to the SOAP HTTP Binding in addition to those described in SOAP 1.2 Part 1 [SOAP Part 1]Security Considerations. Implementors of the SOAP HTTP Binding should carefully review this material.

8 References

8.1 Normative References

SOAP Part 1
W3C Recommendation "SOAP Version 1.2 Part 1: Messaging Framework", Martin Gudgin, Marc Hadley, Noah Mendelsohn, Jean-Jacques Moreau, Henrik Frystyk Nielsen, (See .)
RFC 2616
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.)
RFC 2119
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.)
XML Schema Part 1
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/.)
XML Schema Part 2
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/.)
RFC 2396
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.)
Namespaces in XML
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/.)
XML 1.0
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.)
XML InfoSet
W3C Recommendation "XML Information Set", John Cowan, Richard Tobin, 24 October 2001. (See http://www.w3.org/TR/2001/REC-xml-infoset-20011024/.)
RFC 3023
IETF "RFC 3023: XML Media Types", M. Murata, S. St. Laurent, D. Kohn, July 1998. (See http://www.ietf.org/rfc/rfc3023.txt.)
RFC3902
IETF "RFC 3902: The 'application/soap+xml' media type", M. Baker, M. Nottingham, September 2004. (See http://www.ietf.org/rfc/rfc3902.txt.)

A The "application/soap+xml" Media Type

The original contents of this section have been superceded by RFC3902[RFC3902].

B Mapping Application-Defined Names to XML Names

This appendix details an algorithm for taking an application-defined name, such as the name of a variable or field in a programming language, and mapping it to the Unicode characters that are legal in the names of XML elements and attributes as defined in Namespace in XML [Namespaces in XML]

Hex Digits
[5]   hexDigit   ::=   [0-9A-F]

B.1 Rules for Mapping Application-Defined Names to XML Names

  1. An XML Name has two parts: Prefix and LocalPart. Let Prefix be determined per the rules and constraints specified in Namespaces in XML [Namespaces in XML].

  2. Let T be a name in an application, represented as a sequence of characters encoded in a particular character encoding.

  3. Let M be the implementation-defined function for transcoding of the characters used in the application-defined name to an equivalent string of Unicode characters.

    Note:

    Ideally, if this transcoding is from a non-Unicode encoding, it should be both reversible and Unicode Form C normalizing (that is, combining sequences will be in the prescribed canonical order). It should be noted that some transcodings cannot be perfectly reversible and that Normalization Form C (NFC) normalization may alter the original sequence in a few cases (see Character Model for the World Wide Web [CharMod]). To ensure that matching names continue to match after mapping, Unicode sequences should be normalized using Unicode Normalization Form C.

    Note:

    This transcoding is explicitly to Unicode scalar values ("code points") and not to any particular character encoding scheme of Unicode, such as UTF-8 or UTF-16.

    Note:

    Note: Properly formed surrogate pair sequences must be converted to their respective scalar values ("code points") [That is, the sequence U+D800 U+DC00 should be transcoded to the character U+10000]. If the transcoding begins with a Unicode encoding, non-conforming (non-shortest form) UTF-8 and UTF-16 sequences must be converted to their respective scalar values.

    Note:

    The number of characters in T is not necessarily the same as the number of characters in M, because transcoding may be one-to-many or many-to-one. The details of transcoding may be implementation-defined. There may be (very rarely) cases where there is no equivalent Unicode representation for T; such cases are not covered here.

  4. Let C be the sequence of Unicode scalar values (characters) represented by M(T)

  5. Let N be the number of characters in C. Let C1, C2, ..., CN be the characters of C, in order from most to least significant (logical order).

  6. For each i between 1 (one) and N, let Xi be the Unicode character string defined by the following rules:

    Case:

    1. If Ci is undefined (that is, some character or sequence of characters as defined in the application's character sequence T contains no mapping to Unicode), then Xi is implementation-defined.

    2. If i<=N-1 and Ci is "_" (U+005F LOW LINE) and Ci+1 is "x" (U+0078 LATIN SMALL LETTER X), then let Xi be "_x005F_".

    3. If i=1, and N>=3, and C1 is "x" (U+0078 LATIN SMALL LETTER X) or "X" (U+0058 LATIN CAPITAL LETTER X), and C2 is "m" (U+006D LATIN SMALL LETTER M) or "M" (U+004D LATIN CAPITAL LETTER M), and C3 is "l" (U+006C LATIN SMALL LETTER L) or "L" (U+004C LATIN CAPITAL LETTER L) (in other words, a string three letters or longer starting with the text "xml" or any re-capitalization thereof), then if C1 is "x" (U+0078 LATIN SMALL LETTER X) then let X1 be "_x0078_"; otherwise, if C1 is "X" (U+0058 LATIN CAPITAL LETTER X) then let X1 be "_x0058_".

    4. If Ci is not a valid XML NCName character (see Namespaces in XML [Namespaces in XML]) or if i=1 (one) and C1 is not a valid first character of an XML NCName then:

      Let U1, U2, ... , U6 be the six hex digits [PROD: 5] such that Ci is "U+"U1U2 ... U6 in the Unicode scalar value.

      Case:

      1. If U1=0, U2=0, U3=0, and U4=0, then let Xi="_x"U5U6"_".

        This case implies that Ci is a character in the Basic Multilingual Plane (Plane 0) of Unicode and can be wholly represented by a single UTF-16 code point sequence U+U5U6.

      2. Otherwise, let Xi be "_x"U1U2U3U4U5U6"_".

    5. Otherwise, let Xi be Mi. That is, any character in X that is a valid character in an XML NCName is simply copied.

  7. Let LocalPart be the character string concatenation of X1, X2, ... , XN in order from most to least significant.

  8. Let XML Name be the QName per Namespaces in XML [Namespaces in XML]

C 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 conforming processors are not required to perform validation of encoded SOAP messages.

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.

C.1 Validating Using the Minimum Schema

Although W3C XML schemas are conventionally exchanged in the form of schema documents (see XML Schema [XML Schema Part 1]), the schema recommendation is built on an abstract definition of schemas, to which all processors need to 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 XML Schema [XML Schema Part 1], 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.

C.2 Validating Using the SOAP Encoding Schema

Validation against the minimal schema (see C.1 Validating Using the Minimum Schema) will not succeed where encoded graph nodes have multiple inbound edges. This is because elements representing such graph nodes will carry idattribute information items which are not legal on elements of type "xs:string", "xs:integer" etc. 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 the [local name] and [namespace name] properties of the element information items, need to 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.

D Acknowledgements (Non-Normative)

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

Participants in the Working Group are (at the time of writing, and by alphabetical order): SYSTEM "wgmb.txt"

Previous participants were: SYSTEM "prevwgmb.txt"

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