Resource Directory Description Language (RDDL) Version 2.0

This Version: October 16, 2002

Latest Version: http://www.rddl.org/RDDL2

Previous Version: March 5, 2001

Editors:

Table of contents

1. Introduction

This document describes the Resource Directory Description Language (RDDL). A RDDL document, called a Resource Directory, provides a package of information about some target, including:

The targets which RDDL was designed to describe are XML Namespaces. Examples of "individual related resources" include schemas, stylesheets, and executable code designed to process markup from some namespace. A Resource Directory is designed to be suitable for service as the body of an entity returned by dereferencing a URI serving as an XML Namespace name.

This Document

This version of the specification describes two versions of the Resource Directory syntax; one in XLink and another in RDF. XLink-specific material is visually distinguished like this. RDF-specific material is visually distinguished like this.

For purposes of this discussion, we assume that the XLink namespace http://www.w3.org/1999/xlink is bound to the prefix xlink, that the RDF namespace http://www.w3.org/1999/02/22-rdf-syntax-ns# is bound the prefix rdf, and that the namespace http://www.rddl.org/ is bound to the prefix rddl. and that the namespace http://www.rddl.org/RDDL2# is bound to the prefix rddl.

A DTD for RDDL has been defined using Modularization for XHTML.

This document describes the syntax and semantics of the Resource Directory Description Language 1.0, and also serves as a Resource Directory Description for the namespace http://www.rddl.org/. This specification is subject to change without notice. However, each version is associated with a version specific URI. Version specific RDDL namespace URIs are named as: "http://www.rddl.org/" + YYYYMMDD. Backwards incompatible changes will be publicly announced and associated with a new namespace URI.

The Resource Directory Description Language was initially proposed and specified after discussion on the xml-dev mailing list. Extending HTML with a resource element was proposed in 1996 by Tim Berners-Lee and Dave Raggett. RDDL reflects contributions from many participants in the xml-dev mailing list

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

Overview and Examples

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, and contains a human-readable 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 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.

The Resource Directory Description Language is an extension of XHTML Basic 1.0 into which RDF Descriptions are inserted. RDF processors may parse RDDL documents as RDF. The attribute rddl:annotation-ns="http://www.w3.org/1999/xhtml" indicates to RDF parsers that any XHTML encountered is to be treated as an annotation and skipped. HTML browsers will skip elements outside the XHTML namespace.

Each related resource is described by a rdf:Description element. An arbitrary number of properties may be asserted concerning each related resource; several convenient ones are predefined in the RDDL vocabulary.

Of the other predefined properties, the two most important are identified as rddl:nature and rddl:purpose which respectively identify the nature and purpose of the related resource.

For example, suppose that the XML Namespace identified by http://example.com/L has a DTD at http://example.com/schemas/L.dtd, a RelaxNG schema at http://example.com/schemas/L.rng, and user documentation at http://example.com/docs/L.html.

Here is a RDDL document that could be served as a representation of http://example.com/L. 

<html   xmlns:xlink="http://www.w3.org/1999/xlink"
        xmlns:rddl="http://www.rddl.org/" >
<head><title>RDDL Description for http://example.org/L</title></head>
<body><h1>RDDL Description for http://example.org/L</h1>
<p>This document describes the "L" namespace and provides links to related
  resources</p>
<rddl:resource xlink:type="simple"
  xlink:title="DTD"
  xlink:role="http://www.isi.edu/in-notes/iana/assignments/media-types/application/xml-dtd"
  xlink:arcrole="http://www.rddl.org/purposes#validation"
  xlink:href="http://example.org/schemas/L.dtd">
<p>A DTD for the L language.</p>
</rddl:resource>
<rddl:resource xlink:type="simple"
  xlink:title="Relax NG Schema"
  xlink:role="http://relaxng.org/ns/structure/1.0"
  xlink:arcrole="http://www.rddl.org/purposes#validation"
  xlink:href="http://example.org/schemas/L.rng">
<p>A RelaxNG schema for the L language.</p>
</rddl:resource>
<rddl:resource xlink:type="simple"
  xlink:title="User Documentation"
  xlink:role="http://www.w3.org/1999/xhtml"
  xlink:arcrole="http://www.rddl.org/purposes#reference"
  xlink:href="http://example.org/schemas/L.html">
<p>Reference documentation for L, in XHTML.</p>
</rddl:resource>
</body>
</html>

RDF Option 1

