WSDL 2.0 primer CR comments

The WSDL 2.0 Primer CR contains a number of editorial errors:

* Sections 1.3's heading says "Use of URI and IRI."  Since the section talks
   about URIs and IRIs, and not about the words "URI" and "IRI," the section
   title should probably say "Use of URIs and IRIs."


* Section 2.1.1 says:

     ... a floating point number in USD$ ...

   "USD$" should be "USD" (or some other valid option).

   (Also, is "floating point number" valid outside the realm of fixed-size
   storage with an exponent field?)


* Section 2.2 says:

     A language specification must therefore define the set sentences
     in that language ...

   That should be "... set of sentences ..."


* Section 2.2.2.1 says:

     ... how the children elements of the description element ...

   That should say "child elements" instead of "children elements" (because
   that use of a noun as an adjective requires the singular form).


* Section 2.2.2.1 also says:

     Thus, the order of the WSDL 2.0 elements matters, in spite of
     what the WSDL 2.0 schema says.

   The wording "in spite of ..." implies that there is a contradiction,
   namely, that the schema implies that the order does not matter, and
   that what the schema implies is to be ignored.

   Perhaps saying something like "... the order ... matters, even though
   the schema doesn't specify that it does" would avoid implying something
   false to the reader.

* Section 2.2.3 says:

     (Whew!).

   The period (full stop) is extraneous.  (The exclamation point already
   ends the statement.)

* Section 2.3.3 says:

     So far we have briefly covered both WSDL import/include and schema
     import/include.

   Since slash means (or usually means) "or" (recall, for example, that
   "and/or," which means "and or or"), that should be written out as "...
   WSDL import and include and schema import and include" (also because
   text should probably be readable without having to figure out to
   which word a punctuation character was intended to map).

* Section 4.4.1 says:

     ... is signaled by attribute wsdl:required="false" ...

   That wording isn't quite right.  The construct "attribute xyz" only
   works when "xyz" is the name of the attribute.

   The text should say something like:

      ... is signaled by setting attribute wsdl:required to "false" ...

   or:

     ... is signaled by setting wsdl:required="false" ...

   or:

     ... is signaled by wsdl:required="false" ...

   (The next paragraph has another instance of the same problem.)

* Section 4.2.3 still says:

     <min 3, max 7> <!-- check schema for syntax -->

* Section 5.1 repeatedly refers to "uniquely identify[ing] a message"
   when it really means uniquely identifying a message _type_.  For
   example, the first sentence says:

     It is desirable for a message recipient to have the capability
     to uniquely identify a message in order to handle it correctly.

   That makes it sound like it's about to talk about per-message IDs
   (per-instance IDs).

   The wording should be reworked appropriately.


* Section 5.2 says:

     ... a wide ranging debate ...

   That should be:

     ... a wide-ranging debate ...




Additionally:

* Section 5.6.2 refers to RFC 2396, which has been obsolete for
   over a year.  The section should probably refer to RFC 3986.





Daniel Barclay

Received on Monday, 12 June 2006 22:10:08 UTC