W3C

SOAP Version 1.2 Part 0: Primer

W3C Working Draft 17 December 2001

This version:
http://www.w3.org/TR/2001/WD-soap12-part0-20011217/
Latest version:
http://www.w3.org/TR/soap12-part0/
Editor:
Nilo Mitra (Ericsson)

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 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 first W3C Working Draft of the SOAP Version 1.2 Part 0: Primer 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 XML Protocol Activity.

For a detailed list of changes since the last draft of this document, please refer to Appendix B Change Log.

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
2. Basic Usage Scenarios
2.1 SOAP messages
2.2 SOAP processing model
2.3 SOAP message exchange
2.3.1 Document-style message exchange
2.3.2 Remote procedure call
2.4 Fault scenarios
3. Using various transport bindings
3.1 HTTP binding
3.2 SOAP over email
4. Advanced Usage Scenarios
4.1 Using SOAP intermediaries
4.2 Using other serialization schemes
5. Version transition from SOAP 1.1 to SOAP 1.2
5.1 Changes between SOAP 1.1 and SOAP 1.2
5.2 Interworking between SOAP 1.1 and SOAP 1.2
6. 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 SOAP Version 1.2 Part 1: Messaging Framework (hereafter Part 1) and SOAP Version 1.2 Part 2: Adjuncts (hereafter Part 2) of the SOAP version 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 how specifications of a binding of SOAP onto another underlying protocol may be written.

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 POST 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 SOAP message structures and message exchange patterns. In actual usage scenarios, SOAP will most likely be 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. Also, SOAP provides a full description of the expected actions taken by a SOAP processor on receiving a SOAP message.

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 various request-response type exchanges. Fault situations are also described.

Section 3 describes the ways in which SOAP messages may be transported to realise various usage scenarios.

Section 4 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, and using various encoding schemes to serialize SOAP and application-specific data.

Section 5 describes the changes from SOAP version 1.1 [11] and interworking between the two versions. EdNote: Readers of this primer who wish to see a synopsis of the principal changes between SOAP version 1.2 and 1.1 should consult section 5.1. The WG may decide at some future date to move the contents of this section to a non-normative W3C NOTE.

Section 6 provides references.

1.2 Notational Conventions

Throughout this primer, sample SOAP envelopes and messages are shown as XML 1.0 documents. Part 1 explains that SOAP messages are formally specified as XML Infosets [12], which is an abstract description of their contents. The distinction between the SOAP XML Infosets and the corresponding XML documents is unlikely to be of interest to those using this primer as an introduction to SOAP; those who do care (typically those who port SOAP to new transport bindings) should understand these examples as referring to the corresponding XML Infosets.

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/12/soap-envelope" and "http://www.w3.org/2001/12/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 [7, 8].

Note that the choice of any other 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 [3].

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

2. Basic Usage Scenarios

SOAP messages are fundamentally one-way transmissions between SOAP nodes, from a SOAP sender to a SOAP receiver, but SOAP messages are expected to be combined by applications to implement more complex interaction patterns ranging from request/response to multiple, back-and-forth "conversational" exchanges.

We start by exposing the structure of a SOAP message, and its exchange in some simple usage scenarios based on a travel reservation application. Various aspects of this application scenario will be used throughout the primer. In this application, an employee of a company fills out a travel reservation form with data related to a planned trip, which information is transferred in a SOAP message. The ultimate recipient of this information is a travel booking service, but it is possible that the SOAP message may be "routed" through one or more SOAP intermediaries which act in some way on the message. Some simple examples of such SOAP intermediaries might be ones that log, audit or, possibly, amend each travel request.

In section 2.1, we describe a travel reservation request expressed as a SOAP message, which offers the opportunity to describe the various "parts" of a SOAP message.

Having established the syntactical aspects of a SOAP message, we briefly digress in section 2.2 to provide an overview of the SOAP processing model.

In section 2.3.1 we return to our example to show a response from the travel service in the form of another SOAP message, which forms a part of a conversational message exchange as the various choices meeting the constraints of the travel request are negotiated.

In section 2.3.2, we assume that the various parameters of the travel reservation have been accepted by the traveller, and an exchange - modelled as a remote procedure call (RPC) - between the traveler and the travel service confirms various aspects of the reservation.

Section 2.4 shows examples of fault handling.

Examples and a more detailed discussion of the behaviour and role of SOAP intermediaries is postponed to section 4.

2.1 SOAP messages

Example 1 shows data for a travel reservation expressed in a SOAP message.

Example 1

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/12/soap-envelope"> 
 <env:Header>
  <m:reservation xmlns:m="http://travelcompany.example.org/reservation" 
          env:actor="http://www.w3.org/2001/12/soap-envelope/actor/next"
           env:mustUnderstand="true">
    <m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</reference>
    <m:dateAndTime>2001-11-29T13:20:00.000-05:00</m:dateAndTime>
  </m:reservation>
  <n:passenger xmlns:n="http://mycompany.example.com/employees"
          env:actor="http://www.w3.org/2001/12/soap-envelope/actor/next"
           env:mustUnderstand="true">
   <n:name>John Q. Public</n:name>
  </n:passenger>
 </env:Header>
 <env:Body>
  <p:itinerary xmlns:p="http://travelcompany.example.org/reservation/travel">
   <p:departure>
     <p:departing>New York</p:departing>
     <p:arriving>Los Angeles</p:arriving>
     <p:departureDate>2001-12-14</p:departureDate>
     <p:departureTime>late afternoon</p:departureTime>
     <p:seatPreference>aisle</p:seatPreference>
   </p:departure>
   <p:return>
     <p:departing>Los Angeles</p:departing>
     <p:arriving>New York</p:arriving>
     <p:departureDate>2001-12-20</p:departureDate>
     <p:departureTime>mid morning</p:departureTime>
     <p:seatPreference/>
   </p:return>
  </p:itinerary>
  <q:lodging xmlns:q="http://travelcompany.example.org/reservation/hotels">
   <q:preference>none</q:preference>
  </q:lodging>
 </env:Body>
