Proposed resolution to SOAP 1.2 Rec Issue #10

Dear all,

This is a set of Proposed resolution to SOAP 1.2 Rec Issue #10 
(http://www.w3.org/2000/xp/Group/xmlp-rec-issues.html#x10), for 
consideration by the XMLP WG.

Rec Issue #10 group a number of issues, against "SOAP Version 1.2 Part 
1: Messaging Framework". Each of those sub-issue has been separated from 
the others by a line of "*".

Best regards,

Hervé.

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

Proposed resolution:
--------------------
*No* change.

Rationale:
SOAP Header eii and SOAP Header block eii must not be mixed-up.
The SOAP Envelope eii may contain at most one SOAP Header eii in its 
children. The SOAP Header eii may contain zero or more SOAP header block 
eii in its children.
If an intermediary wishes to add a Header block eii in a SOAP message 
not containing any Header block eii, this intermediary must add a SOAP 
Header eii in the SOAP Envelope eii to contain the new Header block eii. 
This SOAP Header eii will be the first child of the SOAP Envelope eii.
Therefore, the above mentionned second paragraph is correct.

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

Proposed resolution:
--------------------
Reword the paragraph similar to namespace 1.1 scope definition :
<proposal>
The scope of the encodingStyle attribute information item is its owner 
element information item and that element information item's 
descendants, excluding the scope of any inner encodingStyle attribute 
information item.
</proposal>
The nature of the change is an editorial correction that does not affect 
conformance.

Rationale:
As the scoping of the encodingStyle aii is similar to the scoping of 
namespace declaration, it is expected that the current definition, 
althought lacking some clarity is well understood by readers.
However, some rewording may prevent any confusion.

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

Proposed resolution:
--------------------
Do *no* change.

Rationale:
The exerpt perhaps lacks some clarity, however it is only an example and 
as such is sufficient for providing some concrete application of item 5 
requirements.

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

Proposed resolution:
--------------------
Do *no* change.

Rationale:
Taken in context, it is clear that the qname aii defined in 5.4.7.3 
applies to the SupportedEnvelope element and that the qname aii defined 
in 5.4.8.2 applies to the NotUnderstood element.

***********************
* "To SOAP, a URI is simply a formatted string that identifies a web 
resource
    via its name, location, or any other characteristics."
(Ed note: Section 6, first paragraph)

    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?

Proposed resolution:
--------------------
Do *no* change.

Rationale:
The sentence cited by commentator summaries the first paragraph of 
Section 1.2 of RFC 2396 (which defines URIs). Therefore there is no 
reason for changing this sentence.
Regarding other W3C specifications, XML Namespaces treat URIs in a 
specific way, mandating URI comparison to be done using a 
character-by-character comparison.
  On its side, SOAP 1.2 does not define any equivalence rules for URIs.

***********************
* The wording "an ordered list...of names...in the order most to least
    preferred" is unclear, not quite grammatical, and possibly redundant.
(Ed note: Section 5.4.7.1, paragraph 1)

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

Proposed resolution:
--------------------
Do *no* change.

Rationale:
The sentence althought somewhat long is understandable as is.
(EDITORIAL NOTE: as non native english speaker, I can not assert the 
grammatical correctness of the sentence).

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

Proposed resolution:
--------------------
Do *no* change.

Rationale:
A character information item represents only one character (see XML 
Infoset section 2.6) and as such has only one character code. Therefore 
the current form is correct.

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

Proposed resolution:
--------------------
Do *no* change.

Rationale:
The square brackets notation for property names is the standard notation 
defined by the XML Infoset specification (see XML Infoset, Section 1, 
paragraph 5).

***********************
* "The semantics of one or more SOAP header blocks in a SOAP message, or
    the SOAP MEP used MAY require..."
(Ed note: section 2.7.2, paragraph 1)

    Unbalanced comma; should be:

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

Proposed resolution:
--------------------
*Accept* proposal.
The nature of the change is an editorial correction that does not affect 
conformance.

Rationale:
There is effectively a missing comma.

***********************
* "SOAP senders SHOULD NOT generate, but SOAP receivers MUST accept the
    SOAP role..."
(Ed note: section 5.3.2, paragraph 8)

    Unbalanced comma; should be:

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

Proposed resolution:
--------------------
Do *no* change.

Rationale:
It does not seem necessary to balance comma in this sentence.
(EDITORIAL NOTE: a native English speaker should check this).

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

Proposed resolution:
--------------------
Do *no* change.

Rationale:
The words are used to indicate some generic kind of functionnality. They 
could have been written without the quotes, but as this does not hinder 
the understanding of the sentence, there is no need to remove the quotes 
or change the sentence.

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

Proposed resolution:
--------------------
Add a comma after each occurrence of "e.g.".
The nature of the change is an editorial correction that does not affect 
conformance.
(Ed note: there are several occurrences).

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

Proposed resolution:
--------------------
Add a comma after each occurrence of "i.e.".
(Ed note: Section 2.4, paragraph 1, Section 4.2, paragraph 4).

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

Proposed resolution:
--------------------
Modify each instance to read:
'..., that is, ...".
The nature of the change is an editorial correction that does not affect 
conformance.
(Ed note: Section 5.2.1, First bullet; Section 5.3.1, First bullet; 
Sectino 5.4.5.1, First bullet).

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

Proposed resolution:
--------------------
Accept proposed change.
The nature of the change is an editorial correction that does not affect 
conformance.
(Ed note: many occurrences).

***********************
    - "human readable explanation" should be "human-readable explanation"

Proposed resolution:
--------------------
Accept proposed change.
The nature of the change is an editorial correction that does not affect 
conformance.
(Ed note: Section 5.4.2, paragraph 1; Section 5.4.2.1, paragraph 1).

***********************
    - "SOAP related security problems" should be "SOAP-related security
      problems"

Proposed resolution:
--------------------
Accept proposed change.
The nature of the change is an editorial correction that does not affect 
conformance.
(Ed note: Section 7.2, paragraph 2).

***********************
    - "SOAP based authentication mechanism" should be "SOAP-based
      authentication mechanism"

Proposed resolution:
--------------------
Accept proposed change.
The nature of the change is an editorial correction that does not affect 
conformance.
(Ed note: Section 7.3, paragraph 3).

***********************
* In:
      SOAP intermediaries are by definition men-in-the-middle, and represent
      an opportunity for man-in-the-middle attacks.
(Ed note: Section 7.2, paragraph 1).

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

Proposed resolution:
--------------------
Do *no* change.

Rationale:
Even if the occurrence  of "men-in-the-middle" does not need to be 
bundled together on a syntactic point of view, being put in parallel 
with the occurrence of "man-in-the-middle" it is better for clarity to 
keep it bundled together.

Received on Tuesday, 25 November 2003 08:20:13 UTC