As part of the SOAP naming proposal in Dinard [4], I promised to provide
a detailed proposal for how to deal with the transition from SOAP/1.1 to
SOAP/1.2 and consider whether this may or may not work for additional
transitions as we move forward. The goal of the proposal below is to
allow for as smooth a transition as possible.

Note, that this model is likely to also affecting the discussion about
whether to qualify elements and attributes that are part of the SOAP
envelope [3]. I think the only consistent manner in which we can
guarantee a reliable and consistent processing model is to require that
all elements and attributes defined by the SOAP envelope are namespace
qualified.

Below is the proposed wording for a clarifying appendix to the SOAP/1.2
spec regarding versioning. Because it is appendix material, I have not
used uppercase conventions for requirements. As background reading to
why this model was chosen, I direct people at RFC 2145 [2] which talks
about the complexities of HTTP versioning.

* * * * * * * * * *

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

"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 four basic
assumptions:

1) SOAP versioning is directed only at the SOAP envelope. It does
explicitly not address versioning of modules, encodings, protocol
bindings, or otherwise.

2) A SOAP processor must determine whether it supports a SOAP message on
a per message basis. In the following, "support" means understanding the
semantics of the envelope identified by the SOAP envelope namespace
identifier:

    * A SOAP processor 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 processors.

    * A SOAP processor may provide support for multiple
	envelopes. However, when processing a message a SOAP
	processor must use the semantics defined by the
	envelope of that message.

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

4) No versioning model or extensibility model can prevent buggy
implementations. Even though significant work has been going into
clarifying the SOAP processing model, there is no guarantee that a
SOAP/1.2 will behave correctly. Only extensive testing within the SOAP
community and design simplicity at the core can help prevent/catch bugs.

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

1) Because of the SOAP/1.1 rules [1], a compliant SOAP/1.1 processor
receiving a SOAP/1.2 message will generate a VersionMismatch SOAP fault
using an envelope qualified by the
"http://schemas.xmlsoap.org/soap/envelope/" namespace identifier.

2) A SOAP/1.2 processor 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/1.2 processor should
include the list of envelope versions that it supports using the SOAP
upgrade module identified by the
"http://www.w3.org/2001/06/soap-upgrade" identifier.

The upgrade module contains an ordered list of namespace identifiers of
SOAP envelopes that the SOAP processor supports in the order most to
least preferred. Following is an example of a VersionMismatch fault
generated by a SOAP/1.2 processor including the SOAP upgrade module
(ednote: schema to follow):

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

Note that existing SOAP/1.1 processors 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.

* * * * * * * * * * 

How does this sound?

Henrik Frystyk Nielsen 
mailto:henrikn@microsoft.com 

[1] http://www.w3.org/TR/SOAP/#_Toc478383496
[2] http://www.normos.org/ietf/rfc/rfc2145.txt
[3] http://lists.w3.org/Archives/Public/xml-dist-app/2001Jun/0026.html
[4]
http://lists.w3.org/Archives/Member/w3c-xml-protocol-wg/2001Jun/0024.htm
l