<html
    rddl:annotation-ns="http://www.w3.org/1999/xhtml"
    xmlns="http://www.w3.org/1999/xhtml"
    xmlns:rddl="http://www.rddl.org/RDDL2#"
    xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" 
    xmlns:purpose="http://www.rddl.org/purposes#"
 xmlns:apps="http://www.isi.edu/in-notes/iana/assignments/media-types/application/"
>
    <head>
        <title>RDDL Description for http://example.org/L</title>
        <link href="xrd.css" type="text/css" rel="stylesheet" />
   </head>
<body>
    <h1>RDDL Description for http://example.org/L</h1>
    <p>This document describes the "L" namespace and provides links to related
      resources</p>
 <rdf:Description rdf:ID="DTD"
    rddl:title="DTD">
  <purpose:validation>
    <rddl:resource rdf:about="http://example.org/schemas/L.dtd" >
      <rddl:nature rdf:resource="http://www.isi.edu/in-notes/iana/assignments/media-types/application/xml-dtd" />
    </rddl:resource>
     <p>A DTD for the L language.</p>
  </purpose:validation>
 </rdf:Description>
<h2>RELAXNG</h2>
<rdf:Description rdf:ID="RNG"
    rddl:title="Relax NG Schema">
  <p id="rng-prose">A RelaxNG schema for the L language.</p>
  <purpose:validation>
   <rddl:resource rdf:about="http://example.org/schemas/L.rng" >
  <rddl:nature rdf:resource="http://relaxng.org/ns/structure/1.0" />
 </rddl:resource>
  </purpose:validation>
</rdf:Description>
<rdf:Description rdf:ID="UserDoc" 
    rddl:title="User Documentation" >
    <purpose:reference>
   <rddl:resource rdf:about="http://example.org/schemas/L.html" >
    <rddl:nature rdf:resource="http://www.w3.org/1999/xhtml"/>
   </rddl:resource>
      <p>Reference documentation for L, in XHTML.</p>
 </purpose:reference>
  </rdf:Description>
</body>
</html>

RDF Option 2

<html   xmlns:rddl="http://www.rddl.org/"
	  xmlns="http://www.w3.org/1999/xhtml" >
    <head>
        <title>RDDL Description for http://example.org/L</title>
    </head>
    <h:body>
        <h1>RDDL Description for http://example.org/L</h1>
    <p>This document describes the "L" namespace and provides links to
    related resources</p>
    <rddl:resource ID="DTD">
        <rddl:title>DTD</rddl:title>
        <rddl:nature resource="http://www.isi.edu/in-notes/iana/assignments/media-types/application/xml-dtd"/>
        <rddl:purpose resource="http://www.rddl.org/purposes#validation"/>
        <rddl:related resource="http://example.org/L.dtd"/>
        <rddl:prose><p>A DTD for the L language &ltL&gt is the root
element.</p></rddl:prose>
    </rddl:resource>
    <rddl:resource ID="XSD">
        <rddl:title>XML Schema</rddl:title>
        <rddl:nature resource="http://www.w3.org/2001/XMLSchema"/>
        <rddl:purpose resource="http://www.rddl.org/purposes#schema-validation"/>
        <rddl:related resource="http://example.org/L.xsd"/>
        <rddl:prose><p>An XML Schema for the L language &ltL&gt is the root
element.</p></rddl:prose>
    </rddl:resource> ....
</body>
</html>

On XML "Namespace Documents"

XML Namespaces are identified by a URI. If the URI can be dereferenced to yield a representation of the namespace, the representation can be referred to as a "namespace document". Resource Directories as defined by RDDL are designed to serve as namespace documents. It should be emphasized, though, that for a large proportion of applications, there is no requirement or expectation that namespace documents be retrieved at run-time, whether the namespace document is in RDDL or any other form.

On Embedding RDF in XHTML

The design of RDDL assumes that the embedded RDF assertions about related resources are an integral part of a RDDL document and are to read and used according to RDF semantics. An RDF parser may ignore elements in the XHTML namespace, as directed by the rddl:annotation-ns attribute. For example a SAX2 parser thus filter out XHTML, passing everything else to an RDF handler : 

public void startElement(java.lang.String uri,
                         java.lang.String localName,
                         java.lang.String qName,
                         org.xml.sax.Attributes attributes) {
		if (uri.equals(annotation_ns))
			return;
		else
			rdf_parser.startElement(uri,localName,qName,attributes);
}

3. Nature and Purpose

3.1 The Nature of a Related Resource

Related resources have a nature, a machine-readable label provided by the value of the xlink:role attribute. Related resources have a nature, a machine-readable label provided by the value of the rddl:nature property. For example, the nature of an XML Schema designed for use with a namespace would be given as "http://www.w3.org/2001/XMLSchema".