</env:Envelope>

Sample SOAP message for a travel reservation containing header blocks and a body

The SOAP message contains two SOAP-specific sub-elements within the overall Envelope, namely a Header and a Body. The contents of these elements are application defined and not a part of the SOAP specifications, although the latter do have something to say about how such elements must be handled.

A header is optional, but we have chosen to included it in our example. Headers have been designed in anticipation of various uses for SOAP, many of which will involve the participation of other SOAP processing nodes along a message's path from a sender to an ultimate receiver, to allow SOAP processors to exchange information to provide value-added services. These form the mechanism by which SOAP messages may be extended in an application-specific manner.

The Body is the mandatory element within an Envelope, which seems to imply that this is where the main information conveyed in a SOAP message must be carried. The immediate child elements of a Header are called header blocks, and represent some logical grouping of data which, as we shall see, can be targeted at SOAP nodes encountered in the path of a message from a sender to a receiver.

A pictorial representation of the SOAP message in Example 1 is as follows.

Figure 1: SOAP Message structure

In Example 1, the header contains two header blocks, each of which is defined in its own namespace and which represent some aspect pertaining to the overall processing of the body of the SOAP message. For this travel reservation application, such "meta" information pertaining to the overall request is a reservation header block which provides a reference and time stamp for this instance of a reservation, and the traveller's identity in the passenger block.

The header blocks reservation and passenger 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 the next SOAP node encountered en route is indicated by the presence of the attribute actor with value "next", which is a role that all SOAP nodes must be willing to play, while the presence of the mustUnderstand attribute with value "true" indicates that the nodes in question must act upon the information in a manner consistent with the specifications of these header blocks. Such specifications are not a part of SOAP.

The choice of what data is placed in a header block and what goes in the SOAP body are decisions taken at the time of application design. The main point is that header blocks may be targetted at various nodes that might be encountered along a message's path from a sender to the ultimate recipient. Such intermediate SOAP nodes may provide value-added services based on data in such headers. In Example 1, the passenger data is placed in a header block because in our design we might wish to use this data at a SOAP intermediary to do some additional processing - for example, as shown later in Section 4.1, the outgoing message is altered by the SOAP intermediary by having the travel policies pertaining to this employee appended to the message.

The Body element and its associated child elements, itinerary and lodging, are intended for exchange of information between the initial SOAP sender and the SOAP processor which assumes the role of the ultimate SOAP receiver in the message path, which in our case is the travel reservation service. Therefore, the Body and its contents is implicitly targeted and is expected to 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.

A SOAP message such as that in Example 1 may be transferred by different underlying protocols and used in a variety of message exchange patterns. For example, with a Web-based access to a travel service, it could be placed in the body of a HTTP POST request. In another transport binding, it can be sent in an email message (see section 3.2). Section 3 will describe how SOAP messages may be conveyed by a variety of transports. For the time being, we will assume that a mechanism exists for message transfer and concentrate on the details of the messages and their processing.

2.2 SOAP processing model

Having established the various syntactical aspects of a SOAP message, we briefly digress to provide a general overview of the SOAP processing model (specified in Part 1, Section 2).

Example 1bis shows a snippet from a SOAP message with several header blocks. This will be used in the remainder of this section to illustrate various aspects of the processing model.

Example 1bis
<?xml version="1.0" ?>
 <env:Envelope xmlns:env="http://www.w3.org/2001/12/soap-envelope">
   <env:Header>
     <p:oneBlock xmlns:p="http://example.com" env:actor="http://example.com/Log">
     ::::
     </p:oneBlock>
     <q:anotherBlock xmlns:q="http://example.com"
           env:actor="http://www.w3.org/2001/12/soap-envelope/actor/next">
     ::::
     </q:anotherBlock>
     <r:aThirdBlock xmlns:r="http://example.com">
     ::::
     </r:aThirdBlock>
   </env:Header>
   <env:Body >
     ::::
   </env:Body>
 </env:Envelope>
Snippet from a SOAP message showing a variety of header blocks

The SOAP processing model 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 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 subject to the qualifications on the use of certain XML constructs as defined in Part 1, section 3.

Further processing of header blocks and the body depend on the role assumed by the SOAP processor for the processing of a given message instance. SOAP defines an actor attribute - syntactically, anyURI - that may be present in a header element, which defines the role played by the intended target of that header. A SOAP processor is expected to process a header block if it assumes the role identified by the value in the URI. Three standardized actor roles have been defined (see Part 1, section 4.2.2), which are "none", "next" and "anonymous".

In Example 1bis, the header block oneBlock is targeted at any SOAP processor that plays the role defined by the URI http://example.com/Log. For purposes of illustration, we assume that the specification for such a header block requires that any SOAP processor adopting this role log the entire message.

Every SOAP processor receiving a message with a header block that has an actor attribute of "next" must process the contents of the element, as this is a standardized role that every SOAP processor must be willing to assume. Header elements thus attributed are those which are expected to be examined and (possibly) processed by the next SOAP processor along the path of a message, assuming that such a header has not been removed as a result of processing at some node earlier in the message path. In the above example, the header block anotherBlock is targeted at the next node in the message path. In Example 1bis, the SOAP message received by the node playing the role of the "http://example.com/Log", must also be willing to play the role of "next". This is also true for the node which is the ultimate recipient of the message, as it also is the "next" actor.

