DRAFT Rewrite of SOAP Version 1.2 Part 2: Adjuncts

2.1.1 Edge labels

An edge label is an XML qualified name. Two edge labels are equal if and only if their XML expanded names are equal. I.e., both of the following are true:

1. Their local name values are the same.

2. Either of the following is true:

   1. Both of their namespace name values are missing.

   2. Their namespace name values are both present and are both the same.

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

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.

3.1.1 Encoding Graph Edges and Nodes

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

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

1. If the element information item representing the edge does not have a 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/2003/05/soap-encoding" (see SOAP 1.2 Part 1 [SOAP Part 1], SOAP encodingStyle Attribute).

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

3.1.2 Encoding Simple Values

The lexical value of a graph node representing a simple value is the sequence of Unicode characters identified by the character information item children of the element information item representing that node. The element information item representing a simple value node MAY have among its attributes a 'nodeType' attribute information item (see 3.1.7 nodeType Attribute Information Item). Note that certain Unicode characters cannot be represented in XML (see XML 1.0 [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, the [local name] and [namespace name] properties of the child element information item together determine the value of the edge label.

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

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

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

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

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

   • The element information item representing an array node MAY have among its attributes an itemType attribute information item (see 3.1.4.1 itemType Attribute Information Item).

   • The element information item representing an array node MAY have among its attributes an arraySize attribute information item (see 3.1.6 arraySize Attribute Information Item).

5. If a graph edge does not terminate in a graph node then it can either be omitted from the serialization or it can be encoded as an element information item with an xsi:nil attribute 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 xs:QName (see XML Schema [XML Schema Part 2]); its value consists of the pair {namespace name, local name}. Neither the prefix used to construct the QName nor any information relating to any definition of the type is considered to be part of the value. The SOAP graph carries only the qualified name of the type.

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

3.1.5 Unique identifiers

3.1.6 arraySize Attribute Information Item

The arraySize attribute information item has the following Infoset properties:

• A [local name] of arraySize .

• A [namespace name] of "http://www.w3.org/2003/05/soap-encoding".

The type of the arraySize attribute information item is enc:arraySize. The value of the arraySize attribute information item MUST conform to the following EBNF grammar

The arraySize attribute conveys a suggested mapping of a SOAP array to a multi-dimensional program data structure. The cardinality of the arraySize list represents the number of dimensions, with individual values providing the extents of the respective dimensions. When SOAP encoding multidimensional arrays, nodes are selected such that the last subscript (i.e. the subscript corresponding to the last specified dimension) varies most rapidly, and so on with the first varying most slowly. An asterisk MAY be used only in place of the first size to indicate a dimension of unspecified extent; asterisks MUST NOT appear in other positions in the list. The default value of the arraySize attribute information item is "*", i.e. a single dimension of unspecified extent.

3.1.7 nodeType Attribute Information Item

The nodeType attribute information item has the following Infoset properties:

• A [local name] of nodeType .

• A [namespace name] of "http://www.w3.org/2003/05/soap-encoding".

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

The type of the nodeType attribute information item is enc:nodeType.

The value of the nodeType attribute information item MUST, if present, be one of the strings "simple" or "struct" or "array". The value indicates what kind of a value this node represents - a simple value, a compound struct value or a compound array value respectively.

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

4.1.2 Distinguishing Resource Retrievals from other RPCs

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

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

getQuantityInStock(PartNumber="123")

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

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

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

• In cases where all the arguments have been represented in the URI, no SOAP header blocks are to be transmitted and the operation is a safe retrieval, the 6.2 SOAP Web Method Feature and the ??? are used. [***NOAH*** The dangling reference is non-trivial, as it was to the now deleted Response-only MEP. Consider what we now need to replace this, which is: "The Request/response MEP used in a mode where the outbound message has no SOAP envelope and the inbound message has a SOAP envelope." Is that cleaner than saying "The response-only MEP"? This is a perfect example of why having specific MEPs allows users to say what they need out of the transport binding.]Accordingly, no SOAP envelope is transmitted for the request, and the http://www.w3.org/2003/05/soap/features/web-method/Method property is set to "GET". The results of the retrieval are a SOAP RPC response as described in 4.2.2 RPC Response

• In cases where the operation to be performed is not a retrieval, when SOAP header blocks are to be transmitted (a digital signature, for example), or when a retrieval is not safe, the 6.2 SOAP Web Method Feature and the 6.1 SOAP Request-Response Message Exchange Pattern are used [***NOAH*** This should say: The Request/Response MEP used in a mode where both outbound request and inbound response have SOAP envelopes (except in certain error cases, which would have been covered in the MEP description but which we may need to repeat for completeness here.)]. The request envelope is encoded as described in 4.2.1 RPC Invocation, and the results are as described in 4.2.2 RPC Response. The http://www.w3.org/2003/05/soap/features/web-method/Method property is set to "POST".

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

4.2.1 RPC Invocation

An RPC invocation is modeled as follows:

• 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 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 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 follows:

• The response is represented by a single struct containing an outbound edge for the return value and each [out] or [in/out] parameter. The name of the struct is not significant.

• 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 as follows:

  1. There MUST be an outbound edge with a local name of result and a namespace name of "http://www.w3.org/2003/05/soap-rpc" which terminates in a terminal node

  2. The type of that terminal node is a xs:QName and its value is the name of the outbound edge which terminates in the actual return value.

  If the return value of the procedure is void then an outbound edge with a local name of result and a namespace name of "http://www.w3.org/2003/05/soap-rpc" MUST NOT be present.

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

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.

5.1.1 Properties

Under the convention, properties are represented as follows:

• Properties are named with URIs.

• Where appropriate, property values SHOULD have an XML Schema [XML Schema Part 1] [XML Schema Part 2] type listed in the specification which introduces the property.

5.1.2 Property Scope

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

Figure 1: Model describing properties shared between SOAP and Binding

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

This message exchange pattern is identified by the URI (see SOAP 1.2 Part 1 [SOAP Part 1] SOAP Features):

• "http://www.w3.org/2003/05/soap/mep/request-response/"

6.1.2 Description

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

[***NOAH*** Interesting but deep question: if neither the request nor the response has a SOAP envelope, is it still governed by this Rec? Do we need to say something? That's a big conformance change. Before, at least one of the outbound or inbound messages had to be an envelope for this Recommendation to even apply. I think that's an example of the sort of subtle but deep change about which we should be very careful when considering getting rid of Response-only.]

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

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

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

6.1.3 Property Description

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

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

[***NOAH*** I think a bit too much detail has been lost at this point. It basically says, "prepare the context and you're done." Interestingly, the later discussion of the HTTP binding such as 7.5.1.1 Init and 7.5.1.2 Requesting continue to provide the sort of detail that seems appropriate. If we do go with this overall approach, then I suggest that we put here into the MEP description the level of detail similar to what's still in the HTTP section. In other words, explain the state machine in words. I know it's roughed out above, but given that you've told me to build the context, you should tell me what to do with it, at both requester and responder.]

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

• All the rules in SOAP 1.2 Part 1 [SOAP Part 1] Binding Framework regarding streaming of individual SOAP messages MUST be obeyed for both request and response SOAP messages.

• When using streaming SOAP bindings, requesting nodes MUST avoid deadlock by accepting and if necessary processing SOAP response information while the request is being transmitted.

  Note:

  Depending on the implementation used and the size of the messages involved, this rule MAY require that SOAP applications stream application-level response processing in parallel with request generation.

• A requesting node MAY fail, and thus abort transmission of the outbound request, based on information contained in an incoming streamed SOAP response.

6.1.4 Fault Handling

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

If a SOAP fault is generated by the responding SOAP node, the SOAP fault is made available in http://www.w3.org/2003/05/soap/mep/OutboundMessage . 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.

6.2.1 SOAP Feature Name

The SOAP Web Method feature is identified by the URI (see SOAP 1.2 Part 1 [SOAP Part 1] SOAP Features):

• "http://www.w3.org/2003/05/soap/features/web-method/"

6.2.2 Description

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

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

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

6.2.3 SOAP Web Method Feature Properties

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

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

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

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

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

6.3.1 SOAP Feature Name

The SOAP Action figure is identified by the URI (see SOAP 1.2 Part 1 [SOAP Part 1] SOAP Features):

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

6.3.2 Description

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

6.3.3 SOAP Action Figure State Machine

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

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

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

7.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.1 SOAP Request-Response Message Exchange Pattern. Such alternate bindings MAY therefore make use of HTTP features and status codes not required for this binding.

7.1.2 Use of HTTP

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

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

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

7.1.3 Interoperability with non-SOAP HTTP Implementations

Particularly when used with HTTP GET messages, 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.

Even though HTTP often is used on the well-known TCP port 80, the use of HTTP is not limited to that port. As a result, it is possible to have a dedicated HTTP server for handling SOAP processing on a distinct TCP port. Alternatively, it is possible to use a separate virtual host for dealing with SOAP processing. Such configuration, however, is a matter of convenience and is not a requirement of this specification (see SOAP 1.2 Part 1 [SOAP Part 1] Binding to Application-Specific Protocols).

7.1.4 HTTP Media-Type

Conforming implementations of this binding:

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

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

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

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

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

7.5.1 Behavior of Requesting SOAP Node

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

7.5.2 Behavior of Responding SOAP Node

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