Comments from a Read-Through of Part 1

It's my understanding that all of us (on the WG) are supposed to be doing a
complete read through and review of the editors drafts.  The following are
my comments based on a review of the March 23rd draft of part one [1].
Obviously, these comments represent a mix of significant concerns about
either the design or the presentation, with a lot of other less important
suggestions.  Therefore, I have divided the following list into three
sections with the first carrying the most critical points, the next having
moderate importance, and the last ones being essentially editorial or
minor.  I do think that all of these should be considered before we go to
last call.  Many of them can be dealt with by the editors, but some will
require consideration of the workgroup.  Where possible, I have provided
specific suggestions for alternative text.

To avoid sending lots of notes, I have collected all of these comments
together.  I suggest that anyone wishing to respond to or discuss any
particular issue start a new thread.

Most Significant
----------------

** The second paragraph of section 1.4 "Robustness Principle" suggests that
our specification in all cases provides conservative values, but that the
robustness principle suggests that some unspecified broader set of values
should also be accepted.  While I like the robustness principle, I am
concerned about this formulation.  I think that in all cases we should
specify precisely what must be sent and what must be accepted.  In doing
so, we will often obey the robustness principle, and will indeed specify
that a receiver MUST accept values that a legal sender SHOULD NOT send.  I
do not think we should ever be vague about what a conforming receiver
should except.  Specifically, I would propose the following as a
replacement for the second paragraph: "The robustness principle is applied
for several purposes within this recommendation.  For example, section
5.2.2 provides that senders SHOULD NOT send but receiver's MUST accept
certain values of the role attribute."

** Section 1.2 second paragraph:  now says:  "all information items defined
by this specification are identified using XML namespace names".  That's
not true.  For example, the faultcode element is unqualified.  We should
either consistently qualify everything, or else change this statement in
section 1.2.

** Section 2.8, first paragraph: the reference at the end of the paragraph
is wrong.  It should be a reference to the section on extensibility, not to
the section on processing SOAP messages.  In general, I think the wording
and presentation of this section could use a bit of cleanup.

** Section 5, first paragraph: the reference at the end of the first
paragraph is to the section in which the paragraph appears.

** Section 5: the last paragraph suggests that within any element defined
by this specification, whitespace character children are insignificant.  Is
this true for all of our fault elements, for example?  What about
FaultString?  I'm not expert enough on infoset, but I would expect that
fault strings can have significant whitespace.

**Section 5: in general, is there any ambiguity as to whether namespace
declarations, xsi:type, and other such attributes may appear on SOAP
constructs?  (see also comment immediately below)

