Inconsistencies in SOAP 1.1 part 1 Versioning model

Reading through the versioning model in SOAP 1.2 part 1, I came across
two problems which I think we have to fix. They seem to be a left-over
from issue 135 [0] although I can't find any resolution in the
discussion thread [1]. Here is a discussion of the issues and proposed
resolution - comments welcome!

DISCUSSION
----------

1) A long time ago as part of the discussion [1] of issue 135 [0], we
agreed on that the SOAP versioning model is based on the namespace
identifier only and NOT any other part of the envelope. That is, IIF the
namespace URI is NOT the URI identifying the SOAP 1.2 namespace must a
SOAP node generate a SOAP fault with a VersionMismatch fault code.

However, this seems inconsistent with the definition of the Upgrade
header block which describes not only the namespace identifier but also
the local name of the envelope information item. The main reason for
this was so that it is possible to schema validate. Also, in the
definition of the VersionMismatch fault it is not clear on whether it is
only the namespace or the element information item - the envelope
element information is defined to have a local name of "Envelope":

"The processing party found an invalid namespace for the SOAP Envelope
element information item (see 4.1.2 Envelope Versioning Model)".

2) Appendix A talks about the case of receiving SOAP/1.1 messages but
the use of VersionMismatch applies to all namespaces and not only
SOAP/1.1 messages. However, the current text is not clear on whether the
VersionMismatch faultcode in all cases should be accompanied with the
Upgrade element information item expressing which envelope(s) is
supported. Mark Nottingham as well as others pointed this out in the
issue 135 thread [1] but there is no record of it being addressed.

PROPOSAL OUTLINE
----------------

I think the changes to straighten out these problems are fairly small
but important in order to get a consistent spec. Here is what I suggest
we do:

a) Say that versioning is determined based on the namespace name AND
local name of the document information item. If the namespace name AND
local name doesn't match then generate a VersionMismatch fault. Any
other malformation results in a Sender fault.

b) Say that ALL VersionMismatch faults SHOULD use the Upgrade header
block for describing which revision they support. Editorially, this
means moving the description of the Upgrade header block into section
3.4 [5] rather than having it in appendix A [4].

c) Make it absolutely clear that SOAP/1.1 is ONLY used when explicitly
interacting with SOAP/1.1 nodes following the transition strategy
defined by appendix A. In all other cases do we ONLY use SOAP Version
1.2.

d) Clarify the text as in particular appendix A [4] shows signs of not
having been written for use in a spec but rather as background.

PROPOSED RESOLUTION
-------------------

The proposed resolution contains three parts:

  i) Replace existing section 3.1 [2] with clarified text.
     Other than the change to use a qualified name, all
     edits are editorial in nature.

 ii) Insert section on "Upgrade" header block into section
     3.4 in a manner similar to current section 3.4.7 [3].
     Other than making it a SHOULD in all cases, these are 
     only editorial edits.

iii) Replace existing appendix A [4] with clarified text.
     Given i) and ii) these are only editorial changes.

I have uploaded an HTML version of the proposed text at [6] (linked from
[7]) but also included the text below. In [6] you will find the sections
as 2.8, 3.4.7, and Appendix A.

i) Replacement text for section 3.1
-----------------------------------

SOAP Versioning Model

SOAP does not define a traditional versioning model based on major and
minor version numbers. Rather, the SOAP processing model enables
extensiblity of SOAP through the concept of features (see 2.6 Processing
SOAP Messages).

A SOAP node determines whether it supports the version of a SOAP message
on a per message basis. In this context "support" means understanding
the semantics of the envelope identified by the qualified name of the
Envelope element information item (see 3.1 SOAP Envelope). The envelope
versioning model is directed only at the Envelope element information
item. It does NOT address versioning of blocks, encodings, protocol
bindings, or otherwise.

If the child element information item of the document information item
does NOT have a local name of Envelope and a namespace name of
http://www.w3.org/2001/12/soap-envelope then the receiving SOAP node
MUST generate a VersionMismatch SOAP fault (see 3.4 SOAP Fault). Any
other malformation of the message construct MUST be treated as a Sender
SOAP fault (see 3.4 SOAP Fault).

A SOAP node MAY provide support for multiple envelopes. However, when
processing a message a SOAP node MUST use the semantics defined by the
version of that message.

Appendix A Version Transition From SOAP/1.1 to SOAP Version 1.2 defines
a mechanism for transitioning from SOAP/1.1 to SOAP Version 1.2 using
the Upgrade element information item (see 3.4.7 VersionMismatch Faults).

