SOAP Version 1.2 Part 0: Primer

Abstract

SOAP version 1.2 Part 0: Primer is a non-normative document intended to provide a easily readable tutorial on the features of SOAP version 1.2. In particular, it describes the features through various usage scenarios, and is intended to complement the normative texts contained in Part 1 and Part 2 of the SOAP 1.2 specifications.

Status of this Document

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

Editor's Note: The purpose of this editor's copy is to show what the contents of a Primer might be. Almost all the examples shown in this first draft are taken from Parts 1 and 2, with some modifications. Based on the decision of the WG on how to deal with these examples from the main specifications (i.e., retain in specs, move to primer), new examples may have to be provided in future drafts of this document. In any case, new examples will have to be provided to illustrate other usage scenarios. WG members are encouraged to provide such examples for inclusion in future drafts.

Comments on this document should be sent to xmlp-comments@w3.org (public archives). It is inappropriate to send discussion emails to this address.

Discussion of this document takes place on the public <xml-dist-app@w3.org> mailing list (Archives) per the email communication rules in the XML Protocol Working Group Charter.

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

Table of Contents

1. Introduction

1.1 Overview

1.2 Notational Conventions

1.3 SOAP Extensibility Mechanisms

1.4 SOAP Processing Model

2. Basic Usage Scenarios

2.1 One-way SOAP messages

2.2 Two-way SOAP message exchange

2.2.1 Document-style message exchange

2.2.2 Remote procedure call

3. Advanced Usage Scenarios

3.1 Using SOAP header elements

3.2 Using SOAP intermediaries

3.3 Using various transport bindings

3.3.1 HTTP binding

3.3.1.1 SOAP HTTP request

3.3.1.2 SOAP HTTP response

3.3.2. SMTP binding

3.4 Using other serialization schemes

4. Version transition from SOAP 1.1 to SOAP 1.2

4.1 Changes between SOAP 1.1 and SOAP 1.2

4.2 Interworking between SOAP 1.1 and SOAP 1.2

5. References

5.1. Normative references

5.2. Informative references

A. Acknowledgements

B. Change Log

1. Introduction

SOAP version 1.2 Part 0: Primer is a non-normative document intended to provide a easily readable tutorial on the features of SOAP version 1.2 [1, 2]. In particular, it describes the features through various usage scenarios, and is intended to complement the normative texts contained in Part 1 and Part 2 of the SOAP 1.2 specifications.

Part 1 of the SOAP 1.2 specifications defines the SOAP envelope, which is a construct that defines an overall framework for expressing the contents of a SOAP message, identifying who should deal with all or part of it, and whether handling such parts are optional or mandatory. It also defines a transport binding framework, which describes the way by which a SOAP message may be carried as the payload of another protocol.

Part 2 of the SOAP 1.2 specification defines the conventions and a particular encoding scheme for conveying remote procedure calls (RPC) as well as one concrete realization of the binding framework defined in Part 1, namely the exchange of SOAP messages as payload of a HTTP request and response.

This document (the primer) is not normative, which means that it does not provide the definitive specification of SOAP 1.2. The examples provided here are intended to complement the formal specifications, and in any question of interpretation the formal specifications naturally take precedence. The examples shown here provide a subset of the uses expected for SOAP. Its purpose is to help a technically competent person understand how SOAP may be used, by describing representative message exchange patterns and SOAP message structures. In actual usage scenarios, SOAP is most likely a part of an overall solution, and there may be other application-specific requirements which are not captured in these examples.

1.1 Overview

SOAP version 1.2 provides the definition of an XML document which can be used for exchanging structured and typed information between peers in a decentralized, distributed environment. It is fundamentally a stateless, one-way message exchange paradigm, but applications can create more complex interaction patterns (e.g., request/response, request/multiple responses, etc.) by combining such one-way exchanges with features provided by an underlying transport protocol and/or application-specific information. SOAP is silent on the semantics of any application-specific data it conveys, as it is on issues such as the routing of SOAP messages, reliable data transfer, firewall traversal, etc. However, SOAP provides the framework by which application-specific information may be conveyed in an extensible manner (see section 1.3). Also, SOAP provides a full description of the expected actions taken by a SOAP processor on receiving a SOAP message (see section 1.4).

Section 2 of this document provides an introduction to the basic features of SOAP via the simplest usage scenarios, namely a one-way SOAP message, followed by a request-response type exchange.

Section 3 provides a treatment of various features of SOAP that can be used in more complex usage scenarios. These include the use of header elements as an extensibility mechanism to add features to communicating applications, the use of intermediate SOAP processors to provide additional services to an overall application, using alternative means to transfer SOAP messages and the use of alternative encoding schemes to serialize SOAP and application-specific data.

