Comments on a read through of part 2

I know this is somewhat late, but I have completed a read through of part 2
[1].  So far, I have only managed to transcribe my comments through the end
of chapter 4.  Tomorrow is more or less full with teleconferences, but I
will try to get to the rest as soon as possible. I hope this is still
useful.

Most significant comments
-------------------------

* Section 2.1: "An edge in the graph is said to originate at a node and
terminate at a node."  Did we never finally decide whether there can be
edges with no origin?  If so, make sure this and the rest of the
presentation correctly represents our conclusion.  If not, open an issue to
clarify this.

* Section 2.3:
<original>
2. A non-terminal whose outbound edges are distinguished solely by label is
known as a "struct".
</original>
<suggested>
2. A non-terminal whose outbound edges are distinguished solely by label is
known as a "struct".  The edges within a struct MUST be labeled with
distinct names (see 2.1.1 Edge labels).
</suggested>
I don't think we say that anywhere else, and its what distinguishes a
struct from a generic.

* Section 3.1.1:
I noticed that we forget to say that the target of a ref must be encoded.
If the following is agreeable, then please make the change.  Otherwise, I
think we should open an issue to clarify the rule.
<original>
If the element information item representing the edge does have a
refattribute information item ( see 3.1.4.2 ref Attribute Information Item
), then the value of that attribute information item MUST be identical to
the value of exactly one idattribute information item ( see 3.1.4.1 id
Attribute Information Item ) in the same envelope.
</original>
<suggested>
If the element information item representing the edge does have a ref
attribute information item ( see 3.1.4.2 ref Attribute Information Item ),
then the value of that attribute information item MUST be identical to the
value of exactly one idattribute information item ( see 3.1.4.1 id
Attribute Information Item ).  The element on which the ID attribute
appears MUST be within the scope of a SOAP-ENV:encodingStyle attribute with
the value "http://www.w3.org/2001/12/soap-encoding".
</suggested>
By the way: are we clear that it need not be the same use of
SOAP-ENV:encodingStyle?  I.e. you can link across scopes as long as our
encodingis specified?  I think we resolved that, but was never quite clear
on the resolution.

* Section 3.1.3:
I don't think the distinction between locally and globally scoped elements
holds up in the manner that it is presented.  I think the whole thing needs
a serious rethinking to make sure we understand the goals, and have a clear
presentation.  Do we really need to say anything about local and global
scoping at all, now that we are so nearly independent of schema validation?
I suggest we open an issue, and propose as a resolution which to get rid of
the distinction between globally and locally scoped edges.  Completely
remove the concept of local/global from our spec.  Failing that, the
wording needs significant clarification.

* Section 3.1.3:
<original>
If outbound edges are distinguised only by position ( "array" ) then the
local name and namespace name properties of the element information item
are not significant.
</original>
<suggested>
If outbound edges are distinguised only by position ( "array" ) then the
local name and namespace name properties of the element information item
are not significant.  The corresponding edges are unlabeled.
</suggested>

* section 4.0 paragraph 2: I suggest adding a sentence to the end of the
paragraph that would say: "The encoding specified must support the "struct"
and/or "array compound" value constructions from the SOAP data model [ref
to SOAP data model}." Or, if you want to be less subtle: "The encoding
specified must support the SOAP data model [ref to SOAP data model}."
Also:  there is a more or less duplicate statement at the end of section
4.1.  Maybe the duplication should be eliminated?  If not, then perhaps
that paragraph also should say "However, any encoding used MUST support the
SOAP data model."

* Section 4.0: in the list of things needed to invoke an RPC: I suggest
replacing "The URI of the target SOAP node" with "The binding-specific
address of the target SOAP node".  While use of URI's is no doubt
encouraged for addressing SOAP messages, the means of addressing is the
business of the binding, not of RPC.

* Section 4.0: also in the list of things needed to invoke an RPC: I
suggest removing the item that says "An optional procedure or method
signature".  This is really a slippery slope and primarily the business of
specifications like WSDL.  We could replace this with "The identities
(which may be either positional or by name) and values of any arguments to
be passed."  Now it's clear that description languages aren't our business:
we just need to know what to pass in this message.

* Section 4.0: should be RPC section mention any dependence on the req/resp
MEP?  I think so.  New issue?


Moderate significance
---------------------

