SOAP Version 1.2 Part 2: Adjuncts

Editors SNAPSHOT $Date: 2002/10/20 17:51:45 $ @@ @@ @@

This version:
soap12-part2.html
Latest version:
http://www.w3.org/TR/soap12-part2
Previous versions:
http://www.w3.org/TR/2001/WD-soap12-part2-20011217
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 Part1: Messaging Framework. This specification depends on SOAP Version 1.2 Part 1: Messaging Framework [SOAP Part 1].

Status of this Document

This document is an editors' copy that has no official standing.

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.

This is the W3C Last Call Working Draft of the SOAP Version 1.2 specification for review by W3C members and other interested parties. It has been produced by the XML Protocol Working Group (WG), which is part of the Web Services Activity.

This document references "The "application/soap+xml" media type" Internet Draft [SOAP MediaType] which defines the "application/soap+xml" media type. The XML Protocol Working Group intends to use [SOAP MediaType] in an IANA application to register the "application/soap+xml" media type. The Working Group also intends to incorporate the technical content of [SOAP MediaType] into a near future version of SOAP Version 1.2 Part 2, and to maintain that content as part of the SOAP specification.

Following completion of Last Call, the XML Protocol Working Group has agreed to advance the specification according to four exit criteria:

  1. Sufficient reports of implementation experience have been gathered to demonstrate that SOAP processors based on the specification are implementable and have compatible behavior.

  2. An implementation report shows that there are at least two different and interoperable implementations of every mandatory and optional feature.

  3. Formal responses to all comments received by the Working Group.

  4. If these criteria are met, the specification will advance to Proposed Recommendation. If the implementation exit criteria are not met then the specification will enter a Candidate Recommendation phase to ensure they are met.

A list of open Last Call issues against this document can be found at http://www.w3.org/2000/xp/Group/xmlp-lc-issues.

Comments on this document should be sent to xmlp-comments@w3.org (public archive [XMLP Comments]). It is inappropriate to send discussion email to this address. Comments should be sent during the last call review period, which ends on 19 July 2002.

Discussion of this document takes place on the public xml-dist-app@w3.org mailing list [XMLP Dist-App] under the email communication rules in the XML Protocol Working Group Charter [XMLP Charter].

Patent disclosures relevant to this specification may be found on the Working Group's patent disclosure page.

This is a public W3C Working Draft. It is a draft document and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use W3C Working Drafts as reference material or to cite them as other than "work in progress". A list of all W3C technical reports can be found at http://www.w3.org/TR/.


Short Table of Contents

1. Introduction
2. SOAP Data Model
3. SOAP Encoding
4. SOAP RPC Representation
5. A Convention for Describing Features and Bindings
6. SOAP-Supplied Message Exchange Patterns and Features
7. SOAP HTTP Binding
8. References
A. The application/soap+xml Media Type
B. Mapping Application Defined Names to XML Names
C. Using W3C XML Schema with SOAP Encoding (Non-Normative)
D. Acknowledgements (Non-Normative)
E. Part 2 Change Log (Non-Normative)


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.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.3 Properties and Features
6. SOAP-Supplied Message Exchange Patterns and Features
    6.1 Property Conventions for SOAP Message Exchange Patterns
    6.2 SOAP Request-Response Message Exchange Pattern
        6.2.1 SOAP Feature Name
        6.2.2 Description
        6.2.3 State Machine Description
        6.2.4 Fault Handling
    6.3 SOAP Response Message Exchange Pattern
        6.3.1 SOAP Feature Name
        6.3.2 Description
        6.3.3 State Machine Description
        6.3.4 Fault Handling
    6.4 Web Method Specification Feature
        6.4.1 SOAP Feature Name
        6.4.2 Description
        6.4.3 Web Method Feature 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 Receiving
            7.5.1.5 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 Sending
            7.5.2.5 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
    A.1 Registration
    A.2 Security considerations
    A.3 The action parameter
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)
E. Part 2 Change Log (Non-Normative)
    E.1 SOAP Specification Changes


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 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. A convention for describing features and bindings (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 definition and a message exchange pattern supporting non-SOAP requests for SOAP responses, (see 6. SOAP-Supplied Message Exchange Patterns and Features).

  6. The Web Method Specification Feature defines

    a feature for control of methods used on the World Wide Web (see 6.4 Web Method Specification 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 Part0] is a non-normative document intended to provide an easily understandable tutorial on the features of the SOAP Version 1.2 specifications.

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

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

Table 1: Prefixes and Namespaces used in this specification
PrefixNamespaceNotes
env"http://www.w3.org/2002/06/soap-envelope"Defined by [SOAP Part 1].
enc"http://www.w3.org/2002/06/soap-encoding"A normative XML Schema [XML Schema Part1], [XML Schema Part2] document for the "http://www.w3.org/2002/06/soap-encoding" namespace can be found at http://www.w3.org/2002/06/soap-encoding.
rpc"http://www.w3.org/2002/06/soap-rpc"A normative XML Schema [XML Schema Part1], [XML Schema Part2] document for the "http://www.w3.org/2002/06/soap-rpc" namespace can be found at http://www.w3.org/2002/06/soap-rpc.
xs"http://www.w3.org/2001/XMLSchema"Defined in the W3C XML Schema specification [XML Schema Part1], [XML Schema Part2].
xsi"http://www.w3.org/2001/XMLSchema-instance"Defined in the W3C XML Schema specification [XML Schema Part1], [XML Schema Part2].
context"http://www.w3.org/2002/06/soap/bindingFramework/ExchangeContext/"See 6.2 SOAP Request-Response Message Exchange Pattern.
mep"http://www.w3.org/2002/06/soap/mep/"See 6.2 SOAP Request-Response Message Exchange Pattern.
fail"http://www.w3.org/2002/06/soap/mep/FailureReasons/"See 6.2 SOAP Request-Response Message Exchange Pattern.
reqres"http://www.w3.org/2002/06/soap/mep/request-response/"See 6.2 SOAP Request-Response Message Exchange Pattern.
webmeth"http://www.w3.org/2002/06/soap/features/web-method/"See 6.4 Web Method Specification Feature.

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

This specification uses the Extended Backus-Naur Form (EBNF) as described in [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, for example using W3C XML Schema [XML Schema Part1],[XML Schema Part2], 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.

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.

An edge MAY have only an originating graph node, that is be outbound only. An edge MAY have only a terminating graph node, that is be inbound only.

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 Part2]). Two edge labels are equal if and only if both of the following are true:

  1. Their local name values are the same.

  2. 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 Part2] 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]) and

