SOAP Version 1.2 Part 0: Primer (Second Edition)

1.1 Overview

SOAP Version 1.2 provides the definition of the XML-based information which can be used for exchanging structured and typed information between peers in a decentralized, distributed environment. [SOAP Part1] explains that a SOAP message is formally specified as an XML InfosetInformation Set [XML Infoset ],] (henceforth often simply infoset), which provides an abstract description of its contents. Infosets can have different on-the-wire representations,representations (aka serializations), one common example of which is as an XML 1.0 [XML 1.0] document. However, other serializations are also possible, and [MTOM] using the [XOP] format offers one mechanism for doing so for the cases where there is a need to optimize the processing and size of the transmitted message.

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 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 required actions taken by a SOAP node on receiving a SOAP message.

Section 2 of this document provides an introduction to the basic features of SOAP starting with the simplest usage scenarios, namely a one-way SOAP message, followed by various request-response type exchanges, including RPCs. Fault situations are also described.

Section 3 provides an overview of the SOAP processing model, which describes the rules for initial construction of a message, rules by which messages are processed when received at an intermediary or ultimate destination, and rules by which portions of the message can be inserted, deleted or modified by the actions of an intermediary.

Section 4 of this document describes the ways in which SOAP messages may be transported to realize various usage scenarios. It describes the SOAP HTTP binding specified in [SOAP Part2], as well as an example of how SOAP messages may be conveyed in email messages. As a part of the HTTP binding, it introduces two message exchange patterns which are available to an application, one of which uses the HTTP POST method, while the other uses HTTP GET. Examples are also provided on how RPCs, in particular those that represent "safe" information retrieval, may be represented in SOAP message exchanges in a manner that is compatible with the architectural principles of the World Wide Web .

Section 5 of this document provides a treatment of various aspects of SOAP that can be used in more complex usage scenarios. These include the extensibility mechanism offered through the use of header elements, which may be targeted at specific intermediate SOAP nodes to provide value-added services to communicating applications, andusing various encoding schemes to serialize application-specific data in SOAP messages.messages, and the means to provide a more optimized serialization of a SOAP message under certain circumstances.

Section 6 of this document describes the changes from SOAP Version 1.1 [SOAP 1.1].

Section 7 of this document provides references.

For ease of reference, terms and concepts used in this primer are hyper-linked to their definition in the main specifications.

1.2 Notational Conventions

Throughout this primer, sample SOAP envelopes and messages are shown as [XML 1.0] documents. [SOAP Part1] explains that a SOAP message is formally specified as an [XML InfoSet], which is an abstract description of its contents. The distinction between the SOAP XML Infosetsmessage infosets and thetheir representation as 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 protocol bindings where the messages may have alternative representations) should understand these examples as referring to the corresponding XML infosets. Further elaboration of this point is provided in Section 4 of this document.

The namespace prefixes "env", "enc", "rpc", "rep", "xop" and "rpc""xmime" used in the prose sections of this document are associated with the SOAPnamespace names "http://www.w3.org/2003/05/soap-envelope" , "http://www.w3.org/2003/05/soap-encoding", and"http://www.w3.org/2003/05/soap-rpc", "http://www.w3.org/2004/08/representation", "http://www.w3.org/2004/08/xop/include" and "http://www.w3.org/2004/11/xmlmime" 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 Schema specifications [XML Schema Part1], [XML Schema Part2].

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 [RFC 2396]3986].

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/2003/05/soap-envelope"> 
 <env:Header>
  <m:reservation xmlns:m="http://travelcompany.example.org/reservation" 
          env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
           env:mustUnderstand="true">
   <m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</m: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:role="http://www.w3.org/2003/05/soap-envelope/role/next"
           env:mustUnderstand="true">
   <n:name>Åke Jógvan Øyvind</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>

The SOAP message in Example 1 contains two SOAP-specific sub-elements within the overall env:Envelope, namely an env:Header and an env: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 SOAP header element is optional, but it has been included in the example to explain certain features of SOAP. A SOAP header is an extension mechanism that provides a way to pass information in SOAP messages that is not application payload. Such "control" information includes, for example, passing directives or contextual information related to the processing of the message. This allows a SOAP message to be extended in an application-specific manner. The immediate child elements of the env:Header element are called header blocks, and represent a logical grouping of data which, as shown later, can individually be targeted at SOAP nodes that might be encountered in the path of a message from a sender to an ultimate receiver.

SOAP headers have been designed in anticipation of various uses for SOAP, many of which will involve the participation of other SOAP processing nodes - called SOAP intermediaries - along a message's path from an initial SOAP sender to an ultimate SOAP receiver. This allows SOAP intermediaries to provide value-added services. Headers, as shown later, may be inspected, inserted, deleted or forwarded by SOAP nodes encountered along a SOAP message path. (It should be kept in mind, though, that the SOAP specifications do not deal with what the contents of header elements are, or how SOAP messages are routed between nodes, or the manner by which the route is determined and so forth. These are a part of the overall application, and could be the subject of other specifications.)

The SOAP body is the mandatory element within the SOAP env:Envelope, which implies that this is where the main end-to-end information conveyed in a SOAP message must be carried.

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 XML 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 must be processed by the next SOAP intermediary encountered in the message path or, if there is no intermediary, by the ultimate recipient 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 env:role with the value "http://www.w3.org/2003/05/soap-envelope/role/next" (hereafter simply "next"), which is a role that all SOAP nodes must be willing to play. The presence of an env:mustUnderstand attribute with value "true" indicates that the node(s) processing the header must absolutely process these header blocks in a manner consistent with their specifications, or else not process the message at all and throw a fault. Note that whenever a header block is processed, either because it is marked env:mustUnderstand="true" or for another reason, the block must be processed in accordance with the specifications for that block. Such header block specifications are application defined and not a part of SOAP. Section 3 will elaborate further on SOAP message processing based on the values of these attributes.

The choicechoices of what data is placed in a header block and what goes in the SOAP body are decisions takenmade at the time of application design. The main point to keep in mind is that header blocks may be targeted 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 to illustrate the use of this data at a SOAP intermediary to do some additional processing. For example, as shown later in section 5.1, the outbound message is altered by the SOAP intermediary by having the travel policies pertaining to this passenger appended to the message as another header block.

The env:Body element and its associated child elements, itinerary and lodging, are intended for exchange of information between the initial SOAP sender and the SOAP node which assumes the role of the ultimate SOAP receiver in the message path, which is the travel service application. Therefore, the env:Body and its contents are implicitly targeted and are expected to be understood by the ultimate receiver. The means by which a SOAP node assumes such a role is not defined by the SOAP specification, and is determined as a part of the overall application semantics and associated message flow.