Section 4 describes the changes from SOAP version 1.1.

Section 5 provides references.

1.2 Notational Conventions

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC-2119 [3].

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

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

EdNote: Need to correct the reference numbers and check links.

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

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

Editorial notes are indicated with yellow background (may not appear in all media) and prefixed with "EdNote:".

1.3 SOAP Extensibility Mechanisms

 In anticipation of many uses for SOAP, many of which will involve the participation of many SOAP processing nodes along a message's path from a sender to an ultimate receiver, a flexible technique in the form of header blocks has been provided to permit SOAP processors to exchange information without centralized control. These form the mechanism by which SOAP messages may be extended in an application-specific manner.

Header blocks are targeted at a SOAP processor through an actor attribute in the header block element, which takes a value of anyURI. Several standardized actor roles have been defined (see Part 1, section 4.2.2), which are "none", "next" and "anonymous". A SOAP processor is expected to process such header block if it assumes a role identified by the value in the URI. Section 1.4 of this document provides further clarification on the SOAP processing model.

In order to ensure that SOAP processors do not ignore header blocks which are important to the overall purpose of the application, SOAP header blocks also provide for another optional attribute, mustUnderstand, which, if "true", means that the targeted SOAP processor must process the block according to the specification of that block. Such a specification is not a part of SOAP.

The Body element and associated Body blocks are intended for exchange of information between the initial SOAP sender and the SOAP procssor which assumes the role of the ultimate SOAP receiver. Therefore, such elements are implicitly targeted and must be understood by the ultimate target. The means by which a SOAP processor assumes such a role is not a part of the SOAP specification, and is presumably determined as a part of the overall application semantics and associated message flow.

1.4 SOAP Processing Model

The SOAP processing model (specified in Part 1, Section 2) describes the actions taken by a SOAP processor at a node on receiving a SOAP message. There is a requirement for the processor to analyse those parts of a message that are SOAP-specific, namely those elements in the SOAP "env" namespace. Such elements are the envelope itself, the header element and its child elements - referred to as blocks - and the body element. A first step is, of course,the overall check that the SOAP message is syntactically correct. That is, it is an XML document that uses the subset of XML defined in Part 1, section 3.

Further processing of header and body elements depends on the role assumed by the SOAP processor for the processing of a given message instance. SOAP defines an actor attribute - syntactically, any URI - that may be present in a header element, which defines the role played by the intended target of that header. Several standardized actor roles have been defined (see Part 1, 2.2), which are "none", "next" and "anonymous".

The "anonymous" role (which is implicit in that it is not specified by a URI, and is denoted by the absence of the actor attribute) is played by a SOAP processor which assumes the role of the ultimate recipient of a particular SOAP message. The absence of an actor attribute means that the header element is targeted at the SOAP processor which assumes the "anonymous" actor role. The body element is always targeted at the SOAP processor that assumes the "anonymous" role. In that sense, the body element is just like a header element targeted at the anonymous actor, but it has been distinguished to allow for SOAP processors to skip over it if they assume roles other than the anonymous one.

The body element also has another distinguished role. It is the container where information on SOAP-specific faults, i.e., failure to process elements of a SOAP message are placed.

If a header element has an actor attribute of "next", every SOAP processor must process the contents of the element as this is a standardized role that every SOAP processor must assume. Header elements thus attributed are those which are expected to be examined and processed by every SOAP processor along the path of a message.

If a header element has the special actor attribute with value "none", it means that no SOAP processor should process the contents, although a processor may need to examine it if the content is data referenced by another header element that is targeted at the particular SOAP processor.

After a SOAP processor has correctly identified the elements targeted at itself, an additional attribute, mustUnderstand, in the header elements determines further processing actions that are taken. A mustUnderstand value of "true" means that the SOAP processor must process the header with the semantics described in that header's specification. Processing the header appropriately may include removing the header from any generated SOAP message, reinserting the header with the same or altered value, or inserting a new header. The inability to process a mandatory header requires that all further processing of the SOAP message cease, and a SOAP fault be generated.

As a result of processing a SOAP message, SOAP processors may generate SOAP faults, or, depending on the application, generate additional SOAP messages for consumption at other SOAP processors. A SOAP fault is a SOAP message with a body block identifying itself as such. SOAP makes a distinction between generating a fault and ensuring that the fault is returned to the originator of the message or appropriate node which can benefit from this information. Whether a fault can be propagated appropriately depends on the transport.

2. Basic Usage Scenarios

SOAP messages are fundamentally one-way transmissions from a SOAP sender to a SOAP receiver, but SOAP messages are expected to be combined to implement patterns such as request/response.