* Status of document:
<original>
The specification has been split into two documents: SOAP Version 1.2 Part
1: Messaging Framework <soap12-part1.html> which describes the SOAP
envelope and the SOAP underlying protocol binding framework, and SOAP
Version 1.2 Part 2: Adjuncts <soap12-part2.html>, which describes the SOAP
Encoding rules, the SOAP RPC Representation and a concrete HTTP binding
specification.
</original>
<suggested>
The specification consists of two documents: SOAP Version 1.2 Part 1:
Messaging Framework <soap12-part1.html> which describes the SOAP envelope
and the SOAP underlying protocol binding framework, as well as the SOAP
extensibility model and SOAP Version 1.2 Part 2: Adjuncts
<soap12-part2.html>, which describes the SOAP Encoding rules, the SOAP RPC
Representation, Message Exchange Patterns and a concrete HTTP binding
specification.
</suggested>
Note two changes above:  split -> consists & list of items in the specs
updated to match the new TOC.

* section 1:
a) Add "Message Exchange Patterns" to the list of topics covered in part 2.
b) Maybe add "A Convention for Describing Features and Bindings" to the
same list.
c) Capitalize the word "MAY" in the last sentence of the first paragraph.

*Section 2.1.1:
<original>
A given outbound edge is identified either by label or by position, or
both. Position is a total order on all the outbound edges of a given node;
thus any outbound edge can be identified by postiion. An edge label is an
XML Schema Qualified Name (QName). Two edge labels are equal if and only if
both of the following are true:
Their local name values are the same.
Either of the following is true:
Their namespace name values are missing.
Their namespace name values are present and the same
( see XML Schema Datatypes[5] for more information about comparing QNames )
</original>

Other than a spelling error, my main concern is that the first sentence
doesn't make clear that identification is with respect to the outbound
node.  Thus:

<suggested>
Edges outbound from a given node MAY be distinguished by by label, by
position, or both.  Position is a total order on such edges; thus any
outbound edge MAY be uniquely identified by its position <==NOTE SPELLING
FIX . An edge label is an XML Schema Qualified Name (QName) <===NEED BETTER
REFERENCE HERE. Two edge labels are equal if and only if both of the
following are true:
Their local name values are the same.
Either of the following is true:
Their namespace name values are missing.
Their namespace name values are present and the same
See section 2.3 for uses of edge labels and position to distinguish the
members of encoded compound values.
( see XML Schema Datatypes[5] for more information about comparing QNames )
</suggested>

* section 3:
<original>
SOAP Encoding describes how to encode instances of data that conform to the
data model described in 2 The SOAP Data Model for inclusion in SOAP
messages. Note that nothing precludes the specification of different
encodings based on other data models, or indeed that make different use of
the SOAP Data Model.

The serialization rules defined in this section are identified by the URI
"http://www.w3.org/2001/12/soap-encoding". SOAP messages using this
particular serialization SHOULD indicate this using the SOAP encodingStyle
attribute information item (see [1]SOAP Encoding Attribute
<soap12-part1.html>).
</original>
<suggested>
SOAP Encoding describes the XML encoding of data that conforms to the data
model described in 2 The SOAP Data Model.   This encoding MAY be used to
transmit data in SOAP header blocks and/or SOAP bodies. Other data models,
alternate encodings of the SOAP model, as well as unencoded data MAY also
be used in SOAP messages.  (See [ref to encoding style] for specification
of alternate encoding styles, and [ref to RPC] for restrictions on data
models and encodings used to represent SOAP Remote Procedure Calls).

The serialization rules defined in this section are identified by the URI
"http://www.w3.org/2001/12/soap-encoding". SOAP messages using this
particular serialization SHOULD indicate this using the SOAP encodingStyle
attribute information item (see [1]SOAP Encoding Attribute
<soap12-part1.html>).
</suggested>

* Section 3.1.5: I think this is really part of the encoding and should
probably be moved up ahead of 3.1.4.

* Section 3.1.5:
<original>
The type name property of a graph node is computed as follows;
</original>
<suggested>
The type name property of a graph node is a {namespace name, local name}
pair computed as follows:  <== COLON, NOT SEMICOLON
</suggested>