Note that a SOAP intermediary may decide to play the role of the ultimate SOAP receiver for a given message transfer, and thus process the env:Body. However, even though this sort of a behavior cannot be prevented, it is not something that should be done lightly as it may pervert the intentions of the message's sender, and have undesirable side effects (such as not processing header blocks that might be targeted at intermediaries further along the message path).

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, for a Web-based access to a travel service application, it could be placed in the body of a HTTP POST request. In another protocol binding, it might be sent in an email message (see section 4.2). Section 4 will describe how SOAP messages may be conveyed by a variety of underlying protocols. For the time being, it is assumed that a mechanism exists for message transfer and the remainder of this section concentrates on the details of the SOAP messages and their processing.

2.2 SOAP Message Exchange

SOAP Version 1.2 is a simple messaging framework for transferring information specified in the form of an XML infoset between an initial SOAP sender and an ultimate SOAP receiver. The more interesting scenarios typically involve multiple message exchanges between these two nodes. The simplest such exchange is a request-response pattern. Some early uses of [SOAP 1.1] emphasized the use of this pattern as means for conveying remote procedure calls (RPC), but it is important to note that not all SOAP 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 pre-defined description of the remote call and its return.

A much larger set of usage scenarios than that covered by the request-response pattern can be modeled simply as XML-based content exchanged in SOAP messages to form a back-and-forth "conversation", where the semantics are at the level of the sending and receiving applications. Section 2.2.1 covers the case of XML-based content exchanged in SOAP messages between the travel reservation application and the travel service application in a conversational pattern, while section 2.2.2 provides an example of an exchange modeled as an RPC.

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"> 
 <env:Header>
  <m:reservation xmlns:m="http://travelcompany.example.org/reservation" 
      env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
           env:mustUnderstand="true">
   <m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</m: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:role="http://www.w3.org/2003/05/soap-envelope/role/next"
           env:mustUnderstand="true">
   <n:name>Åke Jógvan Øyvind</n:name>
  </n:passenger>
 </env:Header>
 <env:Body>
  <p:itineraryClarification 
    xmlns:p="http://travelcompany.example.org/reservation/travel">
   <p:departure>
     <p:departing>
       <p:airportChoices>
          JFK LGA EWR 
       </p:airportChoices>
     </p:departing>
   </p:departure>
   <p:return>
     <p:arriving>
       <p:airportChoices>
         JFK LGA EWR 
       </p:airportChoices>
     </p:arriving>
   </p:return>  
  </p:itineraryClarification>
 </env:Body>
</env:Envelope>

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"> 
 <env:Header>
  <m:reservation 
     xmlns:m="http://travelcompany.example.org/reservation" 
      env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
           env:mustUnderstand="true">
    <m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</m: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:role="http://www.w3.org/2003/05/soap-envelope/role/next"
           env:mustUnderstand="true">
   <n:name>Åke Jógvan Øyvind</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>

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/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: chargeReservation<m:chargeReservation
      env:encodingStyle="http://www.w3.org/2003/05/soap-encoding"
         xmlns:m="http://travelcompany.example.org/">
   <m:reservation xmlns:m="http://travelcompany.example.org/reservation">
    <m:code>FT35ZBQ</m:code>
   </m:reservation>
   <o:creditCard xmlns:o="http://mycompany.example.com/financial">
    <n:name xmlns:n="http://mycompany.example.com/employees">
           Åke Jógvan Øyvind
    </n:name>
    <o:number>123456789099999</o:number>
    <o:expiration>2005-02</o:expiration>
   </o:creditCard>
   </m:chargeReservation ></m:chargeReservation>
 </env:Body>
</env:Envelope>

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/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:chargeReservationResponse 
         env:encodingStyle="http://www.w3.org/2003/05/soap-encoding"
             xmlns:m="http://travelcompany.example.org/">
       <m:code>FT35ZBQ</m:code>
       <m:viewAt>
         http://travelcompany.example.org/reservations?code=FT35ZBQ
       </m:viewAt>
     </m:chargeReservationResponse>
 </env:Body>
</env:Envelope>

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/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:chargeReservationResponse 
       env:encodingStyle="http://www.w3.org/2003/05/soap-encoding"
           xmlns:rpc="http://www.w3.org/2003/05/soap-rpc"
             xmlns:m="http://travelcompany.example.org/">
       <rpc:result>m:status</rpc:result>
       <m:status>confirmed</m:status>
       <m:code>FT35ZBQ</m:code>
       <m:viewAt>
        http://travelcompany.example.org/reservations?code=FT35ZBQ
       </m:viewAt>
    </m:chargeReservationResponse>
 </env:Body>
</env:Envelope>

2.3 Fault Scenarios

SOAP provides a model for handling situations when faults arise in the processing of a message. SOAP distinguishes between the conditions that result in a fault, and the ability to signal that fault to the originator of the faulty message or another node. The ability to signal the fault depends on the message transfer mechanism used, and one aspect of the binding specification of SOAP onto an underlying protocol is to specify how faults are signalled, if at all. The remainder of this section assumes that a transfer mechanism is available for signalling faults generated while processing received messages, and concentrates on the structure of the SOAP fault message.

The SOAP env:Body element has another distinguished role in that it is the place where such fault information is placed. The SOAP fault model (see SOAP Part 1, section 2.6) requires that all SOAP-specific and application-specific faults be reported using a single distinguished element, env:Fault, carried within the env:Body element. The env:Fault element contains two mandatory sub-elements, env:Code and env:Reason, and (optionally) application-specific information in the env:Detail sub-element. Another optional sub-element, env:Node, identifies via a URI the SOAP node which generated the fault, its absence implying that it was the ultimate recipient of the message which did so. There is yet another optional sub-element, env:Role, which identifies the role being played by the node which generated the fault.

The env:Code sub-element of env:Fault is itself made up of a mandatory env:Value sub-element, whose content is specified in the SOAP specification (see SOAP Part 1 section 5.4.6) as well as an optional env:Subcode sub-element.

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

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"
            xmlns:rpc='http://www.w3.org/2003/05/soap-rpc'>
  <env:Body>
   <env:Fault>
     <env:Code>
       <env:Value>env:Sender</env:Value>
       <env:Subcode>
        <env:Value>rpc:BadArguments</env:Value>
       </env:Subcode>
     </env:Code>
     <env:Reason>
      <env:Text xml:lang="en-US">Processing error</env:Text>
      <env:Text xml:lang="cs">Chyba zpracování</env:Text>
     </env:Reason>
     <env:Detail>
      <e:myFaultDetails 
        xmlns:e="http://travelcompany.example.org/faults">
        <e:message>Name does not match card number</e:message>
        <e:errorcode>999</e:errorcode>
      </e:myFaultDetails>
     </env:Detail>
   </env:Fault>
 </env:Body>
