What's New in SOAP 1.2

»Marc Hadley, »Sun Microsystems

•

email author •

PDF version •

forward abstract •

latest version •

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.

Keywords

»SOAP, »web services.

Table of Contents

1. Introduction

2. "Big Picture" Changes

2.1. Acronym
2.2. Documents
2.3. Infoset
2.4. XML Namespaces

3. Detailed Changes

3.1. Envelope

3.1.1. Trailers
3.1.2. Actors and Roles
3.1.3. Fault Codes
3.1.4. Hierarchical Fault Codes
3.1.5. Misunderstood Header

3.2. Processing Model

3.3. Versioning Mechanism

3.3.1. Upgrade Header

3.4. Binding Framework

3.5. Encoding

3.5.1. Multi-reference Values
3.5.2. References
3.5.3. Arrays
3.5.4. Application to XML Name Mapping
3.5.5. Serialisation Roots
3.5.6. Omitted Accessors

3.6. RPC

3.7. HTTP Binding

Bibliography

Biography

1. 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 Section 2.2) can be broadly categorised into "big picture" and "detailed" chnages. The following sections describe the changes in each of these categories.

2. "Big Picture" Changes

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

2.1. Acronym

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

2.2. Documents

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

[SOAP 1.2 - Part 0] is a non-normative introduction to SOAP.
[SOAP 1.2 - Part 1] describes the structure of SOAP messages, the SOAP processing model and a framework for binding SOAP to underlying protocols. Conformant SOAP implementations must implement everything in Part 1.
[SOAP 1.2 - Part 2] describes optional add-ins to the core of SOAP including a data model and encoding, an RPC convention and a binding to HTTP. Conformant SOAP implementations may implement anything in Part 2, if they do so they must conform to the relevent parts of the specification.

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

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

3. Detailed Changes

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

3.1. Envelope

This section describes changes to the envelope structure.

3.1.1. Trailers

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

Table 1.

SOAP 1.1	SOAP 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>

SOAP 1.1

SOAP 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>

3.1.2. 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:

"None" for header blocks that should never be directly processed.
"Ultimate Receiver" for header blocks that should only be processed by nodes acting as the ultimate receiver of a message.

3.1.3. Fault Codes

SOAP 1.2 adds new fault codes:

"DTDNotSupported" - generated when a received message contains a document type declaration.
"DataEncodingUnknown" - generated when a received message uses an unrecognised value of the encodingStyle attribute.
The SOAP 1.1 "Client" fault code is renamed "Sender" in SOAP 1.2.
The SOAP 1.1 "Server" fault code is renamed "Receiver" in SOAP 1.2.
Additional faults are added for RPC, see Section 3.6.

3.1.4. 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 2 illustrates this.

Table 2.

SOAP 1.1	SOAP 1.2
<e:Fault> <faultcode>e:Server.Memory</faultcode> <faultstring>Out of memory</faultstring> </e:Fault>	<e:Fault> <faultcode> <value>e:Receiver</value> <subcode> <value>p:Memory</value> </subcode> </faultcode> <faultstring>Out of memory</faultstring> </e:Fault>

SOAP 1.1

SOAP 1.2

<e:Fault>
  <faultcode>e:Server.Memory</faultcode>
  <faultstring>Out of memory</faultstring>
</e:Fault>

<e:Fault>
  <faultcode>
    <value>e:Receiver</value>
    <subcode>
      <value>p:Memory</value>
    </subcode>
  </faultcode>
  <faultstring>Out of memory</faultstring>
</e:Fault>

3.1.5. 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>
      <faultcode>
        <value>e:MustUnderstand</value>
      </faultcode>
      <faultstring>Headers not understood</faultstring>
    </e:Fault>
  </e:Body>
</e:Envelope>

3.2. 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:

Determine the roles the node is to play. I.e. the values of the role attribute for which it will assume processing liability.
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.
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.
Process headers and, if the node is the ultimate receipient, the body of the message.
If the node is acting as an intermediary remove headers targetted at the node and forward the message.

3.3. Versioning Mechanism

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

A SOAP 1.2 node that receives a SOAP 1.1 message will respond with a SOAP 1.1 envelope containing a SOAP 1.1 "VersionMismatch" fault.
A SOAP 1.2 node that receives a message from any other version of SOAP (including future versions) will respond with a SOAP 1.2 envelope containing a SOAP 1.2 "VersionMismatch" fault and an Upgrade header with a list of the supported envelope versions.

3.3.1. 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://www.w3.org/2002/10/soap-envelope"/>
  <envelope
    qname="ns2:Envelope" 
    xmlns:ns2="http://www.w3.org/2001/12/soap-envelope"/>
</V:Upgrade>

3.4. Binding Framework

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

Sets out requirements and concepts common to all binding specifications.
Facilitates homogenous description of bindings that support common features.
Facilitates homogenous description of optional features.

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

3.5. Encoding

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

3.5.1. Multi-reference Values

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

Table 3.

SOAP 1.1	SOAP 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>

SOAP 1.1

SOAP 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>

3.5.2. References

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

Table 4.

	SOAP 1.1	SOAP 1.2
Attribute	href	ref
Type	uri-reference	IDREF
Examples	#henryford, http://example.com/picture.gif	henryford

3.5.3. 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 5 illustrates this.

Table 5.

SOAP 1.1	SOAP 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>

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

3.5.5. Serialisation Roots

It is mandatory to mark serialisation roots using the root attribute with a value of "true" in SOAP 1.2.

3.5.6. Omitted Accessors

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

3.6. RPC

SOAP 1.2 adds new RPC specific error subcodes:

"ProcedureNotPresent"
"BadArguments"

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

Table 6.

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

3.7. HTTP Binding

The SOAP 1.1 mandatory SOAPAction HTTP header is optional in SOAP 1.2. A new HTTP status code allows servers to request a SOAPAction header if they require one.

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.

The Content-Type for SOAP 1.2 has changed from text/xml used in SOAP 1.1 to application/soap+xml.

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

Biography

»Marc Hadley

»Sun Microsystems

»Bagshot

»UK

Email: marc.hadley@sun.com

Web: http://www.sun.com/xml/

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.