Comments on SOAP 1.2 specification

I also took an action item to review the SOAP 1.2 spec. Unfortunately I've
only managed to review the Primer in any detail. Here are my comments.

Part 0, Primer:

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

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

2.2.2. Remote procedure calls.
From my understanding, the Web Methods invocation pattern doesn't use the
RPC convention. It's a different convention. Therefore I don't understand
why this long discussion on Web-friendly operations is included in this
section. The Web Methods invocation pattern is covered in section 3.1.1. (If
the authors feel that we need to present the concept of a Web Method prior
to discussing SOAP RPC, then perhaps we can demonstrate a GET for available
flight times, in which case it would appear before the RPC section). The
paragraphs starting with "Items 4 and 5" through "We defer until section 3"
should be removed from this section. Perhaps some of this content should be
moved to section 3.1.1. (I'd also recommend a change in tone. We should not
convey the impression that the Web Method pattern is a modification of
traditional SOAP to support a Web-friendly approach. I'd recommend that it
be presented as the preferred mechanism to implement SOAP-based idempotent
information retrieval.)

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

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 the Web
Methods section.

2.2.2. Remote procedure calls. In the paragraph starting with "The central
role":
This paragraph should be moved to the Web Methods section.
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. General question:
According to this paragraph,
   "In Example 7b, the header block oneBlock is marked with
   a mustUnderstand value set to "true", which means that it
   is mandatory to process this block if the SOAP node plays
   the role identified by "http://example.com/log". The other
   two header blocks are not so marked, which means that SOAP
   processor at which these blocks are targeted need not
   process them."
What happens if the message is never routed to a SOAP node that plays the
role identified by "http://example.com/log"? Is there a way to guarantee
that the message gets routed to a SOAP node that plays that role before it
gets delivered to the ultimate receiver?

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":
"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".

Anne Thomas Manes
Chief Technology Officer
Systinet
http://www.systinet.com
617-868-2224 x1543 (land)
617-642-3144 (mobile)

Received on Wednesday, 17 July 2002 13:55:22 UTC