The Self-Describing Web

Draft Tag Finding 08 February 2008

This version:
Latest version:
Previous versions:,
Noah Mendelsohn, IBM Corp. <>

This document is also available in these non-normative formats: XML.


The Web is designed to support flexible exploration of information, by human users and by automated agents. For such exploration to be productive, information published by many different sources and for a variety of purposes must be comprehensible to a wide range of Web client software. HTTP and other Web technologies can be used to deploy resources that are self-describing, in the sense that only widely available information is necessary for understanding them. Starting with a URI, there is a standard algorithm that a user agent can apply to retrieve and interpret a representation of such resources. Furthermore, when such self-describing resources are linked together, the Web as a whole can support reliable, ad hoc discovery of information. This finding describes how document formats, markup conventions, attribute values, and other data formats can be designed to facilitate the deployment of self-describing Web content.

Status of this Document

This document is an editors' copy that has no official standing.

This document has been produced by the W3C Technical Architecture Group (TAG). It is an editor's draft that has not been approved by the TAG, and it includes revisions motivated by discussions held at the June 2007 Face to Face Meeting of the TAG .

Additional TAG findings, both accepted and in draft state, may also be available. The TAG may incorporate this and other findings into future versions of the [AWWW].

The capitalized terms MUST, SHOULD, and SHOULD NOT are used in this document in accordance with [rfc2119].

Please send comments on this finding to the publicly archived TAG mailing list (archive).

Table of Contents

1 Introduction
2 The Web's Standard Retrieval Algorithm
3 Use of widely deployed standards and formats
4 Creating new formats and standards
    4.1 Use existing URI Schemes, Protocols, and Media Types
    4.2 URI-based Extensibility
    4.3 RDF and the Self-Describing Web
        4.3.1 Using RDFa to produce self-describing HTML
        4.3.2 Using GRDDL to bridge from XML to RDF
    4.4 Self-describing XML documents
5 Conclusions
6 References


A Change log (will be deleted before final publication)
    A.1 Changes in 24 May 2007 Edition
    A.2 Changes in February 2008 Edition

1 Introduction

The World Wide Web has at least two characteristics that distinguish it from many other shared information spaces:

  1. The Web is global: the documents on the Web are contributed by and accessed by a very large number of users.

  2. Supporting ad-hoc exploration is a goal of the Web. Users must therefore be able to get useful information from documents prepared by people whom they don't know, and with whom they have not coordinated in advance.

The chapters below explain in more detail how the following techniques can be used to create, deploy and access self-describing Web resource representations that can be correctly interpreted using only widely available information: Furthermore, when self-describing representations are linked together, the Web as a whole can support reliable, ad hoc discovery of information.

Good Practice

Good Practice: Web resource representations SHOULD be self-describing.

The sections below discuss in more detail the techniques needed to create self-describing content for the Web, how to extend the Web with new formats that are themselves self-describing, and how a standard HTTP-based algorithm enables users to retrieve and interpret such self-describing representations.

2 The Web's Standard Retrieval Algorithm

HTTP is the most widely deployed protocol on the Web, and it is designed to facilitate the deployment of self-describing Web resource representations. Indeed, there is a standard algorithm that a user agent can employ to obtain and interpret the representation of any Web resource that's accessible using the HTTP protocol. Consider the following example, which is representative of many simple Web interactions:

Bob is reading a Web page using his browser. On the page is a link, and Bob is interested in seeing what the link points to, so he clicks on it. Bob has had no previous contact with the owner of the referenced resource, and his browser has not been specially configured for access to it. The steps taken by Bob's browser when he clicks the link illustrate a typical path through the standard retrieval algorithm of the Web (readers unfamiliar with the HTTP protocol may find it useful to consult either [HTTP], or one of the many HTTP introductions available on the Web). Assume that the link Bob clicks is to When he clicks it, his browser:

Neither Bob nor his browser has any advance knowledge of the nature of the resource, yet the browser successfully retrieves a representation, determines its format, and interprets it for him. The link could have been to an image/jpeg picture, an application/xml file, or a document containing RDF triples in application/rdf+xml. Bob's browser could in each case determine the format. Indeed, as Bob continues to browse the Web, his browser is able to determine the format of each representation that's retrieved, and can determine how to present it to him.