</env:Envelope>

In Example 6a, the top-level env:Value uses a standardized XML Qualified Name (of type xs:QName) to identify that it is an env:Sender fault, which indicates that it is related to some syntactical error or inappropriate information in the message. (When a env:Sender fault is received by the sender, it is expected that some corrective action is taken before a similar message is sent again.) The env:Subcode element is optional, and, if present, as it is in this example, qualifies the parent value further. In Example 6a, the env:Subcode denotes that an RPC specific fault, rpc:BadArguments, defined in SOAP Part 2 section 4.4, is the cause of the failure to process the request.

The structure of the env:Subcode element has been chosen to be hierarchical - each child env:Subcode element has a mandatory env:Value and an optional env:Subcode sub-element - to allow application-specific codes to be carried. This hierarchical structure of the env:Code element allows for an uniform mechanism for conveying multiple level of fault codes. The top-level env:Value is a base fault that is specified in the SOAP Version 1.2 specifications (see SOAP Part 1 section 5.4.6) and must be understood by all SOAP nodes. Nested env:Values are application-specific, and represent further elaboration or refinement of the base fault from an application perspective. Some of these values may well be standardized, such as the RPC codes standardized in SOAP 1.2 (see SOAP Part 2 section 4.4), or in some other standards that use SOAP as an encapsulation protocol. The only requirement for defining such application-specific subcode values is that they be namespace qualified using any namespace other than the SOAP env namespace which defines the main classifications for SOAP faults. There is no requirement from a SOAP perspective that applications need to understand, or even look at all levels of the subcode values.

The env:Reason 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. Therefore all that is required is that it reasonably accurately describe the fault situation. It must have one or more env:Text sub-elements, each with a unique xml:lang attribute, which allows applications to make the fault reason available in multiple languages. (Applications could negotiate the language of the fault text using a mechanism built using SOAP headers; however this is outside the scope of the SOAP specifications.)

The absence of a env:Node sub-element within env:Fault in Example 6a implies that it is generated by the ultimate receiver of the call. The contents of env:Detail, as shown in the example, 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 in it cannot be processed. Errors in processing a header block are also signalled using a env:Fault element within the env:Body, but with a particular distinguished header block, env:NotUnderstood, that identifies the offending header block.

Example 6b shows an example of a response to the RPC in Example 4 indicating a failure to process the t:transaction header block. Note the presence of the env:MustUnderstand fault code in the env:Body, and the identification of the header not understood using an (unqualified) attribute, qname, in the special (empty) header block env:NotUnderstood.

<?xml version='1.0' ?>
<env:Envelope  xmlns:env="http://www.w3.org/2003/05/soap-envelope>xmlns:env="http://www.w3.org/2003/05/soap-envelope">
 <env:Header>
    <env:NotUnderstood  qname ="t:transaction"qname="t:transaction"
               xmlns:t="http://thirdparty.example.org/transaction"/>
 </env:Header>  
 <env:Body>
  <env:Fault>
   <env:Code>
    <env:Value>env:MustUnderstand</env:Value>
   </env:Code>
   <env:Reason>
      <env:Text xml:lang="en-US">Header not understood</env:Text>
      <env:Text xml:lang="fr">En-tête non compris</env:Text>
   </env:Reason>    
  </env:Fault>
 </env:Body>
</env:Envelope>

If there were several mandatory header blocks that were not understood, then each could be identified by its qname attribute in a series of such env:NotUnderstood header blocks.

3.1 The "role" Attribute

Further processing of header blocks and the body depend on the role(s) assumed by the SOAP node for the processing of a given message. SOAP defines the (optional) env:role attribute - syntactically, xs:anyURI - that may be present in a header block, which identifies the role played by the intended target of that header block. A SOAP node is required to process a header block if it assumes the role identified by the value of the URI. How a SOAP node assumes a particular role is not a part of the SOAP specifications.

Three standardized roles have been defined (see SOAP Part 1, section 2.2), which are

• "http://www.w3.org/2003/05/soap-envelope/role/none" (hereafter simply "none")
• "http://www.w3.org/2003/05/soap-envelope/role/next" (hereafter simply "next"), and
• "http://www.w3.org/2003/05/soap-envelope/role/ultimateReceiver" (hereafter simply "ultimateReceiver").

In Example 7a, the header block oneBlock is targeted at any SOAP node that plays the application-defined role defined by the URI http://example.com/Log. For purposes of illustration, it is assumed that the specification for such a header block requires that any SOAP node adopting this role log the entire message.

Every SOAP node receiving a message with a header block that has a env:role attribute of "next" must be capable of processing the contents of the element, as this is a standardized role that every SOAP node must be willing to assume. A header block thus attributed is one which is expected to be examined and (possibly) processed by the next SOAP node 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 Example 7a, the header block anotherBlock is targeted at the next node in the message path. In this case, the SOAP message received by the node playing the application-defined role of "http://example.com/Log", must also be willing to play the SOAP-defined role of "next". This is also true for the node which is the ultimate recipient of the message, as it obviously (and implicitly) also plays the "next" role by virtue of being next in the message path.

The third header block, aThirdBlock, in Example 7a does not have the env:role attribute. It is targeted at a SOAP node which assumes the "ultimateReceiver" role. The "ultimateReceiver" role (which can be explicitly declared or is implicit if the env:role attribute is absent in a header block) is played by a SOAP node that assumes the role of the ultimate recipient of a particular SOAP message. The absence of a env:role attribute in the aThirdBlock header block means that this header element is targeted at the SOAP node that assumes the "ultimateReceiver" role.

Note that the env:Body element does not have a env:role attribute. The body element is always targeted at the SOAP node that assumes the "ultimateReceiver" role. In that sense, the body element is just like a header block targeted at the ultimate receiver, but it has been distinguished to allow for SOAP nodes (typically SOAP intermediaries) to skip over it if they assume roles other than that of the ultimate receiver. SOAP does not prescribe any structure for the env:Body element, except that it recommends that any sub-elements be XML namespace qualified. Some applications, such as that in Example 1, may choose to organize the sub-elements of env:Body in blocks, but this is not of concern to the SOAP processing model.

The other distinguished role for the env:Body element, as the container where information on SOAP-specific faults, i.e., failure to process elements of a SOAP message, is placed has been described previously in section 2.3.

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

