Item 42. Document Namespaces with RDDL | Effective XML: 50 Specific Ways to Improve Your XML

All the warnings in the namespace specification that there is not necessarily anything at the end of a namespace URL have not stopped people from typing namespace URLs into their browser location bars and clicking the Go button. If you don't want your error logs filling up with requests for nonexistent documents, you need to put something there. The right thing to put there is a Resource Directory Description Language (RDDL) document. This provides human-readable XHTML documentation for people and machine-readable XLinks for software.

For example, consider the MegaBank Statement Markup Language (MBSML) introduced in Item 5. This was specified as being in the namespace http://namespaces.megabank.com/statement. Assuming you or the company you work for already owns megabank.com (if you don't, what are you doing defining namespaces in that domain?), the first step is to set up a web server at namespaces.megabank.com if one doesn't already exist. This is normally not a high-volume site (at least compared to the server that lets customers check credit card balances , for example), so a cheap Linux box or a virtual host on an existing server will likely be more than sufficient.

The next step is to put a page at the URL http://namespaces.megabank.com/statement. Initially, almost anything that stops your error logs from filling up is sufficient. For example, here's an incredibly simple page I adapted from the one the W3C puts at the XSLT namespace URI.

 <html> <head>   <title> MegaBank Statement Markup Language </title> </head> <body> <p> This is the XML namespace for the <a href="http://developer.megabank.com/xml/">MegaBank Statement Markup Language</a>. </p> <hr /> <address>   <a href="mailto:webmaster@megabank.com">Webmaster</a> </address> </body> </html>

That's good enough to start, but longer term you'd like something that provides a little more information. There are many things you might reasonably expect to find at the end of a namespace URL:

Schemas
DTDs
Stylesheets
Processing software
Documentation

Indeed, any given application might have several of each of these. It is precisely this plethora of possibilities for the end of a namespace URL that led the W3C XML Working Group to punt on the issue of exactly what to put there. Unfortunately, their nondecision just increased the confusion as novice XML developers peppered xml-dev and other mailing lists with questions about how to use XSLT on a computer that wasn't connected to the Internet and thus couldn't load http://www.w3.org/1999/XSL/Transform. After a couple of years of this, Tim Bray and Jonathan Borden decided that it might actually make sense to put a document at the end of a namespace URL, and they invented RDDL as the format for such documents.

RDDL solves the question of what to put at the end of a namespace URL by introducing an additional layer of indirection. A RDDL document is not a specification for the namespace. It is not a schema for the namespace. It is not a stylesheet for documents in the namespace. It is not software for processing content from that namespace. Instead, it is a directory pointing to any, some, or all of these things, neatly wrapped up inside well- formed and valid strict modular XHTML that browsers can display to end users.

The minimal RDDL document is just an XHTML document whose document type declaration points to the RDDL DTD instead of the normal XHTML DTD and whose root element also declares the RDDL and XLink namespaces. (In fact, you can even leave out the document type declaration if you want to.)

 <!DOCTYPE html PUBLIC "-//XML-DEV//DTD XHTML RDDL 1.0//EN"                       "http://www.rddl.org/rddl-xhtml.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"       xmlns:xlink="http://www.w3.org/1999/xlink"       xmlns:rddl="http://www.rddl.org/"> <head>   <title> MegaBank Statement Markup Language (MBSML) </title> </head> <p> This is the XML namespace for the <a href="http://developer.megabank.com/xml/">MegaBank Statement Markup Language</a>. </p> <hr /> <address>   <a href="mailto:webmaster@megabank.com">Webmaster</a> </address> </body> </html>

You can put absolutely any valid strict XHTML markup you care to use in the RDDL document: unordered lists, tables, images, objects, headings, hypertext links, and so on. All of this is normally designed so that the page will look good in a browser to a human reader. Generally, you want to give people reading the document a brief summary of the application that uses the namespace or tell them where they can go to learn everything they need to know.

So far this is nothing you couldn't do with HTML. What RDDL brings to the table is one additional element, which is not shown to human readers but which does provide helpful hints to automated software. This element has the local name resource and lives in the RDDL namespace (http://www.rddl.org/). Each rddl:resource element is a simple XLink that points to some related resource: a schema, a stylesheet, a specification, and so on. For example, here's a rddl:resource element that locates the main DTD for MBSML.

 <rddl:resource xlink:type="simple"    xlink:href="http://developer.megabank.com/xml/mbsml.dtd" />

This rddl:resource element can be placed in the RDDL document anywhere a div or other block-level element may appear. Browsers ignore any tags they don't recognize. Consequently, this has no effect on the content displayed to a person. However, RDDL-aware software looking for these related resources can extract just the rddl:resource elements and ignore everything else.

Sometimes it is convenient to include some content inside the rddl:resource element. As long as this is normal well-formed XHTML that's not a problem. For example, the following rddl:resource element contains both XLinks for the automated processors and a plain- vanilla HTML link with descriptive text for humans .

 <rddl:resource xlink:type="simple"    xlink:href="http://developer.megabank.com/xml/mbsml.dtd">   <p>   The MegaBank Statement Markup Language has a non-normative   <a href="http://developer.megabank.com/dtds/mbsml.dtd">DTD</a>   for use with parsers that don't support schemas. However,   in the event of a conflict between the DTD and the schema,   the schema is authoritative.   </p> </rddl:resource>

A rddl:resource element can even contain another rddl:resource element. Such nested rddl:resource elements have no special relationship to each other. Each is treated on its own. In essence, all the information needed to process any one rddl:resource element is contained completely within the start-tag.