Skip to main content

If you don't have an IBM ID and password, register here.

By clicking Submit, you agree to the developerWorks terms of use.

The first time you sign into developerWorks, a profile is created for you. This profile includes the first name, last name, and display name you identified when you registered with developerWorks. Select information in your developerWorks profile is displayed to the public, but you may edit the information at any time. Your first name, last name (unless you choose to hide them), and display name will accompany the content that you post.

All information submitted is secure.

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerworks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

By clicking Submit, you agree to the developerWorks terms of use.

All information submitted is secure.

Use RDDL with your XML and Web services namespaces

Don't just leave your namespaces dangling in the ether

Uche Ogbuji (uche@ogbuji.net), Principal Consultant, Fourthought, Inc.
Photo of Uche Ogbuji
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 uche@ogbuji.net.

Summary:  The spaghetti of namespaces in, say, a WSDL file can lead to a lot of confusion. Resource Directory Description Language (RDDL) packages information on a namespace. If you use URLs for namespaces, use RDDL as described in this article to provide useful guides to users of your XML documents or Web services.

Date:  14 May 2004
Level:  Intermediate

Comments:  

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 namespace URL riddle

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.


Namespace descriptions for SOAP and WSDL

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-envelope is 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/reservation is 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/employees is 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/travel is the namespace used for the request parameters in the SOAP body.

Enter the RDDL

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 (@) in 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.


Wrap-up

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."


Resources

About the author

Photo of Uche Ogbuji

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 uche@ogbuji.net.

Report abuse help

Report abuse

Thank you. This entry has been flagged for moderator attention.


Report abuse help

Report abuse

Report abuse submission failed. Please try again later.


developerWorks: Sign in

If you don't have an IBM ID and password, register here.


Forgot your IBM ID?


Forgot your password?
Change your password


By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. This profile includes the first name, last name, and display name you identified when you registered with developerWorks. Select information in your developerWorks profile is displayed to the public, but you may edit the information at any time. Your first name, last name (unless you choose to hide them), and display name will accompany the content that you post.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

(Must be between 3 – 31 characters.)


By clicking Submit, you agree to the developerWorks terms of use.

 


Rate this article

Comments

Help: Update or add to My dW interests

What's this?

This little timesaver lets you update your My developerWorks profile with just one click! The general subject of this content (AIX and UNIX, Information Management, Lotus, Rational, Tivoli, WebSphere, Java, Linux, Open source, SOA and Web services, Web development, or XML) will be added to the interests section of your profile, if it's not there already. You only need to be logged in to My developerWorks.

And what's the point of adding your interests to your profile? That's how you find other users with the same interests as yours, and see what they're reading and contributing to the community. Your interests also help us recommend relevant developerWorks content to you.

View your My developerWorks profile

Return from help

Help: Remove from My dW interests

What's this?

Removing this interest does not alter your profile, but rather removes this piece of content from a list of all content for which you've indicated interest. In a future enhancement to My developerWorks, you'll be able to see a record of that content.

View your My developerWorks profile

Return from help

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=XML, SOA and web services
ArticleID=11912
ArticleTitle=Use RDDL with your XML and Web services namespaces
publish-date=05142004
author1-email=uche@ogbuji.net
author1-email-cc=

Tags

Help
Use the search field to find all types of content in My developerWorks with that tag.

Use the slider bar to see more or fewer tags.

For articles in technology zones (such as Java technology, Linux, Open source, XML), Popular tags shows the top tags for all technology zones. For articles in product zones (such as Info Mgmt, Rational, WebSphere), Popular tags shows the top tags for just that product zone.

For articles in technology zones (such as Java technology, Linux, Open source, XML), My tags shows your tags for all technology zones. For articles in product zones (such as Info Mgmt, Rational, WebSphere), My tags shows your tags for just that product zone.

Use the search field to find all types of content in My developerWorks with that tag. Popular tags shows the top tags for this particular content zone (for example, Java technology, Linux, WebSphere). My tags shows your tags for this particular content zone (for example, Java technology, Linux, WebSphere).