WSAWG Comments on SOAP 1.2 LC WDs

David,

As requested, and promised by Chris Ferris, here are WSAWG's 
comments/feedback on the on SOAP 1.2 LC WDs. We have separated out
substantive issues or questions from any editorial feedback and request only
that
the WG respond formally to issues labeled as such (Issue #nn)
(e.g. the editorial comments are yours to dispose as the XMLP
WG sees fit and require no formal response to WSAWG).

Cheers,

Mike Champion / Dave Hollander 
(who thank Chris Ferris for doing the actual work here!)

SOAP1.2 Part 1: Messaging Framework

Issue #1: Possible inconsistency in SOAP Process Model

2.4 Understanding SOAP Headers, 3rd paragraph, 2nd sentences
      "Therefore, for every mandatory SOAP header block targeted to
      a node, that node MUST either process the header block or not
      process the SOAP message at all, and instead generate a fault
      ..."

This sentence implies that there can be at most one detection of a
fault caused by processing a header block as all further message
processing ceases on fault detection.

However, in various parts of Part 1, there is assumption that
multiple misunderstood header blocks may be possibly identified in
a fault message, e.g. in 2.6 Processing SOAP Messages, Rule 3:
      "If one or more of the header blocks identified in the preceding
      step are not understood by the node ..."
e.g. in 5.4.8 SOAP mustUnderstand Faults, 2nd paragraph, 1st
sentence:
      "A SOAP node MAY generate a SOAP fault for any one or more
      SOAP header blocks  ..."

Related commentary on this issue:

"A SOAP node MAY generate a SOAP fault for any one or more SOAP header
blocks that were not understood in a SOAP message."
This sentence is very ambiguous and seems to conflict with this sentence
from section 2.4 Understanding SOAP Headers:
"for every mandatory SOAP header block targeted to a node, that node MUST
either process the header block or not process the SOAP message at all, and
instead generate a fault"
My understanding (according to section 2.4) is that the SOAP node MUST
generate a SOAP fault for the first SOAP header block that is targeted at
that node, contains mustUnderstand="true", and that it does not understand.
When a node encounters a mustUnderstand error, it should stop processing
immediately (i.e., no further processing of other header blocks) and return
the error. Also, this sentence might be construed to mean that the SOAP
node
MAY generate multiple faults. If my understanding is correct, then Example
6
should be changed to include only one Misunderstood header blocks. If not,
then I would recommend that section 2.4 be changed to indicate that
processing may continue after encountering a mustUnderstand fault.

Issue #2: Contradiction in SOAP Process Model

2.4 Understanding SOAP Headers, 3rd paragraph, last sentence
      "Tagging SOAP header blocks as mandatory thus assures that
      such modifications will not be silently (and, presumably,
      erroneously) ignored by a SOAP node to which the header block
      is targeted."

This sentence implies that it will not be possible for modifications
by mandatory header blocks to be silently and erroneously ignored.

However, in the last 2 sentences of the next paragraph, it is said
that
      "it is not an error for an ultimate SOAP receiver to receive a
message
      containing a mandatory header block that is targeted at a role
      other than the ones assumed by the ultimate SOAP receiver.
      This is the case, for example, when a header block has survived
      erroneously due to a routing or targeting error at a preceding
      intermediary."

That is, it is not an error for mandatory header block to survive
erroneously and therefore be silently ignored, thus contradicting the first
sentence quoted.

Issue #3: URI Identification of MEPs

Section 3.3 reads[2]:

|   In general the definition of a message exchange pattern:
|     * Is named by a URI.
|     * Describes the life cycle of a message exchange conforming to the
|       pattern.
|     * Describes the temporal/causal relationships of multiple messages
|       exchanged in conformance with the pattern.
|     * Describes the normal and abnormal termination of a message
|       exchange conforming to the pattern.

This suggests that not all MEPs are identified by a URI. From an
architectural point of view, and according to AR009.3[1], all conceptual
elements should be addressable directly via a URI.

We think that a URI should be required for MEPs: it is easy enough to
assign one and will ease identification.

Issue #4: External references?

Section 2.6 reads[3]:

   "SOAP nodes MAY make reference to any information in the SOAP envelope
   when processing a SOAP body or SOAP header block. For example, a
   caching function can cache the entire SOAP message, if desired."

We wonder about external references. They are not explicitely
disallowed, but not referenced either. Needless to say, we think that
external references are useful, e.g. to reference a large image that
one doesn't want to carry along in the message.

Issue #5: QName vs URI

Sections 5.4.1.3[4] and 5.4.6[5] use and define QNames to identify
fault types, whereas WSAWG requirement AR009.3[1] calls for URIs.

This is related to two open TAG issues:
- Using Qualified Names (QNames) as Identifiers in Content[6].
- Algorithm for creating a URI from a QName[7].

Issue #6

Section 2. SOAP Processing Model. First paragraph.
It would be nice to mention the SOAP Response MEP. Also we don't find that
section 3.3 SOAP Message Exchange Patterns (MEPs) really provides a
description of the relationship between SOAP message exchange patterns and
the SOAP extensibility model. It gives only a very brief definition of a
MEP, and it makes no explicit mention of the extensibility model. It does
describe the relationship between MEPs and the Protocol Binding Framework.

Issue #7

Section 2.7.2. Active Intermediaries. Second paragraph: Question.
It says, "an active intermediary might have removed and encrypted some or
all of the SOAP header blocks found in the inbound message". Shouldn't it
say, "some or all of the SOAP header blocks and SOAP body"?

Issue #8: Length of URIs.

I remember a somewhat long discussion on xml-dist-app about that and
am still unsure about what we should say, but the following statement
struck me[8]:

|   SOAP does not place any a priori limit on the length of a URI. Any
|   SOAP node MUST be able to handle the length of any URI that it
|   publishes and both SOAP senders and SOAP receivers SHOULD be able to
|   deal with URIs of at least 2048 characters in length.

Even though the URI specification doesn't specify any limit on the
length of a URI, the HTTP spec does provide a URI too long error
code[9].

2kB is identified here as a reasonable value to be able to handle.
This seems to be an architectural issue, a Web services one as well as
a Web one. I am afraid that such a statement will have a big impact on
software designed.

I think that I would be more comfortable by saying that software
should be able to handle URIs of arbitrary length, and that a
2kB-length is seen _in SOAP's context_ as a minimum value to support.

Editorial

Section 3.3. SOAP Message Exchange Patterns (MEPs)
It would be nice to add a reference to Part 2, section 6.

Section 4.2. Binding Framework. Third paragraph:
ends with "one or more MEP". Should be "one or more MEPs".

Section 5.2.1. SOAP header block. In the paragraph following Example 3, in
the
sentence, "A SOAP sender generating a SOAP message SHOULD use these
attributes only on SOAP header block.":
It should read, "only on a SOAP header block"

Section 5.4.8. SOAP mustUnderstand Faults. First sentence.
"When a SOAP node generates a fault with a Value of Code set to
"env:MustUnderstand" for," -- delete the word "for".

Section 7.3.1. Binding to Application-Specific Protocols. First paragraph,
last
sentence:
"in order to reuse the existing infrastructure associated that protocol"
should be "associated with that protocol".

SOAP1.2 Part 2: Adjuncts

Issue #9: Question
Section 6.2.3 State Machine Description, Table 6, Transition Condition,
Init
row

If the Transition Condition is "Unconditional", then the boundary
between Init state and the Requesting state is indistinguishable.
Shouldn't the two states be one state?

Issue #10: Question
Section 6.2.3 State Machine Description, last bullet before 6.2.4
      "A requesting SOAP node MAY enter the Fail state, and thus
      abort transmission of the outbound SOAP request, based on
      information contained in an incoming streamed SOAP
      response".

In this case, should the responding SOAP node switch from generating
a SOAP response to a SOAP fault ?  Should the requesting SOAP node also
generate a SOAP fault since it initated the transmission abortion?

Issue #11: Question
Section 7.5.2.1 Init, Table 20, SOAP Fault, Malformed Request Message row
For Malformed Request Message ( HTTP Status Code 400, HTTP
Reason: Bad request) the SOAP Fault is "None".

Why not let the SOAP Fault to be "env:Sender", which is consistent
with Table 23?

Issue #12: Question
Section 7.5.2.2 Receiving, Table 23, SOAP Fault to HTTP Status Mapping

What about mapping RPC Faults (see 4.4 RPC Faults) to HTTP Status?
E.g. rule 2 in 4.4 defines a fault "env:DataEncodingUnknown" which is not
mentioned in Table 23.

Issue #13: S
Section A.1 Rules for mapping application defined names to XML Names, Rule
5, case 4
      "Let U1, U2, ... , U8 be the eight hex digits [PROD: 4] such that Ti
      is "U+" U1 U2 ... U8 in the UCS-4 encoding."

The "U+" notation denotes the Unicode code point rather than either
UCS-2 or UCS-4 encoding.  Moreover, "the full range of Unicode code points
[are] from U+0000 to U+10FFFF inclusive; code points above U+10FFFF MUST
NOT
be used".  (See Character Model for the World Wide Web 1.0, 3.5 Reference
Processing Model.)