The example above shows how HTTP enables the deployment of self-describing Web resources. Imagine if, instead, the link had been to Although Bob's browser could easily open an FTP connection to retrieve a file, there would be no way for it to reliably determine the nature of the information received. Even if the URI were the browser would be guessing if it assumed that the file's contents were HTML, since no normative specification ensures that data from ftp URIs ending in .html is in any particular format.

Good Practice

Good Practice: Use the HTTP protocol to deploy self-describing resources.

3 Use of widely deployed standards and formats

Successful communication depends on the supplier and the consumer(s) of a document having a shared understanding of the information conveyed, and that in turn requires at least some shared assumptions about the form in which the information is represented. The simplest way to achieve this is if the media type, the document encoding, and any other conventions used for the representation are standards and are widely deployed.

Consider Susan, who buys a new digital camera. The software supplied with her camera uploads photos to the Web using the widely-deployed image/jpeg media type, and her Web server correctly labels served representations with that Content-Type. Millions of user agents deployed around the world are preconfigured to display Susan's photographs and to extract metadata such as camera settings from them. Search engines are likely to index them in helpful ways too.

Now consider instead Mary who buys a different camera, with software that does not use widely deployed Web formats. Indeed, the camera's manufacturer has invented a new "raw" file format that takes advantage of the camera's special features. The provided photo management software not only uses that format locally, it also uploads photos to Mary's Web server in that same form. Indeed, it even uploads a .htaccess file, configuring the server to label served representations with the proprietary Content-Type image/x-fancyrawphotoformat. In this example, there are no outright violations of Web architecture, but the decision to use an uncommon and proprietary media type is unfortunate. No existing Web user agents recognize the image/x-fancyrawphotoformat media type, search engine spiders are unlikely to extract useful information from pictures in that format, and so on. Unlike Susan's, which can be viewed by almost anyone, Mary's photos are at best useful to a few people who have the proprietary software needed to decode them.

Good Practice

Good Practice: Web resource representations SHOULD be published using widely deployed standards.

4 Creating new formats and standards

The techniques described above apply in the many cases where widely deployed media types such as image/jpeg are sufficient, but the Web is used for a broad and continually growing range of information. No fixed set of formats and standards can fully meet the need to encode all such information for machine processing. Of course, ways can be found to convey almost any information using standard media types. An employment record, for example, can be transmitted as either text/plain or application/xhtml+xml. The resulting document may be quite suitable for browsing, but it might not facilitate automated discovery of the employee's name, his or her date of hire, and so on. To meet such needs, new standards must be created, e.g. for marking up the names and dates. Similarly, the need may arise to use new values for individual fields such as rel attributes on HTML link elements.

So, although the Web requires self-describing documents that can be understood using only widely deployed standards, there is also a continual need for new formats and encoding conventions. How can new formats and encodings be deployed in a manner that is self-describing? The following sections explore ways of creating new formats and encoding conventions that maximize interoperability with existing Web infrastructure, and that can be used to create self-describing documents.

4.1 Use existing URI Schemes, Protocols, and Media Types

Innovations can be introduced to the Web at many different architectural layers. For example:

  • New URI schemas can be introduced

  • New transfer protocols can be deployed

  • New media types can be introduced

  • New namespace-qualified markup can be defined for XML

  • New RDF properties and ontologies can be defined for the Semantic Web

Often, a given capability could in principle be deployed at any of several different layers. For example, new sorts of content, such as movies, could be made available using new URI schemes and/or with new protocols, but doing so would require updating hundreds of millions of user agents, servers, proxies, and so on to understand these changes to the core mechanisms of the Web. Usually it is preferable to leverage the existing core mechanisms of the Web, such as http-scheme URIs and the HTTP protocol, as these are widely deployed. Indeed, one should usually leverage as many existing layers of the Web's architecture as is practical when introducing new function.

Good Practice

Good Practice: When extending the Web with new formats and functions, use existing URI schemes, protocols, and media types wherever practical.

One way to do this is to use URI-based extensibility within existing media types, as described in the sections below.

4.2 URI-based Extensibility