2.1 One-way SOAP messages

Example 1 shows a simple notification expressed in a SOAP message. The message contains the header block alertcontroland the body block alert which are both application defined and not defined by SOAP. The header block contains the parameters priority and expires which may be processed by any SOAP intermediaries encountered in the message path as well as the ultimate destination of the message. The fact that it is targeted at all SOAP nodes encountered en route is indicated by the presence of the actor "next", which is a role that all SOAP nodes play, while the absence of the mustUnderstand attribute indicates that the nodes in question may or may not act upon the information. The body block contains the actual notification message to be delivered, and is processed by the ultimate SOAP processor.

<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope"> 
 <env:Header>
  <n:alertcontrol xmlns:n="http://example.org/alertcontrol" 
          env:actor="http://www.w3.org/2001/09/soap-envelope/actor/next">
   <n:priority>1</n:priority>
   <n:expires>2001-06-22T14:00:00-05:00</n:expires>
  </n:alertcontrol>
 </env:Header>
 <env:Body>
  <m:alert xmlns:m="http://example.org/alert">
   <m:msg>Pick up Mary at school at 2pm</m:msg>
  </m:alert>
 </env:Body>
</env:Envelope>

A SOAP message such as that in Example 1 may be bound to different underlying protocols and used in a variety of message exchange patterns. For instance, it can be sent in a SMTP message (see section 4.3.3). In another application scenario, such as, for example, a Web-based access to a unified mailbox, it could be returned in the body of a HTTP response returned in response to a HTTP GET request.

2.2 Two-way SOAP message exchange

2.2.1 Document style message exchange

EdNote: Need to find better examples for this section. Examples 2, 3 are a little too RPC-ish.

The following example shows a SOAP message exchange used in connection with HTTP as the underlying protocol taking advantage of the request/response mechanism provided by HTTP. The following examples are concerned primarily with the message exchange aspects, while discussion of the HTTP headers and the specifics of HTTP usage are deferred to section3.3.1of this document.

Examples 2 and 3 show a sample SOAP request and a sample SOAP response, carried as the body of a HTTP POST request and a HTTP response respectively. The SOAP Envelope element is the top element of the XML document representing the SOAP message.

In Example 2, the SOAP request contains a Body block called GetLastTradePrice which defines a single sub-element, the ticker symbol for a stock. As in the previous example, the GetLastTradePrice element is not defined by SOAP itself, which is shown by the XML namespace which qualifies the element thereby disambiguating it from any SOAP-specific element.

POST /StockQuote HTTP/1.1
Host: www.stockquoteserver.com
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn

<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope" >
 <env:Body>
  <m:GetLastTradePrice 
        env:encodingStyle="http://www.w3.org/2001/09/soap-encoding"
        xmlns:m="http://example.org/quotes">
    <symbol>DIS</symbol>
  </m:GetLastTradePrice>
 </env:Body>
</env:Envelope>

Example 3 shows the SOAP message returned by the StockQuote service in the corresponding HTTP response to the request shown in Example 2. The SOAP message responding to the request, contains a Body block GetLastTradePriceResponse with a single sub-element containing the price of the stock.

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

<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope" >
 <env:Body>
  <m:GetLastTradePriceResponse 
        env:encodingStyle="http://www.w3.org/2001/09/soap-encoding"
        xmlns:m="http://example.org/quotes">
   <Price>34.5</Price>
  </m:GetLastTradePriceResponse>
 </env:Body>
</env:Envelope>

In both examples, an (optional) encodingStyle attribute with a value in the SOAP namespace shows that the contents of the GetLastTradePrice and GetLastTradePriceResponse have been serialized according to the particular rules defined in Part 2 section 4.

While SOAP specifies a particular encoding scheme (see Part 2 section 4), the specification makes clear that other encoding schemes may be used for application-specific data within a SOAP message for which purpose it provides the encodingStyle attribute to qualify header and body blocks. The choice of the value for this attribute is an application-specific decision and the ability to interoperate is assumed to have been settled "out-of-band".

2.2.2 Remote procedure call

EdNote: This section and examples needs a lot more beefing up.

One of the design goals of SOAP is to encapsulate remote procedure call functionality using the extensibility and flexibility of XML. Part 2 of the SOAP specification has defined a uniform representation for RPC invocations and responses, which is indicated by the value of the SOAP encodingStyle attribute. Examples of the use of alternative encoding schemes are shown in Section 3.4 of this document.

Using SOAP for RPC is independent of the decision to use a particular means for transferring the RPC call and its return. Application designers have to be aware of characterestics of a particular transport chosen for SOAP RPCs, such as latency, synchrony, etc.