If the env:role attribute has an empty value, i.e., env:role="", it means that the relative URI identifying the role is resolved to the base URI for the SOAP message in question. SOAP Version 1.2 does not define a base URI for a SOAP message, but defers to the mechanisms defined in [XMLBase] for deriving the base URI, which can be used to make any relative URIs absolute. One such mechanism is for the protocol binding to establish a base URI, possibly by reference to the encapsulating protocol in which the SOAP message is embedded for transport. (In fact, when SOAP messages are transported using HTTP, SOAP Part 2 section 7.1.2 defines the base URI as the Request-URI of the HTTP request, or the value of the HTTP Content-Location header.)

The following table summarizes the applicable standardized roles that may be assumed at various SOAP nodes. ("Yes" and "No" means that the corresponding node does or does not, respectively, play the named role.)

3.2 The "mustUnderstand" Attribute

Example 7b augments the previous example by introducing another (optional) attribute for header blocks, the env:mustUnderstand attribute.

<?xml version="1.0" ?>
 <env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
   <env:Header>
     <p:oneBlock xmlns:p="http://example.com" 
           env:role="http://example.com/Log" 
               env:mustUnderstand="true">
     ...
     ...
     </p:oneBlock>
     <q:anotherBlock xmlns:q="http://example.com"
       env:role="http://www.w3.org/2003/05/soap-envelope/role/next">
     ...
     ...
     </q:anotherBlock>
     <r:aThirdBlock xmlns:r="http://example.com">
     ...
     ...
     </r:aThirdBlock>
   </env:Header>
   <env:Body >
     ...
     ...
   </env:Body>
 </env:Envelope>

After a SOAP node has correctly identified the header blocks (and possibly the body) targeted at itself using the env:role attribute, the additional attribute, env:mustUnderstand, in the header elements determines further processing actions that have to be taken. In order to ensure that SOAP nodes do not ignore header blocks which are important to the overall purpose of the application, SOAP header blocks also provide for the additional optional attribute, env:mustUnderstand, which, if "true", means that the targeted SOAP node must process the block according to the specification of that block. Such a block is colloquially referred to as a mandatory header block. In fact, processing of the SOAP message must not even start until the node has identified all the mandatory header blocks targeted at itself, and "understood" them. Understanding a header means that the node must be prepared to do whatever is described in the specification of that block. (Keep in mind that the specifications of header blocks are not a part of the SOAP specifications.)

In Example 7b, the header block oneBlock is marked with a env:mustUnderstand value set to "true", which means that it is mandatory to process this block if the SOAP node plays the role identified by "http://example.com/Log". The other two header blocks are not so marked, which means that SOAP node at which these blocks are targeted need not process them. (Presumably the specifications for these blocks allow for this.)

A env:mustUnderstand value of "true" means that the SOAP node must process the header with the semantics described in that header's specification, or else generate a SOAP 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 message is not forwarded any further.

The env:Body element has no env:mustUnderstand attribute but it must be processed by the ultimate recipient. In Example 7b, the ultimate recipient of the message - the SOAP node which plays the "ultimateReceiver" role - must process the env:Body and may process the header block aThirdBlock. It may also process the header block anotherBlock, as it is targeted at it (in the role of "next") but it is not mandatory to do so if the specifications for processing the blocks do not demand it. (If the specification for anotherBlock demanded that it must be processed at the next recipient, it would have required that it be marked with a env:mustUnderstand="true".)

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, or 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 env:mustUnderstand checking of any headers with those additional roles assumed was performed before any processing began. Also, if a SOAP node assumes such additional roles, it must ensure that it is prepared to do everything that the specifications for those roles require.

The following table summarizes how the processing actions for a header block are qualified by the env:mustUnderstand attribute with respect to a node that has been appropriately targeted (via the env:role attribute).

As a result of processing a SOAP message, a SOAP node may generate a single SOAP fault if it fails to process a message, or, depending on the application, generate additional SOAP messages for consumption at other SOAP nodes. SOAP Part 1 section 5.4 describes the structure of the fault message while the SOAP processing model defines the conditions under which it is generated. As illustrated previously in section 2.3, a SOAP fault is a SOAP message with a standardized env:Body sub-element named env:Fault.

SOAP makes a distinction between generating a fault and ensuring that the fault is returned to the originator of the message or to another appropriate node which can benefit from this information. However, whether a generated fault can be propagated appropriately depends on the underlying protocol binding chosen for the SOAP message message exchange. The specification does not define what happens if faults are generated during the propagation of one-way messages. The only normative underlying protocol binding, which is the SOAP HTTP binding, offers the HTTP response as a means for reporting a fault in the incoming SOAP message. (See Section 4 for more details on SOAP protocol bindings.)

3.3 The "relay" Attribute

SOAP Version 1.2 defines another optional attribute for header blocks, env:relay of type xs:boolean, which indicates if a header block targeted at a SOAP intermediary must be relayed if it is not processed.

Note that if a header block is processed, the SOAP processing rules (see SOAP Part 1 section 2.7.2) requires that it be removed from the outbound message. (It may, however, be reinserted, either unchanged or with its contents altered, if the processing of other header blocks determines that the header block be retained in the forwarded message.) The default behavior for an unprocessed header block targeted at a role played by a SOAP intermediary is that it must be removed before the message is relayed.

The reason for this choice of default is to lean on the side of safety by ensuring that a SOAP intermediary make no assumptions about the survivability past itself of a header block targeted at a role it assumes, and representing some value-added feature, particularly if it chooses not to process the header block, very likely because it does not "understand" it. That is because certain header blocks represent hop-by-hop features, and it may not make sense to unknowingly propagate it end-to-end. As an intermediary may not be in a position to make this determination, it was thought that it would be safer if unprocessed header blocks were removed before the message was relayed.

However, there are instances when an application designer would like to introduce a new feature, manifested through a SOAP header block, targeted at any capable intermediary which might be encountered in the SOAP message path. Such a header block would be available to those intermediaries that "understood" it, but ignored and relayed onwards by those that did not. Being a new feature, the processing software for this header block may be implemented, at least initially, in some but not all SOAP nodes. Marking such a header block with env:mustUnderstand = "false" is obviously needed, so that intermediaries that have not implemented the feature do not generate a fault. To circumvent the default rule of the processing model, marking a header block with the additional attribute env:relay with the value "true" allows the intermediary to forward the header block targeted at itself in the event that it chooses not to process it.

Targeting the header block at the role "next" together with the env:relay attribute set to "true" can always serve to ensure that each intermediary has a chance to examine the header, because one of the anticipated uses of the "next" role is with header blocks that carry information that are expected to persist along a SOAP message path. Of course, the application designer can always define a custom role that allows targetting at specific intermediaries that assume this role. Therefore, there is no restriction on the use of the env:relay attribute with any role except of course the roles of "none" and "ultimateReceiver", for which it is meaningless.

