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.
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.
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
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.
This section describes the "big picture" changes between SOAP 1.1 and SOAP 1.2. Detailed changes are decribed in Detailed Changes .
From version 1.2, SOAP is no longer an acronym. The original expansion "Simple Object Access Protocol" is somewhat misleading.
[SOAP 1.1] is a single document. The SOAP 1.2 specification comes in three parts:
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.
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.
This section describes detailed changes between SOAP 1.1 and SOAP 1.2. "Big picture" changes are decribed in "Big Picture" Changes .
This section describes changes to the envelope structure.
SOAP 1.1 allows additional elements to follow the SOAP Body element, SOAP 1.2 disallows these. Table 1 illustrates this.
| SOAP 1.1 | SOAP 1.2 | ||
|---|---|---|---|
|
|
Table 1
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:
SOAP 1.2 adds new fault codes:
encodingStyle attribute.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.1 | SOAP 1.2 | ||
|---|---|---|---|
|
|
||
|
|
||
|
|
||
|
|
||
|
|
Table 2
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.1 | SOAP 1.2 | ||
|---|---|---|---|
|
|
Table 3
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.
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>
|
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:
role attribute for which it will
assume processing liability.mustUnderstand="true" attribute and a
role attribute with a value matching one of the
roles determined in step 1.SOAP 1.2 adds semantics for deailing with messages from different versions of SOAP:
Upgrade header
with a list of the supported envelope versions.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>
|
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.
SOAP 1.2 provides a similar but simplified version of the encoding provided by SOAP 1.1. The following subsections describes the differences.
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.
In SOAP 1.2 multireference values may be encoded in-place rather than as "top-level" elements. Table 4 illustrates this.
| SOAP 1.1 | SOAP 1.2 | ||
|---|---|---|---|
|
|
Table 4
Graph edges in SOAP encoding are represented differently in SOAP 1.1 and SOAP 1.2. Table 5 illustrates this.
| SOAP 1.1 | SOAP 1.2 | |
|---|---|---|
| Attribute | href | ref |
| Type | uri-reference | IDREF |
| Examples | #henryford, http://example.com/picture.gif | henryford |
Table 5
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.1 | SOAP 1.2 | ||
|---|---|---|---|
|
|
Table 6
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.
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.
In SOAP 1.2 an omitted accessor is equivalent to NIL. The semantics of a NIL accessor are explicitly application dependent.
This section describes the differences between the SOAP 1.2 and SOAP 1.1 RPC conventions.
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 ).
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>
|
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>
|
SOAP 1.2 adds new RPC specific fault subcodes:
SOAP 1.2 adds a new convention for representing RPC return values. Table 7 illustrates this.
| SOAP 1.1 | SOAP 1.2 | ||
|---|---|---|---|
|
|
Table 7
This section discusses differences between the SOAP 1.2 and SOAP 1.1 HTTP binding.
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.
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>
|
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.