Suggest it be change to:  "Let U1, U2, ... , U8 be the eight hex digits
[PROD: 4] such that Mi is U1 U2 ... U8 in the UCS-4 encoding."

Suggest also changing '
      "This case implies that Ti has a UCS-2 encoding, which is
U+U5U6U7U8."
to:
      "This case implies that Ti has a UCS-2 encoding, which is U5U6U7U8."


Issue #14: HTTP binding: interpretation of arbitrary HTTP status
codes

Section 7.5.1.2 Requesting[8] describes how a SOAP sender reacts to
HTTP status codes returned by a SOAP receiver.

Table 17[9] only lists a limited number of methods for which next
states are listed. This seems to be contrary to the robustness
principle cited in Part 1[10]. What would happen if the requesting SOAP
node was receiving a 402 Payment Required[11] for example?

Editorial

Section 5. A Convention for Describing Features and Bindings. First
paragraph:
"it is used to describe a Request-Response MEP 6.2 Request-Response Message
Exchange Pattern and the SOAP HTTP Binding 7. SOAP HTTP Binding elsewhere
in
this document."
It is also used to describe the the 6.4 Web Method Specification Feature
feature and the 6.3 SOAP Response Message Exchange Pattern MEP, isn't it?


SOAP1.2 Part 0, Primer:

Issue #15

2.1. SOAP messages. The paragraph beginning with " A SOAP header".
When I first read this paragraph, I was concerned with the implication that
SOAP headers should be processed by a SOAP intermediary rather than by a
SOAP header processor within a SOAP server. Then it dawned on me that
perhaps the authors view a SOAP header processor as a SOAP intermediary.
Rather than starting with a description that implies the use of an
intermediary, I think the paragraph should start with a basic definition of
a SOAP header: A SOAP header is an extension mechanism that provides a way
to pass information that isn't application payload. Then it should discuss
why you might want to use this information (to pass control, directive, or
contextual information) and how to insert header processors into the SOAP
processing scheme (either as intermediaries or as header processors called
by a SOAP server). Or it might simply make it obvious to the reader that a
SOAP header processor is in fact a SOAP intermediary.

Issue #16:

2.2.1. Document-style message exchange. Example 2.
Shouldn't the returned <p:airportChoices> element contain an enumeration?

Issue #17:

2.2.2. Remote procedure calls.
This discussion about RPC makes the assumption that it will use the HTTP
protocol, and hence spends a great deal of time up front discussing
"Web-friendly" concepts before discussing the basics of the the RPC
convention. I also find the tone to be somewhat defensive -- It sounds as
if
it's trying to convince me that this is the right way to do it (and that I
have
another choice). I much prefer the way this information is presented in
Part
2, Section 4 [12]. It's very straight-forward and direct. It says -- this
is
the way you do RPCs (articulating how it maps to the two MEPs), and when
you're using HTTP as a transport, you need to use the Web Method Feature.
The GET Web Method is the preferred mechanism to implement SOAP-based
idempotent information retrieval.

Since the RPC convention isn't dependent on HTTP, I'd recommend:
1) it be explicitly stated right up front (Part 2, section 4 describes it
in
terms of RPC invocations and responses mapping naturally to HTTP requests
and responses,  but that RPC is not dependent on HTTP).
2) most of the Web-friendly discussion (The paragraphs starting with "Items
4 and 5" through "We defer until section 3") be moved to section 3 with
appropriate references to that section made in this section.

Issue #18:

2.2.2. Remote procedure calls. Point #4.
Is this "information needed to invoke a SOAP RPC"? Isn't this a
clarification of how the information described by points 2 and 3 must be
specified? I understand that we want to explain Web-friendly RPCs, but I
don't think this point belongs in this list. I think it belongs in the
follow-on text with appropriate references to section 3.1.1. I would
therefore recommend a change to the following two paragraphs to first
assert
the requirement to clearly separate the arguments used to identify the
target Web resource from the arguments used to convey data or control
information and then to explain why.  We should promote the Web-friendly
way
as the preferred way to implement information-retrieval requests, as
specified in Section 3.1.3.)

Issue #19:

2.2.2. Remote procedure calls. Point #5.
This point is only valid when using HTTP. Per Part 2, Section 4, this point
should read: "Values for properties as required by any features of the
binding to be used. For example, GET or POST for the webmeth:Method
property
of the 6.4 Web Method Specification Feature."

Issue #20:

2.2.2. Remote procedure calls. The paragraph starting with "Items 4 and 5":
There should be a reference to HTTP in this paragraph (rather than just
referring to the World Wide Web). This paragraph should be moved to section
3.


Editorial

1. Introduction. Last sentence of the paragraph starting with "Part 2".
I don't think this sentence belongs here. (No other part of this first
Introduction section gets into this much detail.) I'm concerned by the
implication that SOAP isn't "Web-friendly". At the very least, if the term
is introduced here, there must be a definition provided with it. I think
the
topic is properly covered as part of the introduction in 1.1 Overview
section in the paragraph starting with Section 3.