an optional type name of type

QName in the namespace named "http://www.w3.org/2001/XMLSchema"

xs:QName

(see [XML Schema Part2]).

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:

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

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

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

Editorial note 
The Working Group solicits feedback from implementers during the Last Call period whether the section on 'generics' should remain in this document or whether it should be removed altogether.

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

The serialization rules defined in this section are identified by the URI "http://www.w3.org/2002/06/soap-encoding". SOAP messages using this particular serialization SHOULD indicate that fact by using the SOAP encodingStyle attribute information item (see [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 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

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

    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 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/2002/06/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.

Note that certain Unicode characters cannot be represented in XML (see [XML 1.0]).

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

    ("struct" or "generic")

    , the

    namespace name and local name

    [local name] and [namespace name]

    properties of the element information item together determine the value of the edge label.

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

      The [local name] and [namespace name]

      properties of the element information item are not significant.

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

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

    xs:QName

    (see [XML Schema Part2]); 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: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 enc:itemType attribute 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 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 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.

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.1.4.1 itemType Attribute Information Item

The itemType attribute information item has the following Infoset properties:

  • A local name of itemType ;

    A [local name] of itemType .

  • A namespace name of "http://www.w3.org/2002/06/soap-encoding".

    A [namespace name] of "http://www.w3.org/2002/06/soap-encoding".

  • A specified property with a value of "true".

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

xs:QName.

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 [local name] of id .

  • A namespace name which is empty

    A [namespace name] of "http://www.w3.org/2002/06/soap-encoding".

  • A specified property with a value of "true".

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

xs:ID.

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 [local name] of ref .

  • A namespace name which is empty

    A [namespace name] of "http://www.w3.org/2002/06/soap-encoding".

  • A specified property with a value of "true".

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

xs:IDREF.

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 [local name] of arraySize .

  • A namespace name of "http://www.w3.org/2002/06/soap-encoding".

    A [namespace name] of "http://www.w3.org/2002/06/soap-encoding".

  • A default value of "*"

The type of the arraySize attribute information item is

arraySize in the namespace named "http://www.w3.org/2002/06/soap-encoding".

enc:arraySize.

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

[1]   arraySizeValue   ::=   ("*" | concreteSize) nextConcreteSize*
[2]   nextConcreteSize   ::=   " " concreteSize
whitespace concreteSize
[3]   concreteSize   ::=   [0-9]+
[4]   whitespace   ::=   (#x20 | #x9 | #xD | #xA)+

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.

The default value of the arraySize attribute information item is "*", that is by default arrays are considered to be of unspecified size.

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 method and procedure calls in commonly used programming languages. For that purpose, this section defines a uniform representation of 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 Part 1]SOAP encodingStyle Attribute) is used to indicate the encoding style of the RPC representation. The encoding thus specified needs to 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:

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] 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.2 SOAP Request-Response Message Exchange Pattern and 6.3 SOAP Response Message Exchange Pattern. 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.1 Identification of RPC Resources

The World Wide Web identifies resources with URIs, but common programming conventions convey identification information in the arguments to procedures, or in the names of those procedures. For example, the call:

updateQuantityInStock(PartNumber="123", NewQuantity="200")

suggests that the resource to be updated is the QuantityInStock for PartNumber "123". Accordingly, when mapping to or from a programming language method or procedure call, any arguments that serve to identify resources (such as the part number above) should when practical be represented in the URI to which the SOAP message is addressed. When mapping to or from a programming language method or procedure call, the name of which identifies or qualifies the identification of a resource (such as QuantityInStock above), such naming or qualification should when practical be represented in the URI to which the SOAP message is addressed. No standard means of representation of arguments or method names is provided by this specification.

Note:

Conventions for specific URI encodings of procedure names and arguments, as well as for controlling the inclusion of such arguments in the SOAP RPC body could be established in conjunction with the development of Web Service interface description languages, could be developed when SOAP is bound to particular programming languages, or could be established on an application or procedure-specific basis.

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 (see [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 SOAP RPC Representation does not define any other value for the webmeth: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 Part 1]SOAP Body) using the following representation:

4.2.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 or array is named identically to the procedure or method name (see B. Mapping Application Defined Names to XML Names).

  • The invocation is represented by a single struct containing an outbound edge for each [in] or [in/out] parameter. The struct is named identically to the procedure or method name and the conventions of B. Mapping Application Defined Names to XML Names SHOULD be used to represent method names that are not legal XML names.

  • Each outbound edge either has a label corresponding to the name of the parameter (see B. Mapping Application Defined Names to XML Names) or a position corresponding to the position of the parameter.

  • Each outbound edge has a label corresponding to the name of the parameter. The conventions of B. Mapping Application Defined Names to XML Names SHOULD be used to represent parameter names that are not legal XML names.

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 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 response is represented by a single struct containing an outbound edge for the return value and each [out] or [in/out] parameter.

  • If the response is represented by a struct, then

    Each parameter is represented by an outbound edge with a label corresponding to the name of the parameter. The conventions of B. Mapping Application Defined Names to XML Names SHOULD be used to represent parameter names that are not legal XML names. A non-void return value is represented in the struct by an outbound edge that may be given any unique label. The XML qualified name of the label of the edge representing the return value is given by a separate outbound edge with a local name of result and the namespace name "http://www.w3.org/2002/06/soap-rpc". The result outbound edge MUST be present and hold the XML qualified name of the edge containing the return value within any struct response if the return value of the procedure is non-void. The result outbound edge MUST NOT be present if the return value of the procedure is void.

  • If the response is represented by an array, each outbound edge has a label corresponding to the position of the parameter. A return value MUST be present if the return value of the procedure is non-void. If present, the return value MUST be represented as the first edge of the array with parameters following. If no return value is present, then parameters begin with the first outbound edge of the array.

  • Invocation faults are handled according to the rules in 4.4 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.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.

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.3 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.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 Part 1]SOAP Fault Codes.

The namespace name for these SOAP fault subcode values is "http://www.w3.org/2002/06/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/2002/06/soap-rpc .

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

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

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

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

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

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

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 Part 1]SOAP Protocol Binding Framework) and it is used to describe

