Re: what's wrong with using XML Schema/HTML/RDF to document namespaces?

Dan Connolly wrote:

>  7. The definitive material for a namespace is normally distributed
> among multiple resources.
> 
> well, in these cases, yes and no: there's one definitive piece
> of documentation to start with, so in that sense, no. But
> that starting document's meaning is a function of other documents.
> So yes.

Seems to me you have a corner case here where XML-schema-ware is all you 
have.  If that's all you have I supppose it is marginally less harmful 
to put it at the namespace URI.  It would be substantially better to put 
an HTML document there saying "at the moment, all we have for this 
namespace is the XML Schema you can find starting _here_, so if you want 
to figure out you're just going to go have to do a view source on it, 
sorry".

Significant namespaces that come equipped only with an XML Schema and 
nothing else are going to be thin on the ground.  I've never heard of 
one.  It's a lousy case to optimize for.

>>An XML Schema is highly architecturally unsound because it is (a) by 
>>default not human readable,
> 
> Hmm... it seems to be as human readable as, say, an SVG document,
> or even HTML; if you have schema visualization tools, you can
> make sense of it. If not, you can follow-your-nose to
> natural langauge documents that explain, to the satisfaction
> of a wide technical audience, what it means.

Give me a break.  You can argue all day that XSD (or SVG, or hexdumped 
bytecodes, or whatever) are as human readable as HTML, but you're 
pushing water uphill.  One of these formats is *designed* to be human 
readable, by default.

>>(b) presupposes a highly controversial 
>>choice among several alternatives thus precluding them,
> 
> I think this is a spurious argument... I am *NOT* saying
> that
> 	For every namespace name, the result of dereferencing
> 	that namespace name is an XML Schema.
> 
> I'm only saying that
> 
> 	For some namespace name(s), the result of dereferencing
> 	that namespace name gives you an XML Schema.

... which has the side-effect that later when you have a DTD and an 
RelaxNG and an RDFS and a suite of CSS modules and some javadocs and so 
on, you're going to have to be able to deal with XML Schema to have any 
hope of fighting your way through to them even if you have no interest 
in XML Schema.  This sucks.

> Surely I, as namespace designer, get to choose what format
> to use to document my namespace, no?
> 
> I chose 3 examples (XML Schema, RDF, HTML) to illustrate
> that I expect different namespace designers to choose
> different formats to document their namespaces.

Well, as a responsible citizen concerned about namespaces being usable, 
I am entitled to complain if you publish a namespace and expect me to 
use it without providing some easy-to-find easy-to-read documentation. 
You expect me to go ahead and blindly unleash a schema processor on 
anything purporting to be in this namespace without checking up on it 
first?  Not on the planet where I live.

>>(c) suggests 
>>that schemas are more interesting or useful than other kinds of 
>>resources,
> 
> In the 2000/04schema-hacking/my case, yes; as namespace designer,
> I've decided that the most useful thing to use to document it is an
> XML Schema.
> 
> Are you saying that's *never* the case?

I'm saying that's a rare, uninteresting, highly suboptimal case.  For 
the simple reason that it is a highly onerous task to force me to bring 
a schema processor to bear to start to figure out what a namespace is about.

> In other cases, we chose HTML or RDF. Are those *never*
> acceptable?

I think HTML is *always* acceptable.  I think HTML decorated with some 
machine-readable pointers to your schemas and RDF and whatever else 
would be better.

>>and (d) has no default way to look up other useful things 
>>that aren't XML schemas.
> 
> Yes, it does: annotations; specifically, the source
> attribute on appinfo and documentation.
> http://www.w3.org/TR/xmlschema-1/#cAnnotations

Sorry, it is just idiotic to bring the entire force of an XML Schema 
implementation to bear to fish out some annotations.  And it remains a 
miserable failure in the (IMHO opinion very common) case where I'm a 
*human* who wants to figure out what this namespace is about.  Using XML 
Schema to carry docs and pointers in its annotations is like using the 
U.S.S. Enterprise to deliver a teddy bear.  -Tim

Received on Wednesday, 11 December 2002 07:59:41 UTC