Re: Comments on a read through of part 2

comments inline

----- Original Message -----
From: "Noah Mendelsohn/Cambridge/IBM" <noah_mendelsohn@us.ibm.com>
To: <xml-dist-app@w3.org>
Sent: Wednesday, April 10, 2002 2:54 AM
Subject: 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.

Done.

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

Done.

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

That is my understanding.

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

I think we need to say how to map an edge name to the [local name] and
[namespace name] properties of an EII. I don't think we need to say any more
than that. Someone else ( Jacek? ) noted earlier that although we define
'local' and 'global' we never use 'em.

> Completely
> remove the concept of local/global from our spec.

So, I would support this.

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

Note done. Pending resolution of local/global issue described above.

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

Done

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

Done

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

Done. 3.1.5 and 3.1.4 swapped.

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

Done

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

Done

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

Done

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

Done.


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

Done

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

Not done. Stylesheet issue, working on a fix.

> Also, I think
> that should be A Mapping Application Defined Names to XML Name  .. make
> "names" plural.

Done

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

Fixed in a recent stylesheet change.

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

Done

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

I think we may need to work on the EBNF. Marc?

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

Comments from others?

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

And, as always, the editors are *VERY* grateful for your input

Gudge

Received on Wednesday, 10 April 2002 06:23:18 UTC