What's New in SOAP 1.2

Keywords: SOAP, Web Services

Marc Hadley
Sun Microsystems
Bagshot
United Kingdom
marc.hadley@sun.com
http://www.sun.com/xml/

Biography

Marc Hadley is a Staff Engineer in the XML Technology Centre at Sun Microsystems. He currently represents Sun on the W3C XML Protocol Working Group where he is co-editor of the SOAP 1.2 specification.

Prior to joining Sun Microsystems, Marc worked for Chrystal Software as a principle consultant and chief engineer developing content management and web delivery systems based on XML.


Abstract


SOAP is currently the subject of a standardisation effort at the W3C. This paper describes the differences between SOAP 1.1 and SOAP 1.2, SOAP 1.2 being the results of the standardisation process.

This document is based on SOAP 1.2 Last Call Working Draft, June 2002. As the SOAP specification is not yet a W3C Recommendation, further changes are possible.


Table of Contents


Introduction
"Big Picture" Changes
     Acronym
     Documents
     Infoset
     XML Namespaces
Detailed Changes
     Envelope
         Trailers
         Actors and Roles
         Fault Codes
         Modified Fault Structure
         Hierarchical Fault Codes
         Modified Fault Semantics
         Misunderstood Header
     Processing Model
     Versioning Mechanism
         Upgrade Header
     Binding Framework
     Encoding
         encodingStyle Attribute
         Multi-reference Values
         References
         Arrays
         Application to XML Name Mapping
         Serialisation Roots
         Omitted Accessors
     RPC
         Use of RPC on the World Wide Web
         RPC Array Representation
         RPC Encoding Constraint
         RPC Fault Codes
         RPC Return Values
     HTTP Binding
         Content Type
         HTTP GET Support
         Miscellaneous Changes
Bibliography

Introduction

This paper outlines the differences between SOAP 1.1 and SOAP 1.2. It is not intended as an in-depth description of new or changed features, rather it aims to highlight the existence of such differences. Readers are referred to the relevent specifications for more in-depth coverage.

The differences between [SOAP 1.1] and SOAP 1.2 (see Documents ) can be broadly categorised into "big picture" and "detailed" changes. The following sections describe the changes in each of these categories.

"Big Picture" Changes

This section describes the "big picture" changes between SOAP 1.1 and SOAP 1.2. Detailed changes are decribed in Detailed Changes .

Acronym

From version 1.2, SOAP is no longer an acronym. The original expansion "Simple Object Access Protocol" is somewhat misleading.

Documents

[SOAP 1.1] is a single document. The SOAP 1.2 specification comes in three parts:

Infoset

SOAP 1.1 is based on [XML 1.0] , SOAP 1.2 is based on [XML Infoset] . In SOAP 1.2 it is left to the specification of a binding to an underlying protocol to specify the XML serialisation used in underlying protocol data units. The HTTP binding specified in [SOAP 1.2 - Part 2] uses XML 1.0 as the serialisation of the SOAP message infoset.

XML Namespaces

The XML namespaces for the envelope and encoding schemas have changed. This allows SOAP processors to easily distinguish between SOAP 1.1 and SOAP 1.2 messages and allows changes in the SOAP schema without affecting existing implementations.

Detailed Changes

This section describes detailed changes between SOAP 1.1 and SOAP 1.2. "Big picture" changes are decribed in "Big Picture" Changes .

Envelope

This section describes changes to the envelope structure.

Trailers

SOAP 1.1 allows additional elements to follow the SOAP Body element, SOAP 1.2 disallows these. Table 1 illustrates this.

SOAP 1.1SOAP 1.2
<e:Envelope ...>
  <e:Header>
    0 or more headers
  </e:Header>
  <e:Body>
    message body
  </e:Body>
  other elements
</e:Envelope>
<e:Envelope ...>
  <e:Header>
    0 or more headers
  </e:Header>
  <e:Body>
    message body
  </e:Body>
</e:Envelope>
Table 1

Actors and Roles

SOAP 1.1 has the actor attribute. In SOAP 1.2 this attribute is renamed to role. The semantics of the attribute are unchanged.

SOAP 1.2 adds two new predefined roles to the existing "Next" role in SOAP 1.1:

Fault Codes

SOAP 1.2 adds new fault codes:

Modified Fault Structure

SOAP 1.2 faults are structured differently to SOAP 1.1. In particular all fault elements are now namespace qualified, many have been renamed and fault codes are now hierarchical (see Hierarchical Fault Codes ). Table 2 shows the mapping between SOAP 1.1 and SOAP 1.2 faults.