ii) Upgrade section in 3.4 
--------------------------

VersionMismatch Faults

When a SOAP node generates a VersionMismatch fault, it SHOULD provide,
in the generated fault message, an Upgrade header block as described
below which detail the qualified names (QNames, per the XML Schema
Datatypes specification[5]) of the supported SOAP envelopes that the
SOAP node supports (see 2.8 SOAP Versioning Model).

The Upgrade header block consists of an Upgrade element information item
containing an ordered list of qualified names 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.

Following is an example of a SOAP node that supports both SOAP Version
1.2 and SOAP/1.1 but which prefers SOAP Version 1.2 (see appendix A
Version Transition From SOAP/1.1 to SOAP Version 1.2 for a mechanism for
transitioning from SOAP/1.1 to SOAP Version 1.2). This is indicated by
including an Upgrade header block with two envelope element information
items, the first containing the local name and namespace name of the
SOAP Version 1.2 Envelope element information item, the latter the local
name and namespace name of the SOAP/1.1 Envelope element.

Example: VersionMismatch fault generated by a SOAP node. The message
includes a SOAP Upgrade header block indicating support for both SOAP
Version 1.2 and SOAP/1.1 but with a preference for SOAP Version 1.2.

<?xml version="1.0" ?>
<env:Envelope xmlns:env="http://www.w3.org/2002/10/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/2002/10/soap-envelope"/>
   <envelope qname="ns2:Envelope" 
             xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/"/>
  </V:Upgrade>
 </env:Header>
 <env:Body>
  <env:Fault>
   <faultcode><value>env:VersionMismatch</value></faultcode>
    <faultstring>Version Mismatch</faultstring>
   </env:Fault>
 </env:Body>
</env:Envelope>

iii) Replacement text for appendix A
------------------------------------

Version Transition From SOAP/1.1 to SOAP Version 1.2

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

1) A SOAP/1.1 node receiving a SOAP Version 1.2 message will
   according to SOAP/1.1 generate a VersionMismatch SOAP fault
   based on a SOAP/1.1 message construct. That is, the
   envelope will have a local name of Envelope and a
   namespace name of
   "http://schemas.xmlsoap.org/soap/envelope/".

2) A SOAP Version 1.2 node receiving a SOAP/1.1 message either

     * MAY process the message as a SOAP/1.1 message
       (if supported), or

     * MUST generate a VersionMismatch SOAP fault based
       on a SOAP/1.1 message construct following SOAP/1.1
       semantics. The SOAP fault SHOULD include an Upgrade
       header block as defined in this specification
       (see 3.4.7 VersionMismatch Faults) indicating support
       for SOAP Version 1.2. This allows a receiving SOAP/1.1
       node to correctly interpret the SOAP fault generated
       by the SOAP Version 1.2 node.

Below is an example of a VersionMismatch SOAP fault generated by a SOAP
Version 1.2 node as a result of receiving a SOAP/1.1 message. The fault
message is a SOAP/1.1 message with an Upgrade header block indicating
support for SOAP Version 1.2.

Example: SOAP Version 1.2 node generating a SOAP/1.1 VersionMismatch
fault message including an Upgrade header block indicating support for
SOAP Version 1.2.

<?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><value>env:VersionMismatch</value></faultcode>
    <faultstring>Version Mismatch</faultstring>
   </env:Fault>
 </env:Body>
</env:Envelope>Note:

Note: Existing SOAP/1.1 nodes are not likely to indicate which envelope
versions they support using the Upgrade element information item. If
nothing is indicated then this means that SOAP/1.1 is the only supported
envelope.

Comments?

Henrik Frystyk Nielsen 
mailto:henrikn@microsoft.com 

[0] http://www.w3.org/2000/xp/Group/xmlp-issues.html#x135
[1]
http://lists.w3.org/Archives/Public/xml-dist-app/2001Nov/thread.html#31
[2] http://www.w3.org/2000/xp/Group/1/10/11/soap12-part1.xml#envvermodel
[3] http://www.w3.org/2000/xp/Group/1/10/11/soap12-part1.xml#mufault
[4] http://www.w3.org/2000/xp/Group/1/10/11/soap12-part1.xml#version
[5] http://www.w3.org/2000/xp/Group/1/10/11/soap12-part1.xml#soapfault
[6]
http://lists.w3.org/Archives/Public/www-archive/2002Mar/att-0044/01-soap
12-part1.html
[7] http://lists.w3.org/Archives/Public/www-archive/2002Mar/0044.html

Received on Monday, 18 March 2002 19:15:09 UTC