The audience for this document should have a working knowledge of XHTML. Some familiarity with RDF is useful, though the basics can be picked up from reading this Primer. Similarly, the basic XML concepts used in this work—in particular namespaces— can be picked up from reading this Primer.

Jo has an upcoming talk at the XTech Conference, on May 8th at 10am, where she will be discussing "web widgets". She blogs an announcement of her talk at http://jo-blog.example.org/. Her blog also includes her contact information (Jo has a fantastic spam filter, so she is unafraid of publishing her email address):

This short piece of mark-up is already full of structured data.

The markup describes an event: a talk that Jo is giving. This event starts at 10am on May 8th. A summary of the event is "a talk at XTech 2007 on web widgets." We also have contact information for Jo: she works for the organization Example.org, with job title of "Distinguished Web Engineer." She can be contacted at the email address "jo@example.org."

At the moment, it is very difficult for software — like web browsers and search engines — to make use of this implicit data. We need a standard mechanism to explicitly express it. This is precisely where RDFa comes in.

Jo would like to add some structure to this blog entry so that readers of her blog might be able to add her talk directly to their calendar. RDFa allows her to do just that, using extra attributes. Since this is a calendar event, Jo will specifically use the iCal vocabulary to denote the data's structure.

The first step is to reference the iCal vocabulary within the HTML page, so that a parser may know where to look up the vocabulary terms:

then, Jo declares a new event and gives it a name:

Note how the class attribute is used here to define the type of the data being expressed, exactly as this attribute was initially intended in HTML. (If Jo wanted to declare multiple types, she could include more than one value in the class attribute with space separation.) Now, Jo wants to make sure that all information within this p describe the event itself. She adds an additional attribute:

then, inside this event declaration, Jo can set up the event fields, reusing the existing HTML. For example, the event summary can be declared as:

The property attribute on the span element declares a data field that pertains to the closest declared about, in this case the Vevent declared in the p. Note how the existing rendered content, "a talk at the XTech Conference about web widgets", is the value of this field. Sometimes, this isn't the right thing. Specifically, the start time of the event should be rendered nicely — "May 8th" —, but should likely be represented in an easy, machine-parsable way, the standard iCal format: 20070508T1000+0200. In this case, the markup needs only a slight modification:

In this case, the actual content of the span element, "May 8th at 10am", is ignored for structured data purposes: it has been replaced by the explicit content attribute. The full markup is then:

The above markup can be interpreted now as a set of RDF triples, the details of which we we explain in Section .

Note that Jo could have used any other HTML element, not just span, to carry the structure of her data. In other words, when the structure of the data is already laid out in the HTML using elements such as h1, em, div, etc..., Jo can simply add the property attribute, and optionally the content attribute, to indicate the specific structure.

Now that Jo has published an event using structured data, she realizes there is much data on her blog that she can mark up in the same way. Her contact information, in particular, is an easy target for structured markup with RDFa:

Jo discovers the vCard RDF vocabulary , which she adds to her existing page. Since Jo thinks of vCards as a way to publish her contact information, she uses the prefix contact to designate this vocabulary. Note that, although Jo already imported the iCal vocabulary, adding the vCard vocabulary is just as easy and does not interfere:

Jo then sets up her vCard using RDFa, by deciding that the appropriate p will be her vcard. She notes, however, that the vCard schema does not require declaring a vCard type. Instead, it is recommended that a vCard refer to a web page that identifies the individual. Jo thus uses RDFa's special attribute about for just for this purpose, indicating that all contained HTML pertain to Jo's designated URL. Note how the about attribute is inherited from parent elements in the HTML: the about attribute on the nearest ancestor applies to declared structured data.

"Simple enough!" Jo realizes. She adds her first vCard fields: name, title, organization and email.

Notice how Jo was able to use the rel attribute directly within the anchor tag for designating her organization and email address. In this case, the rel indicates a relationship between the current URL, designated by about, and the target URL, designated by href. The exact meaning of this relationship is defined by the rel. In this case, contact:org indicates the relationship of "vCard organization", while contact:email indicates the relationship of "vCard email".

The rel attribute is naturally paired with the href attribute, much like the property attribute is paired with the content attribute. The astute reader will notice that we have defined what happens when a property attribute is present without a content attribute, but not what happens when a rel attribute is present without its corresponding href. We explore this feature in Section .