The thrid header block, yetAnotherBlock, in Example 1bis does not have the actor attribute. It is targeted at a SOAP processor which assumes the "anonymous" role. The "anonymous" actor role (which is implicit in that it is not specified by a URI, and is denoted by the absence of the actor attribute in a header block) 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.

Note that the Body element does not have an actor attribute. The body element is always targeted at the SOAP processor that assumes the "anonymous" actor 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 (typically at SOAP intermediaries) 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. SOAP defines a special Body block to convey such fault information. Section 2.4 will provide examples of this.

If a header element has the standardized 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.

Example 1ter augments the previous example by introducing another attribute for header blocks, the mustUnderstand attribute.

Example 1ter
<?xml version="1.0" ?>
 <env:Envelope xmlns:env="http://www.w3.org/2001/12/soap-envelope">
   <env:Header>
     <p:oneBlock xmlns:p="http://example.com" 
           env:actor="http://example.com/Log" env:mustUnderstand="true">
     ::::
     </p:oneBlock>
     <q:anotherBlock xmlns:q="http://example.com"
           env:actor="http://www.w3.org/2001/12/soap-envelope/actor/next">
     ::::
     </q:anotherBlock>
     <r:aThirdBlock xmlns:r="http://example.com">
     ::::
     </r:aThirdBlock>
   </env:Header>
   <env:Body >
     ::::
   </env:Body>
 </env:Envelope>
Snippet from a SOAP message showing a variety of header blocks, one of which is mandatory for processing

After a SOAP processor has correctly identified the header blocks (and possibly the body) targeted at itself using the actor attribute, the additional attribute, mustUnderstand, in the header elements determines further processing actions that have to be taken. 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. (Keep in mind that the specifications of header blocks are not a part of the SOAP specifications.)

In Example 1ter, the header block oneBlock is marked with a mustUnderstand value set to "true", which means that it is mandatory to process this block if the SOAP node plays the role of the actor identified by "http://example.com/log". The other two header blocks are not so marked, which means that SOAP processor at which these blocks are targeted need not process them.

A mustUnderstand value of "true" means that the SOAP processor must process the header with the semantics described in that header's specification, or generate a fault. 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.

The Body element has no such attribute but it must be processed by the ultimate recipient. In Example 1ter, the ultimate recipient of the message - the SOAP processor which plays the "anonymous" actor role - must process both the Body as well as the header blockk aThirdBlock. It may process the header block anotherBlock, as it is targeted at itself (in the role of "next") but it is not mandatory to do so if the specifications for processing the blocks do not demand it.

The role(s) a SOAP node plays when processing a SOAP message can be determined by many factors. The role could be known a priori, set by some out-of-band means, or a node can inspect all parts of a received message to determine which roles it will assume before processing the message. An interesting case arises when a SOAP node, during the course of processing a message, decides that there are additional roles that it needs to adopt. No matter when this determination is made, externally it must appear as though the processing model has been adhered to. That is, it must appear as though the role had been known from the start of the processing of the message. In particular, the external appearance must be that the mustUnderstand checking of any headers with those additional actor roles assumed was performed before any processing began. Also, if a SOAP processor assumes such additional roles, it must ensure that it is prepared to do everything that the specifications for those roles require.

As a result of processing a SOAP message, a SOAP processor may generate SOAP faults if it fails to process a message, or, depending on the application, generate additional SOAP messages for consumption at other SOAP processors. A SOAP fault is a SOAP message with a standardized 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.

Part 1 of the SOAP specifications describes the structure of the fault message and the conditions under which it is generated. However, whether a fault can be propagated appropriately depends on the transport binding chosen for message exchange. The specification does not define what happens if faults are generated during the propagation of one-way messages. The other normative binding, which is the HTTP binding, offers the HTTP response as a means for reporting a fault in the request.

Examples of fault handling are provided in section 2.4.

2.3 SOAP message exchange

SOAP version 1.2 is a simple messaging framework for transferring information in the form of XML documents between a SOAP sender and receiver. The more interesting scenarios typically involve multiple message exchanges. The simplest such exchange is a request-response pattern. Not all request-response exchanges can or need to be modelled as RPCs. The latter is used when there is a need to model a certain programmatic behavior, with the exchanged messages conforming to a well-defined signature for the remote call and its return. A much larger set of request-response exchanges can be modeled simply as documents exchanged, where the semantics are at the level of the sending and receiving applications. Section 2.3.1 covers the latter case, while section 2.3.2 provides an example of an exchange modeled as a RPC.

2.3.1 Document style message exchange

Continuing with the travel request application scenario, Example 2 shows a SOAP message returned from the travel service in response to the reservation request message in Example 1. This response seeks to refine some information in the request, namely the choice of airports in the departing city.

Example 2

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/12/soap-envelope"> 
 <env:Header>
  <m:reservation xmlns:m="http://travelcompany.example.org/reservation" 
          env:actor="http://www.w3.org/2001/12/soap-envelope/actor/next"
           env:mustUnderstand="true">
    <m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</reference>
    <m:dateAndTime>2001-11-29T13:35:00.000-05:00</m:dateAndTime>
  </m:reservation>
  <n:passenger xmlns:n="http://mycompany.example.com/employees"
          env:actor="http://www.w3.org/2001/12/soap-envelope/actor/next"
           env:mustUnderstand="true">
   <n:name>John Q. Public</n:name>
  </n:passenger>
 </env:Header>
 <env:Body>
  <p:itinerary xmlns:p="http://travelcompany.example.org/reservation/travel">
   <p:airportChoices>
     JFK LGA EWR 
   </p:airportChoices>
  </p:itinerary>
 </env:Body>
</env:Envelope>

SOAP Message sent in response to the message in Example 1

