Comments on SOAP Version 1.2 Part 0: Primer

Commenting on http://www.w3.org/TR/2002/WD-soap12-part0-20020626/

My main concern that stood out is the use of XML qnames, the
(namespace name, local name) pair, for identifiers.  This doesn't seem
particular webby to me - URIs are the web's identifiers.

The TAG has been discussing this:

  (DRAFT) TAG Finding: Using Qualified Names (QNames) as Identifiers in Content
  http://www.w3.org/2001/tag/doc/qnameids.html

but offers mostly observations.  This seemed relevant:

  "Using QNames in untyped (#PCDATA or xs:string) attribute values or
  element content places an additional burden on the processor that
  was not anticipated by [XML Namespaces]."

Please consider this draft finding and the SOAP use of qnames.

In particular, SOAP seems to use all of qnames, uris and CDATA in
attribute values and element content as identifiers and it isn't
clear to me coming to this new, when this choice is made or why.


I include the more editorial comments below.

Dave

---

Editorial comments on http://www.w3.org/TR/2002/WD-soap12-part0-20020626/

2.1

m:reference contains something as element that could be a URI
but could look like a qname too given the use elsewhere
of qnames in element content.


Note why xmlns attributes are defined at the most local place in
env:Body rather than on doc element.  I assume this is a convention
for these examples rather than required, which


  "In Example 1, the header contains two header blocks, each of which
  is defined in its own namespace"

so are namespaces part of the SOAP model?  Are these XML namespaces?
Either way - if they are, mention it, if not, add an explanation

---

"The <tt>Body</tt> element ..."

I would rather the <tt>env:Body</tt> element was used throughout if talking
about that precise thing rather than the element local name <tt>Body</tt>.
In this case the example uses <tt>env:Body</tt>, so changing it makes
it more consistent.



2.2.2

Example 4 has the t:transaction "5" hanging about like this:

   ...    env:mustUnderstand="true" >
               5
   </t:transaction>

which took me a while to work out that it was the element content.
Maybe just me.

It has some additional odd formatting:

</m:reservation>   <o:creditCard xmlns:o="http://mycompany.example.com/financial">
 
and indenting that doesn't help reading the XML structure (and SOAP
structs):

     <o:expiration>2005-02</o:expiration>
     </o:creditCard>

Example 4 title says two "in" parameters

How are the parameters 'in'?  It isn't clear from the example.  Is
that the default?  Is it decided out of band?


Example 5a has different indenting levels, style from Example 4 - please
make them consistent.

Example 5a
'out' parameters - how is that indicated in this example?  Unlike
the example 5b which uses rpc:result, this example has no such
indicator.

2.3

Example 7 - why is xmlns:f defined on env:Envelope and not the
env:Header or f:Misunderstood elements?  Is it convention again?

General note: Also noticed some XML args are using '', some ""
I understand these are equivalent, it just stands out to me.


2.4

Example 7a elided example stands out as curious why SOAP mixing use
of qnames URIs, and CDATA for identifiers i.e. why:

 <p:oneBlock xmlns:p="http://example.com" 
            env:role="http://example.com/Log">

and not:

 <p:oneBlock xmlns:p="http://example.com" 
            env:role="p:Log">

I guess it is suuppose roles are expected to be defined as an
unlimited set of terms, ie URIs, rather than as names in an XML
namespace.

I'm comparing to earlier use of the attribute env:encodingStyle
(takes URI value), env:mustUnderstand attribute (takes CDATA
with a fixed set of terms), env:Value element (takes qname value from
fixed set of terms)

It isn't obvious when to use these or why qnames/CDATA are
chosen for fixed sets of terms.

--

The phrase 'actor attribute' suddenly appears in middle of a
paragraph, and related to, the ultimateReceiver role and talks about
the absence of such an attribute indicating such a role, when actors
have never before been discussed!  (this is the first use of the word)
Is this a typo, and 'role attribute' was meant?

I noticed later on in the changes that the role attribute was renamed
from earlier versions, maybe this needs updating.

--

"The body element" para?

should be <tt>Body</tt> since talking about the element, not 
the general SOAP body.

--

in the unlabeled table
  "The following table summarizes how the processing actions"
both columns are the same - why is this table needed?

General: please add numbers, titles (summary?), anchors to all tables
and link to them.


3.1

para 3,4 formatting
HTTP:1)the -> HTTP: 1) the
ofHTTP -> of HTTP
Acceptheader =>  Accept header

General: this suggests more spell checking needed throughout if these
weren't caught.  The HTML uses <span>s around them, so that might be
the cause.

3.1.2

Example 9 formatting near o:creditCard needs fixing as above


4.2
why are 'encoding schemes' labelled with an attribute called
env:encodingStyle ?  Surely this should be env:encodingScheme?


sec 5 not reviewed


sec 6 - references don't seem to be in right document style
from the W3C Style guide.  'Latest version ..' links etc.
missing


General

The HTML uses style="color: #000000" etc.  May be better as CSS
classes and possibly with other emphasis methods for better
accessibility.

Received on Friday, 19 July 2002 17:57:33 UTC