Example 7c shows the use of the env:relay attribute.

<?xml version="1.0" ?>
 <env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
   <env:Header>
     <p:oneBlock xmlns:p="http://example.com" 
           env:role="http://example.com/Log" 
               env:mustUnderstand="true">
     ...
     ...
     </p:oneBlock>
     <q:anotherBlock xmlns:q="http://example.com"
       env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
       env:relay="true">
     ...
     ...
     </q:anotherBlock>
     <r:aThirdBlock xmlns:r="http://example.com">
     ...
     ...
     </r:aThirdBlock>
   </env:Header>
   <env:Body >
     ...
     ...
   </env:Body>
 </env:Envelope>

The header block q:anotherBlock, targeted at the "next" node in the message path, has the additional attribute env:relay="true". A SOAP node receiving this message may process this header block if it "understands" it, but if it does so the processing rules require that this header block be removed before forwarding. However, if the SOAP node chooses to ignore this header block, which it can because it is not mandatory to process it, as indicated by the absence of the env:mustUnderstand attribute, then it must forward it.

Processing the header block p:oneBlock is mandatory and the SOAP processing rules require that it not be relayed, unless the processing of some other header block requires that it be present in the outbound message. The header block r:aThirdBlock does not have an env:relay attribute, which is equivalent to having it with the value of env:relay ="false".= "false". Hence, this header is not forwarded if it is not processed.

SOAP 1.2 Part 1 Table 3 summarizes the conditions which determine when a SOAP intermediary assuming a given role is allowed to forward unprocessed header blocks.

4.1 The SOAP 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 using the underlying TCP/IP network, issues a HTTP request message and receives a HTTP response message over the same TCP 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, the Request-URI, which can also serve as the identification of a SOAP node at the server.

HTTP allows for multiple intermediaries between the initial client and the origin 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.

The HTTP binding in [SOAP Part2] makes use of theSOAP Web Method feature to allow applications to choose the so-called Web method - restricting it to one of GET or POST - to use over the HTTP message exchange. In addition, it makes use of two message exchange patterns that offer applications two ways of exchanging SOAP messages via HTTP: 1) the use of the HTTP POST method for conveying SOAP messages in the bodies of HTTP request and response messages, and 2) the use of the HTTP GET method in a HTTP request to return a SOAP message in the body of a HTTP response. The first usage pattern is the HTTP-specific instantiation of a binding feature called the SOAP request-response message exchange pattern, while the second uses a feature called the SOAP response message exchange pattern.

The purpose of providing these two types of usages is to accommodate the two interaction paradigms which are well established on the World Wide Web. The first type of interaction allows for the use of data within the body of a HTTP POST to create or modify the state of a resource identified by the URI to which the HTTP request is destined. The second type of interaction pattern offers the ability to use a HTTP GET request to obtain a representation of a resource without altering its state in any way. In the first case, the SOAP-specific aspect of concern is that the body of the HTTP POST request is a SOAP message which has to be processed (per the SOAP processing model) as a part of the application-specific processing required to conform to the POST semantics. In the second case, the typical usage that is forseen is the case where the representation of the resource that is being requested is returned not as a HTML, or indeed a generic XML document, but as a SOAP message. That is, the HTTP content type header of the response message identifies it as being of media type "application/soap+xml"."application/soap+xml" [RFC 3902]. Presumably, there will be publishers of resources on the Web who determine that such resources are best retrieved and made available in the form of SOAP messages. Note, however, that resources can, in general, be made available in multiple representations, and the desired or preferred representation is indicated by the requesting application using the HTTP Accept header.

One further aspect of the SOAP HTTP binding is the question of how an application determines which of these two types of message exchange patterns to use. [SOAP Part2] offers guidance on circumstances when applications may use one of the two specified message exchange patterns. (It is guidance - albeit a strong one - as it is phrased in the form of a "SHOULD" in the specifications rather than an absolute requirement identified by the word "MUST", where these words are interpreted as defined in the IETF [RFC 2119].) The SOAP response message exchange pattern with the HTTP GET method is used when an application is assured that the message exchange is for the purposes of information retrieval, where the information resource is "untouched" as a result of the interaction. Such interactions are referred to as safe and idempotent in the HTTP specification. As the HTTP SOAP GET usage does not allow for a SOAP message in the request, applications that need features in the outbound interaction that can only be supported by a binding-specific expression within the SOAP infoset (i.e., as SOAP header blocks) obviously cannot make use of this message exchange pattern. Note that the HTTP POST binding is available for use in all cases.

The following subsections provide examples of the use of these two message exchange patterns defined for the HTTP binding.

GET /travelcompany.example.org/reservations?code=FT35ZBQ  HTTP/1.1
Host: travelcompany.example.org
Accept: text/html;q=0.5, application/soap+xml

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

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"> 
 <env:Header>
  <m:reservation xmlns:m="http://travelcompany.example.org/reservation" 
       env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
           env:mustUnderstand="true">
   <m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</m:reference>
   <m:dateAndTime>2001-11-30T16:25:00.000-05:00</m:dateAndTime>
  </m:reservation>
 </env:Header>
 <env:Body>
  <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
            xmlns:x="http://travelcompany.example.org/vocab#"
     env:encodingStyle="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
   <x:ReservationRequest 
 rdf:about="http://travelcompany.example.org/reservations?code=FT35ZBQ">
      <x:passenger>Åke Jógvan Øyvind</x:passenger>
      <x:outbound>
       <x:TravelRequest>
        <x:to>LAX</x:to>
        <x:from>LGA</x:from>
        <x:date>2001-12-14</x:date>
       </x:TravelRequest>
      </x:outbound>
      <x:return>
       <x:TravelRequest>
        <x:to>JFK</x:to>
        <x:from>LAX</x:from>
        <x:date>2001-12-20</x:date>
       </x:TravelRequest>
      </x:return>
    </x:ReservationRequest>
  </rdf:RDF>
 </env:Body>
</env:Envelope>

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

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/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: chargeReservation<m:chargeReservation
     env:encodingStyle="http://www.w3.org/2003/05/soap-encoding"
          xmlns:m="http://travelcompany.example.org/">
   <m:reservation xmlns:m="http://travelcompany.example.org/reservation">
    <m:code>FT35ZBQ</m:code>
   </m:reservation>
    <o:creditCard xmlns:o="http://mycompany.example.com/financial">
     <n:name xmlns:n="http://mycompany.example.com/employees">
           Åke Jógvan Øyvind
     </n:name>
     <o:number>123456789099999</o:number>
     <o:expiration>2005-02</o:expiration>
    </o:creditCard>
   </m:chargeReservation
   ></env:Body>