As described earlier, the Body contains the primary content of the message, which in this example includes a list of the various alternatives for the airport, conforming to a schema definition in the namespace http://travelcompany.example.org/reservation/travel. In this example, the header blocks from Example 1 are returned (with some sub-element values altered) in the response. This could allow message correlation at the SOAP level, but such headers are very likely to also have other application-specific uses.

The message exchange in Examples 1 and 2 are cases where XML documents conforming to some application-defined schema are exchanged via SOAP messages. Once again, we defer the means by which such messages are transferred.

It is easy enough to see how such exchanges can build up to a "conversational" message exchange pattern. Example 3 shows a SOAP message sent by the traveller in response to that in Example 2 choosing one from the list of airports available. The header block reference with the same value of some of the sub-elements accompanies each message in this conversation, thereby allowing a correlation between them at the application level.

Example 3

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/12/soap-envelope"> 
 <env:Header>
  <m:reservation xmlns:m="http://travelcompany.example.org/reservation" 
          env:actor="http://www.w3.org/2001/12/soap-envelope/actor/next"
           env:mustUnderstand="true">
    <m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</reference>
    <m:dateAndTime>2001-11-29T13:36:50.000-05:00</m:dateAndTime>
  </m:reservation>
  <n:passenger xmlns:n="http://mycompany.example.com/employees"
          env:actor="http://www.w3.org/2001/12/soap-envelope/actor/next"
           env:mustUnderstand="true">
   <n:name>John Q. Public</n:name>
  </n:passenger>
 </env:Header>
 <env:Body>
  <p:itinerary xmlns:p="http://travelcompany.example.org/reservation/travel">
   <p:departure>
     <p:departing>LGA</p:departing>
   </p:departure>
   <p:return>
     <p:arriving>EWR</p:arriving>
   </p:return>
  </p:itinerary>
 </env:Body>
</env:Envelope>

Response to the message in Example 2 continuing a conversational message exchange

2.3.2 Remote procedure call

One of the design goals of SOAP is to encapsulate remote procedure call functionality using the extensibility and flexibility of XML. Part 2 section 4 of the SOAP specification has defined a uniform representation for RPC invocations and responses. In this section, we continue with our travel reservation service example to illustrate the use of SOAP messages to convey remote procedure calls and their return.

The scenario we have in mind is the charging for the trip using a credit card. We assume that this happens in the context of an overall transaction where the credit card is charged only when the travel and the lodging are both confirmed. The traveler provides credit card information and the successful completion of the different activities results in the card being charged and a reservation code returned. This reserve-and-charge interaction between the traveller and the travel service is modeled as a RPC.

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

SOAP does not provide any interface definition language, formal or informal.

For use with SOAP, there is an intended recipient which is the target of the procedure. It is the SOAP node which chooses to adopt the "anonymous" role. Once a node adopts this role, it is the ultimate recipient. The ultimate recipient can identify the "service" which supports the named procedure or method by looking for an URI. One possiblity is that such a URI identifying the target is carried in a SOAP header block. Some protocol bindings, such as HTTP, offer a mechanism for carrying the URI. In general, if a protocol binding specification offers a request-response message exchange pattern, then one of the properties of the specification must be a description of how the target URI is carried in the binding.

We defer until section 3 the discussion of how the URI is carried in HTTP, concentrating here on the SOAP and RPC-specific aspects. For the present, we assume that the RPC shown in Example 4 is appropriately targeted and dispatched.

Example 4

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/12/soap-envelope" >
 <env:Header>
   <m:reservation xmlns:m="http://travelcompany.example.org/reservation" 
          env:actor="http://www.w3.org/2001/12/soap-envelope/actor/next"
           env:mustUnderstand="true">
    <m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</reference>
    <m:dateAndTime>2001-11-29T13:36:50.000-05:00</m:dateAndTime>
   </m:reservation>
   <t:transaction
           xmlns:t="http://thirdparty.example.org/transaction"
           env:encodingStyle="http://example.com/encoding"
           env:mustUnderstand="true" >
               5
   </t:transaction>
 </env:Header>  
 <env:Body>
    <m:reserveAndCharge 
        env:encodingStyle="http://www.w3.org/2001/12/soap-encoding"
             xmlns:m="http://travelcompany.example.org/" >
      <n:name xmlns:n="http://mycompany.example.com/employees">
           John Q. Public
      </n:name>
        <o:creditCard xmlns:o="http://mycompany.example.com/financial">
           <o:number>123456789099999</o:number>
           <o:expiration>2005-02</o:expiration>
         </o:creditCard>
       </m:reserveAndCharge>
  </env:Body>
</env:Envelope>

SOAP RPC request with a mandatory header and two in parameters

The RPC itself is carried as a part of the Body element, and is modelled as a struct which takes the name of the procedure or method, in this case reserveAndCharge. It has been designed to take two input parameters, the name of the credit card holder and the creditCard information. The latter is also a struct, which takes two elements, the card number and an expiration date.

In this example, the encodingStyle attribute with a value in the SOAP encoding namespace shows that the contents of the reserveAndCharge structure have been serialized according to the particular rules defined in Part 2 section 4 of the SOAP specifications. While SOAP specifies this particular encoding scheme, 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 sub-elements. The choice of the value for this attribute is an application-specific decision and the ability of a caller and callee to interoperate is assumed to have been settled "out-of-band". Section 4.2 shows examples of using other serialization schemes.

RPCs may also require additional information to be carried, which can be important for the processing of the call in a distributed environment, but which are not a part of the formal procedure or method signature. In our example, the RPC is carried out in the context of an overall transaction which involves several activities which must all complete successfully before the RPC returns. Example 4 shows how a header element transaction directed at the ultimate recipient (implied by the absence of the actor attribute) can be used to carry such information.

