Resource Directory Description Language (RDDL)

This version: January 15, 2001

Latest Version

Previous Version: January 14, 2001

Editors:

Table of contents

  1. Introduction
  2. Background
  3. Format
    1. Nature
    2. Purpose
  4. resource element
  5. Attributes
    1. xlink:role
    2. xlink:arcrole
    3. xlink:href
    4. xlink:type
    5. xlink:title
    6. xml:lang
    7. id
  6. Resources
  7. References

Introduction

This document defines Resource Directory Description Language (RDDL). A Resource Directory provides a text description of some class of resources and of other resources related to that class. It also contains a directory of links to these related resources. An example of a class of resources is that defined by an XML Namespace. Examples of such related resources include schemas, stylesheets, and executable code. A Resource Directory Description is designed to be suitable for service as the body of a resource returned by dereferencing a URI serving as an XML Namespace name.

The Resource Directory Description Language is an extension of XHTML Basic 1.0 with an added element named resource. This element serves as an XLink to the referenced resource. The Resource Directory Description 1.0 DTD has been defined according to Modularization for XHTML.

This document defines the syntax and semantics of the Resource Directory Description Language, and also serves as a Resource Directory Description for the namespace http://www.rddl.org/.

Background

The Resource Directory Description Language was initially proposed and specified after discussion on the XML-DEV mailing list.

This document has no official standing and has not been considered nor approved by any organization.

The background behind and initial history of RDDL has been described on the XML Coverpages and xmlhack.com and on xml.com. Many people have contributed to RDDL.

Format

Each resource description contains a prose description of the resource and machine readable links which describe the purpose of the link and the nature of the resource being linked to. The prose description is the content of the resource element. The machine readable link is a simple xlink. The nature of the resource being linked to is indicated by the xlink:role attribute and the purpose of the link is indicated by the xlink:arcrole attribute.

Infoset

The RDDL document information set consists of:

The RDDL resouce information item consists of:

To maximize interoperability a RDDL document must not depend on DTD or schema attribute defaulting particularly of namespace and namespace prefix items. A RDDL document must have a valid XML infoset regardless of whether a validating parser has been used.

The nature of a resource

Referenced resources are often primarily described by their nature. The xlink:role attribute describes the nature or type of the referenced resource. The nature of the linked resource often but not always determines how the resource is to be used. For example, an XML Schema linked to a namespace URI would be given an xlink:role="http://www.w3.org/2000/10/XMLSchema". In some cases where there is only one of a particular type of resource, the purpose of the linked resource may be inferred from its xlink:role. For example when there is only one schema type resource associated with a namespace URI and when the type of this resource is an XML Schema, processing software might infer that the purpose of the schema is to validate elements qualified by the namespace.

The purpose of a link to a resource

The xlink:arcrole attribute describes the purpose of the link. When there are several different types of schemata referenced in a RDDL document or several different resources of the same type of schema, the purpose of each resource should be explicitly declared. For example the purpose of one XML Schema resource might be schema validation while the purpose of other XML Schema resources might be either for editing or as included modules. Similarly the purpose of one DTD resource might be to define entities while the purpose of another might be for validation. Multiple referenced XSLT transforms might each have various purposes.

Multiple resources of the same nature and purpose may be included in a RDDL document. An example of when this is desirable is when several included modules of a particular schema format or software language are referenced. In this case, software will need to distinguish among these resources by other factors such as the href of the link or the language of the linked resource

Base URI

The base URI of a RDDL document may be specified according to the W3C XML Base recommendation. The xml:base attribute may be specified on the root html element or on a rddl:resource element.

The rddl:resource Element

The resource element is in a namespace whose name is http://www.rddl.org/. In this discussion, we assume the use of the namespace prefix rddl for this name, and refer to this element as rddl:resource. The rddl:resource element represents a simple xlink, using the attributes defined in the XLink namespace.

The rddl:resource element is placed within the html body. The XHTML %Flow.mix entity has been redefined to contain rddl:resource so it roughly may be placed anywhere a p tag may be placed. The rddl:resource element itself uses the %Flow.mix content model, and should have content which describes the associated resource.

