Comments on SOAP 1.2, Part 0 specification -- updated

After reading up on the Web Method Specification Feature, I realise that I
didn't understand how it is used by the RPC convention. Hence I've made a
few changes to my original 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.
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 it (and that I have
another choice). I much prefer the way this information is presented in Part
2, Section 4 [1]. 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.

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

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.

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

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

[1] http://www.w3.org/TR/soap12-part2/#soapforrpc

Received on Thursday, 18 July 2002 14:40:09 UTC