a Request-Response MEP 6.2 SOAP Request-Response Message Exchange Pattern and the SOAP HTTP Binding 7. SOAP HTTP Binding elsewhere in this document.

a Request-Response MEP (see 6.2 SOAP Request-Response Message Exchange Pattern), a Response MEP (see 6.3 SOAP Response Message Exchange Pattern), the Web Method feature (see 6.4 Web Method Specification 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 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.

    Where appropriate, property values SHOULD have an XML Schema type listed in the specification which introduces the property.

    For example, the type of the RetryCount property above might be xs: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
Figure 1: 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 and Features

6.1 Property Conventions for SOAP 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 NameProperty DescriptionProperty Type
context:ExchangePatternName

A URI that names

The name of

the MEP in operation.
xs:anyURI
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.
xs:anyURI
context:Role

The identifier of the pattern specific role of the local SOAP node participating in the message exchange.

xs:anyURI
context:State

The identifier of 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.

xs:anyURI

6.2 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.2.1 SOAP Feature Name

This message exchange pattern is identified by the URI:

  • "http://www.w3.org/2002/06/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 might 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 might be silent at either or both of the requesting and responding SOAP nodes involved, or might result in the generation of a SOAP or binding-specific fault (see 6.2.4 Fault Handling). Also, during abnormal operation each SOAP 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 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 NameProperty DescriptionProperty Type
reqres:Role A URI denoting the identifier of the pattern specific role of the local SOAP node participating in the message exchange.xs:anyURI
reqres:State A URI denoting the identifier of 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.xs:anyURI
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.Not specified
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.Not specified
reqres:ImmediateDestination

A URI denoting

The identifier of

the immediate destination of an outbound message.
xs:anyURI
reqres:ImmediateSender

A URI denoting

The identifier of

the immediate sender of an inbound message.
xs:anyURI

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 NameProperty ValueNotes
context:ExchangePatternName "http://www.w3.org/2002/06/soap/mep/request-response/" 
context:FailureReason

"None"

A relative URI whose base URI is the value of context:ExchangePatternName

context:Role

"RequestingSOAPNode/"

A relative URI whose base URI is the value of context:ExchangePatternName

context:State

"Init"

A relative URI whose base URI is the value of context:Role

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.

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 context: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 context:Role property of the local message exchange context.

Request-Response MEP State Transition Diagram.
Figure 2: 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 at a responding SOAP node
Property NameProperty ValueNotes
context:ExchangePatternName "http://www.w3.org/2002/06/soap/mep/request-response/"

Initialized as early as possible during the life cycle of the message exchange.

Initialized as early as possible during the life cycle of the message exchange.
context:FailureReason "None"A relative URI whose base URI is the value of context:ExchangePatternName
context:Role

"RespondingSOAPNode"

A relative URI whose base URI is the value of context:ExchangePatternName

Initialized as early as possible during the life cycle the message exchange.

context:State "Init"A relative URI whose base URI is the value of context:Role

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
CurrentStateTransition ConditionNextStateAction
"Init"Unconditional"Requesting"Initiate transmission of request message abstracted in reqres:OutboundMessage .
"Requesting"Message transmission failure"Fail"Set context:FailureReason to "transmissionFailure"
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"
Completed sending request message. Completed receiving response message."Success" 

 

Table 7: Responding SOAP Node State Transitions
CurrentStateTransition ConditionNextStateAction
"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".
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".
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 [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 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).

6.3 SOAP Response Message Exchange Pattern

This section defines the message exchange pattern (MEP) called "SOAP 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.3.1 SOAP Feature Name

This message exchange pattern is identified by the URI:

  • "http://www.w3.org/2002/06/soap/mep/soap-response/"

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

6.3.2 Description

The SOAP Response MEP defines a pattern for the exchange of a non-SOAP message acting as a request followed by a SOAP message acting as a response. In the absence of errors or faults, this message exchange pattern consists of two messages, only one of which is a SOAP envelope:

  • A request transmitted in a binding-specific manner that does not include a SOAP envelope and hence does not involve any SOAP processing by the receiving SOAP node.

  • A response message which contains a SOAP envelope. The MEP is completed by the processing of the SOAP envelope following the rules of the SOAP processing model (see [SOAP Part 1], section SOAP Processing Model).

Abnormal operation during a SOAP Response message exchange might be caused by a failure to transfer the request message or the response message. Such failures might be silent at either or both of the requesting and responding SOAP nodes involved, or might result in the generation of a SOAP or binding-specific fault (see section 6.3.4 Fault Handling). Also, during abnormal operation each SOAP node involved in the message exchange might differ in its determination of the successful completion of the message exchange.

The scope of a SOAP Response MEP is limited to the request for an exchange of 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.

Note:

This MEP cannot be used in conjunction with features expressed as SOAP header blocks in the request because there is no SOAP envelope in which to carry them.

6.3.3 State Machine Description

The SOAP Response MEP defines a set of properties described in Table 8.

Table 8: Property definitions for SOAP Response MEP
Property NameProperty DescriptionProperty Type
reqres:Role A URI denoting the pattern specific role of the local SOAP node participating in the message exchange.xs:anyURI
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.xs:anyURI
reqres:OutboundMessage An abstract structure that represents the current outbound message in the message exchange. This abstracts both SOAP Envelope Infoset (which MAY be null) and any other information structures that are transferred along with the envelope.Not specified
reqres:InboundMessage An abstract structure that represents the current inbound message in the message exchange. This abstracts both SOAP Envelope Infoset (which MAY be null) and any other information structures that are transferred along with the envelope. Not specified
reqres:ImmediateDestination

A URI denoting

The identifier of

the immediate destination of an outbound message.
xs:anyURI
reqres:ImmediateSender

A URI denoting

The identifier of

the immediate sender of an inbound message.
xs:anyURI

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

Table 9: Instantiation of a Message Exchange Context for a requesting SOAP node
Property NameProperty ValueNotes
context:ExchangePatternName "http://www.w3.org/2002/06/soap/mep/soap-response/" 
context:FailureReason "None"A relative URI whose base URI is the value of context:ExchangePatternName
context:Role

"RequestingSOAPNode"

A relative URI whose base URI is the value of context:ExchangePatternName
context:State "Init"A relative URI whose base URI is the value of context:Role
reqres:OutboundMessage An abstraction of the request message that does not include a SOAP envelope infoset. 
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 context: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 context:Role property of the local message exchange context.

SOAP Response MEP State Transition Diagram.
Figure 3: SOAP 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 10 describes the properties that the binding initializes as part of the context's instantiation.

Table 10: Instantiation of Message Exchange Context for an inbound request message
Property NameProperty ValueNotes
context:ExchangePatternName "http://www.w3.org/2002/06/soap/mep/soap-response/"

Initialized as early as possible during the life cycle of the message exchange.

Initialized as early as possible during the life cycle of the message exchange.

context:FailureReason "None"A relative URI whose base URI is the value of context:ExchangePatternName
context:Role

"RespondingSOAPNode"

A relative URI whose base URI is the value of context:ExchangePatternName

Initialized as early as possible during the life cycle the message exchange.

context:State "Init"A relative URI whose base URI is the value of context:Role

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

Table 11: Requesting SOAP Node State Transitions
CurrentStateTransition ConditionNextStateAction
"Init"Unconditional"Requesting"Initiate request
"Requesting"Message transmission failure"Fail"Set context:FailureReason to "transmissionFailure"
Start receiving response message"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 .
"Receiving"Message exchange failure"Fail"Set context:FailureReason to "exchangeFailure"
Completed receiving response message."Success" 

 

Table 12: Responding SOAP Node State Transitions
CurrentStateTransition ConditionNextStateAction
"Init"Start receiving request"Receiving"

Set reqres:ImmediateSender to denote the sender of the request message (if determinable).

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".
Start of response message available in reqres:OutboundMessage "Sending"Initiate transmission of response message abstracted in reqres:OutboundMessage .
"Sending"Message exchange failure"Fail"Set context:FailureReason to "exchangeFailure".
Completed sending response message."Success" 

6.3.4 Fault Handling

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

This MEP makes no claims about the disposition of SOAP faults generated by the responding SOAP node.

A responding SOAP node MAY express fault information as a result of processing the request in the form of a SOAP fault. This can for example be used to express information that might be useful to a receiving SOAP node.

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 "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 11).

6.4 Web Method Specification Feature

This section defines the "Web Method Specification Feature".

6.4.1 SOAP Feature Name

This Web Method Specification Feature is identified by the URI:

  • "http://www.w3.org/2002/06/soap/features/web-method/"

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

6.4.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 Web Method Specification 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 Specification 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.4.3 Web Method Feature State Machine

The Web Method Feature defines a single property, which is described in Table 13.

Table 13: Property definition for the Web Method Feature
Property NameProperty DescriptionProperty Type
webmeth:Method One 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 Web Method Feature in conjunction with the 6.2 SOAP Request-Response Message Exchange Pattern and 6.3 SOAP Response Message Exchange Pattern message exchange patterns. 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 webmeth:Method property. A protocol binding supporting this feature SHOULD set the value of the webmeth: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.

Applications SHOULD use "GET" as the value of webmeth:Method in conjunction with the 6.3 SOAP Response Message Exchange Pattern to support information retrievals which are safe, and for which no parameters other than a URI are required; i.e. when performing retrievals which are idempotent, known to be free of side effects, for which no SOAP request headers are required, and for which security considerations do not conflict with the possibility that cached results would be used. Except in unusual circumstances, other operations SHOULD be performed using "POST" in conjunction with the 6.2 SOAP Request-Response Message Exchange Pattern. Other methods SHOULD not in general be used. For example, use of "PUT" would suggest storing the SOAP envelope Infoset as the created resource, as opposed to processing in the manner required by the SOAP processing model (see [SOAP Part 1], section SOAP Processing Model.

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

7. SOAP HTTP Binding

7.1 Introduction

Editorial note: JJM/MJH20020919
This section had grown over time into an unmanageable entity, with information spread over several paragraphs and notes in an unorganized manner. The editors felt that this situation could be easily remedied by merely shuffling paragraphs around and by creating a clear and coherent structure with four new subsections. This revised section is the result of that change. Unless decorated in green or red (as a result of some other issue resolution) the text has otherwise NOT changed.

The SOAP HTTP Binding provides a binding of SOAP to HTTP. The binding conforms to the SOAP Protocol Binding Framework (see [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.

It uses abstract binding properties as a descriptive tool for defining the functionality of certain features.

The SOAP Protocol Binding Framework (see [SOAP Part 1]SOAP Protocol Binding Framework), the Message Exchange Pattern Specifications (see [SOAP Part 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.

7.1.1 Optionality

The SOAP HTTP Binding is optional and SOAP nodes are NOT required to implement it. 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."

The SOAP version 1.2 specification does not preclude development of other bindings to HTTP or bindings to other protocols, but communication with nodes using such other bindings is not a goal. Note that other bindings of SOAP to HTTP MAY be written to provide support for SOAP Message exchange patterns other than 6.2 SOAP Request-Response Message Exchange Pattern or the 6.3 SOAP Response Message Exchange Pattern. Such alternate bindings MAY therefore make use of HTTP features and status codes not required for this binding. For example, another binding might provide for a 202 or 204 HTTP response status to be returned in response to an HTTP POST or PUT (e.g. a one-way "push" MEP with confirmation).

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.2 SOAP Request-Response Message Exchange Pattern or the 6.3 SOAP 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.3 Interoperability with non-SOAP HTTP Implementations

Particularly when used with the 6.3 SOAP Response Message Exchange Pattern, the HTTP messages produced by this binding are likely to be indistinguishable from those produced by non-SOAP implementations performing similar operations. Accordingly, some degree of interoperation can be made possible between SOAP nodes and other HTTP implementations when using this binding. For example, a conventional Web server (i.e. one not written specifically to conform to this specification) might be used to respond to SOAP-initiated HTTP GET's with representations of Content-Type "application/soap+xml". Such interoperation is not a normative feature of this specification.

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

    [SOAP MediaType]

    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.2 Binding Name

The binding is identified with the URI:

  • "http://www.w3.org/2002/06/soap/bindings/HTTP/"

7.3 Supported Message Exchange Patterns

An implementation of the SOAP HTTP Binding MUST support the following message exchange patterns (MEPs):

7.4 Supported Features

An implementation of the SOAP HTTP Binding MUST support the following feature:

7.5 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 context:Role ) of "RequestingSOAPNode".

  • A SOAP node instantiated at an HTTP server may assume the role (i.e. the property context: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 context:State (see 6.2 SOAP Request-Response Message Exchange Pattern), and are of type xs:anyURI . For brevity, relative URIs are used, the base URI being the value of context:Role .

Failure reasons that are specified in the tables represent values of the property context:FailureReason and their values are relative URIs whose base URI is the value of context:ExchangePatternName . If an implementation enters the "Fail" state, the context:FailureReason property will contain the value specified for the particular transition.

7.5.1 Behavior of Requesting SOAP Node

The overall flow of the behavior of a requesting SOAP node follows a state machine description consistent with either 6.2 SOAP Request-Response Message Exchange Pattern or 6.3 SOAP Response Message Exchange Pattern (differences are indicated as necessary.) 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.5.1.1 Init

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

Table (removed) and Table 14 describe the requesting SOAP node's "Init" state and the values of the HTTP request fields.

Editorial note: MJH20021010
Table "State Description: Init" removed.
Table 14: HTTP Request Fields
FieldValue
HTTP MethodAccording to the webmeth:Method property (typically POST or GET).
Request URIThe value of the URI carried in the reqres: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 reqres:OutboundMessage property is null, then the Content-Type header field MAY be omitted.

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 [RFC 2616], section 14.11) may be used to express an optional compression feature.

HTTP entity body

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 media type "application/soap+xml" are given in

[SOAP MediaType]

A. The application/soap+xml Media Type

. If the SOAP envelope infoset in the reqres:OutboundMessage property is null, then no serialization of the SOAP message is required and the entity body MAY be omitted.

7.5.1.2 Requesting

Table (removed) describes the requesting SOAP node's "Requesting" state.

Editorial note: MJH20021010
Table "State Description: Requesting" removed.

In the "Requesting" state, sending of the request continues whilst waiting for the start of the response message. Table 15 details the transitions that take place when a requesting SOAP 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" or "Receiving", otherwise the next state is "Fail". The choice between "Sending+Receiving" and "Receiving" depends of the MEP in use: "Sending+Receiving" is the next state for Request-Response whilst "Receiving" is the next state for SOAP-Response.

Table 15 details the transitions that take place when a requesting SOAP node receives an HTTP status line and response header fields. Table 15 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] for a registration mechanism for new status codes). HTTP status codes are divided into status code classes as described in [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.

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

The response message follows in HTTP response entity body. Start making an abstraction of the response message available in reqres:InboundMessage .

"Sending+Receiving" or "Receiving"
3xxRedirection

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 reqres:ImmediateDestination property.

"Init"
4xxClient Error  
400Bad Request

Indicates a problem with the received HTTP request message. The problem can be 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.

Indicates a problem with the received HTTP request message.

"Sending+Receiving", "Receiving" or

"Fail"

401Unauthorized

Indicates that the HTTP request requires authorization.

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.

"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 that the response message contained in the following HTTP response entity body may contain a SOAP fault. Other internal server errors may be the cause of this status code. The local binding instance continues to receive the incoming message.

Indicates a server problem or a problem with the received request

"Sending+Receiving"

, "Receiving" or "Fail"

Table 15 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] for a registration mechanism for new status codes). HTTP status codes are divided into status code classes as described in [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 is disabled for resources accepting SOAP/HTTP requests. If the rewriting behavior cannot be disabled, SOAP/HTTP cannot be used in such configurations.

7.5.1.3 Sending+Receiving

Table (removed) describes the requesting SOAP node's "Sending+Receiving" state.

Editorial note: MJH20021010
Table "State Description: Sending+Receiving" removed.

In the "Sending+Receiving" state (6.2 SOAP Request-Response Message Exchange Pattern only), the transmission of the request message and receiving of the response message is completed. The response message is assumed to contain a SOAP envelope serialized according to the rules for carrying SOAP messages in the media type given in the Content-Type header field.

The response MAY be of content type other than "application/soap+xml". Such usage is considered non-normative, and accordingly is not modeled in the state machine. Interpretation of such responses is at the discretion of the receiver.

7.5.1.4 Receiving

In the "Receiving" state (6.3 SOAP Response Message Exchange Pattern only), receiving of the response message is completed. The response message is assumed to contain a SOAP envelope serialized according to the rules for carrying SOAP messages in the media type given in the Content-Type header field.

The response MAY be of content type other than "application/soap+xml". Such a result is particularly likely when a SOAP request sent with a webmeth:Method of "GET" is directed (intentionally or otherwise) to a non-SOAP HTTP server. Such usage is considered non-normative, and accordingly is not modeled in the state machine. Interpretation of such responses is at the discretion of the receiver.

7.5.1.5 Success and Fail

"Success" and "Fail" are the terminal states of the Request-Response and SOAP-Response MEPs. Control over the message exchange context returns to the local SOAP node.

7.5.2 Behavior of Responding SOAP Node

The overall flow of the behavior of a responding SOAP node follows a state machine description consistent with either 6.2 SOAP Request-Response Message Exchange Pattern or 6.3 SOAP Response Message Exchange Pattern (differences are indicated as necessary). The following subsections describe each state in detail.

7.5.2.1 Init

Table (removed) and Table 16 describe the responding SOAP node's "Init" state and the faults it generates respectively.

Editorial note: MJH20021010
Table "State Description: Init" removed.

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

Table 16: 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. Table 17 describes the HTTP response header fields generated by the responding SOAP node. Table 18 describes the HTTP Status Codes associated with SOAP faults that can be generated by the responding SOAP node.

Table (removed) describes the responding SOAP node's "Receiving" state.

Editorial note: MJH20021010
Table "State Description: Receiving" removed.

Table 17 and Table 18 describe the HTTP response header generated by the responding SOAP node.

Table 17: HTTP Response Headers Fields
FieldValue
Status line

Set according to the next table.

200, or set according to Table 18 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 [RFC 2616], section 14.11) may be used to express an optional compression feature.

HTTP Entity Body

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

[SOAP MediaType]

A. The application/soap+xml Media Type

.

 

Table 18: 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.2 SOAP Request-Response Message Exchange Pattern only) the binding completes receiving of the request message and transmission of the response message.

Table (deleted) describes the responding SOAP node's Responding state.

Editorial note: MJH20021010
Table "State Description: Receiving+Sending" removed.
7.5.2.4 Sending

In the "Sending" state (6.3 SOAP Response Message Exchange Pattern only) the binding completes transmission of the response message.

7.5.2.5 Success and Fail

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

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 Part 1]Security Considerations. Implementers of the SOAP HTTP Binding should carefully review this material.