In cases where there is only one resource with a particular nature, the purpose of the linked resource may be inferred from this nature. For example, if there is only one related resource for a particular namespace whose nature indicates that it is a schema, processing software might infer that its purpose is to validate elements in that namespace.

3.2 The Purpose of a Related Resource

Related resources may have a purpose, a machine-readable label provided by the value of the xlink:arcrole attribute. The purpose of a related resource is a property of the namespace not of the resource itself. A namespace is a collection of resources each of which may be labelled by an rdf:ID. The purpose of a related resource is a property of the namespace local resource whose object is the related resource. Thus the purpose related a remote resource to something "inside" the namespace. The purpose is designed to convey the intended usage of the related resource. For example, two related resources might have natures that indicate they are both schemas, but the purposes might indicate that one is designed to validate the "strict" version of the language, the other the "forgiving" form.

4. 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, 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 contains one or more RDF assertions about the related resource.

The rddl:resource must occur in the content of the HTML body element. In the RDDL DTD, the XHTML %Flow.mix entity has been redefined to contain rddl:resource so it roughly may be placed anywhere a p element may be placed. The rddl:resource element itself uses the %Flow.mix content model, and should have human-readable content which describes the associated resource.

Here is a DTD fragment declaring the rddl:resource element, edited for clarity. 

<!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) #FIXED   "simple"
  xlink:arcrole CDATA    #IMPLIED
  xlink:role    CDATA             "http://www.rddl.org/#resource"
  xlink:href    CDATA    #IMPLIED
  xlink:title   CDATA    #IMPLIED
  xlink:show    CDATA    #FIXED   "none"
  xlink:actuate CDATA    #FIXED   "none"
  >

Here is a DTD fragment declaring the rddl:resource element, edited for clarity. 

<!ELEMENT rddl:resource (rddl:nature|rddl:purpose|rddl:prose|rddl:related|rddl:title)*>
<!ATTLIST rddl:resource
  ID            ID       #IMPLIED
  xml:lang      NMTOKEN  #IMPLIED
  xml:base      CDATA    #IMPLIED
  xmlns:rddl    CDATA    #FIXED   "http://www.rddl.org/RDDL2#"
  rddl:title	CDATA	 #IMPLIED
  >
<!ELEMENT rddl:nature EMPTY>
<!ATTLIST rddl:nature
  xml:base      CDATA    #IMPLIED
  resource	CDATA	 #IMPLIED
  >
<!ELEMENT rddl:purpose EMPTY>
<!ATTLIST rddl:purpose
  xml:base      CDATA    #IMPLIED
  resource	CDATA	 #IMPLIED
  >
