Namespaces are quite popular in XML usage and indeed almost ubiquitous in Web services use. They most often take the form of URLs, although they can be any form of Uniform Resource Identifier (URI). Using URLs is not bad in itself, but it can create confusion if the URLs lead to nowhere. Users might try to address their browsers to the URL corresponding to a namespace to gain more information about it; if they do access the namespace URL, it's a good idea to be sure they reach some useful information, rather than a 404 "Not Found" error.
The question then is what sort of document to place at the location of a namespace URL. Some early discussion considered using a form of schema. Since namespace URLs are mostly accessed by people looking for information, many in the XML community decided that readable documentation would be friendlier. Ideally, the document could be augmented by machine-readable metadata so that automated systems could still use the namespace URL to locate such technical material for processing XML text in the namespace, including schemata.
The result of this community discussion is Resource Directory Description Language (RDDL), a standard for packaging information on a namespace. A RDDL document is an XHTML document that contains prose descriptions of the namespace. Using XHTML makes it as compatible with current browsers as possible, and takes advantage of a popular and well-known format for rich documentation. The pointers to technical resources for the namespace are expressed using embedded XLinks. I like to call RDDL documents resource glosses, a name I recommended during the community discussions from which RDDL emerged.
In this article I show how you might use a RDDL document to support namespaces in XML and Web services formats. The example uses popular conventions in SOAP, although the same lessons can be applied to other XML formats. I'll be sticking to RDDL 1.0. Some in the community have started working on RDDL 2.0, but early proposals are very controversial, so I suggest that you concentrate on RDDL 1.0 until the later versions are more settled.
Listing 1 is a copy of example 1 from "SOAP Version 1.2 Part 0: Primer" (see Resources).
Listing 1. Sample SOAP document for a travel reservations Web service
<?xml version='1.0' ?> <env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"> <env:Header> <m:reservation xmlns:m="http://travelcompany.example.org/reservation" env:role="http://www.w3.org/2003/05/soap-envelope/role/next" env:mustUnderstand="true"> <m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</m:reference> <m:dateAndTime>2001-11-29T13:20:00.000-05:00</m:dateAndTime> </m:reservation> <n:passenger xmlns:n="http://mycompany.example.com/employees" env:role="http://www.w3.org/2003/05/soap-envelope/role/next" env:mustUnderstand="true"> <n:name>Åke Jógvan Øyvind</n:name> </n:passenger> </env:Header> <env:Body> <p:itinerary xmlns:p="http://travelcompany.example.org/reservation/travel"> <p:departure> <p:departing>New York</p:departing> <p:arriving>Los Angeles</p:arriving> <p:departureDate>2001-12-14</p:departureDate> <p:departureTime>late afternoon</p:departureTime> <p:seatPreference>aisle</p:seatPreference> </p:departure> <p:return> <p:departing>Los Angeles</p:departing> <p:arriving>New York</p:arriving> <p:departureDate>2001-12-20</p:departureDate> <p:departureTime>mid-morning</p:departureTime> <p:seatPreference/> </p:return> </p:itinerary> <q:lodging xmlns:q="http://travelcompany.example.org/reservation/hotels"> <q:preference>none</q:preference> </q:lodging> </env:Body> </env:Envelope>
This sample SOAP document uses four namespaces:
http://www.w3.org/2003/05/soap-envelopeis the standard SOAP namespace. The W3C actually goes against the recommendations in this article by placing an XML schema for SOAP directly at this URL. However, I think this helps illustrate the unfriendliness of that approach because following the URL requires a browser that can handle W3C XML Schema in a presentable way, and even then reveals a document that may be very perplexing to many readers.
http://travelcompany.example.org/reservationis the namespace used for one of the SOAP header blocks; it marks information used for overall reservations metadata. This is a bogus URL, for purposes of example. In fact, "example.org" and "example.com" are among the domain names reserved by the standards for examples, and are never to be used for actual network domains.
http://mycompany.example.com/employeesis the namespace used for the other SOAP header block; it marks information relating to the client company's passenger identity information.
http://travelcompany.example.org/reservation/travelis the namespace used for the request parameters in the SOAP body.
I'll focus on the first namespace. Listing 2 is a sample RDDL document for this Web service:
Listing 2. Sample RDDL document for a travel reservations Web service namespace
<!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> Namespace description and resource gloss for travelcompany's reservation SOAP header </title> <link href="http://www.rddl.org/xrd.css" type="text/css" rel="stylesheet"/> </head> <body> <h1> Namespace description and resource gloss for travelcompany's reservation SOAP header </h1> <div class="head"> <p> <a href="http://travelcompany.example.org/reservation.rddl"> Latest Version: 17 March 2004 </a> </p> <p>Editor:</p> <ul> <li> <a href="mailto:pm%40travelcompany.com">Paul Moore</a>, Project Manager </li> </ul> </div> <div id="overview"> <h2>Overview</h2> <p>This resource gloss covers the XML namespace <code>http://travelcompany.example.org/reservation</code>. This is the namespace for reservation SOAP headers in travelcompany's Web service. It covers transaction identifiers and time stamps.</p> <p>This document is a <a href="http://www.rddl.org/">RDDL</a> Resource Gloss. RDDL is an XHTML document with special links (XLinks) that locate various resources related to this SOAP Web service. Technical problems with the RDDL glosses hosted at <code>http://travelcompany.example.org/</code> should be sent to <a href='mailto:webmaster%40travelcompany.org'>the administrator</a>.</p> </div> <h2>Resources relevant to reservation SOAP headers</h2> <div id="resources" class="resource"> <rddl:resource xlink:title="Reservation SOAP header schema" xlink:role="http://www.w3.org/TR/html4/" xlink:arcrole="http://www.rddl.org/purposes.htm#normative-reference" xlink:href="http://travelcompany.example.org/reservation.xsd" > <h3>Reservation SOAP header schema</h3> <p> W3C XML schemas for <a href="http://travelcompany.example.org/reservation.xsd"> travelcompany reservation SOAP headers </a> </p> </rddl:resource> <rddl:resource xlink:title="travelcompany Web service root namespace" xlink:role="http://www.rddl.org/#role" xlink:arcrole="http://www.rddl.org/purposes.htm#root-namespace" xlink:href="http://travelcompany.example.org/" > <h3>travelcompany Web service root namespace URI</h3> <p> Root namespace URI <code>http://travelcompany.example.org/</code> is the base for all namespaces relative to travelcompany Web services. </p> </rddl:resource> </div> <div id="footer"> <hr /> <p>Copyright 2004 travelcompany.</p> </div> </body> </html>
The RDDL document type is defined as a valid XHTML 1.1 module. As you can see, a person can easily read the document. The prose provides summary information, authoring, versioning, and maintenance details. The
rddl:resource elements are links to the namespace's supporting documents, and the body is in XHTML which usually allows for natural display even by user agents that don't understand XLink. The
xlink:role gives the nature of the link, which generally expresses what sort of resource is being linked to (for example, a schema or a stylesheet). The
xlink:arcrole attribute expresses the purpose of the link from RDDL to the resource (for example, the linked resource is for validation or is used as a normative reference). A required XLink attribute
xlink:type="simple" is not expressed in the document because it is defined as a
#FIXED attribute in the RDDL DTD.
The link to the root namespace can be especially useful for placing the more specialized namespace URL in the context of a more general base namespace, which presumably has a resource gloss of its own.
Notice that the "at" signs (
mailto e-mail address URLs are encoded as
%40. This is actually the recommended practice for representing this character and most uncommon characters in RFC 1738.
The key to this whole exercise is to get a document that is clear and presentable to the reader, and has machine-readable links to related resources. Notice the specification of CSS in Listing 2:
<link href="http://www.rddl.org/xrd.css" type="text/css" rel="stylesheet"/>
This is the conventional stylesheet used to render RDDL, although nothing requires you to use it. It is quite simple and makes for readable resource glosses in just about any browser.
RDDL is very easy and inexpensive to use with namespaces, and indeed some users have even used RDDL as a format for expressing general resource repositories. If you already make an effort to place, say, a schema at the end of the namespace, then you just need to add one level of indirection in the form of the resource gloss. You should be able to use the example in Listing 2 as a quick start, pasting it into an editor and updating it to match your own namespace information. It's rare for an XML vocabulary to explicitly specify or recommend a document to be placed at a namespace URL (RDF/XML is one of these rare cases), but if you are using such a vocabulary, do follow its recommendations, even if that means not using RDDL in some cases.
Even though I recommend sticking to RDDL 1.0 for now, the W3C's Technical Architecture Group (TAG) is working to evolve RDDL into a more formal standard for the Web. This is part of the mix of activity that has led to confusion about the development of RDDL 2.0. Proposals now in play range from expressing RDDL in RDF to suppressing the XLink trappings (relying more on re-purposed attributes from standard XHTML). The intended result is a document format that, as Tim Bray said in one of the relevant discussions on the TAG mailing list, "SHOULD be used for the representations of resources which happen to be namespaces."
- Take a moment to browse the RDDL 1.0 specification, which is very simple and readable. The specification is edited by Jonathan Borden and Tim Bray.
- Gain a deep understanding of namespaces from James Clark's essay "XML Namespaces."
- Follow the example in this article to the source at the SOAP Version 1.2 Part 0, the primer for the SOAP specifications.
- Take the tutorial "Modularization of XHTML" by Nicholas Chase (developerWorks, October 2001) to better understand the building blocks of XHTML as well as the mechanism by which RDDL correctly extends the language.
- Explore the work of the French National Institute of Statistics and Economic Studies (INSEE) in using RDDL to drive an entire repository of related resources, in the article "A RDDL repository of core datatypes" by Eric van der Vlist.
- Another good example of RDDL is the Schematron resource directory. Schematron is an XML schema language.
- Get a picture of the evolution of RDDL from community to W3C standard in the Technical Architecture Group's issue "What should a 'namespace document' look like?"
- Find more related resources on the developerWorks XML and SOA and Web services zones. You can also sign up for the weekly
Web services/XML tips newsletter.
- Browse for books on these and other technical topics.
- Find out how you can become an IBM Certified Developer in XML and related technologies.
Uche Ogbuji is a consultant and co-founder of Fourthought Inc., a software vendor and consultancy specializing in XML solutions for enterprise knowledge management. Fourthought develops 4Suite, an open source platform for XML, RDF, and knowledge-management applications. Mr. Ogbuji is also a lead developer of the Versa RDF query language. He is a computer engineer and writer born in Nigeria, living and working in Boulder, Colorado, USA. You can contact Mr. Ogbuji at firstname.lastname@example.org.