Re: Comments from a Read-Through of Part 1

Noah,

Thanks for the detailed review! Comments follow.

Cheers,

Chris

Jean-Jacques Moreau wrote:

> Now to the moderate ones...
> 
> Noah Mendelsohn/Cambridge/IBM wrote:
> 
> 
>>Moderate Importance
>>-------------------
>>
>>* Section 5.4.2: Should we allow xml:lang on faultString?  This will
>>probably be a concern for the internationalization folks.
>>
> 
> Raised as an issue.


No brainer, IMO. I think it should/must.


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


I have never understood the rationale for this (same with Fault).


> 
> 
>>* 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."
>>
> 
> Done.
> 
> 
>>* 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.
>>
> 
> Done.
> 
> 
>>* 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..."
>>
> 
> Done.
> 
> 
>>* 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.
>>
> 
> Done.
> 
> 
>> That said, I think my proposed rewording is still
>>a bit lumpy, so some further wordsmithing might be needed.
>>
> 
> Not done.
> 
> 
>>* (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."
>>
> 
> Done.
> 
> 
>>* 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".
>>
> 
> Done.
> 
> 
>>*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.
>>
> 
> Agreed. Done.
> 
> 
>>* 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.
>>
> 
> Ibid. for 5.2. Gudge?
> 
> 
>>* 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."
>>
> 
> Changed to:
>         <p>To be recognized as carrying SOAP error information,
>         a SOAP message MUST contain exactly one SOAP <el>Fault</el>,
>         and that fault MUST be the only child element of the SOAP body.
>         A SOAP fault <emph>element information item</emph> MAY appear within
>         a SOAP header block, or as a descendant of a child <emph>element
>         information item</emph> of the SOAP body; but, in such cases, the
> element has
>         no SOAP-defined semantics.</p>


+1 but I liked Noah's wording better.


> 
>>* 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.
>>
> 
> Raised as an issue.
> 
> 
>>* 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.
>>
> 
> s/faultactor/faultnode/. Done.


woo hoo! :)


> 
> 
>> (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.)"
>>
> 
> Not done. Is this not covered by <faultrole> instead?
> 
> 
>>*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?
>>
> 
> My guess is that not listing them disallows them. Gudge?
> 
> 
>>*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."
>>
> 
> Swapped the two sentences, i.e. changed to:
>    <p>A SOAP node MAY generate a SOAP fault for any one or more
>    SOAP header blocks that were not understood in a SOAP message.
>    It is NOT a requirement that the fault contain the
>    qualified names of ALL such blocks.</p>
> 
> Thanks again.
> 
> Jean-Jacques.
> 
> 
>

Received on Friday, 5 April 2002 09:30:38 UTC