8. References

8.1 Normative References

[SOAP Part 1]
W3C Working Draft "SOAP Version 1.2 Part 1: Messaging Framework", Martin Gudgin, Marc Hadley, Jean-Jacques Moreau, Henrik Frystyk Nielsen, @@@@@@ (See soap12-part1.html.)
[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 Part1]
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 Part2]
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.)
[SOAP MediaType]
IETF Internet Draft "The 'application/soap+xml' media type", M. Baker, M. Nottingham, "draft-baker-soap-media-reg-02.txt" July 9, 2002. (Work in progress). (See http://www.markbaker.ca/2001/12/draft-baker-soap-media-reg-02.txt.)

8.2 Informative References

[SOAP Part0]
W3C Working Draft "SOAP Version 1.2 Part 0: Primer", Nilo Mitra, @@@@@@ (See soap12-part0.html.)
[XMLP Comments]
XML Protocol Comments Archive (See http://lists.w3.org/Archives/Public/xmlp-comments/.)
[XMLP Dist-App]
XML Protocol Discussion Archive (See http://lists.w3.org/Archives/Public/xml-dist-app/.)
[XMLP Charter]
XML Protocol Charter (See http://www.w3.org/2000/09/XML-Protocol-Charter.)
[RFC 2045]
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.)
[RFC 2026]
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.)
[RFC 2817]
IETF "RFC 2817: Upgrading to TLS Within HTTP/1.1", R. Khare, S. Lawrence, May 2000. (See http://www.ietf.org/rfc/rfc2817.txt.)

A. The "application/soap+xml" Media Type

This appendix defines the "application/soap+xml" media type which can be used to describe SOAP 1.2 messages serialized as XML. It is referenced by the corresponding IANA registration document [SOAP MediaType].

A.1 Registration

MIME media type name:

application

MIME subtype name:

soap+xml

Required parameters:

none

Optional parameters:
charset

This parameter has identical semantics to the charset parameter of the "application/xml" media type as specified in [RFC 3023].

action

See section A.3 The action parameter.

Encoding considerations:

Identical to those of "application/xml" as described in [RFC 3023], section 3.2, as applied to the SOAP envelope infoset.

Security considerations:

See section A.2 Security considerations.

Interoperability considerations:

There are no known interoperability issues.

Published specification:

This document (Part 2) and [SOAP Part 1] (Part 1).

Applications which use this media type:

No known applications currently use this media type.

Additional information:
File extension:

SOAP messages are not required or expected to be stored as files.

Fragment identifiers:

Identical to that of "application/xml" as described in [RFC 3023], section 5.

Base URI:

As specified in [RFC 3023], section 6. Also see [SOAP Part 1], section Use of URIs in SOAP.

Macintosh File Type code:

TEXT

Person and email address to contact for further information:

Mark Baker <mbaker@idokorro.com>

Intended usage:

COMMON

Author/Change controller:

The SOAP 1.2 specification set is a work product of the World Wide Web Consortium's XML Protocol Working Group. The W3C has change control over these specifications.

A.2 Security considerations

Because SOAP can carry application defined data whose semantics is independent from that of any MIME wrapper (or context within which the MIME wrapper is used), one should not expect to be able to understand the semantics of the SOAP message based on the semantics of the MIME wrapper alone. Therefore, whenever using the "application/soap+xml" media type, it is STRONGLY RECOMMENDED that the security implications of the context within which the SOAP message is used is fully understood. The security implications are likely to involve both the specific SOAP binding to an underlying protocol as well as the application-defined semantics of the data carried in the SOAP message (though one must be careful when doing this, as discussed in [SOAP Part 1], section Binding to Application-Specific Protocols.

Also, see [SOAP Part 1], the entire section Security Considerations.

In addition, as this media type uses the "+xml" convention, it shares the same security considerations as described in [RFC 3023], section 10.

A.3 The action parameter

This optional parameter can be used to specify the URI that identifies the intent of the message. In SOAP 1.2, it serves a similar purpose as the SOAPAction HTTP header

field

did in SOAP 1.1. Namely, its value identifies the intent of the message.

The value of the action parameter is an absolute URI-reference as defined by [RFC 2396]. SOAP places no restrictions on the specificity of the URI or that it is resolvable.

Although the purpose of the action parameter is to indicate the intent of the SOAP message there is no mechanism for automatically computing the value based on the SOAP envelope. In other words, the value has to be determined out of band.

It is recommended that the same value be used to identify sets of message types that are logically connected in some manner, for example part of the same "service". It is STRONGLY RECOMMENDED that the URI be globally unique and stable over time.

The presence and content of the action parameter MAY be used by servers such as firewalls to appropriately filter SOAP messages and it may be used by servers to facilitate dispatching of SOAP messages to internal message handlers etc. It SHOULD NOT be used as an insecure form of access authorization.

Use of the action parameter is OPTIONAL. SOAP Receivers MAY use it as a hint to optimize processing, but SHOULD NOT require its presence in order to operate.

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 [Namespaces in XML]

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

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

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

    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 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 T1, T2, ... , TN be the characters of TAG, in order from left to right.

    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 mapping of the characters of the application to characters of Unicode.

    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 NFC normalization may alter the original sequence in a few cases. See http://www.w3.org/TR/charmod/#sec-Transcoding. 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. For each i between 1 (one) and N, let Mi be M(Ti).

    Let C be the sequence of Unicode Scalar Values (characters) represented by M(T)

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

    Let N be the number of characters in C. Let C1, C2, ..., CN be the characters of C, in order from most to least signifcant (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 Ti has no mapping to Unicode (i.e. M(Ti) is undefined), then Xi is implementation-defined

      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, Ti is "_" (underscore), and Ti+1 is "x" (lowercase letter x), then let Xi be "_x005F_".

      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, N>=3, T1 is either "x" (lowercase letter x) or "X" (uppercase letter X), T2 is either "m" (lowercase letter m) or "M" (uppercase letter M), and T3 is either "l" (lowercase letter l) or "L" (uppercase letter L), then let Xi be "_xFFFF_"T1

      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 recapitalization thereof), then let Xi be "_xFFFF_"T1

    4. If Ti is not a valid XML NCName character or if i=1 (one) and T1 is not a valid first character of an XML NCName, then:

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

      Let U1, U2, ... , U8 be the eight hex digits [PROD: 5] such that Ti is "U+"U1U2 ... U8 in the UCS-4 encoding.

      Let U1, U2, ... , U8 be the eight hex digits [PROD: 5] such that Ci is "U+"U1U2 ... U8 in the Unicode Scalar Value.

      Case:

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

        This case implies that Ti has a UCS-2 encoding, which is U+U5U6U7U8.

        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+U5U6U7U8.

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

    5. Otherwise, let Xi be Mi. That is, any character in

      TAG

      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

    left to right.

    most to least significant.

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

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

     Ælfred -> Ælfred
   άγνωστος -> άγνωστος
ᜉᜅᜎᜈ        -> _x1709__x1705__x170E__x1708_
ᏙᏚᎥ         -> _x13D9__x13DA__x13A5_
      

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

validation of encoded SOAP messages MUST NOT be required by conforming processors.

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 Part1]), the schema recommendation is build 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 Part1], 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 id attribute 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

element namespace names and local names

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.

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

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): Vidur Apparao (Netscape), Camilo Arbelaez (webMethods), Carine Bournez (W3C), Michael Champion (Software AG), Glen Daniels (Macromedia, formerly Allaire), Paul Denning (MITRE), Frank DeRose (Tibco), Colleen Evans (Progress Software), David Fallside (Chair, IBM), Dietmar Gaertner (Software AG), Martin Gudgin (Microsoft Corporation, formerly DevelopMentor), Marc Hadley (Sun Microsystems), Gerd Hoelzing (SAP AG), Oisin Hurley (IONA Technologies), John Ibbotson (IBM), Ryuji Inoue (Matsushita Electric), Kazunori Iwasa (Fujitsu Limited), Murali Janakiraman (Rogue Wave), Mario Jeckle (DaimlerChrysler Research & Technology), Mark Jones (AT&T), Anish Karmarkar (Oracle), Jacek Kopecky (Systinet), Yves Lafon (W3C), Michah Lerner (AT&T), Bob Lojek (Intalio), Brad Lund (Intel), Noah Mendelsohn (IBM, formerly Lotus Development), Jeff Mischkinsky (Oracle), Nilo Mitra (Ericsson), Jean-Jacques Moreau (Canon), Highland Mary Mountain (Intel), Don Mullen (Tibco), Masahiko Narita (Fujitsu Limited), Eric Newcomer (IONA Technologies), Henrik Frystyk Nielsen (Microsoft Corporation), David Orchard (BEA Systems, formerly JamCracker), Andreas Riegg (DaimlerChrysler Research & Technology), Herve Ruellan (Canon), Marwan Sabbouh (MITRE), Miroslav Simek (Systinet), Simeon Simeonov (Macromedia, formerly Allaire), Nick Smilonich (Unisys), Lynne Thompson (Unisys), Patrick Thompson (Rogue Wave), Asir Vedamuthu (webMethods), Pete Wenzel (SeeBeyond), Ray Whitmer (Netscape), Volker Wiechers (SAP AG), Amr Yassin (Philips Research), Jin Yu (Martsoft).

