W3C home > Mailing lists > Public > public-ws-desc-comments@w3.org > April 2005

RE: QA Review on WSDL 2.0 Part 1, Editorial comments

From: Jonathan Marsh <jmarsh@microsoft.com>
Date: Fri, 29 Apr 2005 16:03:59 -0700
Message-ID: <7DA77BF2392448449D094BCEF67569A507609C62@RED-MSG-30.redmond.corp.microsoft.com>
To: Dominique HazaŽl-Massieux <dom@w3.org>
Cc: <public-ws-desc-comments@w3.org>

Thank you for the comment below, and for your patience with us in resolving it.  We tracked the comment below as Issue LC7 [1].  The editors have addressed the editorial matters you highlight below in their latest draft [2].

If you agree with our disposition of your comment, we'd like you to acknowledge it within two weeks; otherwise we will assume you are satisfied.  The WG plans to enter a second (short) Last Call period in the near future, and we invite you to review that publication as well.

[1] http://www.w3.org/2002/ws/desc/4/lc-issues/issues.html#LC7
[2] http://dev.w3.org/cvsweb/~checkout~/2002/ws/desc/wsdl20/wsdl20.html


> -----Original Message-----
> From: public-ws-desc-comments-request@w3.org [mailto:public-ws-desc-
> comments-request@w3.org] On Behalf Of Dominique HazaŽl-Massieux
> Sent: Thursday, August 05, 2004 5:48 PM
> To: public-ws-desc-comments@w3.org
> Subject: 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/W
> D-wsdl20-20040803/
> 
> --
> Dominique HazaŽl-Massieux - http://www.w3.org/People/Dom/
> W3C/ERCIM
> mailto:dom@w3.org
Received on Friday, 29 April 2005 23:04:08 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Tuesday, 8 January 2008 14:20:31 GMT