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.It is to be considered a work in progress and does not imply endorsement by the W3C membership nor by the XML Protocol WG, where it is currently under review and discussion.It is a draft document that may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use this document as reference material or to cite it as anything other than "work in progress".

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.

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 SMTP binding

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

4.1 Changes between SOAP 1.1 and SOAP 1.2

4.2 Interworking between SOAP 1.1 and SOAP 1.2

6. References

A. Acknowledgements

B. Change Log

C. Unedited contributed text

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 a framework for the specification of a binding of SOAP onto another underlying protocol such as HTTP, SMTP, etc.

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. SOAP 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 a request-response type exchange. 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.

Section 6 provides references.

1.2 Notational Conventions

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 [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 intermediaries might be a corporate travel office that logs, audits and, possibly, amends each travel request, or a personal calendaring application which puts a tentative "hold" at the requested travel times.

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 RPC - between the traveler and the travel service confirms various aspects of the reservation

Examples and discussion of the behaviour and role of intermediaries is postponed to section 4.

2.1 SOAP messages

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

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope"> 
 <env:Header>
  <m:reservation xmlns:m="http://travelcompany.org/reservation" 
          env:actor="http://www.w3.org/2001/09/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.com/employees"
          env:actor="http://www.w3.org/2001/09/soap-envelope/actor/next"
           env:mustUnderstand="true">
   <n:name>John Doe</n:name>
  </n:passenger>
 </env:Header>
 <env:Body>
  <p:itinerary xmlns:p="http://travelcompany.com/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.com/reservation/hotels">
   <q:preference>none</q:preference>
  </q:lodging>
 </env:Body>
</env:Envelope>

As a SOAP message is an XML document, it can start with the usual XML preamble <?xml....?>. The SOAP message contains two SOAP-specific sub-elements within the overall Envelope, namely a Header and aBody. A Header is optional, but we have chosen to included it in our example. 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 and a Body are called, respectively, header blocks and body blocks, and represent some logical grouping of data. 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.

In anticipation of many 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, a flexible technique in the form of header blocks has been provided to permit SOAP processors to exchange information. These form the mechanism by which SOAP messages may be extended in an application-specific manner.

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

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 all SOAP nodes encountered en route is indicated by the presence of the attribute actorwith value "next", which is a role that all SOAP nodes 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. In this example, we will assume that the specifications for the two mandatory header blocks require that the information in the entire message be logged. Section 4.1 shows a more complex case where the relayed message is altered by the intermediary.

The Body element and associated body blocks, 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, such elements are implicitly targeted and are 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 instance, it can be sent in a SMTP message (see section 3.2). In another transport binding, such as, for example, a Web-based access to a travel service, it could be placed in the body of a HTTP POST request. 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 an overview of the 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, anyURI - 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, 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.

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.

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.

After a SOAP processor has correctly identified the elements targeted at itself, the 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 chosen for message exchange.

We provide examples of fault handling in section 2.4.

2.3 SOAP message exchange

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.

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope"> 
 <env:Header>
  <m:reservation xmlns:m="http://travelcompany.org/reservation" 
          env:actor="http://www.w3.org/2001/09/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.com/employees"
          env:actor="http://www.w3.org/2001/09/soap-envelope/actor/next"
           env:mustUnderstand="true">
   <n:name>John Doe</n:name>
  </n:passenger>
 </env:Header>
 <env:Body>
  <p:itinerary xmlns:p="http://travelcompany.com/reservation/travel">
   <p:airportChoices>
      <simpleType name='airports'>
        <annotation>
          <documentation>Airport choices for New York</documentation>
        </annotation>
        <restriction base='string'>
          <enumeration value='JFK'>
           <annotation>
            <documentation>John F. Kennedy</documentation>
           </annotation>
          </enumeration>
          <enumeration value='LGA'>
           <annotation>
            <documentation>La Guardia</documentation>
           </annotation>
          </enumeration>
         <enumeration value='EWR'>
           <annotation>
            <documentation>Newark</documentation>
           </annotation>
         </enumeration>
        </restriction>  
       </simpleType>
   </p:airportChoices>
  </p:itinerary>
 </env:Body>
</env:Envelope>

As described earlier, the Body contains the primary content of the message, namely an enumeration of the various alternatives for the airport. 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 in the form of SOAP messages are exchanged. Once again, we defer the means by which such a message is 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.

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope"> 
 <env:Header>
  <m:reservation xmlns:m="http://travelcompany.org/reservation" 
          env:actor="http://www.w3.org/2001/09/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.com/employees"
          env:actor="http://www.w3.org/2001/09/soap-envelope/actor/next"
           env:mustUnderstand="true">
   <n:name>John Doe</n:name>
  </n:passenger>
 </env:Header>
 <env:Body>
  <p:itinerary xmlns:p="http://travelcompany.com/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>

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 our with out 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:

• 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. We defer until section 3 the discussion of how the URI is carried, 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.

<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope" >
 <env:Header>
   <m:reservation xmlns:m="http://travelcompany.org/reservation" 
          env:actor="http://www.w3.org/2001/09/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://travelcompany.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/09/soap-encoding"
             xmlns:m="http://travelcompany.org/" >
      <n:name xmlns:n="http://mycompany.com/employees">
           John Doe
      </n:name>
        <o:creditCard xmlns:n="http://mycompany.com/financial">
           <o:number>123456789099999</o:number>
           <o:expiration>2005-02</o:expiration>
         </o:creditCard>
       </m:reserveAndCharge>
  </env:Body>
</env:Envelope>

The RPC itself is carried 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 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 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 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". 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 the body block 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.

<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope" >
 <env:Header>
       <t:Transaction
           xmlns:t="http://travelcompany.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/09/soap-encoding"
             xmlns:m="http://travelcompany.org/" >
           <confirmation>
               <reference>FT35ZBQ</reference>
               <viewAt>http://travelcompany.com/reservations/</viewAt>
           </confirmation>
       </m:reserveAndChargeResponse>
   </env:Body>
</env:Envelope>

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. Thus, while most examples of SOAP for RPC use the HTTP protocol binding, it is not limited to that means alone. Section 3.1 provides examples of HTTP bindings.

2.4 Fault scenarios

SOAP provides a model for handling situations where faults arise in the processing of a message. The SOAPBody 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 in theBody 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.

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

The faultcode indicates that it is a server fault, and therefore not related to any syntactical error in the message (which would have been a "Client" 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 misunderstood header via a qname attribute in the special (empty) header block Misunderstood.

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

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 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, respectively those to HTTP and SMTP.

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 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 at which the invocation is targeted. 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://www.travelcompany.org/Charging". The SOAP message (details elided) is sent in the body of a HTTP POST method directed at the above-mentioned URI.

POST /Charging HTTP/1.1
Host: www.travelcompany.org
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn

<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope" >
 <env:Header>
   ::::::
 </env:Header>  
 <env:Body>
    <m:reserveAndCharge 
        ::::::
    </m:reserveAndCharge>
  </env:Body>
</env:Envelope>

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.

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>
       ::::
 </env:Header>  
 <env:Body>
       ::::
   </env:Body>
</env:Envelope>

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.

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"
            xmlns:f='http://www.w3.org/2001/09/soap-faults'>
  <env:Body>
    <env:Fault>
      <faultcode>env:Server</faultcode>
      <faultstring>Processing Error</faultstring>
      <detail>
        <e:myfaultdetails xmlns:e="http://travelcompany.org/faults" >
          <message>Name does not match card number</message>
          <errorcode>999</errorcode>
        </e:myfaultdetails>
      </detail>
    </env:Fault>
 </env:Body>
</env:Envelope>

EdNote: More examples will be provided in a future draft based on the resolution of the 2xx vs 5xx debate.

3.2 SMTP binding

Application developers can use the Internet email infrastructure to move SOAP messages as either email text or attachments. The Simple Mail Transport Protocol (SMTP) specification [9] 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 11 shows the travel reservation request message from Example 1 carried as an SMTP message between a sending and receiving SMTP 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: john.doe@mycompany.com
To: reservations@travelcompany.org
Subject: Travel to LA
Date: Thu, 29 Nov 2001 13:20:00 EST
Message-Id: <EE492E16A0B8D311AC490090276D208424960C0C@mycompany.com> 

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope"> 
 <env:Header>
  <m:reservation xmlns:m="http://travelcompany.org/reservation" 
          env:actor="http://www.w3.org/2001/09/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.com/employees"
          env:actor="http://www.w3.org/2001/09/soap-envelope/actor/next"
           env:mustUnderstand="true">
   <n:name>John Doe</n:name>
  </n:passenger>
 </env:Header>
 <env:Body>
  <p:itinerary xmlns:p="http://travelcompany.com/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.com/reservation/hotels">
   <q:preference>none</q:preference>
  </q:lodging>
 </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 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.

Example 12 is exactly the same scenario as described forExample 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 within the SOAP envelope in a header block message-id to enable message correlation. A equally plausible solution could have been to not include such a header block but rely on the existing reservation block. Again, how such correlation is achieved are functions of how such applications are designed, and is not within the scope of SOAP.

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

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope"> 
 <env:Header>
  <z:message-id xmlns:z="http://travelcompany.com/mailhost">
     EE492E16A0B8D311AC490090276D208424960C0C@mycompany.com
  </z:message-id>
  <m:reservation xmlns:m="http://travelcompany.org/reservation" 
          env:actor="http://www.w3.org/2001/09/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.com/employees"
          env:actor="http://www.w3.org/2001/09/soap-envelope/actor/next"
           env:mustUnderstand="true">
   <n:name>John Doe</n:name>
  </n:passenger>
 </env:Header>
 <env:Body>
  <p:itinerary xmlns:p="http://travelcompany.com/reservation/travel">
   <p:airportChoices>
      :::::
   </p:airportChoices>
  </p:itinerary>
 </env:Body>
</env:Envelope>

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 any 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, 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, which includes information that qualifies any travel request.

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/09/soap-envelope"> 
 <env:Header>
  <m:reservation xmlns:m="http://travelcompany.org/reservation" 
          env:actor="http://www.w3.org/2001/09/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.com/employees"
          env:actor="http://www.w3.org/2001/09/soap-envelope/actor/next"
           env:mustUnderstand="true">
   <n:name>John Doe</n:name>
  </n:passenger>
  <z:travelPolicy xmlns:z="http://mycompany.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.com/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.com/reservation/hotels">
   <q:preference>none</q:preference>
  </q:lodging>
 </env:Body>
</env:Envelope>

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 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. Suggestions? An RDF encoding perhaps?

5. Version transition from SOAP 1.1 to SOAP 1.2

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.

• SOAP 1.2 does not permit any element after the body. The SOAP 1.1 schema definition allowed for such a possibility, but the textual description is silent about it.
• SOAP 1.2 defines the new Misunderstood header element for conveying information on a mandatory header block which could not be processed.
• The namespaces of the two protocols are of course different.
• SOAP 1.2 defines two new actor roles, "none" and "anonymous", together with a more detailed procssing model on how these behave.
• SOAP 1.2 provides a <response> element for RPCs. EdNote: Many more for RPCs?

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

6. References

A. Acknowledgements

Highland Mary Mountain (Intel) provided material for the section on the SMTP binding, for which much thanks. Paul Denning provided a wealth of material for a usage scenario, which is temporarily placed in Appendix C.

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

C. Unedited contributed text

EdNote: Text provided by Paul Denning added with minor editing. It is perhaps best to consider this as input to the usage scenarios document.

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