XRD Sneak-Peek

(Or, Delivering on the Promise of Simple)

XRD Stack XRD is an evolution of the XRDS descriptor format, and a direct replacement of the XRDS-Simple project. The new format is being designed with a very clear set of requirements:

  1. Deliver on the promise of simplicity, providing a document format that is intuitive and focused.
  2. Support the basic use cases of self-description and related services.
  3. Align the format structure with existing, well established web architecture components (link).
  4. Delegate as much as possible to extensions, leaving the core format lean and mean.

Let’s jump right in…

An XRD describes a resource. If an application wants to learn more about a resource (identified by a URI), it looks for its XRD document. To do so, it uses a discovery protocol (XRD uses LRDD as its primary discovery solution). An XRD answers two questions about a resource:

  1. What are its characteristics, its attributes, or as XRD puts it, its ‘types’?
  2. What its relationship to other resources, what services are associated with it, or in XRD, its ‘links’?

The following examples are a pretty complete representation of the XRD format. In these examples, a blog hosted at http://blog.example.com uses a platform that supports the (made up) BLGX API protocol. The first XRD shown below describes a single article:


The article URI is http://blog.example.com/article/id/314 which is the subject of the XRD. It is the resource the XRD describes. The article can be reached using a human-friendly URI http://blog.example.com/cool_new_thing. The alternative URI is called an alias in XRD. Aliases allow a single XRD to describe a resource with more than one URI.

An XRD can only have one subject but many aliases, and the subject can be considered the resource’s canonical URI. If the XRD was obtained by performing discovery on the alias URI, it tells the application that the resource owner prefers the subject URI as the canonical identifier for the resource.

The <Expires> element defines how long the XRD is good for. If the XRD is obtained using HTTP, the HTTP protocol provides a way to accomplish the same goal. The main reasons for including this element are that not every developer has access to HTTP headers, and more importantly, XRDs are very useful as configuration files and are likely to be distributed using methods other than HTTP. If an XRD is obtained using HTTP, and the HTTP protocol provides its own expiration information, the document expires at the earlier expiration of the two.

The next element is <Type>. This is the element used to describe the resource itself. It is done by assigning (or tagging) the resource with URI-formatted strings that tell the application something about the resource. For example, in our made up blog API, the first type tells the application this blog supports version 1.2 of the API, and the second that it supports the language extension. Applications are free to specify their own types (using domains as a namespace). Protocols are encouraged to define such types for common use and interoperability.

Last, the XRD provides any number of links to other resources or services. If the resource represents a person, this can be a list of social networks, address book, calendar, or identity provider (such as OpenID). If the resource is protected using OAuth, the link can provide information on how to obtain a token. The <Link> element is directly mapped to the Link header semantics. In the example above, the link provides the profile page of the article’s author.

There is one more element which is shown in the following example:


The <URITemplate> element operates just like the <URI> element, providing the location of the linked resource. However, unlike <URI>, the template element provides a pattern which can be used to create unique URIs based on some additional inputs. In this example, the XRD describes the entire blog (which has an alias under a different TLD). The blog provides a way to find the main photo of each article by adding the ‘;photo’ suffix to any article URI. This is expressed using the template above.

If you are familiar with XRDS or XRDS-Simple, XRD would be pretty easy to understand. The main changes from XRDS are:

  • Removed XRDS top level element.
  • Added XRD-level <Type> for describing the resource itself.
  • Renamed <Service> to <Link>.
  • Replaced Service-level <Type> with <Rel>. More on that in a follow up post.
  • Added a URI template element.
  • Renamed <CanonicalID> to <Subject>, and <EquivID> to <Alias>.

In my next post on XRD I’ll describe how this will apply to OAuth Discovery and preview the upcoming OAuth Discovery draft. It will explain the XRD architecture in more details and show how it fixes many of the problem identified in the existing XRDS format.

2 thoughts on “XRD Sneak-Peek

  1. Hi,
    I don’t see the need for the MediaType element. Isn’t that making the same mistake that you pointed out in http://www.hueniverse.com/hueniverse/2009/02/redefining-discovery.html regarding OpenID version support?
    If (using first example above) http://blog.example.com/author/steve support both some standard for vCard-style information and the HTML version, why are you specifying the MediaType here? Just use discovery on that URLs to see which formats it supports.

  2. is part of the link framework. It offers a hint as to what the client should expect to find at the target URI. Don’t confuse it with describing the relationship. It is included mostly because every other link facility supports it (usually via the ‘type’ parameter).
    Another way to think about it, is that not every resource is an API endpoint. Many just store documents that don’t have “capabilities”. In the author example, the media type hint can help you figure out if it is a useful link for your application. But at the end, it is just a hint (applications may choose to elevate its level).

Comments are closed.