</env:Envelope>

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

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

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

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
  <env:Body>
    <env:Fault>
     <env:Code>
       <env:Value>env:Sender</env:Value>
       <env:Subcode>
        <env:Value>rpc:BadArguments</env:Value>
       </env:Subcode>
     </env:Code>
     <env:Reason>
      <env:Text xml:lang="en-US">Processing error</env:Text>
      <env:Text xml:lang="cs">Chyba zpracování</env:Text>
     </env:Reason>
     <env:Detail>
      <e:myFaultDetails 
        xmlns:e="http://travelcompany.example.org/faults" >
        <e:message>Name does not match card number</e:message>
        <e:errorcode>999</e:errorcode>
      </e:myFaultDetails>
     </env:Detail>
   </env:Fault>
 </env:Body>
</env:Envelope>

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

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" >
  <env:Body>
    <m:retrieveItinerary 
        env:encodingStyle="http://www.w3.org/2003/05/soap-encoding"
             xmlns:m="http://travelcompany.example.org/">
      <m:reservationCode>FT35ZBQ</m:reservationCode>
    </m:retrieveItinerary>
  </env:Body>
</env:Envelope>

GET /Reservations/itinerary?reservationCode=FT35ZBQ  HTTP/1.1
Host: travelcompany.example.org
Accept: application/soap+xml

POST /Reservations?code=FT35ZBQ HTTP/1.1
Host: travelcompany.example.org
Content-Type: application/soap+xml; charset="utf-8"
Content-Length: nnnn

<?xml version='1.0'?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/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: chargeReservation<m:chargeReservation
      env:encodingStyle="http://www.w3.org/2003/05/soap-encoding"
         xmlns:m="http://travelcompany.example.org/">
   <m:reservation xmlns:m="http://travelcompany.example.org/reservation">
    <m:code>FT35ZBQ</m:code>
   </m:reservation>
   <o:creditCard xmlns:o="http://mycompany.example.com/financial">
    <n:name xmlns:n="http://mycompany.example.com/employees">
           Åke Jógvan Øyvind
    </n:name>
    <o:number>123456789099999</o:number>
    <o:expiration>2005-02</o:expiration>
   </o:creditCard>
   </m:chargeReservation ></m:chargeReservation>
 </env:Body>
</env:Envelope>

4.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. However, there is a non-normative W3C Note [SOAP Email Binding] describing an email binding for SOAP, its main purpose being to demonstrate the application of the general SOAP Protocol Binding Framework described in [SOAP Part 1].

Example 14 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 receiver node has SOAP capabilities, to which the body of the email is delivered for processing. (It is assumed that the sending node also has SOAP capabilities so as to be able to process any SOAP faults received in response, or to correlate any SOAP messages received in response to this one.)

From: a.oyvind@mycompany.example.com
To: reservations@travelcompany.example.org
Subject: Travel to LA
Date: Thu, 29 Nov 2001 13:20:00 EST
Message-Id: <EE492E16A090090276D208424960C0C@mycompany.example.com>
Content-Type: application/soap+xml 

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"> 
 <env:Header>
  <m:reservation xmlns:m="http://travelcompany.example.org/reservation" 
      env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
         env:mustUnderstand="true">
    <m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</reference><m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</m: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:role="http://www.w3.org/2003/05/soap-envelope/role/next"
         env:mustUnderstand="true">
   <n:name>Åke Jógvan Øyvind</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>

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

Although 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 [SMTP] 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 the 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 successful data delivery when none occurred.

SMTP delivery status messages are separate from message processing at the SOAP layer. Resulting SOAP responses to the contained SOAP data will be returned through a new email message which may or may not have a link to the original requesting email at the SMTP level. The use of the [RFC 2822] In-reply-to: header can achieve a correlation at the SMTP level, but does not necessarily offer a correlation at the SOAP level.

Example 15 is exactly the same scenario as described for Example 2, which shows the SOAP message (body details omitted for brevity) sent from the travel service application to the travel reservation application seeking clarification on some reservation details, except that 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 header block to correlate SOAP messages. Again, how such correlation is achieved is application-specific, and is not within the scope of SOAP.

From: reservations@travelcompany.example.org
To: a.oyvind@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:<EE492E16A090090276D208424960C0C@mycompany.example.com>
Content-Type: application/soap+xml

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"> 
 <env:Header>
  <m:reservation xmlns:m="http://travelcompany.example.org/reservation" 
     env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
       env:mustUnderstand="true">
    <m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</reference><m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</m: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:role="http://www.w3.org/2003/05/soap-envelope/role/next"
        env:mustUnderstand="true">
   <n:name>Åke Jógvan Øyvind</n:name>
  </n:passenger>
 </env:Header>
 <env:Body>
  <p:itinerary
     xmlns:p="http://travelcompany.example.org/reservation/travel">
   <p:itineraryClarifications>
      ...
      ...
   </p:itineraryClarifications>
  </p:itinerary>
 </env:Body>
</env:Envelope>

5.1 Using SOAP Intermediaries

The travel reservation scenario used throughout the primer offers an opportunity to expose some uses of SOAP intermediaries. Recall that the basic exchange was the exchange of a travel reservation request between a travel reservation application and a travel service application. 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 is not the ultimate receiver. SOAP Version 1.2 describes two types of intermediaries: forwarding intermediaries and active intermediaries.

A forwarding intermediary is a SOAP node which, based on the semantics of a header block in a received SOAP message or based on the message exchange pattern in use, forwards the SOAP message to another SOAP node. For example, processing a "routing" header block describing a message path feature in an incoming SOAP message may dictate that the SOAP message be forwarded to another SOAP node identified by data in that header block. The format of the SOAP header of the outbound SOAP message, i.e., the placement of inserted or reinserted header blocks, is determined by the overall processing at this forwarding intermediary based on the semantics of the processed header blocks.

An active intermediary is one that does additional processing on an incoming SOAP message before forwarding the message using criteria that are not described by incoming SOAP header blocks, or by the message exchange pattern in use. Some examples of such active intervention at a SOAP node could be, for instance, encrypting some parts of a SOAP message and providing the information on the cipher key in a header block, or including some additional information in a new header block in the outbound message providing a timestamp or an annotation, for example, for interpretation by appropriately targeted nodes downstream.

