QA Review on WSDL 2.0 Part 1, Editorial comments

Reviewing http://www.w3.org/TR/2004/WD-wsdl20-20040803/ (part 3)

Editorial issues:
- section 1.3 (WSDL terminology) has only one item; I would find
surprising that this specification only defines one new concept; e.g. a
'Web Service Component'  would probably deserve to be defined here;
also, linking to the WS Glossary may be a good idea

- section 2's title is "Component Model" and uses these phrases a few
times, but doesn't define it

- section 2 has most of the meaty stuff (the component model), but it is
somewhat diluted by the XML serialization formalism; I wonder if moving
the XML serialization in a different section (or in an appendix) would
enhance the readability of the spec;

- I suggest marking up and styling appropriately (or maybe
capitalizing?) words that are used in a very specific way in the
specification; e.g. in 2.1.1 "At the abstract level, the Definitions
component is just a container for two categories of components; WSDL
components and type system components." would better read IMHO as "At
the abstract level, the Definitions Component is just a container for
two categories of component: WSDL Components and Type System Components"
(I used capitalization in this case, but italicizing may work better).

- the document introduction still calls Part 2 "Message Exchange
Patterns", although it's now called Predefined extensions

- the document refers to the language as "WSDL"; since WSDL has been
available in several versions, I suggest using "WSDL 2.0" instead - if
not everywhere, at least in the introduction

- in 2.1.1 "Note that it is RECOMMENDED that the value of the
targetNamespace attribute information item SHOULD be a dereferencible
URI and that it resolve to a WSDL document which provides service
description information for that namespace"; the "SHOULD" is not needed
since the sentence is preceded by "RECOMMENDED"

- I suggest linking the XPointer scheme definition for WSDL (appendix C)
from section 2.1.1., where dereferenceability of components is mentioned

- there are only 2 examples of complete WSDL definitions in the whole
spec (one in an appendix); adding a few simple examples in the course of
the spec may help the reader a bit more; more generally, having a bit
more illustrations of what WSDL is about would help [I see that a primer
is in preparation; still, I don't think a few included examples would
hurt]
Also, the first example (in 2.7.1.1.1) should declare that <definitions>
(and its children) are in the WSDL namespace
The second example (in C.4) uses a relative URI as its
xsi:schemaLocation; any reason to use "wsdl20.xsd" instead of
"http://www.w3.org/2004/08/wsdl/wsdl20.xsd"?

- section 2.2.2.3 introduces the notion of style, which is only
explained later in 2.4.1.1; would be good to make a link from the former
to the latter

- section 2.4.2 reads "If the Interface Operation component uses a
{message exchange pattern} for which there is no output element, such as
'http://www.w3.org/2004/08/wsdl/in-only'"; but according to the
paragraph above "The RPC style MUST NOT be used for Interface Operation
components whose {message exchange pattern} property has a value other
than 'http://www.w3.org/2004/08/wsdl/in-only' or
'http://www.w3.org/2004/08/wsdl/in-out'.", this should not be "such as",
but "i.e."; or did I miss something?

- 2.4.2.1 starts with "The wrpc:signature extension AII MAY be be used":
what is AII? "be" is repeated twice
thereafter, it uses the notion of a function signature, without much
introduction; since "RPC" is never translated into "Remote Procedure
Call", it looks a bit awkward

- in section 2.5.1 "by the global element declaration reference by the
{element} property.", "reference" should read "referenced"

- section 2.8.2 reads "An OPTIONAL required attribute" which contradicts
the model described in 2.8.1  where {required} is REQUIRED

- 2.17, "the combination of these two properties need not be unique" ,
"need" should read "needs"

- in section 3, "W3C XML Schema Description Language" isn't a proper way
to refer to XML Schema; use "W3C XML Schema" or 'W3C XML Schema
language'

- section 4.2 uses "DOES NOT" (upper case), as if it was an RFC Keyword;
IT'S NOT

- the document references XML 1.0 Second  Edition, while the third has
been published earlier this year

- it also references outdated versions of XML Infoset and WebArch (see
[1])

- the table of contents should use real markup, rather than &nsbp;; I've
provided a patch to xmlspec for this purpose [2]

- a few typos: "compomnent", "dereferencible" (should be dereferenceable
AFAIK), "implicitely" (implicitly), "requestor" (requester) based on the
spell checker [3]

1. TR references checker:
http://www.w3.org/2000/06/webdata/xslt?xslfile=http%3A%2F%2Fwww.w3.org%2F2004%2F07%2Freferences-checker&xmlfile=http%3A%2F%2Fcgi.w3.org%2Fcgi-bin%2Ftidy-if%3FdocAddr%3Dhttp%253A%252F%252Fwww.w3.org%252FTR%252F2004%252FWD-wsdl20-20040803%252F&
2. http://lists.w3.org/Archives/Public/spec-prod/2004AprJun/0000.html
3.
http://www.w3.org/2002/01/spellchecker?uri=http://www.w3.org/TR/2004/WD-wsdl20-20040803/

-- 
Dominique Hazaël-Massieux - http://www.w3.org/People/Dom/
W3C/ERCIM
mailto:dom@w3.org