Comments on XML Schema: Component Designators (version of March 9 2004)

[bcc to www-qa]

Hello, XML Schema WG,

I've had a look at the following document, with a QA-ish eye; my hope is
that reviewing your document early in its Rec-track life may make it
easier for you to take the comments into account.

Document reviewed:
http://www.w3.org/TR/2004/WD-xmlschema-ref-20040309/
XML Schema: Component Designators
W3C Working Draft 9 March 2004

Conformance related comments:
- the document doesn't distinguish normative from information sections;
it would useful to do so to allow your readers to see where the
requirements are set at first glance
- the documents seems to use a declarative style to define its
requirements, although there is an occurrence RFC 2119 Keyword ("MAY")
in 4.; the declarative style seems pretty appropriate to this abstract
type of specification, but it makes it harder to identify edge-cases and
error processing if applicable
- the conformance section is marked as "To be done"; does the WG has
even a remote idea of what conformance to this specification would look
like? if so, documenting this would be tremendously useful; e.g., is
there any expectation to define an XML Schema Designator processor? or
is it out of scope for this specification? what about XML Schema
Designator generators (which, confusingly enough, would likely XML
Schema processors)?
- 4.2.3 has "The URI on the left hand side of the schema component
designator should be a URI of an actual document, in some media type.
That media type should be some XML derivative, so that the XPointer
framework applies." ; this seems very fuzzy: a URI is an identifier ; in
this case, what it identifies would be a schema designator rather than
"a document"; I think it should say "The schema designator URI should be
dereferenceable ; if it is, the representation of this URI should be an
XML document with a MIME-Type on which the XPointer framework applies"
- "In the simplest case, where there is one root schema document, the
URI of that document suffices" ; maybe a "SHOULD" for XSCD generators
would be in order, with a reference to the WebArch principle
http://www.w3.org/TR/2003/WD-webarch-20031209/#uri-aliases
- compatibility with XPath in the XSCD steps would be a big plus

Editorial comments:
- the EBNF in 4.1 seems to contradict the possibility of using the
xmlns() scheme in the relative-schema-component-designator 
- "schena" should read "schema" in 4.2.2
- the formatting of the TOC is done with   ; please use the
appropriate HTML markup instead (nested <ul> or <ol>)
- "Structurally, the first part looks like a URI, and the second part
looks like an XPointer fragment identifier. An absolute schema component
designator therefore is structurally a URI reference." -> why 'looks
like' rather than 'is'? (at least, it should be either 'looks like' in
all the cases, or 'is' in all the cases)
- splitting the bibliography into Normative/Informative references would
be good
- I have some suspicion the document was produced with XMLSpec; could
the XML version be provided as a non-normative alternative version to
the doc?

Thanks,

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