* Section 4.2:
<original>
Additional information relevant to the encoding of an RPC invocation but
not part of the formal procedure or method signature MAY be expressed in
the RPC encoding. If so, it MUST be expressed as a header block.
</original>
<suggested>
Additional information relevant to the encoding of an RPC invocation but
not part of the formal procedure or method signature MAY be expressed in an
envelope carrying an RPC invocation or response.  Such additional
information must be expressed as SOAP header blocks.
</suggested>

Minor and editorial
-------------------

* Section 2.1 first paragraph, second sentence:  "An edges that originates"
==> "An edge in that originates"

* Section 2.2: "( of type XML Schema QName )."  This seems a bit informal.
Don't we usually say something like "of type QName in the namespace....",
perhaps followed by a formal reference to the schema data types
specification?  A similar informal reference occurs in the note in item 1
in the list in section 3.1.5.  Suggest you check all references to
datatypes in both specs.

* Section 3.1 "To describe encoding"  ===> "To describe the encoding"

* Section 3.1.3 (and others):  The reference to "A Mapping Application
Defined Name to XML Name )" is very confusing.  I think we should make that
"Appendix A: Mapping Application Defined Name to XML Name".  We should
correct both the references and the appendix itself IMO.  Also, I think
that should be A Mapping Application Defined Names to XML Name  .. make
"names" plural.

* Section 3.1.3: "it can be encoded as an element information item with an
xsi:nilattribute information item." correct spacing between nil and
attribute.

* Section 3.1.5 "However, nothing herein prohibits development of
additional specifications that desribe the use of SOAP with particular
schema languages or type systems." ====> "However, nothing herein prohibits
development of additional specifications to <===CHANGED WORD describe
<==SPELLING CORRECTED the use of SOAP with particular schema languages or
type systems."

* Section 3.1.6:
<original>
Value of enc:arraySize
</original>
<suggested>
The value of enc:arraySize must conform to the following EBNF [ref to EBNF}
grammar:
</suggested>

* Section 3.1.6:
Maybe:  add a production for "digit = [0-9]+"  (my EBNF is rusty, make sure
this is right)

* Section 3.2:
During deserialization a SOAP receiver:
...
MAY generate an env:Sender SOAP fault with a subcode of enc:UntypedValue if
the type name property of an encoded graph node is unspecified."
Why?  It seems like needless complexity to introduce this fault, use of
which is non mandatory anyway.  Not a big deal, but I wonder whether KISS
would suggest getting rid of this for now.

* Section 4.1: "The invocation is viewed as a single struct or array
containing an outbound edge for each [in] or [in/out] parameter" ===>"The
invocation is represented by a single struct or array containing an
outbound edge for each [in] or [in/out] parameter"

* Section 4.1: "The response is viewed as a single struct or array
containing an outbound edge for the return value and each [out] or [in/out]
parameter. " ===> "The response is represented by a single struct or array
containing an outbound edge for the return value and each [out] or [in/out]
parameter. "

* Section 4.3: "The SOAP RPC Representation introduces additional SOAP
fault subcode values to the fault codes described in [1] section Fault
Codes <soap12-part1.html>. " ====> "The SOAP RPC Representation introduces
additional SOAP fault subcode values to be used in conjunction with the
fault codes described in [1] section Fault Codes <soap12-part1.html>. "
Also, a period is missing at the end of this paragraph.

* Section 4.3: suggestion: "A fault with a value of "env:Sender" for
faultcode and a value of "rpc:ProcedureNotPresent" for subcode MUST be
generated when the receiver cannot find the procedure specified." ===> "A
fault with a value of "env:Sender" for faultcode and a value of
"rpc:ProcedureNotPresent" for subcode MUST be generated when the receiver
does not support the procedure or method specified."  I don't think we want
to suggest anything that has to do with the means by which a server
resolves or "finds" the procedures that it is asked to invoke.   Also:  the
rest of the spec uses the term "procedure or method", so I added that.

* Section 4.3: "In all cases the values of the detail and faultstring
element information items are implementation defined. They MAY be specified
by some external document." ====> "In all cases the values of the detail
and faultstring element information items are implementation defined.
Details of their use MAY be specified by some external document." Though
the intention is clear, I believe that gramatically the antecedent of
"They" was ambiguous. (Also, I'm still not very comfortable with the term
"external document", but don't have any bright ideas for alternatives at
the moment).

As always, I hope this helps.   Cheers.

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

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

Received on Tuesday, 9 April 2002 22:10:25 UTC