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 14:43:25 UTC