Re: SOAP 1.2 Pt.1 feedback - wording (semantic and editorial)

>> The wording of the second paragraph doesn't quite allow for multiple
   header elements: can't all be the first child of the parent element.

I think you're confused here.  What you can add if necessary is the:

        <soap:Header> 

element, of which the SOAP Rec makes clear there can be at most one.  It 
can have multiple children, which are the multiple header blocks referred 
to in the first para.  The multiple blocks are the children of the single 
Header element, which can be added if and only if not previously there.


------------------------------------------------------------------
Noah Mendelsohn                              Voice: 1-617-693-4036
IBM Corporation                                Fax: 1-617-693-8676
One Rogers Street
Cambridge, MA 02142
------------------------------------------------------------------







Daniel Barclay <Daniel.Barclay@fgm.com>
Sent by: xmlp-comments-request@w3.org
09/09/2003 02:43 PM

 
        To:     xmlp-comments@w3.org
        cc:     (bcc: Noah Mendelsohn/Cambridge/IBM)
        Subject:        SOAP 1.2 Pt.1 feedback - wording (semantic and editorial)



Some feedback regarding SOAP Version 1.2 Part 1: Messaging Framework
(24 June 2003):

Wording related to semantics:

* Section 2.7.2.1 says:

     ...
     Element information items for additional header blocks MAY be added 
to
     the [children] property of the SOAP Header element information item 
as
     detailed in 2.7.2 SOAP Forwarding Intermediaries.

     In this case, a SOAP Header element information item MAY be added, as
     the first member of the [children] property of the SOAP Envelope 
element
     information item, if it is NOT already present."
     ...

   The wording of the second paragraph doesn't quite allow for multiple
   header elements: can't all be the first child of the parent element.


* Section 5.1.1 says:

     ...
     The scope of the encodingStyle attribute information item is that of 
its
     owner element information item and that element information item's
     descendants, unless a descendant itself carries such an attribute
     information item.
     ...

   The wording seems to have several problems.

   1.  Is the scope of an attribute the _scope_ of some elements or is it
       the elements?

       (If the scope of the attribute is the scope of some elements, then
       what is the scope of an element?  Specifically, does it include its
       descendants?  If so, then the wording "and that element information
       item's descendants" would be redundant, right?)

       Should "the scope...is that of...element" be "the scope...is...
       element"?

    2. The wording that tries to exclude descendents that have their own
       encodingStyle attributes doesn't specify what it intends to.

       As written with "unless," the specification says that _any_
       descendent that also carries the attribute excludes _all_
       descendents from the scope (not just those descendents in the
       subtree rooted at the descendent with the attribute).

       (Additionally, nothing clearly limits the scope of the "unless" to
       the phrase "that element information item's descendants," so it can
       also be taken to mean the any descendant with the attribute also
       removes the parent element from the scope.)

       Starting with "except for descendants that..." would more likely
       result in the intended semantics.


* Section 3.3, item 5 says:

     ...we can imagine a module which encrypts and removes the SOAP body,
     inserting instead a SOAP header block containing a checksum and an
     indication of the encryption mechanism used. The specification for 
such a
     module would indicate that the decryption algorithm on the receiving 
side
     is to be run prior to any other modules which rely on the contents of 
the
     SOAP body.

   That seems to refer to removing the plaintext body and adding a header
   that contains only the checksum and algorithm indication (without 
either
   putting the encrypted body in the header, or added a replacement body
   element with the encrypted data in it).


* Sections 5.4.7.3 and 5.4.8.2 give conflicting definitions of "the qname
   attribute information item."

   The first should limit itself to "the qname attribute information item
   of a SupportedEnvelope element [info. item]" and the other should 
address
   only NotUnderstood elements.


* "To SOAP, a URI is simply a formatted string that identifies a web 
resource
   via its name, location, or any other characteristics."

   Should that include "location, or any other characteristics" after 
"name"?
   Saying that URIs identify things by location can imply that one must
   resolve host names (e.g., abc.com vs. www.abc.com) to determine 
identity.

   Don't other W3C specifications (especially XML Namespaces) treat URIs 
just
   as strings?




Just editorial:

* The wording "an ordered list...of names...in the order most to least
   preferred" is unclear, not quite grammatical, and possibly redundant.

   The phrase "...in the order most to least preferred" isn't grammatical,
   and suggests "in the _order_ most preferred" by the node, instead of
   ordered from the _version_ most preferred by the node.

   Maybe it should say "...a list...of names...ordered from most preferred 
to
   least preferred."


* "...character information item children whose character code is amongst
   the white space characters..." should probably be "...character 
information
   item children whose character codes are amongst the white space
   characters..." (several occurrences).


* Properties are referred to with brackets, as in "the [children]
   property."

   That is not the standard English use of brackets, and is confusing.
   (Try reading "The [notations] and [unparsed entities] properties are
   both empty. The [base URI], [character encoding scheme] and [version]
   properties can have any legal value.")

   Why not write "the children property" or:

     the "children" property


* "The semantics of one or more SOAP header blocks in a SOAP message, or
   the SOAP MEP used MAY require..."

   Unbalanced comma; should be:

    "The semantics of one or more SOAP header blocks in a SOAP message, or
     the SOAP MEP used, MAY require..."


* "SOAP senders SHOULD NOT generate, but SOAP receivers MUST accept the
   SOAP role..."

   Unbalanced comma; should be:

   "SOAP senders SHOULD NOT generate, but SOAP receivers MUST accept, the
   SOAP role..."


* Section 3.1 says:

     ...example features may include "reliability", "security", 
"correlation",
     "routing", and message exchange patterns (MEPs)
     ...

   The words appear to be used in their normal senses, but they are 
enclosed
   in quotes.  Either the quotes should be removed, or something should be
   changed to make clear why they are in quotes.  (Are the words quoted
   because they are literal names for the features?  If so, their being
   names should be mentioned.)


* "e.g. ..." should be "e.g., ..." (at least one occurrence)


* "i.e. ..." should be "i.e., ..." (at least one occurrence)


* "...items...SHOULD have..., that is the name of the element SHOULD..."
   should be:

     ...items...SHOULD have...; that is, the name of the element 
SHOULD..."

   (There are several instances of that.)


* "namespace qualified" should be "namespace-qualified" (at least two
   occurrences); also:

   - "human readable explanation" should be "human-readable explanation"
   - "SOAP related security problems" should be "SOAP-related security
     problems"
   - "SOAP based authentication mechanism" should be "SOAP-based
     authentication mechanism"

* In:

     SOAP intermediaries are by definition men-in-the-middle, and 
represent
     an opportunity for man-in-the-middle attacks.

   the occurrence of "men-in-the-middle" should probably be "men in the
   middle" because in the above sentence it is not being used as an
   adjective and therefore doesn't need to be bundled together (as
   "man-in-the-middle" is used and bundled at the end of the sentence).


Daniel Barclay

Received on Tuesday, 9 September 2003 15:36:03 UTC