The procedure in our charging example has been designed to return two parameters, one providing a confirmation number for the reservation and the other an URL where the details of the reservation may be viewed. The RPC response is returned in the Body element of a SOAP message, with is modelled as a struct taking the procedure name and the word "Response" appended. This is shown in Example 5, where the header again identifies the transaction within which this RPC was performed.

Example 5

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/12/soap-envelope" >
 <env:Header>
       <t:transaction
           xmlns:t="http://thirdparty.example.org/transaction"
           env:encodingStyle="http://example.com/encoding"
           env:mustUnderstand="true" >
               5
       </t:transaction>
 </env:Header>  
 <env:Body>
       <m:reserveAndChargeResponse 
             env:encodingStyle="http://www.w3.org/2001/12/soap-encoding"
             xmlns:m="http://travelcompany.example.org/" >
           <m:confirmation>
               <reference>FT35ZBQ</reference>
               <viewAt>
               http://travelcompany.example.org/reservations?code=FT35ZBQ
               </viewAt>
           </m:confirmation>
       </m:reserveAndChargeResponse>
   </env:Body>
</env:Envelope>

RPC response to the call shown in Example 4

While, in principle, using SOAP for RPC is independent of the decision to use a particular means for transferring the RPC call and its return, certain transport bindings that support a request-response message exchange pattern may be more naturally suited for such purposes. A transport binding supportinga request-response pattern can provide the correlation between a request and a response. Of course, the designer of a RPC-based application could choose to put a correlation ID relating a call and its return in a SOAP header, thereby making the RPC inependent of any underlying transport. In any case, 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 - and standardized - 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. Section 3.1 provides examples of HTTP bindings. However, while most examples of SOAP for RPC use the HTTP protocol binding, it is not limited to that means alone.

2.4 Fault scenarios

SOAP provides a model for handling situations where faults arise in the processing of a message. The SOAP Body element has another distinguished role in that it is the place where fault information is placed. The SOAP fault model (see Part 1, section 4.4) requires that all SOAP-specific and application-specific faults be reported using a single distinguished element, Fault, carried within the Body element. The Fault element contains a standardized faultcode and faultstring sub-elements and (optionally) application-specific information in the Details sub-element within the Fault. Another optional sub-element faultactor identifies the SOAP processor which generated the fault, its absence implying that it was the unlimate recipient of the message which did so.

Example 6 shows a SOAP message returned in response to the RPC request in Example 5 indicating a failure to process the SOAP message.

Example 6

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/12/soap-envelope"
            xmlns:f='http://www.w3.org/2001/12/soap-faults'>
  <env:Body>
    <env:Fault>
      <faultcode>env:Receiver</faultcode>
      <faultstring>Processing Error</faultstring>
      <detail>
        <e:myfaultdetails xmlns:e="http://travelcompany.example.org/faults" >
          <message>Name does not match card number</message>
          <errorcode>999</errorcode>
        </e:myfaultdetails>
      </detail>
    </env:Fault>
 </env:Body>
</env:Envelope>

Sample SOAP message indicating failure to process the SOAP Body in Example 4

The faultcode indicates that it is a Receiver fault, and therefore not related to any syntactical error in the message (which would have been a Sender fault). The faultstring sub-element is not meant for algorithmic processing, but rather for human understanding; so, even though this is a mandatory item, the chosen value need not be standardized. So all that is required is that it reasonably accurately describe the fault situation. The absence of a faultactor element implies that it is generated by the origin server. The detail entries are application-specific.

During the processing of a SOAP message, a fault may also be generated if a mandatory header element is not understood or the information contained there cannot be processed. Errors in processing a Header element is also signalled using a Fault element within the Body, but the detail sub-element is not used, and a particular distinguised header element, Misunderstood, in the SOAP faults namespace, identifies the offending header.

Example 7 shows an example of a response to the RPC in Example 4 indicating a failure to process the reservation header block. Note the presence of the MustUnderstand fault code in the Body, and the identification of the header not understood via a qname attribute in the special (empty) header block Misunderstood.

Example 7

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/12/soap-envelope"
            xmlns:f='http://www.w3.org/2001/12/soap-faults'>
 <env:Header>
    <f:Misunderstood qname='m:reservation'
                           xmlns:m="http://travelcompany.example.org/reservation"  />
 </env:Header>  
 <env:Body>
    <env:Fault>
      <faultcode>env:MustUnderstand</faultcode>
      <faultstring>Header not understood</faultstring>
    </env:Fault>
 </env:Body>
</env:Envelope>

Sample SOAP message indicating failure to process the SOAP Body in Example 4

If there were several mandatory headers that were not understood, then each would be identified by its qname attribute in a series of such Misunderstood sub-elements.

3. Using various transport bindings

SOAP messages may be exchanged using a variety of "underlying" protocols, including other application layer protocols. The specification 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 SOAP header block.

EdNote: A future draft will align with and provide further explanatory text and examples relating to the Transport Binding Framework defined in the latest WD of Part 1.

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, respectively those to HTTP and email. It should be emphasized again that the only normative binding for SOAP 1.2 messages is to HTTP. The example in section 3.2 showing email as a transport mechanism for SOAP is simply meant to suggest that other choices are possible, although not standardized at this time.

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.

The normative SOAP/HTTP binding specification in Part 2 only defines the use of the HTTP POST method for conveying SOAP messages in HTTP requests.

HTTP allows for multiple 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. Note, however, that HTTP intermediaries are distinct from SOAP intermediaries.

Examples 8 and 9 show an example of a HTTP binding, using the same scenario as that for Example 4 and Example 5, respectively, namely conveying a RPC in the body of a SOAP message. Here we concentrate on the HTTP headers and their role.