One mechanism by which an active intermediary can describe the modifications performed on a message is by inserting header blocks into the outbound SOAP message. These header blocks can inform downstream SOAP nodes acting in roles whose correct operation depends on receiving such notification. In this case, the semantics of such inserted header blocks should also call for either the same or other header blocks to be (re)inserted at subsequent intermediaries as necessary to ensure that the message can be safely processed by nodes yet further downstream. For example, if a message with header blocks removed for encryption passes through a second intermediary (without the original header blocks being decrypted and reconstructed), then indication that the encryption has occurred must be retained in the second relayed message.

In the following example, a SOAP node is introduced in the message path between the travel reservation and travel service applications, which intercepts the message shown in Example 1. An example of such a SOAP node is one which logs all travel requests for off-line review by a corporate travel office. Note that the header blocks reservation and passenger in that example are intended for the node(s) that assume the role "next", which means that it is targeted at the next SOAP node in the message path that receives the message. The header blocks are mandatory (the mustUnderstand attribute 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. (Note that the specifications of the header blocks must require that the same header blocks be reinserted in the outbound message, because otherwise, the SOAP processing model would require that they be removed.) In this case, the SOAP node acts as a forwarding intermediary.

A more complex scenario is one where the received SOAP message is amended in some way not anticipated by the initial sender. In the following example, it is assumed that a corporate travel application at the SOAP intermediary attaches a header block to the SOAP message from Example 1 before relaying it along its message path towards the travel service application - the ultimate recipient. The header block contains the constraints imposed by a travel policy for this requested trip. 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 role attribute) make use of the information conveyed by it when processing the body of the message.

Example 16 shows an active intermediary inserting an additional header block, travelPolicy, intended for the ultimate recipient which includes information that qualifies the application-level processing of this travel request.

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"> 
 <env:Header>
  <m:reservation xmlns:m="http://travelcompany.example.org/reservation" 
     env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
        env:mustUnderstand="true">
    <m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</reference><m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</m: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:role="http://www.w3.org/2003/05/soap-envelope/role/next"
       env:mustUnderstand="true">
   <n:name>Åke Jógvan Øyvind</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>

5.2 Using Other Encoding Schemes

Even though SOAP Version 1.2 defines a particular encoding scheme (see SOAP Part 2 section 3), its use is optional and the specification makes clear that other encoding schemes may be used for application-specific data within a SOAP message. For this purpose it provides the attribute env:encodingStyle, of type xs:anyURI, to qualify header blocks, any child elements of the SOAP env:Body, and any child elements of the env:Detail element and their descendants. It signals a serialization scheme for the nested contents, or at least the one in place until another element is encountered which indicates another encoding style for its nested contents. The choice of the value for the env:encodingStyle attribute is an application-specific decision and the ability to interoperate is assumed to have been settled "out-of-band". If this attribute is not present, then no claims are being made about the encoding being used.

The use of an alternative encoding scheme is illustrated in Example 17. Continuing with the travel reservation theme, this example shows a SOAP message which is sent to the passenger from the travel service after the reservation is confirmed, showing the travel details. (The same message was used in Example 8b in another context.)

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"> 
 <env:Header>
  <m:reservation xmlns:m="http://travelcompany.example.org/reservation" 
     env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
        env:mustUnderstand="true">
   <m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</m:reference>
   <m:dateAndTime>2001-11-30T16:25:00.000-05:00</m:dateAndTime>
  </m:reservation>
 </env:Header>
 <env:Body>
  <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
            xmlns:x="http://travelcompany.example.org/vocab#"
    env:encodingStyle="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
   <x:ReservationRequest 
 rdf:about="http://travelcompany.example.org/reservations?code=FT35ZBQ">
      <x:passenger>Åke Jógvan Øyvind</x:passenger>
      <x:outbound>
       <x:TravelRequest>
        <x:to>LAX</x:to>
        <x:from>LGA</x:from>
        <x:date>2001-12-14</x:date>
       </x:TravelRequest>
      </x:outbound>
      <x:return>
       <x:TravelRequest>
        <x:to>JFK</x:to>
        <x:from>LAX</x:from>
        <x:date>2001-12-20</x:date>
       </x:TravelRequest>
      </x:return>
    </x:ReservationRequest>
  </rdf:RDF>
 </env:Body>
</env:Envelope>

