issue 78

I've been asked by the WG to seed discussion on issue 78 from the issues
list [1].

The crux of issue 78 can be described as follows:

<crux>
In the case where

1.) multiple independent elements are present in the Body of a SOAP RPC
request or response message (for example, when one multi-reference element
is present in the Body in addition to the request/response element), and
2.) no external metadata description (for example, a WSDL description) of
the RPC is available

it's not possible (or, at least, it’s very difficult) to determine which
independent element in the Body is the request/response element. Order alone
cannot be used to make the determination since SOAP 1.1 does not dictate an
ordering for independent elements in the Body.
</crux>

In an email on the soapbuilders list [2], Andrew Layman suggested a solution
to issue 78 that leverages the SOAP "root" attribute, defined in Section 5.6
of the SOAP spec [3]. Section 5.6 reads:

<section56>
"The SOAP root attribute can be used to label serialization roots that are
not true roots of an object graph so that the object graph can be
deserialized. The attribute can have one of two values, either "1" or "0".
True roots of an object graph have the implied attribute value of "1".
Serialization roots that are not true roots can be labeled as serialization
roots with an attribute value of "1". An element can explicitly be labeled
as not being a serialization root with a value of "0".

The SOAP root attribute MAY appear on any subelement within the SOAP Header
and SOAP Body elements. The attribute does not have a default value."
</section56>

In his email, Andrew describes how he proposes to use the root attribute to
solve issue 78:

"I believe [Section 5.6] says that, in the serialization of a graph
containing multi-reference values, one may place an attribute like
SOAP-ENC:root='0' on elements to declare that they are not, in fact, the
element representing the method invocation or response."

Andrew provides the following example to show how he proposes to use the
root attribute to distinguish multi-reference elements from the
request/response element:

<SOAP-ENV:Body
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
  <SOAP-ENC:int id="i1" SOAP-ENC:root='0'>34.5</SOAP-ENC:int>
  <m:GetLastTradePriceResponse xmlns:m="Some-URI">
    <PriceAndVolume>
      <LastTradePrice href="#i1"/>
      <DayVolume>10000</DayVolume>
    </PriceAndVolume>
  </m:GetLastTradePriceResponse>
</SOAP-ENV:Body>

Andrew also remarked in his email that Section 5.6 "wins an award for
obscurity." In order to make clear the meaning that Andrew claims Section
5.6 has, I propose we rewrite the section as follows:

<ProposedRewriteOfSection56>
The SOAP root attribute MAY be used to divide independent elements at the
same nesting level into 2 categories: those that are serialization roots and
those that are not. The purpose of marking an element as a serialization
root is to distinguish it as a starting point for processing. This is
similar to the way the "start" parameter in the MIME multipart/related media
type "points, via a content-ID, to the body part that contains the object
root." [4]

When not explicitly forbidden, there may be multiple serialization roots at
the same nesting level (for example, in the SOAP Header).

The root attribute can have one of two values, "1" or "0". The value "1"
indicates that an element is a serialization root. The value "0" indicates
that an element is not a serialization root. The attribute does not have a
default value. All independent elements without the root attribute MUST be
assumed to be non-roots except in the case where there are no elements with
a root attribute with a value of “1”. In that case, the first independent
element at that level without the root attribute MUST be considered to be
the single serialization root at that level. If no such element exists, it
is an error.
</ProposedRewriteOfSection56>

If this proposed rewrite does not capture the meaning the SOAP 1.1 authors
originally intended to convey in Section 5.6, I trust they will let us know.
;>)

A comment is in order on the "except" clause and the sentence that follows
it in the proposed rewrite. It seems that some implementations have been
using order to determine which element in the body is the request/response
(in spite of the fact that SOAP 1.1 doesn't provide any support for this).
Namely, these implementations interpret the first lexical element as the
request/response and all subsequent elements as multi-reference elements.
The "except" clause and the sentence that follows it in the proposed rewrite
are intended to provide backwards compatibility for these implementations.

I have attached a table of possible distributions of root attributes on
various elements in a nesting level to demonstrate that the proposed rewrite
covers all possible cases. I would ask members of the WG to examine this
table carefully to make sure I haven't made any errors.

If we accept the proposed rewriting of section 5.6, then I would suggest we
make the following accompanying change to Section 7.1:

<ProposedRewriteOfSection71>
The Body of a SOAP RPC message MUST contain one and only one serialization
root. In the case of a request message, this root is the request element. In
the case of a response message, this root is EITHER a response element OR a
fault element.

In the case of a method with a void return type and no [out] or [in,out]
parameters, the response element will be empty, in which case it MAY be
omitted. This will cause the Body to be empty. If the Envelope contains an
empty Body and does not contain a Header, the entire Envelope MAY be
omitted.
</ProposedRewriteOfSection71>

One final point. If we use the SOAP-ENC:root attribute as suggested, then
the RPC representation in Section 7.1 becomes explicitly dependent on the
default SOAP encoding. I don't know if it's everyone's understanding that
such a dependency already exists.

Frank DeRose
TIBCO Software Inc.
3165 Porter Dr
Palo Alto, CA 94303
650-846-5570 (vox)
650-846-1267 (fax)
frankd@tibco.com
www.tibco.com

[1] http://www.w3.org/2000/xp/Group/xmlp-issues#x78
[2] http://groups.yahoo.com/group/soapbuilders/message/1909
[3] http://www.w3.org/TR/SOAP/#_Toc478383501
[4] http://www.ietf.org/rfc/rfc2112.txt (Section 3: "Intended Usage")