In the commonly used case of using HTTP as the underlying transfer protocol, an RPC invocation maps naturally to the HTTP request and an RPC response maps to the HTTP response. However, while the examples below show using SOAP for RPC using the HTTP protocol binding, it is not limited to that means alone.

To invoke an RPC, the following information is needed, which may be expressed by a variety of means including formal Interface Definition Languages:

• The target of the procedure or method
• A procedure or method name
• An optional procedure or method signature
• The parameters to the procedure or method

For use with SOAP, a URI serves as the target of the procedure. It identifies both the target SOAP processor as well as the "service" at that node which supports the named procedure or method.

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

RPCs may also require additional information to be carried, which can be important for the processing of the call in a distributed environment. Example A in section 3.1 shows how a header element can be used to carry such information.

 Example 4 shows a RPC request directed at a stock quote service available at the URI "http://www.stockquoteserver.com/StockQuote". The RPC is carreid as a part of the Body element, and the body block is a struct which takes the name of the procedure or method, in this case GetLastTradePriceDetailed. It has been designed to take two input parameters, the ticker name for the stock and the company name.

POST /StockQuote HTTP/1.1
Host: www.stockquoteserver.com
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn 

<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope" >
   <env:Body>
       <m:GetLastTradePriceDetailed 
             env:encodingStyle="http://www.w3.org/2001/09/soap-encoding"
             xmlns:m="http://example.org/quotes" >
           <Symbol>DEF</Symbol>
           <Company>DEF Corp</Company>
       </m:GetLastTradePriceDetailed>
   </env:Body>
</env:Envelope>

The procedure has been designed to return two out parameters, denoting the LastTradePrice and DayVolume. The RPC response is returned in the Body element of a SOAP message, with the body block taking the procedure name and the word "Response" appended. This is shown in example 5.

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

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

3. Advanced usage scenarios

3.1 Using SOAP header elements

The SOAP Header element provides a modular and flexible means by which applications may independently define features for use with SOAP without impacting the basic messaging protocol itself. The semantics of such header sub-elements, called header blocks - are not defined by SOAP although SOAP defines how a SOAP processor deals with header entries.

Additional information relevant to the encoding of an RPC invocation but not part of the formal procedure or method signature MAY be expressed in the RPC encoding. If so, it MUST be expressed as a header block.

An example of the use of a header block is the passing of a transaction ID along with a RPC invocation in a SOAP message. Since the transaction ID is not part of the procedure (and hence the signature) and is typically held in an infrastructure component rather than application code, there is no direct way to pass the necessary information with the invocation. By adding a header block with an application-specific name that is understood by transaction-aware applications, the transaction manager on the receiving side can extract the transaction ID and use it without affecting the coding of remote procedure calls.

Example A shows an example of a remote procedure call which is bound within the context of a transaction, which is identified by a header block, Transaction, which is directed at the ultimate destination (implied by the absence of the actor attribute) and identified as a header that must be understood by that node.

POST /StockQuote HTTP/1.1
Host: www.stockquoteserver.com
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn

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

Example B shows the return, where the header again identifies the transaction within which this procedure call was performed.

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

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

 SOAP processing rules require that mandatory headers be processed fully, or the entire processing fail and a SOAP message with a SOAP fault indicating a failure to understand a mandatory header be generated. Such a response includes a new SOAP-specific header element, Misunderstood, with empty content and an attribute which contains the fully qualified name of the header which could not be processed.

Example C shows the response where the Transaction header block in the RPC request of Example A could not be processed. 

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

<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope">
   <env:Header>
       <f:Misunderstood qname='t:Transaction' xmlns:t="http://example.org/tx"/>
   </env:Header>
   <env:Body>
       <env:Fault>
           <faultcode>env:MustUnderstand</faultcode>
           <faultstring>SOAP Must Understand Error</faultstring>
       </env:Fault>
   </env:Body>
</env:Envelope>

3.2 Using SOAP intermediaries

EdNote: Text provided by PD with minor editing. No time to harmonize it with 3.1, with which there is overlap, or to make it fit stylistically with the rest of the document. I thought it important to get this out for review and defer revision to a future draft.

This section describes several usage scenarios involving intermediaries, how the SOAP specification pertains to them, and illustrates how SOAP extensions may be used to implement them.

One usage scenario [ 13] states that an SOAP sender (not necessarily the initial SOAP sender) wants the SOAP message to be handled with specific QOS as it traverses the SOAP message path to include multiple SOAP processing intermediaries. Information in the SOAP message is used to select appropriate QoS mechanisms (e.g., RSVP, Diffserv, MPLS, etc.). Lets assume that the sender wants to take advantage of QOS capabilities along the SOAP message path on an end-to-end basis, or at least on the portion of the SOAP message path into and out of a SOAP Intermediary.