<!ELEMENT rddl:resource (#PCDATA | %Flow.mix;)*>
<!ATTLIST rddl:resource
  id ID #IMPLIED
  xml:lang NMTOKEN #IMPLIED
  xml:base CDATA #IMPLIED
  xmlns:rddl	CDATA #FIXED 'http://www.rddl.org/'
  xlink:type	(simple|extended|arc|locator|resource)	#FIXED "simple"
  xlink:arcrole CDATA		#IMPLIED
  xlink:role	CDATA		"http://www.rddl.org/#resource"
  xlink:href	CDATA		#IMPLIED
  xlink:title	CDATA		#IMPLIED
  xlink:embed	CDATA		#FIXED "none"
  xlink:actuate	CDATA		#FIXED "none"
  >

The definition above has been edited for clarity.

Attributes

xlink:role

The value of this attribute must be a URI reference. A URI reference may contain a URI part and a fragment identifier. Per XLink, when present the URI part must be an absolute URI. It provides a machine-readable identifier for the nature or type of the related resource. Software performing resource resolution may dispatch on the this value.

The value of the xlink:role attribute indicates the nature of the related resource. When the related resource is an XML namespace compliant document and when the resource can be distinguished by the namespace of the root element, this namespace URI should generally be the value of the xlink:role attribute. In these cases the nature of the document is defined as the type of the root element.

When the related resource is not an XML document but is adequately distinguished by a MIME type, the value of the xlink:role attribute may reflect this MIME type with values formed by the concatenation of the prefix http://www.isi.edu/in-notes/iana/assignments/media-types/ with a MIME type e.g. http://www.isi.edu/in-notes/iana/assignments/media-types/text/css.

It is anticipated that many related-resource types will be well known and the RDDL document http://www.rddl.org/roles.htm contains descriptions of well known xlink:roles.

The value defaults to http://www.rddl.org/#resource. This URI reference corresponds to the qualified name rddl:resource.

xlink:arcrole

The value of this attribute must be a URI reference. A URI reference may contain a URI part and a fragment identifier. Per XLink, when present the URI part must be an absolute URI. It provides a machine-readable identifier for the purpose of the link to the related resource. Software perfoming resource resolution may dispatch on the this value.

In some cases the purpose of the document can only be partially determined by the type of the root element. For example a RDDL document has a root element html qualified by the XHTML namespace. The nature of a RDDL document is that it is an XHTML document though its purpose is to serve as a directory of resources. In this situation the root element type does not completely specify the nature nor adequately specify the purpose of the document. The presence of both xlink:role and xlink:arcole attributes for a single resource link provides flexibility in such situations.

It is anticipated that the purpose of many links to related resources will be well known. A list of well-known link purposes may be found in the RDDL directory http://www.rddl.org/arcrole.htm.

xlink:href

This XLink locator attribute's value is a URI reference to the target related resource

xlink:title

A human readable short descriptive title. This should be specified but not be seen as a replacement for descriptive content.

xlink:type

The xlink:type is always "simple" in this version of the specification.

xlink:show and xlink:actuate

Not used. The only legal value is "none".

xml:lang

The xml:lang attribute value may be used to qualify the resource by language code.

id

The id attribute value may be used to give the resource description a name.

Related Resources for RDDL

CSS Stylesheet

A CSS stylesheet used to provide the "look-and-feel" of this document, suitable in general for RDDL documents.

DTD

A DTD rddl-xhtml.dtd for RDDL, defined as an extension of XHTML Basic 1.0 using Modularization for XHTML

The DTD includes a number of modules:

RDF Schema

An RDF Schema for RDDL.

RELAX

A RELAX Schema for RDDL

OASIS Open Catalog

The OASIS Open Catalog Format catalog for RDDL. This catalog defines PUBLIC and SYSTEM identifiers related to the DTD.

TREX

A TREX Schema xhtml-rddl.trex for RDDL

The TREX Schema includes a number of modules:

ZIP

The RDDL spec, DTDs and other contents of the directory, zipped for download.

Java API

An example of a Java API for RDDL, code to implement it based on SAX is here here. This code is shown as an example and is not-normative to the specification.

JAR

The above code packaged as a java archive.

An example of how it might be used in the case where an XML Schema for the namespace is desired:

  RDDLURL rurl = new RDDLURL(
                        "http://www.rddl.org/", 
                        "http://www.w3.org/2000/10/XMLSchema",
                        "http://www.rddl.org/arcrole.htm#schema", 
                        ); // a namespace URI, the root namespace
	InputStream is = rurl.getInputStream(); // and you get the XSD
	...

XSLT API

An example of an XSLT for RDDL, which accepts the params role and arcrole. The transform inserts the document referenced by xlink:href in the output. This code is shown as an example and is not-normative to the specification.

RDDL to RSS 1.0 converter

This is an XSLT transform which converts a RDDL document into RSS. This code is shown as an example and is not-normative to the specification.

C# API

Jason Diamond's C# API for the RDDL on the Microsoft .NET platform. A ZIP file.

References

  1. W3C XML Names
  2. IETF RFC 2396
  3. W3C XHTML 1.0
  4. W3C XLink
  5. W3C XHTML Basic 1.0
  6. W3C Note Harvesting RDF Statements from XLinks
  7. W3C XML Base
  8. W3C XML Infoset