In Example 17, the body of the SOAP message contains a description of the itinerary using the encoding of a graph of resources and their properties using the syntax of the Resource Description Framework (RDF) [RDF]. (Very briefly, as RDF syntax or usage is not the subject of this primer, an RDF graph relates resources - such as the travel reservation resource available at http://travelcompany.example.org/reservations?code=FT35ZBQ - to other resources (or values) via properties, such as the passenger, the outbound and return dates of travel. The RDF encoding for the itinerary might have been chosen, for example, to allow the passenger's travel application to store it in an RDF-capable calendar application, which could then be queried in complex ways.)

6. Changes Between SOAP 1.1 and SOAP 1.25.3 Optimized serialization of SOAP Version 1.2 hasmessages

The [MTOM] specification provides a mechanism to support such use cases. It should be noted, though, that the specification does not address the general problem of handling the inclusion of non-XML content in arbitrary XML documents, but confines itself to the specific case of SOAP message transmission optimization for certain type of content.

In order to allow for independence from the underlying protocol binding, so that the optimization mechanism may be available over a variety of transports, as well as to retain the principal SOAP binding paradigm - that the SOAP message infoset, however serialized, be transmitted unchanged between adjacent nodes - [MTOM] defines an Abstract SOAP Transmission Optimization feature, of which one implementation is provided for the particular case of HTTP-based transmission of an optimized SOAP message in a MIME Multipart/Related [RFC 2387] package. This makes use of the [XOP] format (on which more in Section 5.3.2) which is an alternative serialization of an XML infoset geared towards a more eficient processing and representation of Base64-encoded content.

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

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"> 
 <env:Header>
  <m:reservation xmlns:m="http://travelcompany.example.org/reservation" 
          env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
           env:mustUnderstand="true">
   :::
  </m:reservation>
  <n:passenger xmlns:n="http://mycompany.example.com/employees"
          env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
           env:mustUnderstand="true">
   :::
  </n:passenger>
 </env:Header>
 <env:Body>
  <o:travelAgencyLogo xmlns:o="http://travelcompany.example.org/images">HlkR4cT
YvAQLAcOAAAAAAQCAAgEAA0GAAEJAAYLAAoNAA8PAAAAJAQCJAgEJA0GJAEJJAYLJAoNJ
A8PJAAASAQCSAgESA0GSAEJSAYLSAoNSA8PSAAQbAQSbAgUbA0WbAEZbAYbbAodbA8fbAAQkAQSk
AgUkA0WkAEZkAYbkAodkA8fkAAgtAQitAgktA0mtAEptAYrtAottA8vtAAg2AQi2Agk2A0m2AEp2
              :::
qG4dSiwpp2eK4LZLr6tuqTWump4H4xSz6G1dioPCqT5eWq5EtdUdJSSoYLAMjqasWYLZYmTOrz+o
7aJOt+aM9rWrxut4DAArILM9t0kShRgCFJaUk+uvAgshVRaPlXebGyv67APwKb9qw/r0di/a6Cxn
lELvZYABAsD==</o:travelAgencyLogo>
  <p:itinerary
    xmlns:p="http://travelcompany.example.org/reservation/travel">
   <p:departure>
     :::
   </p:departure>
   <p:return>     
     :::
   </p:return>
  </p:itinerary>
  <q:lodging
   xmlns:q="http://travelcompany.example.org/reservation/hotels">
   <hotel> 
    :::
   </hotel>
   <r:areaMap xmlns:r="http://travelcompany.example.org/maps">HlkR4kTYMCgoAQMAAAA
AA8///ru6q/8zPzMzM/7v/CLsw6pne+4jPCIgACHcwFWYhBFUQBEQABDM
AEBAsAAAAAAjAIKAAUw/gRRCFlmnopqrFHJvvNyyLw2Ji56789+/ADKcHia3OiMpSEoEobgKHDnS
             :::
w83hCNkr0gECT1bgEaJigpDmwFEvYOkDCgYQLMus1QDgFUYOoGGN+gtPdYYgOMDZLhwyA+BHyDMR
qweAJoAgAcYHvzTQktoAsODhl4LYBIDMevgtHPUDiAmg5gSQTUB8ETxO1HKAJRj4OI70AMeKgriF
LOECAAwO=</r:areaMap>
  </q:lodging>
 </env:Body>
</env:Envelope>

MIME-Version: 1.0
Content-Type: Multipart/Related; boundary=example-boundary; 
  type=application/xop+xml; 
  start="<itinerary123.xml@travelcompany.example.org>";
  startinfo="application/soap+xml;action=\"http://travelcompany.example.org/Process\""
Content-Description: This is an example of an optimized SOAP message

--example-boundary
Content-Type: application/xop+xml; charset=UTF-8
type="application/soap+xml;action=\"http://travelcompany.example.org/Process\""
Content-Transfer-Encoding: 8bit
Content-ID: <itinerary123.xml@travelcompany.example.org>

<?xml version='1.0'?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" 
     xmlns:xmime='http://www.w3.org/2004/06/xmlmime'> 
 <env:Header>
  <m:reservation xmlns:m="http://travelcompany.example.org/reservation" 
          env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
           env:mustUnderstand="true">
   :::
  </m:reservation>
  <n:passenger xmlns:n="http://mycompany.example.com/employees"
          env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
           env:mustUnderstand="true">
   :::
  </n:passenger>
 </env:Header>
 <env:Body>
  <o:travelAgencyLogo xmlns:o="http://travelcompany.example.org/images"
    xmime:contentType='image/jpg'><xop:Include xmlns:xop='http://www.w3.org/2003/12/xop/include' 
      href="cid:logo.gif@travelcompany.example.org"/></o:travelAgencyLogo>
  <p:itinerary
    xmlns:p="http://travelcompany.example.org/reservation/travel">
   <p:departure>
     :::
   </p:departure>
   <p:return>     
     :::
   </p:return>
  </p:itinerary>
  <q:lodging
   xmlns:q="http://travelcompany.example.org/reservation/hotels">
   <hotel> 
    :::
   </hotel>
   <r:areaMap xmlns:r="http://travelcompany.example.org/maps" 
      xmime:contentType="image/jpg"><xop:Include xmlns:xop='http://www.w3.org/2003/12/xop/include' 
         href="cid:map123.jpg@travelcompany.example.org"/></r:areaMap>
  </q:lodging>
 </env:Body>
</env:Envelope>

--example-boundary
Content-Type: image/jpg
Content-Transfer-Encoding: binary
Content-ID: <logo.gif@travelcompany.example.org>

::: the binary data :::

--example-boundary
Content-Type: image/jpg
Content-Transfer-Encoding: binary
Content-ID: <map123.jpg@travelcompany.example.org>

::: the binary data :::

--example-boundary--

HTTP/1.1 200 OK
Content-Type: Multipart/Related; boundary=example-boundary; 
  type=application/xop+xml; 
  start="<itinerary123.xml@travelcompany.example.org>";
  startinfo="application/soap+xml;action=\"http://travelcompany.example.org/Process\""
Content-Description: This is an example of an optimized SOAP message
Content-Length: nnnn

--example-boundary
Content-Type: application/xop+xml; charset=UTF-8
type="application/soap+xml;action=\"http://travelcompany.example.org/Process\""
Content-Transfer-Encoding: 8bit
Content-ID: <itinerary123.xml@travelcompany.example.org>

<?xml version='1.0'?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" 
     xmlns:xmime='http://www.w3.org/2004/06/xmlmime'> 
 <env:Header>
  <m:reservation xmlns:m="http://travelcompany.example.org/reservation" 
          env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
           env:mustUnderstand="true">
   :::
  </m:reservation>
  <n:passenger xmlns:n="http://mycompany.example.com/employees"
          env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
           env:mustUnderstand="true">
   :::
  </n:passenger>
 </env:Header>
 <env:Body>
  <o:travelAgencyLogo xmlns:o="http://travelcompany.example.org/images"
    xmime:contentType='image/jpg'><xop:Include xmlns:xop='http://www.w3.org/2003/12/xop/include' 
      href="cid:logo.gif@travelcompany.example.org"/></o:travelAgencyLogo>
  <p:itinerary
    xmlns:p="http://travelcompany.example.org/reservation/travel">
   <p:departure>
     :::
   </p:departure>
   <p:return>     
     :::
   </p:return>
  </p:itinerary>
  <q:lodging
   xmlns:q="http://travelcompany.example.org/reservation/hotels">
   <hotel> 
    :::
   </hotel>
   <r:areaMap xmlns:r="http://travelcompany.example.org/maps" 
      xmime:contentType="image/jpg"><xop:Include xmlns:xop='http://www.w3.org/2003/12/xop/include' 
         href="cid:map123.jpg@travelcompany.example.org"/></r:areaMap>
  </q:lodging>
 </env:Body>
</env:Envelope>

--example-boundary
Content-Type: image/jpg
Content-Transfer-Encoding: binary
Content-ID: <logo.gif@travelcompany.example.org>

::: the binary data :::

--example-boundary
Content-Type: image/jpg
Content-Transfer-Encoding: binary
Content-ID: <map123.jpg@travelcompany.example.org>

::: the binary data :::

--example-boundary--