Previous members were: Yasser alSafadi (Philips Research), Bill Anderson (Xerox), Mark Baker (Idokorro Mobile, formerly Sun Microsystems), Philippe Bedu (Electricite de France), Olivier Boudeville (Electricite de France), Don Box (DevelopMentor), Tom Breuel (Xerox), Dick Brooks (Group 8760), Winston Bumpus (Novell), David Burdett (Commerce One), Charles Campbell (Informix Software), Alex Ceponkus (Bowstreet), Miles Chaston (Epicentric), David Clay (Oracle), David Cleary (Progress Software), Ugo Corda (Xerox), Paul Cotton (Microsoft Corporation), Fransisco Cubera (IBM), Ron Daniel (Interwoven), Dug Davis (IBM), Ray Denenberg (Library of Congress), Mike Dierken (DataChannel), Andrew Eisenberg (Progress Software), Brian Eisenberg (DataChannel), John Evdemon (XMLSolutions), David Ezell (Hewlett Packard), Eric Fedok (Active Data Exchange), Chris Ferris (Sun Microsystems), Daniela Florescu (Propel), Dan Frantz (BEA Systems), Michael Freeman (Engenia Software Corp), Scott Golubock (Epicentric), Rich Greenfield (Library of Congress), Hugo Haas (W3C), Mark Hale (Interwoven), Randy Hall (Intel), Bjoern Heckel (Epicentric), Erin Hoffman (Tradia), Steve Hole (MessagingDirect Ltd.), Mary Holstege (Calico Commerce), Jim Hughes (Fujitsu Software Corp), Yin-Leng Husband (Hewlett Packard, formerly Compaq), Scott Isaacson (Novell), Eric Jenkins (Engenia Software), Jay Kasi (Commerce One), Jeffrey Kay (Engenia Software), Richard Koo (Vitria Technology Inc.), Alan Kropp (Epicentric), Julian Kumar (Epicentric), Peter Lecuyer (Progress Software), Tony Lee (Vitria Technology Inc.), Henry Lowe (OMG), Matthew MacKenzie (XMLGlobal Technologies), Murray Maloney (Commerce One), Richard Martin (Active Data Exchange), Alex Milowski (Lexica), Kevin Mitchell (XMLSolutions), Ed Mooney (Sun Microsystems), Dean Moses (Epicentric), Rekha Nagarajan (Calico Commerce), Raj Nair (Cisco), Mark Needleman (Data Research Associates), Art Nevarez (Novell), Mark Nottingham (Akamai Technologies), Conleth O'Connell (Vignette), David Orchard (Jamcracker), Kevin Perkins (Compaq), Jags Ramnaryan (BEA Systems), Vilhelm Rosenqvist (NCR), Waqar Sadiq (Vitria Technology Inc.), Rich Salz (Zolera) Krishna Sankar (Cisco), George Scott (Tradia), Shane Sesta (Active Data Exchange), Lew Shannon (NCR), John-Paul Sicotte (MessagingDirect Ltd.), Aaron Skonnard (Developmentor), Soumitro Tagore (Informix Software), James Tauber (Bowstreet), Jim Trezzo (Oracle), Randy Waldrop (webMethods), Fred Waskiewicz (OMG), David Webber (XMLGlobal Technologies), Stuart Williams (Hewlett Packard), Yan Xu (DataChannel), Susan Yee (Active Data Exchange).

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