When using HTTP, the request URI indicates the resource to which the invocation is "posted". Other than it be a valid URI, SOAP places no restriction on the form of an address (see [3] for more information on URIs).

 Example 8 shows a RPC request directed at the charging application at the travel service available at the URI "http://travelcompany.example.org/Charging". The SOAP message (details elided) is sent in the body of a HTTP POST method directed at the above-mentioned URI. When placing SOAP messages in HTTP bodies, the HTTP Content-type header must be chosen as "application/soap".

Example 8

POST /Charging HTTP/1.1
Host: travelcompany.example.org
Content-Type: application/soap; charset="utf-8"
Content-Length: nnnn

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

RPC in Example 4 carried in an HTTP POST Request

Example 9 shows the RPC return sent by the travel service in the corresponding HTTP response to the request from Example 5. SOAP using HTTP transport follows the semantics of the HTTP status codes for communicating status information in HTTP. For example, the 2xx series of HTTP status codes indicate that the client's request (including the SOAP component) was successfully received, understood, and accepted etc.

Example 9

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

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

RPC return in Example 5 embedded in an HTTP Response indicating a successful completion

If an error occurs while processing the request, the HTTP binding specification requires that a HTTP 500 "Internal Server Error" be used with an embedded SOAP message containing a SOAP fault indicating the server-side processing error.

Example 10 is the same scenario as Example 6, but with the HTTP headers added.

Example 10

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

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/12/soap-envelope">
  <env:Body>
    <env:Fault>
      <faultcode>env:Receiver</faultcode>
      <faultstring>Processing Error</faultstring>
      <detail>
        <e:myfaultdetails xmlns:e="http://travelcompany.example.org/faults" >
          <message>Name does not match card number</message>
          <errorcode>999</errorcode>
        </e:myfaultdetails>
      </detail>
    </env:Fault>
 </env:Body>
</env:Envelope>

Sample SOAP message in a HTTP Response indicating failure to handle the SOAP Body in Example 4

EdNote: More examples will be provided in a future draft showing some 2xx vs 5xx cases.

3.2 SOAP over email

Application developers can use the Internet email infrastructure to move SOAP messages as either email text or attachments. The examples shown below offer one way to carry SOAP messages, and should not be construed as being the standard way of doing so. The SOAP version 1.2 specifications do not specify such a binding.

Example 11 shows the travel reservation request message from Example 1 carried as an email message between a sending and receiving mail 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.

Example 11

From: john.public@mycompany.example.com
To: reservations@travelcompany.example.org
Subject: Travel to LA
Date: Thu, 29 Nov 2001 13:20:00 EST
Message-Id: <EE492E16A0B8D311AC490090276D208424960C0C@mycompany.example.com> 

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/12/soap-envelope"> 
 <env:Header>
  <m:reservation xmlns:m="http://travelcompany.example.org/reservation" 
          env:actor="http://www.w3.org/2001/12/soap-envelope/actor/next"
           env:mustUnderstand="true">
    <m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</reference>
    <m:dateAndTime>2001-11-29T13:20:00.000-05:00</m:dateAndTime>
  </m:reservation>
  <n:passenger xmlns:n="http://mycompany.example.com/employees"
          env:actor="http://www.w3.org/2001/12/soap-envelope/actor/next"
           env:mustUnderstand="true">
   <n:name>John Q. Public</n:name>
  </n:passenger>
 </env:Header>
 <env:Body>
  <p:itinerary xmlns:p="http://travelcompany.example.org/reservation/travel">
   <p:departure>
     <p:departing>New York</p:departing>
     <p:arriving>Los Angeles</p:arriving>
     <p:departureDate>2001-12-14</p:departureDate>
     <p:departureTime>late afternoon</p:departureTime>
     <p:seatPreference>aisle</p:seatPreference>
   </p:departure>
   <p:return>
     <p:departing>Los Angeles</p:departing>
     <p:arriving>New York</p:arriving>
     <p:departureDate>2001-12-20</p:departureDate>
     <p:departureTime>mid morning</p:departureTime>
     <p:seatPreference/>
   </p:return>
  </p:itinerary>
  <q:lodging xmlns:q="http://travelcompany.example.org/reservation/hotels">
   <q:preference>none</q:preference>
  </q:lodging>
 </env:Body>
</env:Envelope>

SOAP message from Example 1 carried in a SMTP message

The header in Example 11 is in the standard form [RFC 2822] for email messages.

While an email is a one-way message exchange, and no guarantee of delivery is provided, email infrastructures like the Simple Mail Transport Protocol (SMTP) specification [9] offer a delivery notification mechanism which, in the case of SMTP, 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 messages separate from message processing at the SOAP layer. 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. The use of the RFC 2822

Example 12 is exactly the same scenario as described for Example 2, which shows the SOAP message (body details elided for brevity) sent from the travel service to the passenger, only it is carried as an email message. In this example, the original email's Message-Id is carried in the additional email header In-reply-to:, which correlates email messages at the SMTP level, but cannot provide a SOAP-specific correlation. In this example, the application relies on the reservation block to correlate messages. Again, how such correlation is achieved are functions of how such applications are designed, and is not within the scope of SOAP.

Example 12