Many documents, particularly those that convey machine-readable data or messages, encode information using specifications that are specialized to particular purposes. Such specifications may cover details of particular data formats such as lists of customers or inventory records, experimental results of scientific experiments, listings for television shows, details of university course offerings, information about molecular structures or drug tests, etc. Because of the great variety and number of such formats and their specifications, it's not practical to assume that even most of them will be directly implemented by typical Web user agents. Instead, the Web provides means by which the necessary specifications can be discovered, and to a significant degree implemented, dynamically and automatically. This is done by:

  • ensuring that every specification, and in many cases each markup tag or data value used, is identified with a URI

  • ensuring that such URIs are used in the instance either directly as data values or tag names, or else to identify the encodings used

  • making available as Web representations of each such URI the information needed to dynamically interpret the information in the instance

In other words, it should be possible to discover from each Web representation the conventions used to encode it, and particularly in cases where those conventions are not widely deployed, to find within the representations links to specifications, ontologies and/or programs necessary for interpreting the representation. So, just as the Web may be used to dynamically discover a great wealth of resources, it can also be used to dynamically discover the specifications, ontologies, or programs needed to interpret the representations of those resources.

Example: The Atom Syndication Format [ATOM] is an XML-based format for syndicating information about blogs and other Web resources. ATOM entries can include <atom:link> elements such as the following:

  <title>An interesting picture</title>
  <link rel="enclosure" type="image/jpeg" length="12345"
    <content type="xhtml" xml:lang="en"
      <div xmlns="">
        <p><[Update: Here's an interesting picture.]</p>

The link elements identify external resources, in this case an image/jpeg photograph. Furthermore, each link can carry a rel attribute that specifies the relationship between the linked resource and the ATOM entry that links it. In the example above, the relationship is specified as enclosure which, according to the ATOM specification, indicates that the linked photograph may have been too large for inline processing with the rest of the feed.

What's of interest for this finding is the fact that values of the rel attribute are URIs (actually [IRI]s, which are the internationalized form of URIs), or else the values can be mapped to URIs. This means that anyone, anywhere can invent a new sort of link relationship, can assign a URI to identify that relationship, and can use that value in the rel attribute. For example:

  <title>An interesting picture</title>
  <link rel=""
        type="image/jpeg" length="12345"
    <content type="xhtml" xml:lang="en"
      <div xmlns="">
        <p><[Update: Here's an interesting picture.]</p>

Furthermore, anyone doing this can (and indeed should) provide information about that new relationship via HTTP from the assigned URI. For convenience, the ATOM specification also provides that short form names such as enclosure in the first example can be registered with IANA, and ATOM provides a deterministic mapping to a URI for each of these. These URIs are formed by prepending the fixed base URI to the short form. Thus, the first example above is in fact using the relationship

These examples show how URIs used as data values allow for distributed assignment of new values. More importantly for this finding, the use of URIs for such values provides the opportunity for information about those values to be discovered dynamically on the Web.

Good Practice

Good Practice: Web representations SHOULD link to the information needed to support automatic processing of those representations.

The following sections explain how a number of Web technologies can be applied to achieve such dynamic integration of new Web representation formats.

4.3 RDF and the Self-Describing Web

RDF [RDF] plays an important and distinguished role as the preferred technology for creating self-describing Web data resources, and for integrating representations rendered using other technologies such as XML. The result is a single, global self-describing Semantic Web that integrates not only resources that are themselves built or represented using RDF, but also the other Web resources to which that RDF links, as well as those that can be mapped to RDF using technologies such as [GRDDL] . Readers unfamiliar with RDF should consult the RDF primer [RDFPrimer] as a prerequisite to understanding the discussion below.

Each RDF statement is a triple consisting of a subject, a predicate (typically the identifier for a property, or for a relationship between two Web resources), and an object (the value of the property or the referent of the relationship). The subject, the predicate, and often the object as well, are themselves identified by URIs, enabling the dynamic discovery introduced in 4.2 URI-based Extensibility above — if a user agent has no built in knowledge of some particular RDF subject, relationship, or object, it can often use the URI to retrieve the information necessary for processing. Indeed, RDF's Schema [RDFSchema] and OWL Ontology technologies [OWL] together offer a standard, machine-processable means of describing particular uses of RDF. They provide the standard means by which software can discover the the relationships between RDF statements (e.g. that two seemingly differing predicates are the "owl:sameAs" each other), or other information needed for processing the RDF.

Consider Amy, who uses an RDF-enabled user agent to retrieve an RDF/XML document containing the following element:

<rdf:RDF xmlns:rdf=""

  <employeeData:employee rdf:about="">
    <employeeData:name>Bob Smith</employeeData:name>
    <employeeData:email rdf:resource=""/>


The user agent is general purpose, and although it has rules for certain commonly used ontologies, it has no built in code to handle the employeeData properties in the above example. To dynamically acquire the necessary function, the agent does an HTTP GET for The GET returns an OWL ontology, from which the agent discovers that is rdfs:subPropertyOf the property, one that the agent recognizes as designating a person's e-mail address. The agent offers Amy the option to send e-mail to Bob Smith. Amy's browser has, in an important sense, automatically extended itself for processing the employee data.

Good Practice

Good Practice: Information provided directly in RDF, or information for which automated means can be used to discover corresponding RDF, contributes to the self-describing Semantic Web.

Because its model is uniform, because all of its self-description is provided in the same model as the data itself, and because all RDF information is linked into the Web as a whole, RDF provides uniquely powerful facilities for dynamic integration of a self-describing Web. Therefore, it's particularly important that information not originally supplied in an RDF-specific format be convertible into RDF. The sections below discuss two means of doing this: the first shows how RDFa can integrate HTML documents into the Semantic Web, and the second illustrates the use of GRDDL to extract RDF from XML documents.

4.3.1 Using RDFa to produce self-describing HTML

[RDFa] is a W3C draft Recommendation for embedding Semantic Web statements into ordinary HTML Web pages. This example illustrates how RDFa can integrate HTML into the self-describing Semantic Web:

Mary is exploring the Web using a browser that has been enhanced with capabilities for interpreting RDFa. Her browser knows to look through each Web page that she browses, picking out information from the RDFa, and helping her to use it. For example, the page might contain the following HTML, which represents an [RDFVCard]-style contact listing. (This example is adapted from one in [RDFa]):

    <p class="contactinfo" 
        My name is
        <span property="contact:fn">
            Joseph Smith
        I'm a
        <span property="contact:title">
            distinguished web engineer
        <a rel="contact:org" href="">
        You can contact me
        <a rel="contact:email" href="">
            via email

Even though this document is of media type application/xhtml+xml, which is not a member of the RDF family of media types, an RDFa-enabled user agent can extract RDF from this document. This document conveys as RDF a set of semantic Web statements about the Web resource The predicates are all named with the same base URI, for which the shorthand prefix contact is established in the HTML. Using this syntax, the RDFa carries triples for relationships such as the full name of the contact (, which is Joseph Smith, the e-mail address ( which is, and so on.

An RDFa-enabled user agent can extract these triples and use them to help Mary work with the data they contain, or to integrate with other Semantic Web information. Indeed RDF is designed for such use because, as discussed above in 4.3 RDF and the Self-Describing Web, Semantic Web triples are inherently self-describing. If a user agent needs more information about the processing of the email triple it can, like Amy's user agent, do an HTTP GET and use the results to get more information. With luck, that information will lead the agent to automatically discover that, in the example, can indeed be used to send mail to the person named Joseph Smith. The browser can then offer Mary the option to send e-mail to Joe, or to add Joe to her address book.

Good Practice

Good Practice: RDFa SHOULD be used to make information conveyed in HTML self-describing.

Note: at this time, drafts of the [RDFa] specification are available, but the media-type registration for HTML itself has not been updated to reflect RDFa. As described in TAG Finding [AuthoritativeMetadata], conventions like RDFa are normative only if provided for in the applicable specification for the media-type in which they are used. Thus, for RDFa to be fully integrated with 2 The Web's Standard Retrieval Algorithm, the HTML and/or XHTML media-type registrations must be be updated. Use of RDFa is in any case encouraged in the interim until that happens.

4.3.2 Using GRDDL to bridge from XML to RDF

RDFa provides a standard means of encoding RDF information in XHTML documents, but many other XML variants lack that capability. Furthermore, RDFa requires explicit encoding of each triple in the XHTML instance, and that may in some cases be impractical. [GRDDL] provides a standard means of extracting useful RDF statements (triples) from a broad range of XML document formats. Each GRDDL-enabled XML document links to a transformation that, when applied to the document, produces RDF triples. Typically, the same GRDDL transformation can be used on entire families of similar XML documents.

For example, assume that Albert uses a GRDDL-enabled user agent to retrieve an XML document containing the following fragment:

<employees xmlns="">
  <employee name="Bob Smith">

Note that, unlike the earlier examples, this is neither in HTML nor in RDF; we can assume that is a namespace created by some particular business for use in its own busines documents. Albert's agent has no built in knowledge of this namespace, and so can not do much with it. Now assume that Albert instead retrieves a different document. Most of the markup and data in it is identical to the first, but this document is GRDDL enabled:

<employees xmlns=""
  <employee name="Bob Smith">

Albert's user agent is GRDDL aware, so it transforms the <employees> information to RDF using the supplied GRDDL_For_employeeNS.xsl transformation. If Albert is lucky, that transformation produces RDF triples that the agent understands, or that the agent can dynamically discover how to process using the techniques described above in 4.3 RDF and the Self-Describing Web. As in the earlier examples, Albert's user agent offers to send mail to Bob Smith.

Good Practice

Good Practice: GRDDL SHOULD be used to integrate XML documents into the self-describing Semantic Web.

4.4 Self-describing XML documents

Section 4.3.2 Using GRDDL to bridge from XML to RDF described how GRDDL can be used to integrate XML documents with the RDF-based Semantic Web. This section describes a related technique for creating new, self-describing XML formats.

Given that a Web document is of media type application/xml, or in the family of media types application/____+xml, recursive processing from the root element down may be applied to determine not just the overall nature of the document, but also the meaning in context of its sub-elements. Doing this, however, requires understanding of the semantics of each named element. Although a few specific XML variants such as application/xhtml+xml may be directly supported by some user agents, no user agent can build in support for the ever growing set of XML languages used for Web representations. This section describes how namespace documents, discoverable from the XML tag names in the markup, can be used to make such languages self-describing, and to enable automated processing of them.

When XML namespaces are used [XMLNamespaces], each XML element is named with a qualified name, consisting of a prefix and a local name. In the following example, the root element has the qualified name <inventory:inventoryItem>:


Qualified names map to expanded names such as {,inventoryItem}, comprised of a namespace name URI ( and a local name (inventoryItem). The namespace name URI serves at least two roles: the most obvious and the most widely understood is to distinguish expanded names in one namespace from those in another; the other role, and the one that's most important for purposes of this finding, is that it provides Web identification for the namespace itself. The namespace is a Web resource, and like any other resource, it can and should provide representations using HTTP. A user agent processing an XML document can retrieve descriptions of the namespaces used in that document, and can use that retrieved information to determine how to correctly process the XML markup. The W3C TAG is currently working on a finding that will describe best practices for creating such representations of namespaces. Drafts of the finding, which are available at [NamespaceDocuments], recommend the use of [RDDL] as a preferred means of documenting namespaces. RDDL is itself extensible, but it is commonly used to suggest XML Schemas (in any of several languages), XSLT Stylesheets, etc. that are usable with markup from the namespace being described.

Example: assume that user Bob is browsing the Web, and that he follows a link to a resource that returns the XML above as its representation. Bob's browser uses 2 The Web's Standard Retrieval Algorithm to retrieve the representation, to determine its character encoding, and to discover that its Content-type is application/inventory+xml. Of course, it's very unlikely that Bob's browser has built in knowledge of the inventory XML language, but the Content-type makes clear [XMLMediaType] that the representation can be interpreted as XML with Namespaces. The root element tag is from namespace, which uses the http scheme, so Bob's browser does an HTTP GET from that URI. What comes back is a RDDL document containing the following <rddl:resource> element:

   xlink:title="Transform Inventory XML to HTML for Browsing">

This designates a stylesheet ( that can be applied to format the inventory XML as HTML — the browser automatically retrieves and applies the stylesheet, producing HTML that is rendered on the screen. Without any manual intervention from Bob, his browser automatically displays the inventory record in a format that's convenient to read and print. Bob's browser may also be enabled for XML validation, in which case it can look in the RDDL for a link to a schema to be used for validating inventory markup, and can use that to check the document.

Bob's browser has, like Amy's in the RDF example shown earlier, extended itself for processing of the inventory markup language. Unless the RDDL provides a link to one or more executable program that processes inventory records, it's unlikely that Bob's browser can automatically discover everything that one might reasonably want to know about processing inventory markup. Still, even the limited automatic function described above is very useful, and RDDL is an extensible framework that can be easily adapted to provide new kinds of information about namespaces. Note that because RDDL documents are themselves XML, GRDDL can be applied to derive RDF statements from them (see 4.3.2 Using GRDDL to bridge from XML to RDF). In this way, self-describing XML documents can be integrated with the self-describing Semantic web. [NamespaceDocuments] describes this technique in more detail.

5 Conclusions

Ad hoc exploration of the Web is possible only if resource representations are self-describing. Using the techniques described above and starting with an http- or https-scheme URI, a user agent can proceed step by step to retrieve a representation, reliably discover the conventions that have been used to encode it, and if necessary, dynamically find instructions for processing it. Those who invent new document formats, new markup tags, or new conventions for encoding particular data values should use the techniques described above to make those formats self-describing. When these techniques are used, and when self-describing representations are linked together, the Web as a whole can support reliable, ad hoc discovery of information.

6 References

M. Nottingnam, R. Sayre (Eds.) RFC 4287: The Atom Syndication Format. December 2005 (See
R. Fielding, I. Jacobs, Authoritative Metadata. W3C Technical Architecture Group Finding, April, 2006. (See
I.Jacobs, N. Walsh, Architecture of the World Wide Web. W3C. December, 2004. (See
D. Connolly, Gleaning Resource Descriptions from Dialects of Languages (GRDDL), W3C Candidate Recommendation, May, 2007 (See
J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. Leach, T. Berners-Lee RFC 2616: Hypertext Transfer Protocol - HTTP/1.1. June 1999 (See
, M. Duerst, M. Suignard RFC 3987: Internationalized Resource Identifiers (IRIs). January 2005 (See
T. Berners-Lee, N. Mendelsohn B. Adida, M. Birbeck The Rule of Least Power. W3C Technical Architecture Group Finding, February, 2006 (See
N. Mendelsohn, S. Williams, The use of Metadata in URIs. W3C Technical Architecture Group Finding, January, 2007. (See
N. Walsh, Associating Resources with Namespaces. W3C Technical Architecture Group Draft Finding, December, 2005. (See
D. McGuinness, F. van Harmelen (Eds.) OWL Web Ontology Language Overview . W3C Recommendation, February 2004. (See
J. Borden, T. Bray, Resource Directory Description Language (RDDL). W3C. February, 2002. (See
G. Klyne, J. Carroll (Eds.) Resource Description Framework (RDF): Concepts and Abstract Syntax. W3C Recommendation, February 2004. (See
R. Ianella Representing vCard Objects in RDF/XML. W3C Note, February 2001. (See
F.Manola, E. Miller (Eds.) RDF Primer. W3C Recommendation, February 2004. (See
D. Birckley, R.V. Guha (Eds.) RDF Vocabulary Description Language 1.0: RDF Schema. W3C Recommendation, February 2004. (See
B. Adida, M. Birbeck RDFa Primer 1.0: Embedding RDF in XHTML. W3C. (working draft) March, 2007. (See
M. Murata, S. St. Laurent, D. Kohn RFC 3023: XML Media Types. January 2001 (See
T. Bray, D. Hollander, A. Layman, R. Tobin, Namespaces in XML 1.1. W3C, August, 2006 (2nd Edition). (See

A Change log (will be deleted before final publication)

6-Dec-2005 [NRM]: initial version

25-Feb-2007 [NRM]: trying to get it good enough to circulate

A.1 Changes in 24 May 2007 Edition

  • Changed title to "Self-describing Web"

  • New discussion of discovery of specs, role of RDF, etc.

  • Extensive editorial work.

A.2 Changes in February 2008 Edition

  • Major rewrite to take account of formal review from June 2007 (Google) F2F, and also informal comments made during hallway discussions at Sept. 2007 (Southampton) F2F. Changes include:

  • Story about "you reading this document" is gone.

  • Standard retrieval algorithm for Web added

  • Rearranged TOC and heading structure