A SOAP header block is one possible approach to implementing this scenario. The SOAP 1.2 specification does not define this hypothetical SOAP QOS block. An initial SOAP sender sends a SOAP message containing a QOS header block through one or more SOAP intermediaries to an ultimate SOAP receiver. The intermediary is targeted by the initial SOAP sender from within the SOAP message by inserting an actor attribute within the QOS Block to be used at the SOAP intermediary as described in the SOAP processing model (Part 1, section 2.5). The SOAP specifications do not state how the actor attribute is to be used by the SOAP sender. Potentially, it can be used in the context of the SOAP binding framework to provide a hint for message routing. However, message routing and the role of actor in message routing is not within the scope of the SOAP 1.2 specifications. The SOAP intermediary must examine the SOAP QOS Block, and determine how to invoke the QOS capabilites exposed via the SOAP binding. If the SOAP QOS Block is marked mustUnderstand, then the intermediary is expected to be QOS-aware. If it is not QOS-aware, then a SOAP fault is generated, as this mandatory header cannot be processed. If it is QOS-aware, but cannot honor the specific QOS parameters carried in the QOS Block, then any fault or other response to the sender or elsewhere (e.g., log file) is not defined in the SOAP specifications. The specification of the QOS extension, when defined, would need to describe error handling, negotiations, or other processing under all circumstances.