From: reservations@travelcompany.example.org
To: john.public@mycompany.example.com
Subject: Which NY airport?
Date: Thu, 29 Nov 2001 13:35:11 EST
Message-Id: <200109251753.NAA10655@travelcompany.example.org>
In-reply-to:<EE492E16A0B8D311AC490090276D208424960C0C@mycompany.example.com>

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/12/soap-envelope"> 
 <env:Header>
    <m:reservation xmlns:m="http://travelcompany.example.org/reservation" 
          env:actor="http://www.w3.org/2001/12/soap-envelope/actor/next"
           env:mustUnderstand="true">
    <m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</reference>
    <m:dateAndTime>2001-11-29T13:35:00.000-05:00</m:dateAndTime>
  </m:reservation>
  <n:passenger xmlns:n="http://mycompany.example.com/employees"
          env:actor="http://www.w3.org/2001/12/soap-envelope/actor/next"
           env:mustUnderstand="true">
   <n:name>John Q. Public</n:name>
  </n:passenger>
 </env:Header>
 <env:Body>
  <p:itinerary xmlns:p="http://travelcompany.example.org/reservation/travel">
   <p:airportChoices>
      :::::
   </p:airportChoices>
  </p:itinerary>
 </env:Body>
</env:Envelope>

SOAP message from Example 2 carried in an email message with a header correlating it to a previous message.

4. Advanced usage scenarios

4.1 Using SOAP intermediaries

Our application scenario offers us an opportunity to expose some uses of SOAP intermediaries. Recall that the basic exchange was the exchange of a travel reservation request between an employee and a travel service. SOAP does not specify how such a message path is determined and followed. That is outside the scope of the SOAP specification. It does describe, though, how a SOAP node should behave if it receives a SOAP message for which it may not be the ultimate recipient.