DateAuthorDescription
20021017MJGQualified id and ref attributes in 3.1.5.1 id Attribute Information Item and 3.1.5.2 ref Attribute Information Item per resolution of issue 326
20021011MJHMajor overhaul of HTTP binding section and some changes to MEP section.
20021007MJH Removed some remaining QNameisms from values of FaulureReason property in HTTP binding.
20020926MJHAdded issue 306 resolution (SHOULD use appendix B) to sections 4.2.1 and 4.2.2
20020926MJHAdded issue 319 resolution (http provides base URI) to section 7.1.2.
20020926MJHMoved decription of rpc ns prefix from rpc section to the table at the top of the document with all of the other ns prefixes.
20020926MJHAdded resolution of issue 298 (removed array representation of RPC).
20020926MJHAdded resolution of issue 383.
20020923MJHTidied up formatting of tables 4 and 9, no substantive changes.
20020922MJGCleaned up stuff regarding URIs for property values. Made sure all URIs that function as bases URIs have trailing /. Changed several occurences of soap/mep/request-response so soap/mep/soap-response in 6.3 SOAP Response Message Exchange Pattern
20020922MJGRemove 'generics' from 2.3 Values and 3.1.3 Encoding compound values per resolution of issues 297 ,361 and 365
20020920MJH Finished making role, state and failure reason URIs.
20020920JJM Added missing title to 4th subsection in HTTP Binding/Introduction.
20020919MJH Made a start making role, state and failure reason URIs.
20020919JJM Shuffled paragraphs in "HTTP Introduction", and created subsections.
20020916HFN Added 'diff="add"' around note in 3.1.2 Encoding simple values
20020915HFN Changed title of Appendix A from "The "application/soap+xml" media type draft-baker-soap-media-reg-02.txt" to "The "application/soap+xml" Media Type"
20020915HFN Added missing "to" in table 18.
20020903JJM Replace ref to media-type IETF by ref to appendix A, since the draft is now an empty shell and the contents was moved to the spec instead.
20020903JJM Global replace for "HTTP header" by "HTTP header field".
20020902HFN Incorporated resolution to issue 284 by removing the term "binding-specific address" from RPC convention section.
20020826NRM In 5.1.1 Properties, added comma after "Where appropriate". Without the comma the sentence parses ambiguously.
20020823MJG Amended B.1 Rules for mapping application defined names to XML Names per resolution of issue 270
20020823MJG Added Latin-1 and non-Latin-1 (Greek, Tagalog, Cherokee) examples to B.1 Rules for mapping application defined names to XML Names ( this does not show up in the diff ) per resolution of issue 270
20020823MJG Amended description of graph edges in 2.1 Graph Edges to allow for null references ( outbound edges that don't terminate ) and initial inbound edge ( the edge which terminates at the initial serialization point but has no originating node ). Also amended 3.1.1 Encoding graph edges and nodes to state that in certain cases an element information item represents both a graph node and a graph edge. Both changes as per issue 353
20020823MJG Changed from 'local name', 'namespace name' and 'specified' to '[local name]', '[namespace name]' and '[specified]' in 3.1.1 Encoding graph edges and nodes, 3.1.3 Encoding compound values, 3.1.4.1 itemType Attribute Information Item, 3.1.5.1 id Attribute Information Item, 3.1.5.2 ref Attribute Information Item, 3.1.6 arraySize Attribute Information Item and C.2 Validating using the SOAP Encoding schema as per issue 352
20020823MJG Changed from "type 'localname' in the namespace 'namespaceuri'" to "type prefix:localname" in 2.2 Graph Nodes, 3.1.4 Computing the Type Name property, 3.1.4.1 itemType Attribute Information Item, 3.1.5.1 id Attribute Information Item, 3.1.5.2 ref Attribute Information Item and 3.1.6 arraySize Attribute Information Item as per issue 352
20020822MJGRemoved XLink from 8.1 Normative References ( does not show up in diff ) per the resolution of issue 352
20020822MJGAmended 5. A Convention for Describing Features and Bindings per resolution of issue 343
20020822MJGAmended C. Using W3C XML Schema with SOAP Encoding per resolution of issue 285
20020822MJGAmended title of 6.1 Property Conventions for SOAP Message Exchange Patterns from Property Conventions for Message Exchange Patterns ( does not show up in diff ) per resolution of issue 328
20020822MJGAmended title of 6.2 SOAP Request-Response Message Exchange Pattern from Request-Response Message Exchange Pattern ( does not show up in diff ) per resolution of issue 328
20020822MJGAmended 7.1 Introduction per resolution of issue 286
20020822MJGAmended title of 3.1 Mapping between XML and the SOAP Data Model from Rules for encoding Graphs in XML ( does not show up in diff ) per resolution of issue 353
20020822MJGAmended 3.2 Decoding Faults per resolution of issue 283
20020820MJGAmended 1. Introduction, 3.1.6 arraySize Attribute Information Item, 4.1.2 Distinguishing Resource Retrievals from other RPCs, 4.2.3 SOAP Encoding Restriction, 4.4 RPC Faults, 7.5.1.2 Requesting and Table (deleted) per resolution of issue 282
20020820MJGAmended member and previous member lists. There is no diff markup for this.
20020815MJGAmended 7.5.2.1 Init, Table (removed), Table 16, 7.5.2.2 Receiving, Table (removed), Table 17, Table 18 per resolution of issue 339 and issue 340.
20020815MJGAmended Table 5 and Table 10 to have a third column, Notes. Moved text related to initialization into Notes column from Property Value column.
20020815MJGAmended 5.1.1 Properties per resolution of issue 268. Also updated Table 2, Table 3, Table 8 and Table 13
20020813MJGRemoved the ID property from nodes in the 2.2 Graph Nodes per resolution of issue 314
20020813MJGChanged the last paragraph of the note at the end of 3.1.4 Computing the Type Name property to refer to SOAP Encoding rather than SOAP per resolution of issue 318
20020812MJGChanged last paragraph of 6.4.3 Web Method Feature State Machine per resolution of issue 228
20020812MJGAdding change log :)