Hack 60 Create an RDDL Document

RDDL is a XHTML language extension that can help dispel a confusion that surrounds XML namespaces, and let people find out more about your vocabularies.

The Resource Directory Description Language or RDDL (http://www.rddl.org) was developed by members of the xml-dev mailing list (http://www.xml.org/xml/xmldev.shtml) in late 2000 and early 2001; Jonathan Borden and Tim Bray were the primary developers. It was created as one possible solution to the XML namespace problem, which is basically that an URI that uses a http:// scheme suggests that the URI is pointing at a resource, such as an actual document; however, this is not necessarily the case with XML namespaces, and so it creates confusion.

RDDL provides a partial solution to this problem by providing a special document called a resource directory that can hold information about resources that are associated with a target namespace name. If you find XML namespaces a bit annoying, RDDL is a solution that can help. One of the main benefits of RDDL is that it's both human- and machine-readable. It uses XHTML so you can read it in a browser, and it also use XLink, whose special natures and purposes can help an application discover other resources.

RDDL essentially extends the XHTML Basic module (http://www.w3.org/TR/xhtml-basic/) with a resource element. This element is allowed to contain mixed content [Hack #1] but chiefly it uses XML and XLink [Hack #28] attributes. Table 4-1 describes the attributes of the resource element, based on a DTD fragment in the RDDL spec (http://www.rddl.org/#resource).

Table 4-1. Attributes of the RDDL resource element
RDDL attribute	Required?	Value description
id	optional	A unique identifier for the resource description.
xml:lang	optional	A language token, such as `en`, `de`, `fr`, or `es`, for the resource description.
xml:base	optional	The base URI for the resource description ( [Hack #28] ).
xmlns:rddl	fixed	A namespace declaration for RDDL having a fixed value of `http://www.rddl.org`.
xlink:type	fixed	The XLink type. Currently a fixed value of `simple`.
xlink:arcrole	optional	A URI reference that is a machine-readable identifier for the purpose of this resource; for example, http://www.rddl.org/purposes/#schema-validation. For a list of possible purposes, see http://www.rddl.org/purposes/.
xlink:role	defaulted	A URI reference that is a machine-readable identifier for the nature of this resource; defaults to `http://www.rddl.org/#resource`. For a list of possible natures, see http://www.rddl.org/natures/.
xlink:href	optional	A URI reference to the resource related to the target.
xlink:title	optional	A short, human-readable descriptive title for the resource.
xlink:embed	fixed	Not used; value of `none`.
xlink:actuate	fixed	Not used; value of `none`.

More and more namespace names or URIs resolve to resource descriptions. For example, XML Schema's namespace URI (http://www.w3.org/2001/XMLSchema) resolves to such a resource description document. The source markup for this document follows in Example 4-3, and it is displayed in Figure 4-1.

Example 4-3. xmlschema-rddl.html

<?xml version='1.0'?>

<!DOCTYPE html PUBLIC "-//XML-DEV//DTD XHTML RDDL 1.0//EN" "http://www.w3.org/2001/rddl

/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/" xml:lang="en">

<head>

 <title>XML Schema</title>

</head>

<body>

<h1>XML Schema</h1>

<div class="head">

<p>13 February 2001<br/>[Updated 31 March 2004]</p>

</div>

<div id="toc">

<h2>Table of contents</h2>

<ol>

 <li><a href="#intro">Introduction</a></li>

 <li><a href="#related.resources">Resources</a></li>

</ol>

</div>

<div id="intro">

<h2>Introduction</h2>

<p>This document describes the <a href="#xmlschemap1">XML Schema</a> 

namespace. It also contains a directory of links to these 

related resources,  using <a href="http://www.rddl.org/">Resource 

Directory Description Language</a>.</p>

</div>

<div id="related.resources">

<h2>Related Resources for XML Schema</h2>

<!-- start resource definitions -->

<h2>Schemas for XML Schema</h2>

<div class="resource" id="DTD">

<rddl:resource xlink:title="DTD for validation" 

xlink:arcrole="http://www.rddl.org/purposes#validation" xlink:role="http://www.isi.edu/

in-notes/iana/assignments/media-types/application/xml-dtd" xlink:href="XMLSchema.dtd">

<h3>DTD</h3>

<p>A DTD <a href="XMLSchema.dtd">XMLSchema.dtd</a> for XML 

Schema.  It incorporates an auxiliary DTD, <a href="datatypes.dtd">datatypes.dtd</a>.</p>

</rddl:resource>

</div>

<rddl:resource id="xmlschema" xlink:title="XML Schema schema 

document" xlink:role="http://www.w3.org/2001/XMLSchema" xlink:arcrole="

http://www.rddl.org/purposes#schema-validation" xlink:href="XMLSchema.xsd">

<div class="resource">

<h2>XML Schema</h2>

<p>An <a href="XMLSchema.xsd">XML Schema schema document</a> 

for XML Schema schema documents. This corresponds to 

<a href="http://www.w3.org/TR/2004/PER-xmlschema-1-20040318/

#normative-schemaSchema">the version published in the Proposed 

Edited Recommendation</a> revision of XML Schema.</p>

</div>

</rddl:resource>

</div>

<div id="references" class="resource">

<h2>Normative References</h2>

<ol>

<li>

<rddl:resource id="xmlschemap1" xlink:title="W3C CR 

XML Schema Part 1" xlink:role="http://www.w3.org/TR/html4" xlink:arcrole="

http://www.rddl.org/purposes#normative-reference" xlink:href="http://www.w3.org/TR/2004/

PER-xmlschema-1-20040318/">

<a href="http://www.w3.org/TR/2004/PER-xmlschema-1-20040318/">XML 

Schema Part 1:  Structures</a> (Proposed Edited Recommendation)

</rddl:resource>

</li>

</ol>

</div>

</body>

</html>

At the top of the document in Example 4-3, the document type declaration uses an RDDL DTD rather than an XHTML DTD. The bold portions of the XHTML markup show the resource elements prefixed with rddl, the attributes they have, and the mixed content they hold. For example, the first resource element uses the xlink:title, xlink:arcrole, xlink:role, and xlink:href attributes.

The xlink:role attribute, with a value of http://www.isi.edu/in-notes/iana/assignments/media-types/application/xml-dtd, signifies that the document uses the application/xml-dtd media type (see http://www.ietf.org/rfc/rfc3023.txt). After the start tag, the resource element contains mixed-element and text content that describes the resource in human terms.

Figure 4-1. Resource description of XML Schema in Netscape

The RDDL spec also provides links for an RDDL DTD, grammars in RELAX (http://www.xml.gr.jp/relax/), RELAX NG (http://www.relaxng.org), and TREX (http://www.thaiopensource.com/trex/), a Schematron schema (http://xml.ascc.net/resource/schematron/schematron.html), and numerous other resources, including Java and C# APIs.

You can use the document xmlschema-rddl.html as a model for creating your own RDDL document.

4.3.1 See Also

Leigh Dodds' XML.com introduction to RDDL: http://xml.com/pub/a/2001/02/28/rddl.html
Elliotte Rusty Harold's "RDDL Me This: What Does a Namespace URL Locate?": http://xml.oreilly.com/news/xmlnut2_0201.html
There is a proposal out for RDDL 2.0, released in early 2004, which does not include XLink attributes: http://www.rddl.org/rddl2