SOAP 1.1SOAP 1.2
e:Fault
e:Fault
faultcode
e:Code, e:Subcode, e:Value
faultstring
e:Reason
faultactor
e:Node, e:Role
detail
e:Detail
Table 2

Hierarchical Fault Codes

SOAP 1.1 allows extension of fault codes using a "dot" notation, SOAP 1.2 disallows this and provides a more XML-like representation instead. Table 3 illustrates this.

SOAP 1.1SOAP 1.2
<e:Fault>
  <faultcode>e:Server.Memory</faultcode>
  <faultstring>Out of memory</faultstring>
</e:Fault>
<e:Fault>
  <e:Code>
    <e:Value>e:Receiver</e:Value>
    <e:Subcode>
      <e:Value>p:Memory</e:Value>
    </e:Subcode>
  </e:Code>
  <e:Reason>Out of memory</e:Reason>
</e:Fault>
Table 3

Modified Fault Semantics

SOAP 1.2 constrains the body of a SOAP fault message to only contain a single child element, that element being the SOAP Fault element. The semantics of a SOAP message containing a SOAP Fault element plus sibling elements are not defined.

Misunderstood Header

SOAP 1.2 adds a new standard header for reporting additional information in "MustUnderstand" faults. In the example shown below, a receiver is reporting that it failed to understand two mandatory headers: abc:Extension1 and def:Extension2.

<e:Envelope>
  <e:Header>
    <f:Misunderstood qname='abc:Extension1'/>
    <f:Misunderstood qname='def:Extension2'/>
  </e:Header>
  <e:Body>
    <e:Fault>
      <e:Code>
        <e:Value>e:MustUnderstand</e:Value>
      </e:Code>
      <e:Reason>Headers not understood</e:Reason>
    </e:Fault>
  </e:Body>
</e:Envelope>

Processing Model

SOAP 1.2 clarifies the processing model of SOAP 1.1. In particular a SOAP node should process an incoming message according to the following rules in the order given:

  1. Determine the roles the node is to play. I.e. the values of the role attribute for which it will assume processing liability.
  2. Identify mandatory headers targetted to the node. I.e. header marked with a mustUnderstand="true" attribute and a role attribute with a value matching one of the roles determined in step 1.
  3. Generate a "MustUnderstand" fault if one or more of the headers identified in step is not understood. I.e. the node does not contain software for processing the header.
  4. Process headers and, if the node is the ultimate receipient, the body of the message.
  5. If the node is acting as an intermediary remove headers targetted at the node and forward the message.

Versioning Mechanism

SOAP 1.2 adds semantics for deailing with messages from different versions of SOAP:

Upgrade Header

SOAP 1.2 adds an Upgrade header that is used to carry the supported envelope versions when a node reports a "VersionMismatch" fault. An example is shown below.

<V:Upgrade xmlns:V="http://www.w3.org/2001/12/soap-envelope">
  <envelope
    qname="ns1:Envelope" 
    xmlns:ns1="http://schemas.xmlsoap.org/soap/envelope/"/>
  <envelope
    qname="ns2:Envelope" 
    xmlns:ns2="http://www.w3.org/2001/12/soap-envelope"/>
</V:Upgrade>

Binding Framework

SOAP 1.1 defines a single binding to HTTP. SOAP 1.2 defines an abstract binding framework that:

SOAP 1.2 also defines a concrete binding to HTTP and a non-normative email binding.

Encoding

SOAP 1.2 provides a similar but simplified version of the encoding provided by SOAP 1.1. The following subsections describes the differences.

encodingStyle Attribute

In SOAP 1.2 the encodingStyle attribute may only be used on child elements of the Body, Header and fault Detail elements. In SOAP 1.1, the attribute is allowed on any element in the envelope.

Multi-reference Values

In SOAP 1.2 multireference values may be encoded in-place rather than as "top-level" elements. Table 4 illustrates this.

SOAP 1.1SOAP 1.2
<e:Books>
  <e:Book>
    <title>My Life and Work
    </title>
    <author href="#henryford" />
  </e:Book>
  <e:Book>
    <title>Today and Tomorrow
    </title>
    <author href="#henryford" />
  </e:Book>
</e:Books>
<author id="henryford">
 <name>Henry Ford</name>
