A Version Transition from SOAP1.1 to SOAP Version 1.2 | XML, Web Services, and the Data Revolution


Team-Fly

	XML, Web Services, and the Data Revolution By Frank P. Coyle
	Table of Contents

	Appendix B. SOAP Version 1.2 Part 1: Messaging Framework

A Version Transition from SOAP/1.1 to SOAP Version 1.2

The SOAP/1.1 specification[15] says the following on versioning in section 4.1.2:

"SOAP does not define a traditional versioning model based on major and minor version numbers . A SOAP message MUST have an Envelope element associated with the "http://schemas.xmlsoap.org/soap/envelope/" namespace. If a message is received by a SOAP application in which the SOAP Envelope element is associated with a different namespace, the application MUST treat this as a version error and discard the message. If the message is received through a request/response protocol such as HTTP, the application MUST respond with a SOAP VersionMismatch faultcode message (see section 4.4) using the SOAP "http://schemas.xmlsoap.org/soap/envelope/" namespace."

That is, rather than a versioning model based on shortnames (typically version numbers), SOAP uses a declarative extension model which allows a sender to include the desired features within the SOAP envelope construct. SOAP says nothing about the granularity of extensions nor how extensions may or may not affect the basic SOAP processing model. It is entirely up to extension designers be it either in a central or a decentralized manner to determine which features become SOAP extensions.

The SOAP extensibility model is based on the following three basic assumptions:

SOAP versioning is directed only at the SOAP envelope. It explicitly does not address versioning of blocks, encodings, protocol bindings, or otherwise .
A SOAP node must determine whether it supports the version of a SOAP message on a per message basis. In the following, "support" means understanding the semantics of the envelope version identified by the QName of the Envelope element information item:
- A SOAP node receiving an envelope that it doesn't support must not attempt to process the message according to any other processing rules regardless of other up- or downstream SOAP nodes.
- A SOAP node may provide support for multiple envelope versions. However, when processing a message a SOAP node must use the semantics defined by the version of that message.
It is essential that the envelope remains stable over time and that new features are added using the SOAP extensibility mechanism. Changing the envelope inherently affects interoperability, adds complexity, and requires central control of extensions ”all of which directly conflicts with the SOAP requirements.

The rules for dealing with the possible SOAP/1.1 and SOAP Version 1.2 interactions are as follows :

Because of the SOAP/1.1 rules, a compliant SOAP/1.1 node receiving a SOAP Version 1.2 message will generate a Version-Mismatch SOAP fault using an envelope qualified by the "http://schemas.xmlsoap.org/soap/envelope/" namespace identifier.
A SOAP Version 1.2 node receiving a SOAP/1.1 message may either process the message as SOAP/1.1 or generate a SOAP VersionMismatch fault using the "http://schemas.xmlsoap.org/soap/envelope/" namespace identifier. As part of the SOAP VersionMismatch fault, a SOAP Version 1.2 node should include the list of envelope versions that it supports using the SOAP upgrade extension identified by the "http://www.w3.org/2001/12/soap-upgrade" identifier.

The upgrade extension consists of an Upgrade element information item.

The Upgrade element information item contains an ordered list of namespace identifiers of SOAP envelopes that the SOAP node supports in the order most to least preferred.

The Upgrade element information item has:

A local name of Upgrade ;
A namespace name of http://www.w3.org/2001/12/soap-upgrade ;
One or more envelope child element information items as described below.

The envelope element information item has:

A local name of envelope ;
A namespace name which is empty;
An unqualified attribute information item with a local name of qname and a type of QName in the "http://www.w3.org/2001/XMLSchema" namespace.

The value of the qname attribute information item specifies the qualified name of an element that the SOAP node accepts as the top-level element of a SOAP message

Following is an example of a VersionMismatch fault generated by a SOAP Version 1.2 node including the SOAP upgrade extension:

Example: VersionMismatch fault generated by a SOAP Version 1.2 node, and including a SOAP upgrade extension

 <?xml version="1.0" ?> <env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/  envelope/">   <env:Header>     <V:Upgrade xmlns:V="http://www.w3.org/2001/12/soap-upgrade">       <envelope qname="ns1:Envelope"        xmlns:ns1="http://  www.w3.org/2001/12/soap-envelope"/>     </V:Upgrade>   </env:Header>   <env:Body>     <env:Fault>       <faultcode>env:VersionMismatch</faultcode>       <faultstring>Version Mismatch</faultstring>     </env:Fault>   </env:Body> </env:Envelope>

The following is an example of some future SOAP node which returns multiple envelope elements in the Upgrade element. This SOAP node prefers the Envelope element in the "http://www.example.org/2002/10/soap-envelope" namespace but will also accept the Envelope element in the "http://www.w3.org/2001/12/soap-envelope" namespace.

Example: VersionMismatch fault generated by some future SOAP node, and including a SOAP upgrade extension with multiple envelope elements

 <?xml version="1.0" ?> <env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/  envelope/">   <env:Header>     <V:Upgrade xmlns:V="http://www.w3.org/2001/12/soap-upgrade">       <envelope qname="ns1:Envelope" xmlns:ns1="http://www.  example.org/2002/10/soap-envelope"/>       <envelope qname="ns2:Envelope" xmlns:ns2="http://www.w3.  org/2001/12/soap-envelope"/>     </V:Upgrade>   </env:Header>   <env:Body>     <env:Fault>       <faultcode>env:VersionMismatch</faultcode>       <faultstring>Version Mismatch</faultstring>     </env:Fault>   </env:Body> </env:Envelope>

Note that existing SOAP/1.1 nodes are not likely to indicate which envelope versions they support. If nothing is indicated then this means that SOAP/1.1 is the only supported envelope.


Team-Fly

Top