2.2.2. Remote procedure calls. In the paragraph starting with "The central
role":
This paragraph should be moved to section 3.
A space is required here: "Part 2 Section 4.1.1provides"
  also
"data that is necessary" should be "data that are necessary"

2.2.2. Remote procedure calls. Example 4:
For readability, here should be a line break between the elements in this
line:
</m:reservation>   <o:creditCard
xmlns:o="http://mycompany.example.com/financial">
and this line:
</n:name>     <o:number>123456789099999</o:number>

2.2.2. Remote procedure calls. Third paragraph from the end, starting with
"While in principle":
"inependent" is misspelled.

2.4. SOAP processing model. Second paragraph:
"(with their contents elided for brevity)" -- we might want to use a more
well-known term than "elided" -- perhaps "removed" or "edited".

2.4. SOAP processing model. eleventh paragraph, starting "If a header
element":
"content is data" should be "contents are data".

2.4. SOAP Processing model. The paragraph starting with "The following
table":
"appropriate" should be "appropriately".

3. Using various protocol bindings. The paragraph starting with "Thus it is
apparent":
The phrase "accomplish a particular application semantics" (which appears
twice in this paragraph) should be either "accomplish particular
application
semantics" or "accomplish a particular application semantic".

3. Using various protocol bindings. The paragraph starting with "Among
other
things":
The last sentence reads, "a non-SOAP message acting as a response followed
by a SOAP message included as a part of the response" should say, "a
non-SOAP message acting as a request followed by a SOAP message included as
a part of the response".

3. Using various protocol bindings. The paragraph starting with "Part 2
section 7specifies":
A space is required here: "Part 2 section 7specifies"

3.1. HTTP binding. Last sentence of the paragraph starting with "The
purpose
of providing":
"Acceptheader" should be "Accept header"

3.1.1. SOAP HTTP Get usage. The second paragraph, beginning with "Example
8a
shows":
A space is required here:
"URIhttp://travelcompany.example.org/reservations?code=FT35ZBQ"

3.1.1. SOAP HTTP Get usage. The third-to-last paragraph starting with "In
Example 8b"
"outboundandreturn" shoudl be "outbound and return".

3.1.2. SOAP HTTP POST usage. Example 9:
For readability, a line should be inserted between the elements here:
</m:reservation>    <o:creditCard
xmlns:o="http://mycompany.example.com/financial">
and here:
</n:name>    <o:number>123456789099999</o:number>

3.1.2. SOAP HTTP POST usage. In the paragraph betwee Example 9 and Example
10.
"Example 10 shows the RPC return (with details elided)" -- again I
recommend
using a more common word than "elided".

3.1.2. SOAP HTTP POST usage. Last paragraph.
Are we using American or English spelling? Should "behaviour" be
"behavior"?

3.1.3. Conveying Web-friendly RPCs. In the paragraph just before Example
12b, starting with "Furthermore":
The sentence "SOAP 1.2 recommends that the SOAP Response message exchange
pattern be used as described in section 3.1.2." should refer to section
3.1.1.

3.1.3. Conveying Web-friendly RPCs. In the paragraph just before Example
13,
starting with "Example 13":
"thenameof" should be "the name of" and "Bodyelement" should be "Body
element".

3.2. SOAP over email. In the paragraph starting with "Example 15":
I recommend using a more commonly known word than "elided". Also a space is
required in "email'sMessage-Id".

5. Changes between SOAP 1.1 and SOAP 1.2. Under "Document structure", first
bullet:
"strucure" should be "structure".

References

  1. http://www.w3.org/2002/ws/arch/2/06/wd-wsa-reqs-20020605.html#AC009.3
  2. http://www.w3.org/TR/2002/WD-soap12-part1-20020626/#soapmep
  3. http://www.w3.org/TR/2002/WD-soap12-part1-20020626/#procsoapmsgs
  4. http://www.w3.org/TR/2002/WD-soap12-part1-20020626/#faultsubvalueelem
  5. http://www.w3.org/TR/2002/WD-soap12-part1-20020626/#faultcodes
  6. http://www.w3.org/2001/tag/doc/qnameids.html
  7. http://www.w3.org/2001/tag/ilist#rdfmsQnameUriMapping-6
  8.
http://www.w3.org/TR/2002/WD-soap12-part2-20020626/#http-reqbindwaitstate
  9.
http://www.w3.org/TR/2002/WD-soap12-part2-20020626/#tabreqstatereqtrans
  10. http://www.w3.org/TR/2002/WD-soap12-part1-20020626/#RFC1123
  11. http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.3
  12. http://www.w3.org/TR/soap12-part2/#soapforrpc

Received on Friday, 26 July 2002 09:34:47 UTC