</author>
<e:Books>
   <e:Book>
      <title>My Life and Work</title>
      <author id="henryford" >
         <name>Henry Ford</name>
      </author>
   </e:Book>
   <e:Book>
      <title>Today and Tomorrow</title>
      <author ref="henryford" />
   </e:Book>
</e:Books>
Table 4

References

Graph edges in SOAP encoding are represented differently in SOAP 1.1 and SOAP 1.2. Table 5 illustrates this.

SOAP 1.1SOAP 1.2
Attributehrefref
Typeuri-referenceIDREF
Examples#henryford, http://example.com/picture.gifhenryford
Table 5

Arrays

SOAP 1.1 partially transmitted and sparse arrays have been removed in SOAP 1.2. In addition the SOAP 1.1 arrayType attribute has been replaced with itemType and arraySize attributes. Table 6 illustrates this.

SOAP 1.1SOAP 1.2
<numbers enc:arrayType="xs:int[2]">
  <number>3</number> 
  <number>4</number> 
</numbers>
<numbers enc:itemType="xs:int" enc:arraySize="2">
  <number>3</number>
  <number>4</number>
</numbers>
Table 6

Application to XML Name Mapping

SOAP 1.2 defines an algorithm for mapping between application and XML names. This is required due to restrictions on allowed element names in XML.

Serialisation Roots

SOAP 1.1 included a root attribute that could be used to mark roots of an encoded graph. SOAP 1.2 removes this attribute. See RPC Encoding Constraint for details of how to determine the element that represents an RPC invocation or response.

Omitted Accessors

In SOAP 1.2 an omitted accessor is equivalent to NIL. The semantics of a NIL accessor are explicitly application dependent.

RPC

This section describes the differences between the SOAP 1.2 and SOAP 1.1 RPC conventions.

Use of RPC on the World Wide Web

A common implementation pattern for SOAP 1.1 is to deploy a single SOAP endpoint at a particular URI and then internally dispatch SOAP requests to application logic. This approach hides all of the resources provided by the endpoint behind a single URI and prevents direct addressing of individual resources. E.g. a travel company might provide the following services via SOAP: flight searches, flight booking, hotel searches, hotel booking, car booking, itinerary management, travel insurance services, etc. However if all of these services are hidden behind the same URI then they are effectively invisible in URI space. This approach effectively reduces the world wide web to a transport layer and negates the impressive robustness and scaleability of the current web architecture.

SOAP 1.2 recommends that, where practical, separate resources are identified by separate URIs such that SOAP endpoints fit into the web architecture in the same way as other web accessible resources. This has the added advantage that SOAP resources are now suitable for use with the HTTP GET method instead of being tied to HTTP POST (see HTTP GET Support ).

RPC Array Representation

SOAP 1.2 allows the use of either an array or a struct to represent RPC invocations and responses. SOAP 1.1 allows only structs.

The array based serialisation is useful in circumstances where the number of arguments is not known in advance or in languages that support only positional arguments. E.g. the following SOAP Body shows an invocation of a function that takes a variable number of arguments.

<e:Envelope xmlns:e='...'>
  <e:Body>
    <f:addNumbers xmlns:f='...' e:encodingStyle='...'>
      <n>10</n>
      <n>15</n>
      ...
      <n>3</n>
    </f:addNumbers>
  </e:Body>
</e:Envelope>

RPC Encoding Constraint

SOAP 1.2 constrains the body of a SOAP message using the SOAP encoding for RPC to only contain a single child element, that child representing the RPC invocation or response struct or array.

E.g. the following SOAP Body would be valid according to the SOAP encoding, but not valid when used in conjuction with the RPC convention.

<e:Envelope xmlns:e='...'>
  <e:Body>
    <f:addNumbers xmlns:f='...' e:encodingStyle='...'>
      <n ref='aNum'/>
      <n ref='aNum'/>
    </f:addNumbers>
    <n id='aNum'>10</num>
  </e:Body>
</e:Envelope>

Whilst the following SOAP Body (which is an alternative serialisation of the same struct) would be valid according to the SOAP encoding and also valid when used in conjuction with the RPC convention.

<e:Envelope xmlns:e='...'>
  <e:Body>
    <f:addNumbers xmlns:f='...' e:encodingStyle='...'>
      <n id='aNum'>10</n>
      <n ref='aNum'/>
    </f:addNumbers>
  </e:Body>
</e:Envelope>

RPC Fault Codes

SOAP 1.2 adds new RPC specific fault subcodes:

RPC Return Values

