[Fwd: review of SOAP 1.2 Part 1]

-------- Original Message --------
Subject: review of SOAP 1.2 Part 1
Resent-Date: Wed, 15 May 2002 09:19:59 -0400 (EDT)
Resent-From: w3c-xml-protocol-wg@w3.org
Date: Wed, 15 May 2002 07:15:59 -0400
From: Christopher Ferris <chris.ferris@sun.com>
To: w3c-xml-protocol-wg <w3c-xml-protocol-wg@w3.org>

As requested, I've reviewed the current SOAP 1.2 Part 1[1] and Part 2[2]
specs. My comments follow.

Cheers,

Chris

[1] http://www.w3.org/2000/xp/Group/2/05/14/soap12-part1-1.117.html
[2] http://www.w3.org/2000/xp/Group/2/05/14/soap12-part2-1.93.html

General comments:

- no mention/reference of Primer in SOAP Part 1 (and Part 2)? recommend
it be added into the Introduction section in a manner similar to XML Schema
part 1:

"This document is primarily intended as a language definition reference.
As such, although it contains a few examples, it is not primarily designed
to serve as a motivating introduction to the design and its features, or
as a tutorial for new users. Rather it presents a careful and fully
explicit definition of that design, suitable for guiding implementations.
For those in search of a step-by-step introduction to the design, the
non-normative [XML Schema: Primer] is a much better starting point
than this document."

- use of 'optional' to describe cardinality can result in confusion
because in RFC2119 the term refers to 'optional to implement'.
In the case of the SOAP role and mustUnderstand attributes,
a SOAP node is REQUIRED to implement the processing associated
with these attributes which are only "optional" from the
perspective of the designer of a SOAP header block w/r/t
whether they will be permitted as AII children of the
SOAP header block's EII [attributes] property.

- use of CASE alone to distinguish between RFC2119 meaning
and conventional meaning is confusing. suggest that different
words be used whenever possible (e.g. 'might' instead of 'may')
would strongly advise against use of the word 'must'
in all but the RFC2119 sense. A reader could mistake this
for a typo (where the editors simply neglected to capitalize
the term).

- the term 'SOAP block' is still used, yet term is not defined. suggest
that the glossary term 'SOAP header block' be used consistently
throughout and be substituted for all instances of 'SOAP block'.

- the term 'header block' is also used. suggest that 'SOAP header
block' be substituted for 'header block'

- aren't the namespace URIs going to change?

- there are cases where the font seems to be different (see
sect 5.4) than the rest of the document. this should be fixed

- sect 5.4.7 example is very contrived. It makes little sense
to return a VersionMismatch fault in a 1.2 envelope.

- part2 sect 3.1.2 - why is "lexical value" in quotations? I can
see Mike Meyers now... remove the quotation marks

Received on Wednesday, 15 May 2002 23:47:05 UTC