<!ELEMENT rddl:prose (#PCDATA| %Flow.mix; )*>
<!ATTLIST rddl:prose
  id            ID       #IMPLIED
  xml:lang      NMTOKEN  #IMPLIED
  xml:base      CDATA    #IMPLIED
  >
<!ELEMENT rddl:related EMPTY>
<!ATTLIST rddl:related
  xml:base      CDATA    #IMPLIED
  resource	CDATA	 #IMPLIED
  >

RDDL allows the rddl:resource element to occur within the %Flow.mix; context, that is roughly wherever a div element may occur. 


        


      

      

        

          4.1 Unique Identifier
        

        

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

        

          The rdf:ID attribute value may be used to give the resource
          description a unique identifier.
        

      

      

        

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

        

          Future versions of XHTML may allow the use of xml:base
          on some or all XHTML elements, and its semantics should apply even
          when on another XHTML element, for example the body, or
          div element, that contains a rddl:resource
          element.
        

      

      

        

          4.3 Language
        

        

          The language of the text contained by an element is specified by the
          xml:lang
          attribute. This attribute can be specified on XHTML elements and on
          the rddl:resource element. An html element
          in an XHTML document may specify both lang and
          xml:lang attributes, but the lang attribute
          is not used by RDDL processors.
        

      

    

    
    

      

        5. RDF Properties Provided by RDDL
      

      

        

          5.1 rddl:nature
        

        

          The value of this attribute must be a URI reference. It provides a
          machine-readable identifier for the nature of
          the related resource. Software may dispatch on this value.
        

        

          When the related resource is an XML language for which a namespace
          name has been defined, and for which the namespace name adequately
          distinguishes the nature of the resource, the namespace name should
          be used as its nature.
        

        

          When the related resource is not an XML document but is adequately
          distinguished by a MIME type, the value of the
          rddl:nature property 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 natures will be well
              known. A list of well-known natures may be found in the RDDL
              directory http://www.rddl.org/natures.
            

          

        

          If no nature is provided for a related resource, the default value is
          http://www.rddl.org/#resource.
        

      

      

        

          5.2 rddl:purpose
        

        

          The value of this property must be a URI reference. It provides a
          machine-readable identifier for the purpose of
          the link to the related resource. Software may dispatch on this
          value.
        

        
          

            

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

          

      
      

      

        5.3 rddl:title
      

      

        A human readable short descriptive title. This should be specified but
        not be seen as a replacement for descriptive content to be provided in
        rddl:prose.
      

    

	

		
annotation-ns attribute

		
The rddl:annotation-ns attribute contains a space 
		delimited list of namespace URIs whose elements are considered annotations, or text descriptions, of the
		target namespace/resource, and not RDF assertions related to the described resource. An RDF parser will ignore such elements or their text content. 
		The parser will continue to parse child elements of the annotation element and handle such children appropriately i.e. child elements within an
		annotation namespace will be ignored and others will be treated as RDF.
		

	

    

      

        6. Related Resources for RDDL
      

      

        

          6.1 Well-Known Related-Resource Natures
        

        

          A list of well-known
          related-resource natures, with descriptions.
        

      

      

        

          6.2 Well-Known Related-Resource Purposes
        

        

          A list of well-known
          related-resource purposes, with descriptions.
        

      

      
        

          

            6.3 CSS Stylesheet
          

          

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

        

      
      
        

          

            6.5 RDF Schema
          

          

            An RDF Schema
            for RDDL. This code is shown as an example and is not normative.
          

        

      
        

          

            6.6 RELAX
          

          

            A RELAX
            Namespace Grammar for RDDL. This grammar, contributed by Murata
            Makoto, defines RDDL as a hedge grammar.
          

          

            Included modules:
          

          
        

      
      
        

          

            6.7 Schematron
          

          

            A Schematron
            Schema for RDDL.
          

        

        
          

            

              6.8 Schematron XSLT implementation
            

            

              A Schematron Schema for RDDL 'compiled' into XSLT is here.
            

          

      
        

          

            6.9 OASIS Open Catalog
          

          

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

        

      

        
          

            6.10 TREX
          

          

            A TREX Schema xhtml-rddl.trex
            for RDDL
          

          

            Note: to streamline this document, links to the modules have been
            commented out
          

      
      

      
        

          

            6.11 ZIP
          

          

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

        

      
        

          

            6.12 Java API
          

          

            An example of a Java API for RDDL. A RDDL description of the object
            model is here
          

          

            Code to implement it based on SAX is here here. This code
            is shown as an example and is not normative.
          

        

      
        

          

            6.13 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/purposes#schema-validation", 
                        ); // a namespace URI, the root namespace
        InputStream is = rurl.getInputStream(); // and you get the XSD
        ...


        

      
        

          

            6.14 XSLT Stylesheet
          

          

            An example of an XSLT
            stylesheet 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.
          

        

      
        

          

            6.15 RDDL Table View
          

          

            An example of an XSLT
            stylesheet which extracts RDDL resource elements into an HTML
            table. This code is shown as an example and is not normative.
          

        

      
        

          

            6.17 RDDL to RDF converter
          

          

            This is an XSLT transform
            which converts a RDDL document into RDF. This code is shown as an
            example and is not normative.
          

        

      
        

          

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

        

      
        

          

            6.19 C# API
          

          

            Jason Diamond's C#
            API for the RDDL on the Microsoft .NET platform. A ZIP file.
            This is referenced as an example and is not normative.
          

        

      
        

          

            6.20 IE5 Behavior
          

          

            An IE5 Behavior that uses the xlink:href as a link. If you are
            using IE5 then you are viewing this behavior.
          

        

      
        

          

            6.21 Home RDDL Directory
          

          

            This resource references a RDDL
            document containing a collection of resources referencing other
            RDDL documents.
          

        

    
    

    

      

        8. Normative References
      

      
    
        
  1. 
          
            W3C XML Names 
        
  2. 
          
            IETF RFC 2396 
        
  3. 
          
            W3C XLink 
        
  4. 
          
            W3C XHTML Basic 1.0 
        
  5. 
          
            W3C XML Base 
  
        
  6. 
          
            W3C XPointer 
        
  7. 
          
            W3C XML Infoset
        
        
    8. 
      

    

    

      

        9. Informative References
      

      
    
        
  1. 
          
            W3C XHTML 1.0 
        
  2. 
          
            W3C Note Harvesting RDF
            Statements from XLinks 
        
  3. 
          
            W3C
            Modularization of XHTML
        
        
    4. 
      

    

    
Jonathan
      Borden