SOAP 1.2 adds a new convention for representing RPC return values. Table 7 illustrates this.

SOAP 1.1SOAP 1.2
<e:Body>
  <m:GetTradePriceResponse>
    <xxx>34.5</xxx>
  </m:GetTradePriceResponse>
</e:Body>
<e:Body>
  <m:GetTradePriceResponse>
    <rpc:result>xxx</rpc:result>
    <xxx>34.5</xxx>
  </m:GetTradePriceResponse>
</e:Body>
Table 7

HTTP Binding

This section discusses differences between the SOAP 1.2 and SOAP 1.1 HTTP binding.

Content Type

The media type for SOAP 1.2 has changed from text/xml used in SOAP 1.1 to application/soap+xml. The application/soap+xml media type is described in [application/soap+xml] .

The SOAP 1.1 mandatory SOAPAction HTTP header has been removed in SOAP 1.2. In its place is an optional action parameter on the application/soap+xml media type.

HTTP GET Support

The HTTP binding for SOAP 1.1 only discusses use of the HTTP POST method for carrying SOAP messages. This has been widely criticized since it negates the optimisation possibilities conveyed by the semantics HTTP GET - namely that the action performed in response to the GET is both safe (information retrieval only) and idempotent (side effects of N>0 identical requests are the same as for a single request). In practice this makes GET requests good candidates for cacheing and also permits use of read locks in databases etc.

SOAP 1.2 adds support for the use of HTTP GET in the SOAP HTTP binding. The semantics of HTTP GET are respected such that the action performed by SOAP endpoint responding to a request transmitted via HTTP GET should be both safe and idempotent.

An example of a HTTP GET request is shown below:

GET /itinerary?reservation=1234567890 HTTP/1.1
Host: travelcompany.com
Accept: application/soap+xml

Note the use of the Accept header to indicate that a SOAP response is required. The SOAP node might respond with:

HTTP/1.1 200 OK
Content-Type: application/soap+xml
Content-Length: nnnn

<?xml version="1.0"?>
<e:Envelope xmlns:e='...'>
  <e:Body>
    <f:itinerary xmlns:f='...'>
      <f:itinid>1234567890</f:itinid>
      ...
    </f:itinerary>
  </e:Body>
</e:Envelope>

Miscellaneous Changes

SOAP 1.2 does not provide a binding to the experimental HTTP extension framework.

SOAP 1.2 provides a finer grained mapping between SOAP errors and HTTP status codes than SOAP 1.1.

Bibliography

[SOAP 1.1]
W3C Note "Simple Object Access Protocol (SOAP) 1.1", Don Box, David Ehnebuske, Gopal Kakivaya, Andrew Layman, Noah Mendelsohn, Henrik Nielsen, Satish Thatte, Dave Winer, 8 May 2000. (See http://www.w3.org/TR/SOAP/).
[SOAP 1.2 - Part 0]
W3C Working Draft "SOAP Version 1.2 Part 0: Primer", Nilo Mitra, Dec 2001. (See http://www.w3.org/TR/soap12-part0/).
[SOAP 1.2 - Part 1]
W3C Working Draft "SOAP Version 1.2 Part 1: Messaging Framework", Martin Gudgin, Marc Hadley, Jean-Jacques Moreau, Henrik Frystyk Nielsen, Dec 2001. (See http://www.w3.org/TR/soap12-part1/).
[SOAP 1.2 - Part 2]
W3C Working Draft "SOAP Version 1.2 Part 2: Adjuncts", Martin Gudgin, Marc Hadley, Jean-Jacques Moreau, Henrik Frystyk Nielsen, Dec 2001. (See http://www.w3.org/TR/soap12-part2/).
[XML 1.0]
W3C Recommendation "Extensible Markup Language (XML) 1.0 (Second Edition)", Tim Bray, Jean Paoli, C. M. Sperberg-McQueen, Eve Maler, 6 October 2000. (See http://www.w3.org/TR/2000/REC-xml-20001006).
[XML Infoset]
W3C Recommendation "XML Information Set", John Cowan, Richard Tobin, 24 October 2001. (See http://www.w3.org/TR/2001/REC-xml-infoset-20011024/).
[application/soap+xml]
IETF "INTERNET DRAFT: The 'application/soap+xml' media type", M. Baker, M. Nottingham, January 14, 2002. (Work in progress). (See http://www.ietf.org/internet-drafts/draft-baker-soap-media-reg-00.txt.)