(The above example slightly simplifies the vCard vocabulary where email is concerned, since vCard technically requires indicating the type of the email. This simplification is for clarity's sake.)

Jo's complete HTML with RDFa is thus:

Note how, if Jo changes her email address link, her organization, or the title of her talk, the RDFa approach will automatically pick up these changes in the marked up, structured data. The only places where this doesn't happen is when the content attribute must override the rendered content, which is inevitable when the human-rendered data and the machine-readable data must differ.

The RDF triples generated by the above markup are detailed in Section .

What if Jo does not have complete control over the HTML of her blog? For example, she may be using a templating system which makes it particularly difficult to add the vocabularies in the html element at the top of her page without adding it to every page on her site. Or, she may be using a web blogging provider that doesn't allow her to change the header of the page to begin with.

Fortunately, RDFa uses standard XML namespaces, which means that the vocabularies can be imported "locally" to an HTML element. Jo's HTML blog page could express the exact same structured data with the following markup:

Of course, just like in the case of the vocabularies defined on the top-level html tag, more than one vocabulary can be imported into any element. In this case, each p only needs one vocabulary: the first uses iCal, the second uses vCard. This approach helps with the desired ability to copy-and-paste HTML from one page to another: the closer the namespace declarations to their relevant statements, the easier it is to copy and paste the content.

RDFa is parsed to generate RDF triples, which we denote using N3 notation . URIs are written using angle brackets, e.g. <http://example.org/foo/bar>, literals are written in quotation marks, e.g. "a talk", and QNames are written directly, e.g. cal:summary.

In Section , Jo published an event. The RDF triples extracted from her markup are:

In Section , Jo published contact information. The RDFa is parsed to generate the following RDF triples:

(The ^^XMLLiteral notation, which denotes a datatype, will be explained shortly.)

Consider a (fictional) photo management web site called Shutr, whose web site is http://www.shutr.net. Users of Shutr can upload their photos at will, annotate them, organize them into albums, and share them with the world. They can choose to keep these photos private, or make them available for public consumption under licensing terms of their choosing.

The primary interface to Shutr is its web site and the HTML it delivers. Since photos are contributed by users with significant amount of built-in structured data (camera type, exposure, etc...) and additional, explicitly provided data (photo caption, license, photographer's name), Shutr may benefit from using RDF to express this structure.

We explore how Shutr might use RDFa to express RDF right in the HTML it already publishes. We assume an additional XML namespace, shutr, which corresponds to URI http://www.shutr.net/rdf/shutr#.

The simplest structured data Shutr might want to expose is basic information about a photo album: the creator of the album, the date of creation, and its license. We consider literal properties first, and URI properties second. (We ignore photo-specific data for now, as that involves RDF statements about an image, which is not an HTML document. We will, of course, get back to this soon.)

A literal property is a string of text, e.g. "Ben Adida", a number, e.g. "28", or any other typed, self-contained datum that one might want to express as a property. In RDFa, literal properties are expressed using the property attribute and an optional content attribute.

Consider Mark Birbeck, a user of the Shutr system with username markb, and his latest photo album "Vacation in the South of France." This photo album resides at http://www.shutr.net/user/markb/album/12345. The HTML document presented upon request of that URI includes the following HTML snippet:

Notice how the rendered HTML contains elements of the photo album's structured data. Using RDFa, Shutr can mark up this HTML to indicate these structured data properties without repeating the raw data:

An RDFa-aware browser would thus extract the following RDF triples:

When the existing HTML elements already delineate the exact structure, adding a new span element is not required. One can easily add the RDFa attributes to existing HTML elements:

which yields the same RDF triples, of course. The use of an extra span is helpful when existing HTML markup isn't enough to isolate the rendered content that is relevant to the RDF triple.

A reader who knows about XML datatypes might, at this point in the presentation, wonder what datatype these values will have. Given the above RDFa, "Vacation in the South of France" is an XML Literal. In some cases, this may not be appropriate. Consider an expanded HTML snippet which includes the photo album's creation date:

A precise way to augment this HTML with RDFa is:

which would yield the following triples (note how the default datatype is XMLLiteral, which explains the first example above.):

Going further, Shutr realizes that 2007-01-02, while a correct xsd:date representation, is not exactly user-friendly. In this case, having the rendered data be the same as the structured data might not be the right answer. Shutr may instead opt for the following RDFa:

The above HTML will render the date as "January 2nd, 2007" but will yield the exact same triples as above. The use of the content attribute should be limited to cases where the rendered text is not well-enough structured to represent the data.

If Shutr wants to indicate that a specific object, e.g. "Mark Birbeck", plays two different roles, e.g. creator and publisher, the markup can easily be updated to reflect this duality without repeating the data:

In all of the above markup and triples, as well as in the rest of the document, we use the dc:creator predicate with both literals, e.g. strings, and URIs, e.g. names and "persons": both are allowed by the Dublin Core specification. We show in how to refer to fragments of a document, and in how to create deeper structures to address this type of issue.

A URI property is one that is merely a reference to a web-accessible resource, e.g. an image, a PDF document, or another HTML document, all reachable via the web. In RDFa, URI properties are expressed using the rel and href attributes. The href attribute is the well-understood target of a link, while rel indicates a relationship.

Shutr may want to give its users the ability to license their photos to the world under certain specific conditions. For this purpose, there are numerous existing licenses, including those published by Creative Commons. Thus, if Mark Birbeck chooses to license his vacation album for others to reuse, Shutr might use the following HTML snippet:

This clickable link has an intended meaning: it is the document's license. Using RDFa can cement that meaning within the HTML itself:

Note the use of the rel attribute to indicate a URI property rather than a textual one. The use of this attribute goes hand in hand with an href attribute within the same element. This href attribute indicates the URI object of the RDF triple. Thus, the above RDFa yields the following triple:

It is worth noting that the rel attribute, like property and class, supports multiple values, separated by spaces. The triples generated are the same as if each value were declared independently.

Compared with other existing RDF mechanisms to indicate Creative Commons licensing—e.g. a parallel RDF/XML file or inline RDF/XML within HTML comments—, the RDFa approach provides Creative Commons and Shutr with a significant integrity advantage: the clickable link is the semantic link, and any change to the target will change both the human and machine views. Also, a simple copy-and-paste of the HTML will carry through both the rendered and semantic data.

In both cases, the target URI may provide an HTML document which includes further RDFa statements. The Creative Commons license page, for example, may include RDFa statements about its legal details.

Shutr may choose to present many photos in a given HTML page. In particular, at the URI http://www.shutr.net/user/markb/album/12345, all of the album's photos will appear inline. Structured data about each photo can be included simply by specifying an about attribute:

, Sunset in Nice

, W3C Meeting in Mandelieu

]]>

