I love ironies. In fact, I collect them. One of my favorite ironies
about XML is that this technology, which has its genesis in
documentation is rarely used to document applications created with it.
Ironies can make you laugh and ironies can make you cry. If you find
yourself knee deep in a modern XML document, you are more likely to want
to cry. Cry out for some documentation as to what all these darned tags
mean!
In days of yore, the one true source of documentation was the DTD
schema. These days, schemas (regardless of notation) may or may not
exist. Even if they do, there is no guarantee that they can be fished
out of the ether easily. Even if they can, who knows how informative
they will be? Sometimes you need the free-flowing expressive power of a
document format to express your ideas. Only so much richness can be
squeezed into a comment!
Irony number two coming up: the XML world now has a way of making every
element and every attribute globally unique. It is called the namespaces
in XML recommendation[1]. This recommendation uses URIs as the
uniquification mechanism for elements and attributes. Fine. However (and
this is the irony), there is no guarantee that there is anything at the
end of these namespace URIs. It is just a *name* not the address of a
retrievable resource.
Try telling that to Eudora or Word or any of a gazillion other Web-aware
apps that cheerfully turn these things into hypertext links just begging
to be clicked. There can be no more disappointing moment during the
search for documentation of an XML application than when you get a "404"
attempting to retrieve the resource named in a namespace name.
For the sake of completeness, imagine that this article now spends a
thousand paragraphs or so arguing the merits and de-merits of treating a
namespace as anything other than a set of names. Those of you interested
in all the philosophical nuances may seek enlightenment in the XML Cover
Pages[2]. Furthermore, imagine that after said one thousand paragraphs,
I convince you that it is a good idea to put something at the end of
your namespace URIs...
Now that we have decided that it is a good idea to put a retrievable
resource at the end of a namespace URI, what should we put there?
Here we hit the age old tension between making something easy for humans
to read and easy for computers to read. As I sit in Eudora or Emacs
reading XML fragments, I want to be able to follow the links in the
namespaces and retrieve something human readable. On the other hand, in
my software, I would like to be able to retrieve a resource for the
namespace and automatically process it. I can envisage wanting to
enumerate all the tag names. I can envisage seeking to retrieve a good
CSS stylesheet to render the schema and so on.
Enter RDDL[3]. A blend of machine and human readable XHTML basic format
that provides both human readable documentation about a namespace and a
bunch of machine processable links to related resources such as style
sheets, schemata, and so on.
RDDL is a simple, effective way to document your namespaces. As a
founding member of the non-nominalist, anti namespace 404 movement, I
urge you to use RDDL liberally.
NOTES
[1] http://www.w3.org/TR/REC-xml-names/
[2] http://xml.coverpages.org/rddl.html
[3] http://www.rddl.org
