- From: Daniel Barclay <Daniel.Barclay@fgm.com>
- Date: Tue, 09 Sep 2003 14:43:24 -0400
- To: xmlp-comments@w3.org
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