The above RDFa yields the following triples:

This same approach applies to statements with URI objects. For example, each photo in the album has a creator and may have its own usage license.

, Sunset in Nice taken by photographer Mark Birbeck , licensed under a Creative Commons Non-Commercial License .

W3C Meeting in Mandelieu taken by photographer Steven Pemberton , licensed under a Creative Commons Commercial License .

]]>

This yields the following triples:

At this point, Shutr might begin to worry about the fast-growing size of its HTML document, given that the photo's URI must be repeated in the about attribute for every RDF property expressed. To address this issue, RDFa allows the value of this attribute to be inherited from a parent or ancestor element. In other words, if an element carries a rel or property attribute, but no about attribute, an RDFa browser will determine the subject of the RDF statement by navigating up the parent hierarchy of that element until it finds an about, or until it gets to the root element, at which point the default is about="".

Thus, the markup for the above example can be simplified to:

Sunset in Nice , taken by photographer Mark Birbeck , licensed under a Creative Commons Non-Commercial License .

W3C Meeting in Mandelieu , taken by photographer Steven Pemberton licensed under a Creative Commons Commercial License .

]]>

which yields the same triples as the previous example, though, in this case, one can easily see the parallel to the corresponding N3 shorthand:

While it makes sense for Shutr to have a whole web page dedicated to each photo album, it might not make as much sense to have a single page for each camera owned by a user. A single page that describes all cameras belong to a single user is the more likely scenario. For this purpose, RDFa provides ways to make structured data statements about chunks of documents using natural HTML constructs.

Consider the page http://www.shutr.net/user/markb/cameras, which, as its URI implies, lists Mark Birbeck's cameras. Its HTML includes:

and the photo page will then include information about which camera was used to take each photo:

... using the Nikon D200, ...

... ]]>

The RDFa syntax for formally specifying the relationship is exactly the same as before, as expected:

... using the Nikon D200, ...

... ]]>

which corresponds to:

Then, the HTML snippet at http://www.shutr.net/user/markb/cameras is:

which then yields the following triples:

Consider, specifically, that Tim Berners-Lee is encouraging folks to publish a FOAF file. Let's express (a portion of) Tim's FOAF file using RDFa. We start with a portion of Tim's homepage:

We can easily mark up the "one-layer deep" structure, specifically the email, phone, and fax fields with properties foaf:mailbox, foaf:phone, and foaf:fax:

Now, we need to express the address information in relation to Tim, as well as the address's properties, e.g. street address, city, state, etc. Recall that, when referencing another named resource, we've used the rel attribute. For example, to describe the licensing of a document, we've used the markup:

What we need to do here is describe a relationship of foaf:address between Tim and some unnamed node of data, off which we want to hang additional properties. Thus, we use the rel attribute again, this time without a corresponding href.

The HTML element on which this rel is expressed, in this case dd, then represents a blank node (in RDF terminology) that is the object of the foaf:address relationship. In addition, the subject of all contained RDFa statements is transparently set to be this blank node, as if there were an implicit about. This then allows the following markup to say exactly what we mean:

This layering of structured data easily extends to multiple layers. Consider what Tim might do if he were to list both his home and office addresses. The properties foaf:office and foaf:home each relate a foaf:Person to a location, and each location has an address. Thus, the markup becomes, quite naturally:

Using this technique, it is relatively easy and natural to express fairly extensive and complex structured data.

When interpreted as RDF, the use of the rel attribute without a corresponding href creates a new RDF blank node. Specifically, in the first example where Tim publishes a single address, the triples are:

In the case of the multiple addresses, the triples become:

In most cases, it is neither useful nor desired to make the internal components of the structured data accessible by the outside world. For example, there is likely no good reason for Tim to give his office address a URI which other RDF statements might reference. Simply handing out his FOAF URI is enough.

However, in some cases, it may in fact be useful to name all components yet to continue to use the rel without an href to designate the structured relationship. RDFa allows this as naturally as possible: if the element on which the rel is added has an id or an about, then the value of that attribute becomes the name of the node, and all triples are appropriately updated. about takes precedence over id, since it is an explicit RDFa statement.

For example, if Tim chose the following markup:

the triples would then become:

Note that this doesn't change anything significant about the structured data itself, only that the address is now addressable by other structured data statements.