Proposed resolution to SOAP 1.2 Rec Issue 11

> Some feedback regarding SOAP Version 1.2 Part 2:
>
> Wording related to semantics:
>
> * Section 3.1.6 doesn't say in which order array dimension sizes are 
> listed.
>    (It doesn't say whether the first size in the list is the size of 
> the first
>    dimension or is the size of the last dimension.)

PROPOSAL: State that the sizes are listed in order, from first to last.

> * Section 3.1.6 uses its own definition of whitespace.  Should it 
> refer to
>    the XML specification's definition, so that if the XML 
> specification's
>    definition is modified in some future version (for example to 
> include
>    the EBCDIC newline character), future versions of the SOAP spec 
> (which
>    would refer to XML x.x instead of XML 1.0) will automatically 
> follow XML
>    evolution?

PROPOSAL:  change whitespace definition to "<as defined by XML>"

> * Section 3.1.6 doesn't define that sequences of digit characters 
> allowed
>    by the syntax are to be interpreted as regular decimal 
> representations
>    of integers.

PROPOSAL: No change.
Rationale: By default, all digits are to be interpreted in this 
fashion. This is accepted practice in W3C specifications.

> * "A relative URI whose base URI is ..."
>
>    Is that wording technically correct?
>
>    Does a relative URI really have a base URI, or is it the occurrence 
> of
>    a relative URI that has a base URI?
>
>    (The relative URI "x" doesn't have a base URI.  If I put it (a copy 
> of
>    it?) in an HTML document and viewed the document, then the 
> occurrence in
>    the document would have a base URI (the URI from which I retrieved 
> the
>    document).)
>
>    RFC 2396 refers to the base URI of a document and defines the base 
> URI
>    for resolution, but doesn't seem to mention a base URI of a URI 
> reference.
>
>    Should "A relative URI whose base URI is..." be "A relative URI 
> that will
>    be resolved against..."?
>
>    Also, must it be relative, or is it just allowed to be relative?

PROPOSAL: adopt suggested text. (table 4)

> Just editorial:
>
> * The wording "invocations of method and procedure calls" is 
> confusingly
>    inaccurate.  (A call _is_ an invocation.  You can invoke a 
> procedure;
>    you can't invoke a procedure _call_ (well, unless you're talking 
> about
>    "invoking" (executing) a procedure call statement that sets up for 
> and
>    then actually invokes a procedure).)

PROPOSAL: change "invocations of method and procedure calls" (section 4 
Intro) to "invocations of methods and procedures."

> * As written, the wording:
>
>      When mapping to or from a programming language method or procedure
>      call, the name of which identifies...
>
>    refers to the (non-existent) name of a _call_, instead of to the 
> called
>    method or procedure.

PROPOSAL: change "language method or procedure call" (4.1.1) to 
"language method or procedure."

> * "on an application or procedure-specific basis" should be
>    "on an application- or procedure-specific basis"
>
> * "the binding specific expression" should be "the binding-specific
>     expression"
>
> * "application defined data" should be "application-defined data"
>
> * "the application defined name" should be "the application-defined 
> name"
>
> * "is entirely platform independent" should be "is entirely
>     platform-independent "
>
> * "are implementation defined" should be "are implementation-defined"

PROPOSAL: Adopt the suggested text.
Rationale: When a compound phrase is used as an adverb, it should be 
hyphenated.

> * "i.e. ..." should be "i.e., ..." (several instances)

PROPOSAL: No change.
Rationale: This is a matter of style; either form is acceptable, as 
long as it is used consistently.

> * Delimiting special terms with brackets (e.g., "A [local name] of 
> ref")
>    is confusing (because it is not standard English use of brackets).

PROPOSAL: No change.
Rationale: This is well-recognised notation in W3C specifications.

> * "The struct is named identically to the procedure or method name":
>    Either:
>
>      "The struct name is identical to the procedure or method name."
>
>    or:
>
>      "The struct is named identically to the procedure or method."

PROPOSAL: Adopt the second suggestion. (4.2.1)

> * "the distinction between per message-exchange and more widely scoped
>    properties":
>
>    - "per message-exchange [properties]" should be 
> "per-message-exchange
>      [properties]"
>
>    - "the distinction between per-message-exchange properties and more
>      widely scoped properties"  would be clearer

PROPOSAL: Adopt the second suggestion. (5.1.2)

> * "containers called Message Exchange Context..."
>
>    Shouldn't that be "containers called the Message Exchange 
> Context..."?

PROPOSAL: No change.
Rationale: This doesn't add any clarity to the text.

> * In Figure 1, at least three labels don't match the terms in the
>    immediately preceding text:
>    - "SOAP" (instead of "SOAP node")
>    - "Environment" (instead of Environment Context)
>    - "Transport Message Exchange Context" (instead of "Message Exchange
>      Context")

PROPOSAL: Update the illustration. (5.1.2)

> * It looks like "Environment" was intended to be renamed to 
> "environment
>    context" but not all references were edited.  For example, section
>    5.1.2.2 says:
>
>       The environment context is...
>
>       The values...in Environment...
>
>    and section 5.1.2 says:
>
>       called...Environment Context.
>
>    The intended form should be determined and all references should be
>    edited to follow that indented form.

PROPOSAL: normalise on "Environment Context."

> * Table 4 is extremely wide (and can be hard to read and print).  It
>    would be helpfule if optional line breaks were be inserted in the
>    long URIs in that table (and in other tables).

PROPOSAL: No change.

> * "SOAP places no restrictions on the specificity of the URI or that it
>    is resolvable."
>
>    Something didn't get edited consistently.

PROPOSAL: "SOAP places no restrictions on the specificity of the URI,
and does not guarantee that it is resolvable."

> * "The media type of the request entity body (if present) otherwise,
>    omitted..."
>
>    apparently should be:
>
>      The media type of the request entity body, if present; otherwise,
>      none...

PROPOSAL: Adopt the suggested text. (Table 16)

> * "The response message follows in HTTP response..." should be
>    "The response message follows in the HTTP response..."

PROPOSAL: Adopt the suggested text. (Table 17)

> * "it is recommended that such behavior is disabled" should be
>    "it is recommended that such behavior be disabled"

PROPOSAL: Adopt the suggested text. (7.5.1.2)

> * "...it is strongly RECOMMENDED that...implications...is fully 
> understood"
>    should be:
>
>       ...it is strongly RECOMMENDED that...implications...be fully 
> understood

PROPOSAL: Adopt the suggested text. (A.2)

> * "the schema recommendation is build on..." should be "the schema
>    recommendation is built on..."

PROPOSAL: Adopt the suggested text. (C.1) Also, should be 
"Recommendation", not "recommendation", throughout.

> * The SOAP encoding schema linked to from the main document says:
>
>    Schema defined in the SOAP Version 1.2 Part 2 specification Proposed
>      Recommendation:
>       http://www.w3.org/TR/2003/PR-soap12-part2-20030507/

PROPOSAL: Update text and link to REC. (8.1, 8.2)

> * The main document _contain_ a copy of the SOAP Encoding Schema in the
>    text.  Doing so would make the HTML document more self-contained.

PROPOSAL: No change.
Rationale: XML Schemas are not intended to be human-readable (Gudge 
notwithstanding).


--
Mark Nottingham   Principal Technologist
Office of the CTO   BEA Systems