If the intermediary is QOS-aware, then presumably the information in the QOS Block is used when forwarding the SOAP message further along on its message path toward the ultimate SOAP receiver. In addition to the use of SOAP Blocks to extend the functionality of SOAP, this scenario may also requires extensions to the HTTP binding, or a completely new binding. The Binding Framework allows for additional properties, outside the SOAP envelope, that may be required to invoke the lower layer QOS mechanisms. Additional properties (within the Binding Framework) may be required. For sake of discussion, lets assume that the SOAP node will send the SOAP message using HTTP, but traffic classification of this HTTP flow would be done using diffserv so particular per-hop behaviors can be used within the network enroute to the next SOAP node. Traffic classification for diffserv can be done by the SOAP node sending the SOAP message, or by network devices (assuming they know how to recognize the particular HTTP flow). If traffic classification is handled by a network device, perhaps communications would be needed between the SOAP node and the network device, for example, to provide the network device with the TCP/IP port numbers and IP addresses of the HTTP connection. This would presume some way to obtain this port and address information, which probably involves an API or properties that are beyond the scope of the SOAP 1.2 specifications. (Note, SOAP spec, binding framework, needs to address extension of the existing HTTP binding.

For example, to state that a separate spec can define properties in accordance with the binding framework to extend the capability of the HTTP binding (or any other binding). In the case of SOAP RPC, a QOS extension at the ultimate SOAP receiver may attempt to insert a QOS Block in RPC response. The RPC response may succeed, but perhaps the desired QOS cannot be delivered on the return message path. It is not clear if a SOAP fault should be generated. Likewise, if a SOAP Intermediary on the return message path cannot honor the QOS Block (assumed to be marked mustUnderstand), is it permissable to convert the SOAP RPC response to a SOAP fault? A SOAP extension in the initial SOAP sender is needed to insert this SOAP QOS Block. The sender may need to use properties as defined by the SOAP binding framework to communicate QOS parameters to be used by the underlying network. Since a sOAP binding must define the rules for how the data is exchanged using the underlying protocol, a custom or supplemental binding may be required to support this QOS usage scenario. The HTTP binding described in the SOAP 1.2 specification does not explicitly support QOS properties. The SOAP 1.2 specification does not preclude extensions to this HTTP binding, which would provide the capability to define either QOS properties or a requirement to examine the SOAP envelope (i.e., sOAP QOS Block) to determine the QOS used for transmission. Alternatively, a completely new binding can be specified that includes QOS explicitly, rather than as an extension to an existing binding.

3.3 Using various transport bindings

SOAP messages may be exchanged using a variety of "underlying" protocols, including other application layer protocols. The description of how SOAP messages may be passed from one SOAP processor to another using an underlying protocol is called a transport binding.

Part 1 provides a general framework for describing how applications may choose to use the features provided by a particular underlying protocol to accomplish a particular application semantics. SOAP itself does not provide any mechanism for compensating for differences in features (e.g., message correlation, reliability) provided by different underlying protocols. Whatever feature that is required by a particular application but is not available in the chosen underlying infrastructure has to be provided as a SOAP extension, i.e., a header.

Part 2 specifies one standardized transport binding, namely how SOAP is used in conjunction with HTTP as the underlying protocol, taking advantage of the request/response mechanism provided by HTTP to ensure correlation of messages.

The next sections show examples of two such bindings for SOAP, namely those to HTTP and SMTP.

3.3.1 HTTP binding

HTTP has a well-known connection model and a message exchange pattern. The client identifies the server via a URI, connects to it via the underlying TCP/IP network, issues a HTTP request message and receives a HTTP response message over the same connection. HTTP implicitly correlates its request message with its response message; therefore, an application using this binding can chose to infer a correlation between a SOAP message sent in the body of a HTTP request message and a SOAP message returned in the HTTP response. Similarly, HTTP identifies the server endpoint via a URI, which can also serve as the identification of a SOAP processor at the node.

SOAP only defines the use of the HTTP POST method for conveying SOAP messages in HTTP requests.

HTTP allows for mutliple intermediaries between the initial client and the server identified by the request URI, in which case the request/response model is a series of such pairs.

3.3.1.1 SOAP HTTP request

Examples X and Y show a sample SOAP/HTTP request and a sample SOAP/HTTP response. The SOAP/HTTP request contains a block called GetLastTradePrice which takes a single parameter, the ticker symbol for a stock. As in the previous example, the GetLastTradePrice element is not defined by SOAP itself. The service's response to this request contains a single parameter, the price of the stock. The SOAP Envelope element is the top element of the XML document representing the SOAP message. XML namespaces are used to disambiguate SOAP identifiers from application specific identifiers.

POST /StockQuote HTTP/1.1
Host: www.stockquoteserver.com
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn

<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope" >
 <env:Body>
  <m:GetLastTradePrice 
        env:encodingStyle="http://www.w3.org/2001/09/soap-encoding"
        xmlns:m="http://example.org/quotes">
    <symbol>DIS</symbol>
  </m:GetLastTradePrice>
 </env:Body>
</env:Envelope>

3.3.1.2 SOAP HTTP reponse

Example Y shows the SOAP message sent by the StockQuote service in the corresponding HTTP response to the request from Example X. SOAP over HTTP follows the semantics of the HTTP Status codes for communicating status information in HTTP. For example, a 2xx status code indicates that the client's request including the SOAP component was successfully received, understood, and accepted etc.

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

<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope" >
 <env:Body>
  <m:GetLastTradePriceResponse 
        env:encodingStyle="http://www.w3.org/2001/09/soap-encoding"
        xmlns:m="http://example.org/quotes">
   <Price>34.5</Price>
  </m:GetLastTradePriceResponse>
 </env:Body>
</env:Envelope>

If an error occurs while processing the request, the SOAP HTTP server MUST issue an HTTP 500 "Internal Server Error" response and include a SOAP message in the response containing a SOAP fault indicating the SOAP processing error.

EdNote: Details may need to be changed based on the resolution of the 2xx vs 5xx debate. More examples will be provided.

The SOAP fault model (see Part 1, section 4.4) requires that all SOAP and application-specific faults be reported using a single distinguished element, Fault, carried in the SOAP Body element. If there is an error in the processing of the Body of a SOAP message, it is signalled via standardized faultcode and (standardized?)faultstringsubelements and (optionally) application-specific information in the Details sub-element within the Fault. Example Z shows a HTTP Response with an embedded SOAP message returned in response to the HTTP request in Example X indicating a failure to process the SOAP message. The faultcode indicates that it is a server fault, and the absence of a faultactor element implies that it is generated by the origin server. The detail entries are application-specific.

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

<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope" >
  <env:Body>
    <env:Fault>
      <faultcode>env:Server</faultcode>
      <faultstring>Server Error</faultstring>
      <detail>
        <e:myfaultdetails xmlns:e="http://example.org/2001/09/faults" >
          <message>My application didn't work</message>
          <errorcode>1001</errorcode>
        </e:myfaultdetails>
      </detail>
    </env:Fault>
 </env:Body>
</env:Envelope>

Whilst errors in processing a Header element is also signalled via a Fault element, the Details subelement is not used, and a particular distinguised header element, Misunderstood, signals the offending header. Example C shows an example of a response indicating a failure to process a header.

3.3.2 SMTP binding

EdNote: Severely edited version of text provided by MHM. Any changes, errors or omissions are mine.

Application developers can use the Internet email infrastructure to move SOAP messages as either email text or attachments. The Simple Mail Transport Protocol (SMTP) specifications provide an alternative medium for the transfer of SOAP messages, and a future extension of the SOAP specifications may specify a particular binding for this purpose. The examples shown below offer one way to carry SOAP messages, and should not be construed as being the standard way of doing so.

Example P shows the alert message from Example 1 carries as an SMTP message between a sending and receiving user agent. It is implied that the sender and receiver nodes also have SOAP capabilities, to which the body of the email is delivered for processing.

From: SOAPRequester@example.com
To: SOAPResponder@example2.com
Subject: Alert Message
Date: Mon, 24 Sep 2001 15:32:11 CST
Message-Id: <EE492E16A0B8D311AC490090276D208424960C0C@example.com> 

<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope"> 
 <env:Header>
  <n:alertcontrol xmlns:n="http://example.org/alertcontrol" 
          env:actor="http://www.w3.org/2001/09/soap-envelope/actor/next">
   <n:priority>1</n:priority>
   <n:expires>2001-06-22T14:00:00-05:00</n:expires>
  </n:alertcontrol>
 </env:Header>
 <env:Body>
  <m:alert xmlns:m="http://example.org/alert">
   <m:msg>Pick up Mary at school at 2pm</m:msg>
  </m:alert>
 </env:Body>
</env:Envelope>

While SMTP is a one-way message exchange, and no guarantee of delivery is provided, SMTP offers a delivery notification mechanism which is also not guaranteed. The underlying protocol mechanisms are called Delivery Status Notification (DSN) and Message Disposition Notification (MDN). These notifications take the form of email messages sent to the email address specified in the mail header. Applications, as well as email end users, can use these mechanisms to provide a status of an email transmission, but these, if delivered, are notifications at the SMTP level. The application developer must fully understand the capabilities and limitations of these delivery notifications or risk assuming a data delivery when none occurred.

SMTP delivery status is separate from SOAP layer message processing. Resulting SOAP responses to the contained SOAP data will be processed through a new email message with no link to the original requesting email at the SMTP level. Example Q shows a SOAP message sent from the receiver to the originator acknowledging the alert in the body. In this example, the requesting email's Message-Id is carried within the SOAP envelope in a header block to enable message correlation. Again, how such correlation is achieved is not within the scope of SOAP.

From: SOAPResponder@example2.com
To: SOAPRequester@example.com
Subject: Alert Message
Date: Mon, 24 Sep 2001 16:02:11 CST
Message-Id: <200109251753.NAA10655@example2.com>

<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope"> 
 <env:Header>
  <m:message-id xmlns:m="http://example.com/mailhost">
     EE492E16A0B8D311AC490090276D208424960C0C@example.com
  </m:message-id>
  <n:alertcontrol xmlns:n="http://example.org/alertcontrol" 
          env:actor="http://www.w3.org/2001/09/soap-envelope/actor/next">
    <n:priority>1</n:priority>
    <n:expires>2001-06-22T14:00:00-05:00</n:expires>
  </n:alertcontrol>
 </env:Header>
 <env:Body>
  <m:alert xmlns:m="http://example.org/alert">
   <m:msg>O.K.</m:msg>
  </m:alert>
 </env:Body>
</env:Envelope>

3.4 Using other serialization schemes

While SOAP specifies a particular encoding scheme (see Part 2 section 4), the specification makes clear that other encoding schemes may be used for application-specific data within a SOAP message for which purpose it provides the encodingStyle attribute to qualify header and body blocks. The choice of the value for this attribute is an application-specific decision and the ability to interoperate is assumed to have been settled "out-of-band".

The encodingStyle attribute may also be associated with the overall SOAP message, as an attribute of the Envelope, in which case it signals a serialzation scheme for the nested contents or at least until another element is encountered which indictes another encoding style for its nested contents.

 EdNote: More to be provided.

4. Version transition from SOAP 1.1 to SOAP 1.2

4.1 Changes from SOAP 1.1 to SOAP 1.2

EdNote: This section will provide all the changes in SOAP 1.2 compared to SOAP 1.1 The list thus far includes:

• No trailers
• New Misunderstood header element
• Namespace changes
• <response> element for RPCs

4.2 Interworking between SOAP 1.1 and SOAP 1.2

EdNote: To be provided. Wonder what can be said here that has not been covered in Part 1 Appendix A.

5. References

A. Acknowledgements

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

Members of the Working Group are (at the time of writing, and by alphabetical order): Yasser al Safadi (Philips Research), Vidur Apparao (Netscape), Don Box (DevelopMentor), David Burdett (Commerce One), Charles Campbell (Informix Software), Alex Ceponkus (Bowstreet), Michael Champion (Software AG), David Clay (Oracle), Ugo Corda (Xerox), Paul Cotton (Microsoft Corporation), Ron Daniel (Interwoven), Glen Daniels (Allaire), Doug Davis (IBM), Ray Denenberg (Library of Congress), Paul Denning (MITRE Corporation), Frank DeRose (TIBCO Software, Inc.), Brian Eisenberg (Data Channel), David Ezell (Hewlett-Packard), James Falek (TIBCO Software, Inc.), David Fallside (IBM), Chris Ferris (Sun Microsystems), Daniela Florescu (Propel), Dan Frantz (BEA Systems), Dietmar Gaertner (Software AG), Scott Golubock (Epicentric), Rich Greenfield (Library of Congress), Martin Gudgin (Develop Mentor), Hugo Haas (W3C), Marc Hadley (Sun Microsystems), Mark Hale (Interwoven), Randy Hall (Intel), Gerd Hoelzing (SAP AG), Oisin Hurley (IONA Technologies), Yin-Leng Husband (Compaq), John Ibbotson (IBM), Ryuji Inoue (Matsushita Electric Industrial Co., Ltd.), Scott Isaacson (Novell, Inc.), Kazunori Iwasa (Fujitsu Software Corporation), Murali Janakiraman (Rogue Wave), Mario Jeckle (Daimler-Chrysler Research and Technology), Eric Jenkins (Engenia Software), Mark Jones (AT&T), Jay Kasi (Commerce One), Jeffrey Kay (Engenia Software), Richard Koo (Vitria Technology Inc.), Jacek Kopecky (IDOOX s.r.o.), Alan Kropp (Epicentric), Yves Lafon (W3C), Tony Lee (Vitria Technology Inc.), Michah Lerner (AT&T), Richard Martin (Active Data Exchange), Noah Mendelsohn (Lotus Development), Nilo Mitra (Ericsson Research Canada), Jean-Jacques Moreau (Canon), Masahiko Narita (Fujitsu Software Corporation), Mark Needleman (Data Research Associates), Eric Newcomer (IONA Technologies), Henrik Frystyk Nielsen (Microsoft Corporation), Mark Nottingham (Akamai Technologies), David Orchard (JamCracker), Kevin Perkins (Compaq), Jags Ramnaryan (BEA Systems), Andreas Riegg (Daimler-Chrysler Research and Technology), Hervé Ruellan (Canon), Marwan Sabbouh (MITRE Corporation), Shane Sesta (Active Data Exchange), Miroslav Simek (IDOOX s.r.o.), Simeon Simeonov (Allaire), Nick Smilonich (Unisys), Soumitro Tagore (Informix Software), James Tauber (Bowstreet), Lynne Thompson (Unisys), Patrick Thompson (Rogue Wave), Randy Waldrop (WebMethods), Ray Whitmer (Netscape), Volker Wiechers (SAP AG), Stuart Williams (Hewlett-Packard), Amr Yassin (Philips Research) and Dick Brooks (Group 8760).

Previous members were: Eric Fedok (Active Data Exchange) Susan Yee (Active Data Exchange) Alex Milowski (Lexica), Bill Anderson (Xerox), Ed Mooney (Sun Microsystems), Mary Holstege (Calico Commerce), Rekha Nagarajan (Calico Commerce), John Evdemon (XML Solutions), Kevin Mitchell (XML Solutions), Yan Xu (DataChannel) Mike Dierken (DataChannel) Julian Kumar (Epicentric) Miles Chaston (Epicentric) Bjoern Heckel (Epicentric) Dean Moses (Epicentric) Michael Freeman (Engenia Software) Jim Hughes (Fujitsu Software Corporation) Francisco Cubera (IBM), Murray Maloney (Commerce One), Krishna Sankar (Cisco), Steve Hole (MessagingDirect Ltd.) John-Paul Sicotte (MessagingDirect Ltd.) Vilhelm Rosenqvist (NCR) Lew Shannon (NCR) Henry Lowe (OMG) Jim Trezzo (Oracle) Peter Lecuyer (Progress Software) Andrew Eisenberg (Progress Software) David Cleary (Progress Software) George Scott (Tradia Inc.) Erin Hoffman (Tradia Inc.) Conleth O'Connell (Vignette) Waqar Sadiq (Vitria Technology Inc.) Tom Breuel (Xerox) David Webber (XMLGlobal Technologies) Matthew MacKenzie (XMLGlobal Technologies) and Mark Baker (Sun Microsystems).

The examples in this document are based on the SOAP/1.1 specification whose authors were: Don Box (Develop Mentor), David Ehnebuske (IBM), Gopal Kakivaya (Microsoft Corp.), Andrew Layman (Microsoft Corp.) Noah Mendelsohn (Lotus Development Corp.), Henrik Frystyk Nielsen (Microsoft Corp.), Satish Thatte (Microsoft Corp.) and Dave Winer (UserLand Software, Inc.).

We also wish to thank all the people who have contributed to discussions on xml-dist-app@w3.org.

B. Change Log