In the following example, we introduce a SOAP node in the request path, which intercepts the message shown in Example 1. One example of such a node could be a corporate travel office which logs all travel requests. Note that the header blocks reservation and passenger in that example are addressed to the actor "next", which means that it is intended for the next SOAP node that receives the message. The header blocks are mandatory (the mustUnderstandattribute is set to "true"), which means that the node must have knowledge (through an external specification of the header blocks' semantics) of what to do. A logging specification for such header blocks might simply require that various details of the message be recorded at every node that receives such a message, and that the message be relayed along the message path unchanged.

A more complex scenario is one where the SOAP message is amended in some way. In the following example, we assume that the corporate travel application attaches a header block to the SOAP message before relaying it along its message path towards the travel service - the ultimate recipient. The specification of such a header block might require that the ultimate recipient (and only the ultimate recipient, as implied by the absence of the actor attribute) make use of the information conveyed by it when processing the body of the message.

Example 13 shows an intermediary adding an additional header block, travelPolicy, intended for the ultimate recipient which includes information that qualifies the processing of any travel request.

Example 13

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/12/soap-envelope"> 
 <env:Header>
  <m:reservation xmlns:m="http://travelcompany.example.org/reservation" 
          env:actor="http://www.w3.org/2001/12/soap-envelope/actor/next"
           env:mustUnderstand="true">
    <m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</reference>
    <m:dateAndTime>2001-11-29T13:20:00.000-05:00</m:dateAndTime>
  </m:reservation>
  <n:passenger xmlns:n="http://mycompany.example.com/employees"
          env:actor="http://www.w3.org/2001/12/soap-envelope/actor/next"
           env:mustUnderstand="true">
   <n:name>John Q. Public</n:name>
  </n:passenger>
  <z:travelPolicy xmlns:z="http://mycompany.example.com/policies" env:mustUnderstand="true">
   <z:class>economy</z:class>
   <z:fareBasis>non-refundable<z:fareBasis>
   <z:exceptions>none</z:exceptions>
  </z:travelPolicy>
 </env:Header>
 <env:Body>
  <p:itinerary xmlns:p="http://travelcompany.example.org/reservation/travel">
   <p:departure>
     <p:departing>New York</p:departing>
     <p:arriving>Los Angeles</p:arriving>
     <p:departureDate>2001-12-14</p:departureDate>
     <p:departureTime>late afternoon</p:departureTime>
     <p:seatPreference>aisle</p:seatPreference>
   </p:departure>
   <p:return>
     <p:departing>Los Angeles</p:departing>
     <p:arriving>New York</p:arriving>
     <p:departureDate>2001-12-20</p:departureDate>
     <p:departureTime>mid morning</p:departureTime>
     <p:seatPreference/>
   </p:return>
  </p:itinerary>
  <q:lodging xmlns:q="http://travelcompany.example.org/reservation/hotels">
   <q:preference>none</q:preference>
  </q:lodging>
 </env:Body>
</env:Envelope>

SOAP message from Example 1 for a travel reservation after an intermediary has inserted a mandatory header intended for the ultimate recipient of the message

4.2 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 elements and their contents. 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 in the next draft. Suggestions include an XMI and/or an RDF encoding.

5. Version transition from SOAP 1.1 to SOAP 1.2

EdNote:The contents of sections 5.1 and 5.2 may be moved at some future date to a non-normative W3C NOTE. It is also possible that section 5.2 may be deleted from such a document. The WG has not taken any decision on these. In the interests of developing the contents of section 5.1 further, independently of its eventual home, reviewers of this document are urged to provide further instances of changes between the two SOAP versions.

5.1 Changes from SOAP 1.1 to SOAP 1.2

SOAP version 1.2 has a few changes in syntax from that of SOAP 1.1 [11]. The following is a list of features where the two specifications differ. The purpose of this list is to provide the reader with a quick and easily accessible summary of the differences between the two specifications.

5.2 Interworking between SOAP 1.1 and SOAP 1.2

EdNote: This section will be removed from the primer in a future draft.

6. References

[1] W3C Working Draft "SOAP 1.2 Part 1: Messaging Framework", Martin Gudgin, Marc Hadley, Jean-Jacques Moreau, Henrik Frystyk Nielsen, 2 October 2001 (See http://www.w3.org/TR/2001/WD-soap12-part1-20011217.)

[2] W3C Working Draft "SOAP 1.2 Part 2: Adjuncts", Martin Gudgin, Marc Hadley, Jean-Jacques Moreau, Henrik Frystyk Nielsen, 2 October 2001 (See http://www.w3.org/TR/2001/WD-soap12-part2-20011217.)

[3] IETF "RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax", T. Berners-Lee, R. Fielding, L. Masinter, August 1998. Available at http://www.ietf.org/rfc/rfc2396.txt

[4] IETF "RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1", R. Fielding, J. Gettys, J. C. Mogul, H. Frystyk, T. Berners-Lee, January 1997. Available at http://www.ietf.org/rfc/rfc2616.txt

[5] W3C Recommendation "Extensible Markup Language (XML) 1.0 (Second Edition)", Tim Bray, Jean Paoli, C. M. Sperberg-McQueen, Eve Maler, 6 October 2000. Available at http://www.w3.org/TR/2000/REC-xml-20001006

[6] W3C Recommendation "Namespaces in XML", Tim Bray, Dave Hollander, Andrew Layman, 14 January 1999. Available at http://www.w3.org/TR/1999/REC-xml-names-19990114/

[7] W3C Recommendation "XML Schema Part 1: Structures", Henry S. Thompson, David Beech, Murray Maloney, Noah Mendelsohn, 2 May 2001. Available at http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/

[8] W3C Recommendation "XML Schema Part 2: Datatypes", Paul V. Biron, Ashok Malhotra, 2 May 2001. Available at http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/

[9] SMTP is defined in a series of RFCs:

[10] http://www.w3.org/TR/2001/WD-xmlp-reqs-20010319/#N673

[11] W3C Note "Simple Object Access Protocol (SOAP) 1.1", Don Box et al, 8 May, 2000 (available at http://www.w3c.org/TR/SOAP/)

[12] W3C Recommendation "XML Information Set", John Cowan, Richard Tobin, 24 October 2001. (See http://www.w3.org/TR/xml-infoset/.)

A. Acknowledgements

Highland Mary Mountain (Intel) provided the initial material for the section on the SMTP binding. Paul Denning provided material for a usage scenario, which has been moved to the Usage Scenarios WD.

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

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

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

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

B. Change Log

Date Author Description
11/12/01 NM Comments from Chris Ferris incorporated plus some general cleanup of Acknowledgements (copied from Part 1, References and Status sections. Moved contents of sec.1.2, 1.3 elsewhere to provide gradual intro.
11/12/01 NM Replaced examples taken from Parts 1, 2 with new examples throughout (more non-RPC) per WG request
11/13/01 NM Moved PD contribution to new appendix C; derived new example for intermediaries. Altered table of contents to make transport bindings 1st level header..
11/14/01 NM Added text for intermediaries. Added figure. Added text on differencess between v1.1 & 1.2
11/15/01 NM Checked links
11/16/01 NM General cleanup.
11/30/01 NM Changed to W3C-WD.css; updated status section based on parts 1,2 text; changed links in "This version:", "Latest version:" and "Previous version:"
11/30/01 NM Added text in sections 1.1.and 4 on the likelihood of section 4 moving to a W3C NOTE eventually (as agreed at F2F).
11/30/01 NM Removed Appendix C (moved to Usage Scenarios WD)
12/3/01 NM Added suggested text from Noah M in section 1.2 + reference to Infoset Rec. Added <? xml...?> consistently throughout, per Jean-Jacques M (JJM) comment.
12/3/01 NM Changed Sec 3.2 from SMTP to email per discussions at F2F and further wordsmithing with Jacek K. Added cautionary note in section 3 about email binding not being standardized.
12/3/01 NM Added text in section 2.1 to motivate what goes in a header vs. body per handwritten comments from SW and JJM (look here).
12/3/01 NM Additional text to cover JJM's third bullet point (reference) on motivating document style vs. RPC has been put at the start of section 2.3.1 (rather than in sec 2.1 as suggested).
12/3/01 NM Corrected use of "next" attribute value in section 2.2 per comments from Noah M and Stuart W at F2F.
12/3/01 NM Per F2F agreement, added text in section 2.2 word-smithed together with Doug Davis on clarifying issue 154
12/3/01 NM Miscellaneous (handwritten) comments from Stuart W included:
  • "subset of XML" in sec 2.2 changed suitably to avoid controvertial word "subset"
  • Passenger name changed throughout to something tasteful, if banal
  • Example 2 changed to remove schema syntax from body, which has been made a list conforming to some schema
  • Example 4 corrections in syntax; changed NS of transaction header
  • minor miscellaneous word changes for precision
12/3/01 NM Comments from David F made at F2F included: "SOAP node" linked to definition in Part 1; example URIs changed to xxx.example.com/org.
12/4/01 NM Added text in sec 2.3.2 to:
  • state that SOAP does not provide any IDL (per JJM comment)
  • elaborate on the "target" for the procedure or method
  • clarify that some protocol bindings may be able to carry the target URI
12/4/01 NM Corrected text following Example 5 to require a request-response MEP per SW (handwritten) comments
12/4/01 NM Changed to "application/soap" in examples 8,9 with accompanying text.
12/4/01 NM Added new items to section 5 on differences between SOAP 1.1 and 1.2
12/4/01 NM Combed whole document to ensure that the term "Body blocks" was not used except in the context of SOAP faults. Changed Figure to replace Body block.
12/4/01 NM Per SW (handwritten) comments, corrected cross-layering in Example 12 by removing message-id element from SOAP header. Added In-reply-to email header, and suitable text explaining issues related to correlation.
12/4/01 NM Added examples and accompanying text to Sec 2.2 per JJM comment to improve clarity of the precessing model.
12/5/01 NM General cleanup of the text.
12/13/01 NM Changed soap namespace from /09/ to /12/