QA Review on WSDL 2.0 Part 1, intro and conformance issues

After having reviewed http://www.w3.org/TR/2004/WD-wsdl20-20040803/, I
collected a (rather largish) set of comments; overall, I found the doc
very clear and precise; having more examples embedded would help
understanding and reading it, although I understand a primer is being
developed.

I've split my detailed comments in 3 parts:
- conformance issues
- technical issues
- editorial issues

This mail has the first set, I'll send separate mails for each set.

Conformance issues (these comments have been mostly inspired from specGL
[4]):

* Document conformance
http://www.w3.org/TR/2004/WD-wsdl20-20040803/#markup
 "Note that the WSDL language is defined in terms of the component model
defined by this specification. As such, it is explicitly NOT a
conformance requirement to be able to process documents encoded in a
particular version of XML, in particular XML 1.1 [XML 1.1]." is both
very hard to read, and probably in contradiction with the header
"document conformance"; I guess this needs clarification
It is particularly unclear to me that defining conformance for an
"element information item" has any sense at all.

* Also, section 1.2 ("Notational conventions") adds the definition of
"valid/not valid WSDL document", with important conformance
requirements. I suggest it should be moved to the conformance section,
and the normative schema should be referenced from there. Additionally,
while using the content-negotiated URI as a namespace URI is a good
idea, I suggest referring explicitly the schema URI (with the .xsd
extension) would be better when talking about the schema itself.

* it would be interesting to list (maybe in an appendix) what
constraints are not translated in the provided XML Schema

* Processor conformance
http://www.w3.org/TR/2004/WD-wsdl20-20040803/#processor
"""This section defines a class of conformant WSDL processors that are
intended to act on behalf of a party that wishes to make use of a Web
service"""
I suggest that you give a specific label to this class of WSLD
processors, à la "WSDL 2.0 requesting processor" - you'll probably find
something better.

* "a conformant WSDL processor MUST accept any legal WSDL document":
what is a legal WSDL document? I suggest saying "conformant WSDL
document" - but I'm still unclear whether you define that at all in the
section above

* you use both the expressions "a processor MUST fault" and "a processor
MUST fail"; do they mean the same thing? In any case, I think you should
clarify what is meant by those (i.e. what consist failing/faulting in?),
and if they mean the same thing, only use one of the expressions; also,
since the name 'fault' is used in a very well defined context in the
spec, I think you should avoid using the verb 'fault' unless it relates
to the said context; more generally, I think developing the notion of
error handling for a WSDL processor would be benefitial

* "a conformant WSDL processor MUST either agree to fully abide": I
think this an abusive usage of MUST, since "agreeing" is not an
operation that a WSDL process does; I would suggest "a conformance WSDL
processor MUST immediately cease processing (fault) if it doesn't agree
to fully abide ...."

* "that it does not choose to implement." -> "it chooses not to
implement", or maybe "it doesn't implement"

* the "Note:" under this defines conformance requirements for a provider
agent, which is out of scope for the given section; I suggest creating a
different section, even if that's the only requirement for it

* the section 6.1 on mandatory extensions adds requirements both for
requesting and providing processors; most are duplicated in the
conformance section, but I think a few are not (e.g. "the provider agent
MUST support every extension, Feature or Property that is declared as
optional in the WSDL document"); I suggest they should be added to the
conformance section
http://www.w3.org/TR/2004/WD-wsdl20-20040803/#mandatoryext

*likewise, section 4.1 makes a suggestion for processors:
"Processors are encouraged to keep track of the source of component
definitions, so that multiple, mutual, and circular includes do not
require establishing identity on a component-by-component basis."
http://www.w3.org/TR/2004/WD-wsdl20-20040803/#includes
Maybe this could be added as a SHOULD in the conformance section

* section 1.1 reads "All parts of this specification are normative, with
the EXCEPTION of notes, pseudo-schemas, examples, and sections
explicitly marked as "Non-Normative"."; some of the "Note:"s include
normative-like language, e.g. 
"Support for the W3C XML Schema Description Language [XML Schema:
Structures],[XML Schema: Datatypes] is required of all processors." 
or
"If a WSDL document declares an extension or feature as optional, then
if that extension or feature could apply to messages sent by the
provider agent as well, then the provider agent MUST NOT send any
messages that requires the requester agent to support that extension or
feature."
Please fix.


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