** Section 5.1: in the description of the envelope attribute information
item, we say "zero or more namespace qualified attribute information
items".  This vaguely suggests that user-defined qualified attributes may
be supplied in addition to those from our specification.  If the schema for
SOAP is normative (I don't remember whether it is) that might settle the
question, but in any case I think the wording could be more clear.  Similar
comments would apply to the definitions of many other elements in chapter
5.

** Section 5.2.2: and/or section 2.3: do we state anywhere what the
comparison rules are for URI's used as role attributes?  Keep in mind that
in general on the web, such comparison rules are determined by the URI
scheme.  In the case of HTTP, case is not significant.  I think we want to
be clear that, as with XML namespaces, what we have in mind is straight
string comparison.  There's no way we want a SOAP processor to have to know
all the rules for a wide variety of schemes.  ...closely related to the
following proposal on section 6.0:

** Section 6.0:  This section provides general information on the use of
URI's in SOAP, and specifically says:  "SOAP does not define any
equivalence rules for URIs in general as these are defined by the
individual URI schemes and by RFC 2396 [6]. However, because of
inconsistencies with respect to URI equivalence rules in many current URI
parsers, it is RECOMMENDED that SOAP senders do NOT rely on any special
equivalence rules in SOAP receivers in order to determine equivalence
between URI values used in a SOAP message."  In the case of role name
URI's, I think this is much too vague to guarantee interoperability.  For
example, it implies that an http URI used in a role attribute might come
back uppercased in a faultRole report, or that a role name of http://abc
might match http://aBc.   I suggest the following replacement for the
paragraph in question:  "SOAP does not in general define any equivalence
rules for URIs, except when used as the value for attributes defined in
this recommendation.   Where this recommendation calls for comparison with
attribute values of type anyURI  (e.g. when determining whether a node acts
in a role), equality is defined as identity of the sequence of character
information items comprising the attribute value.  Similarly, when a URI is
to be copied from one message to another (e.g. when a faultRole is
reported), an exact copy of the the characters MUST be supplied."

**Section 5.2.3, last paragraph: Current version: "If relaying the message,
a SOAP intermediary MAY substitute a non-canonical value with the canonical
value "true" and MAY omit the SOAP mustUnderstand attribute information
item if the value is "false" or "0"."   Proposed replacement: "If relaying
the message, a SOAP intermediary MAY substitute "true" for the value "1",
or "false" for "0".  The SOAP mustUnderstand attribute information item may
be omitted if its value would have been "false" or "0"."  The original
seemed to suggest that a non-canonical value for false (i.e. "0") could be
replaced by the canonical value "true".

**Section 7.0 (Security Considerations): I strongly feel that this section
should be nonnormative and should be moved to an appendix.  It is strictly
advisory, and has essentially no testable assertions.  The possible
exception is section 7.3.1 which is on the use of ports.  If we want to
keep that in the main portion of the text, I suggest we move it to the
binding framework.  I also suggest that a bit more editing be done on
section 7, as the concepts are subtle and it's not always clear what's
really intended.

Moderate Importance
-------------------

* Section 5.4.2: Should we allow xml:lang on faultString?  This will
probably be a concern for the internationalization folks.

* We seem to be somewhat inconsistent in our use of qualified and
unqualified names.  For example, the upgrade element itself is qualified,
but within it, elements are unqualified.

* Section 1.6.2: definition of SOAP header block: the first sentence
defines the block as "an element information item used to delimit..."; the
last sentence says "The type of a SOAP header block is identified by the
fully qualified name of the outer element information item of the block".
This seems somewhat inconsistent.  If the header block is defined as "an
element", and how can it have "an outer element"?  There is only one.  It
would probably better to reword the last sentence as "The type of a SOAP
header block is identified by the fully qualified name of the block element
information item."

* Section 2.3, last paragraph: remove the paragraph, which says that the
ultimate SOAP receiver must process the message body, and that the message
path for the message ends at its ultimate SOAP receiver.  Both statements
are true, but they do not belong in this section, and are redundant with
statements made elsewhere.

* Section 2.6,paragraph beginning "SOAP nodes can make reference to any
information in the SOAP envelope".  That sentence should read SOAP nodes
MAY make reference to any information..."

* Section 4.1, suggest rewording of item 2 in the list: Original: "To
facilitate homogeneous description of bindings that support common
features".  Proposed provision: "To facilitate homogeneous description in
situations where multiple bindings support common features."  The point is
that we are dealing with situations where multiple bindings are involved.
The original wording suggested that a single binding might be supporting
commonly used features.  That said, I think my proposed rewording is still
a bit lumpy, so some further wordsmithing might be needed.

* (not urgent, but closely tied to the change above) Section 4.1, suggest
rewording of item 3 in the list: Original: "To facilitate homogeneous
description of optional features."  Propose provision:  "To facilitate
consistency in the specification of optional features."

* Section 5.1.1, and its third paragraph: Original "then no claims are made
regarding the encoding style of that element information item".  Proposed
revision:  "then no claims are made regarding the encoding style of that
element information item and its descendants".

*Section 5.2.1, last sentence of the last paragraph: this paragraph
basically says that attributes on a header block element may not be
defaulted.  This more or less duplicates the statement made in section 1.2
in the paragraph that begins "SOAP does not require any XML schema
processing...".  Suggest that this be removed from 5.2.1.

* Section 5.3: there are two bullet lists in this section.  The last entry
in the first list, and first entry in the second list convey the same
information.  Both of them indicate that element information item children
of the body must be namespace qualified.  Duplication should be eliminated.

* Section 5.4: original: "If present, a SOAP Fault MUST appear as a direct
child of the SOAP body and MUST NOT appear more than once within a SOAP
Body."  Suggested replacement: "To be recognized as carrying SOAP error
information, there MUST be exactly one SOAP Fault as the only child element
of the SOAP body.  A SOAP fault element information item MAY appear within
a header block, or as a descendant of a child element of the body; in such
cases the element has no SOAP-defined semantics."

* Section 5.4.1: the third bullet indicates that a fault code element may
have one or two child element information items.  The first is a mandatory
value, the second is an optional subcode.  Question: do we require these to
occur in order?  The current specification does not say, and therefore
implies that order is insignificant.  The same question arises later in
this section in the discussion of subcode.

* Section 5.4.3:  Suggested clarification:  Original:  "The value of the
faultactor element information item is the URI that identifies the SOAP
node that generated the fault"  Proposed clarification: "As described in
section 2.1, each SOAP node must be identified by a URI.  The value of the
faultactor element information item is the URI that identifies the SOAP
node that generated the fault.  (Note: this URI MAY but need not be the
same as the URI naming a role assumed by the node.  See section 2.2 for
information about naming of SOAP roles.)"

*Section 5.4.5:
Original:
"All child element information items of the detail element information item
are called detail entries.
Each such element information item:
MAY be namespace qualified.
MAY have an encodingStyleattribute information item."
Question:  Can they have element children?  What about additional
attributes?

*Section 5.4.8:  Original: "It is NOT a requirement that the fault contain
the qualified names of ALL header blocks that were not understood in a SOAP
message. A SOAP node MAY generate a fault immediately upon encountering a
header block that is not understood containing information about that
single header block only. Alternatively SOAP nodes MAY generate a combined
fault containing information about all the header blocks that were not
understood at once."  I think this formulation conflicts with our
declaritive approach to specifying processing rules.  In particular, the
phrase "immediately upon encountering" smacks of a determined processing
order.  I would suggest the following as an alternative "It is NOT a
requirement that the fault contain the qualified names of ALL header blocks
that were not understood in a SOAP message. A SOAP node MAY generate a
fault for any one or more such blocks."

Minor
-----

Section 1.2, first paragraph: perhaps "message examples in this document
are shown using XML 1.0" should say "message examples in this document are
shown using XML 1.0 syntax"?

Section 2.6 first paragraph: suggest replacing "as long as all SOAP
messages" with "as long as all generated SOAP messages".  I think it's a
bit clearer.

Section 2.6, Note at the end: the word "survived" is misspelled.  The
entire document needs to be spell checked.

Section 2.7.1: suggest the following minor rewording of the first sentence.
Original: "The semantics of one or more SOAP blocks in a SOAP message, or
the SOAP message exchange pattern used MAY request that the SOAP message be
forwarded it to another SOAP nodes...".  I don't think that either
"semantics" or a "pattern" can make a request.   Proposed provision: "The
semantics of one or more SOAP blocks in a SOAP message, or the SOAP message
exchange pattern used MAY >>require<< that the SOAP message be forwarded it
to another SOAP nodes..."

Section 5.4.5:  wording is a bit  confusing  Original: "The absence of the
detail element information item indicates that a SOAP Fault is not related
to the processing of the SOAP Body . This can be used to find out whether
the SOAP Body was at least partially processed by the ultimate SOAP
receiver before the fault occurred, or not."  What is "this" in the last
sentence?  Suggested alternative:  "The absence of the detail element
information item indicates that a SOAP Fault is not related to the
processing of the SOAP Body.  Presence of the detail element information
item is a signal that the SOAP Body was at least partially processed by the
ultimate SOAP receiver before the fault occurred."

Section 5.4.6, first paragraph: I believe that the reference to XML
Namespaces [7] should in fact be to the Schema Datatypes recommendation.

Section 5.4.6:
- Table entry for VersionMismatch.  Original:  "The processing party found
an invalid element information item..."  Replace with:  "The faulting node
found an invalid element information item..."  A processing party sounds
like something we would have with cake and ice cream once our SOAP
implementation worked.  Later in that same definition:  Original:  "The
namespace, localname or both did not match the Envelope element information
item (see 2.8 SOAP Versioning Model and 5.4.7 VersionMismatch Faults)"
Replacement: "The namespace, localname or both did not match the Envelope
element information item required by this recommendation (see 2.8 SOAP
Versioning Model and 5.4.7 VersionMismatch Faults)."
-I believe that the header on the first column in the table should be
"Local Name", as opposed to "Name"
-Table entry for DTDNotSupported to be removed per issue 191
-In the description of DataEncodingUnknown:  Replace "A header or body
targetted at the current SOAP node is scoped (see 5.1.1 SOAP encodingStyle
Attribute) with a data encoding that the current node does not support."
with "A header or body targetted at the faulting SOAP node is scoped (see
5.1.1 SOAP encodingStyle Attribute) with a data encoding that the faulting
node does not support."

Sorry this list is so long.  I hope this is of help in refining our work.

[1] http://www.w3.org/2000/xp/Group/2/03/23/soap12-part1-1.37.html

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

Received on Thursday, 4 April 2002 22:30:03 UTC