W3C

RDFa API

An API for extracting structured data from Web documents

W3C Working Draft 19 April 2011

This version:
http://www.w3.org/TR/2011/WD-rdfa-api-20110419/
Latest published version:
http://www.w3.org/TR/rdfa-api/
Latest editor's draft:
http://www.w3.org/2010/02/rdfa/sources/rdfa-api/
Previous version:
http://www.w3.org/TR/2010/WD-rdfa-api-20100923/
Editors:
Manu Sporny, Digital Bazaar, Inc.
Benjamin Adrian, German Research Center for Artificial Intelligence GmbH
Authors:
Nathan Rixham, Invited Expert
Mark Birbeck, Backplane Ltd.
Ivan Herman, W3C

This document is also available in this non-normative format: Diff from previous Working Draft.


Abstract

RDFa [RDFA-CORE] enables authors to publish structured information that is both human- and machine-readable. Concepts that have traditionally been difficult for machines to detect, like people, places, events, music, movies, and recipes, are now easily marked up in Web documents. While publishing this data is vital to the growth of Linked Data, using the information to improve the collective utility of the Web for humankind is the true goal. To accomplish this goal, it must be simple for Web developers to extract and utilize structured information from a Web document. This document details such a mechanism; an RDFa Application Programming Interface (RDFa API) that allows simple extraction and usage of structured information from a Web document.

How to Read this Document

This section is non-normative.

This document is a detailed specification for an RDFa API. The document is primarily intended for the following audiences:

For those looking for an introduction to the use of RDFa, or some real-world examples, please consult the RDFa Primer [RDFA-PRIMER].

If you are not familiar with RDF, you should read about the Resource Description Framework (RDF) [RDF-CONCEPTS] before reading this document. The [RDF-CONCEPTS] document outlines the core data model that is used by RDFa to express information.

If you are not familiar with RDFa, you should read and understand the [RDFA-CORE] specification. It describes how data is encoded in host languages using RDFa. A solid understanding of concepts in RDFa Core will inevitably help you understand how the RDFa API works in concert with how the data is expressed in a host language.

If you are not familiar with the RDF API, you should read about the Resource Description Framework Application Programming Interface [RDF-API] which is the base specification for this document. The [RDF-API] specification outlines fundamental programming concepts for working with Web-based data.

If you are a Web developer and are already familiar with RDF and RDFa, and you want to programatically extract RDFa content from documents, then you will find the Concept Diagram and Developing with the API sections of most interest. It contains a handful of ECMAScript examples on how to use the RDFa API.

Readers who are not familiar with the Terse RDF Triple Language [TURTLE] may want to read the specification in order to understand the short-hand RDF notation used in some of the examples.

This document uses the Web Interface Definition Language [WEBIDL] to specify all language bindings. If you intend to implement the RDFa API you should be familiar with the Web IDL language [WEBIDL].

Examples may contain references to existing vocabularies and use abbreviations in CURIEs and source code. The following is a list of all vocabularies and their abbreviations, as used in this document:

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This document was previously published by the RDFa Working Group, whose charter was expanded in March 2011 to include work on the RDF API in addition to continuing work on the RDFa specifications. Due to the expansion in scope, the RDFa Working Group was renamed to the RDF Web Applications Working Group.

This document was published by the RDF Web Applications Working Group as a Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-rdfa-wg@w3.org (subscribe, archives). All feedback is welcome.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of Contents

1. Introduction

This section is non-normative.

RDFa provides a means to enable machine-readable markup of structured data in human-readable Web documents. Structured data that is contained in documents, such as people, films, companies, events, and so on, can provide an added layer of information to Web Applications. The RDFa API provides a set of interfaces that make it easy to access structured data in Web documents.

A document that contains RDFa effectively provides two data layers. The first layer is the information about the document itself, such as the relationship between the elements, the value of its attributes, the origin of the document, and so on, and this information is usually provided by the Document Object Model, or DOM [DOM-LEVEL-1].

The second data layer comprises information provided by embedded metadata, such as company names, film titles, ratings, and so on, and this is usually provided by RDFa [RDFA-CORE], Microformats [MICROFORMATS], DC-HTML, GRDDL, or Microdata.

Whilst this embedded information could be accessed via the usual DOM interfaces -- for example, by iterating through child elements and checking attribute values -- the potentially complex interrelationships between the data mean that it is more efficient for developers if they have direct access to the data after it has been extracted.

For example, a document may contain the name of a person in one section and the phone number of the same person in another; whilst the basic DOM interfaces provide access to these two pieces of information through normal navigation, it is more convenient for authors to have these two pieces of information available in one object.

This specification defines the RDFa API, which may be used by developers and Web Applications to access structured data contained in Web documents.

1.1 Design Considerations

This section is non-normative.

RDFa 1.0 [RDFA-SYNTAX] has seen substantial growth since it became an official W3C Recommendation in October 2008. It has seen wide adoption among search companies, e-commerce sites, governments, and content management systems. There are numerous interoperable implementations and growth is expected to continue to rise with the latest releases of RDFa 1.1 [RDFA-CORE], XHTML+RDFa 1.1 [XHTML-RDFA], and HTML+RDFa 1.1 [HTML-RDFA].

In an effort to ensure that Web applications are able to fully utilize RDFa, this specification outlines an API and a set of interfaces that extract RDF data from Web documents and other document formats that utilize RDFa. The RDFa API is designed with maximum code expressiveness and ease of use in mind. Furthermore, a deep understanding of RDF and RDFa is not necessary in order to extract and utilize the structured data embedded in RDFa documents.

Since there are many Web browsers and programming environments for the Web, the rapid adoption of RDFa requires an interoperable API that Web document designers can count on being available in all Web browsers. The RDFa API provides a uniform and developer-friendly interface for extracting RDFa from Web documents.

Since most browser-based applications and browser extensions that utilize Web documents are written in ECMAScript [ECMA-262], the implementation of the RDFa API is primarily concerned with ensuring that concepts covered in this document are easily utilized in ECMAScript.

While ECMAScript is of primary concern, the RDFa API specification is language independent and is designed such that DOM tool developers may implement it in many of the other common Web programming languages such as Python, Java, Perl, and Ruby. Objects that are defined by the RDFa API are designed to work as seamlessly as possible with language-native types, operators, and program flow constructs.

1.2 Goals

The design goals that drove the creation of the APIs that are described in this document are:

Ease of Use and Expressiveness
While this should be a design goal for all APIs, special care is taken to ensure that developers can accomplish common tasks using a minimal amount of code. While execution speed is always an important factor to consider, it is secondary to minimizing the amount of work a developer must perform to extract and use data contained in the document.
Modularity and Pluggability
This high-level API is part of a larger family of lower-level APIs for interfacing with RDF data on the Web. Special care has been taken to ensure that this API can be implemented without requiring the larger family of APIs. If the larger family of APIs is available, however, this API fits in nicely with those RDF APIs.
DOM Orthogonality
Interfaces defined on the Document should match programming paradigms that are familiar to developers. For example, if one were to attempt to retrieve Element Nodes by Subject, the name of the method should be document.getElementsBySubject(), which roughly mirrors the document.getElementsByClassName() functionality that is a part of [DOM-LEVEL-1].
Native Language Constructs
Data is exposed and processed in a way that is natural for ECMAScript and many other Web programming languages like Python, Ruby and even C++. For example, Projections are exposed as native language constructs. By ensuring that programming language constructs are considered in the design of the API, we ensure that the API won't fight the language and thus, the developer.
CURIEs and Templates
Some of the mechanisms that underpin RDF are difficult to use in everyday programming. For example, having to type out an entire URI is not only laborious for a programmer, but also error prone and overly-verbose. RDFa Core [RDFA-CORE] introduces the concept of a Compact URI Expression, or CURIE. This API builds on the CURIE concept and allows URIs to be expressed as CURIEs. The API should also provide short-cuts that reduce the amount of code that has to be repeated. Projection Templates are one example of reducing repetitive code writing as it can be stored in a single variable and re-used when building Projetions.

1.3 Concept Diagram

The following diagram describes the relationship between all concepts discussed in this document.

The RDFa API Concept Stack

Concept Stack for the RDFa API and RDF API

The RDFa API is layered on top of concepts defined by the RDF API. The lowest level concepts are Triples, Graphs and Projections. Triples, Graphs and Projections are data structures used by Web Developers to work with data expressed in RDF languages. Working directly with the data structures can be cumbersome at times, such as the requirement to use absolute URIs when accessing properties, thus Profiles are provided to support accessing the data using compact URIs (CURIEs). Data Parsers and Data Serializers provide mechanisms to both read and write RDF data in a variety of RDF languages. All of these concepts are provided via a high-level interface called the RDF Environment.

API implementers should note that only the portions of the RDF API that are directly used by this API need to be implemented for a conforming RDFa API implementation. That is, only Projections are required to be implemented from the RDF API for a fully conformant RDFa API implementation.

The higher-level RDFa API provides two interfaces for accessing data in the document. Simple queries for DOM data may be performed using the Document interface, while more complex queries for structured data may be performed using the Document Data interface.

2. Developing with the API

This section is non-normative.

The following section provides an overview of the basic RDFa API that developers may find most useful in day-to-day programming exercises. An overview of the more advanced RDFa API is also provided, which may help developers when tackling some of the more complex RDFa programming tasks.

2.1 Basic Concepts

This section is non-normative.

This API provides a number of interfaces to enable:

The Basic API

Many web developers will find that the basic functionality provided by the RDFa API is sufficient for day-to-day programming tasks. Since developers typically work with object-oriented data structures, the basic API is geared toward building language-native objects called Projections and returning them to the developer.

Retrieving Data in the Document

document.data.getSubjects(optional property, optional value)
Retrieves a list of all subjects expressed in the document that match the given arguments. If no arguments are provided, all subjects expressed in the document are returned.
document.data.getProperties(optional subject)
Retrieves a list of all properties expressed in the document that match the given subject. If a subject isn't provided, all properties expressed in the document are returned.
document.data.getValues(optional subject, optional property)
Retrieves a list of all values expressed in the document that match the given subject and property. If no arguments are provided, all values expressed in the document are returned.
document.data.getProjection(subject, optional template)
Retrieves a single Projection given a subject and an optional template. The template is used for the purposes of building the Projection in an application-specific way. To retrieve a Projection by a particular subject, one could do the following: document.data.getProjection("http://example.com/people#bob").
document.data.getProjections(optional property, optional value, optional template)
Retrieves a list of Projections given an optional property and value to match against. A template can be provided for the purposes of building the Projection in an application-specific way. To retrieve a list of Projections that contain the foaf:name property, one could do the following: document.data.getProjections("foaf:name").

Retrieving DOM Elements

document.getElementsByType(type)
Retrieves a list of DOM Nodes given a type to match against. The type is the rdf:type expressed in the DOM Node. The type can be expressed via the typeof, rel, rev or the property attribute.
document.getElementsBySubject(subject)
Retrieves a list of DOM Nodes given a subject to match against. The subject can be expressed via the about, href, src, or resource attribute.
document.getElementsByProperty(property, optional value)
Retrieves a list of DOM Nodes given a property and an optional value to match against. Properties can be expressed via the typeof, rel, rev or property attribute.

IRI Mapping

document.data.setMapping(mapping, iri)
Gets and sets short-hand IRI mappings that are used by the API. These mappings allow values such as foaf to be mapped to a longer IRI, for example: http://xmlns.com/foaf/0.1/. This mapping ensures that when a developer specifies a compact URI like foaf:Person, that it is expanded to http://xmlns.com/foaf/0.1/Person before it is used by the underlying API.

Advanced Processing

document.data.rdfa.query(query, optional template)
Retrieves an array of Projections based on a set of selection criteria. The template is used to build a language-native object that is specific to the needs of the developer and the application.

Using the Basic API

The following section uses the markup shown below to demonstrate how to extract and use subject, properties, values and Projections using the RDFa API. The following markup is used for the examples in this section and is assumed to be served from a document located at http://example.org/people.

<div prefix="foaf: http://xmlns.com/foaf/0.1/" about="#albert" typeof="foaf:Person">
  <span property="foaf:name">Albert Einstein</span>
</div>
Retrieving Basic Data

Often, developers must determine whether or not a document contains the type of data that they are interested in processing. The RDFa API provides a simple mechanism to extract things like subjects, properties and values from the current document. The return types for subjects and properties are always sequences of strings. Values are typically converted into language-native types. Strings and language-native types are used in order to make processing the data easier on the developer.

For example to get all of the subjects expressed in a document, one can use the following call:

var subjects = document.data.getSubjects();

To get the list of properties for each subject retrieved above, a developer could process each subject in a loop, like so:

for(var i = 0; i < subjects.length; i++)
{
   var subject = subjects[i];
   var properties = document.data.getProperties(subject);
   // ... process the properties ...
}

To retrieve only subjects containing a particular property, such as a name property, a developer could do the following:

var subjectsWithNames = document.data.getSubjects("http://xmlns.com/0.1/foaf/name");

Once the subjects containing a particular property are known, queries can be done on each subject to retrieve the values of properties:

var namedSubject = subjectsWithNames[0];
var names = document.data.getValues(namedSubject, "http://xmlns.com/0.1/foaf/name");

To retrieve all values for a particular property, such as all of the names listed in the document, the following code could be executed:

var allNames = document.data.getValues(null, "http://xmlns.com/0.1/foaf/name");

There are many more combinations of arguments passed to the basic getter methods for subjects, properties and values that allow high-level querying of data in the document. While this method of working with data may be useful to many developers, others may want to construct this data into a more object-oriented view of the data. In order to support this scenario, the RDFa API introduces Projections in the next section.

Working with Projections

Retrieving Projections by Type

A Projection is an object-oriented view of a particular subject that is expressed in the document. For example, to get all projections that express people in a document, a developer can do the following:

var people = document.data.getProjections("http://www.w3.org/1999/02/22-rdf-syntax-ns#type", "http://xmlns.com/foaf/0.1/Person");
A developer can also specify short-cuts to use when specifying the URI:
document.data.setMapping("rdf", "http://www.w3.org/1999/02/22-rdf-syntax-ns#type");
document.data.setMapping("foaf", "http://xmlns.com/foaf/0.1/");
var people = document.data.getProjections("rdf:type", "foaf:Person");

Retrieving Projections by Subject

You can also get a Projection by its subject:

var albert = document.data.getProjection("http://example.org/people#albert");

You can also specify a relative IRI and the document IRI will be automatically pre-pended:

var albert = document.data.getProjection("#albert");

Retrieving Projections by Property

You can get a list of Projections by their properties:

var peopleNamedAlbert = document.data.getProjections("foaf:name", "Albert Einstein");

Using Projections

You can retrieve property values from Projections like so:

var albert = document.data.getProjection("#albert");
var name = albert.get("foaf:name");

You can specify values that you would like to map to a Projection:

var albert = document.data.getProjection("#albert", {"name": "foaf:name"});
var name = albert.name;
The DOM may change between calls to any of the RDFa API data retrieval methods. These changes may cause subsequent calls to the same methods to return different results. As with any call against a DOM that is changing, developers are advised to program accordingly in order to avoid race conditions and other issues resulting from a changing data set.
Managing Elements with Data

Retrieving Elements Containing Data by Type

You can retrieve the DOM Element that is described above by doing the following:

var elements = document.getElementsByType("http://xmlns.com/foaf/0.1/Person");
or you can specify a short-cut to use when specifying the IRI:
document.data.setMapping("foaf", "http://xmlns.com/foaf/0.1/");
var elements = document.getElementsByType("foaf:Person");

Retrieving Elements Containing Data by Subject

You can also get a list of Elements by the subject of the data:

var elements = document.getElementsBySubject("http://example.org/people#albert");

You can also specify a relative IRI and the document IRI will be automatically pre-pended:

var elements = document.getElementsBySubject("#albert");

Retrieving Elements by Property

You can get a list of Elements by the properties and values that they declare:

var elements = document.getElementsByProperty("foaf:name", "Albert Einstein");

Modifying DOM Elements

You can modify elements that are returned just like any other DOM Node, for example:

var elements = document.getElementsByProperty("foaf:name", "Bob");
for(i = 0; i <= elements.length; i++)
{
   var e = elements[i];
   e.style.setProperty('color', '#00cc00', null);
}

The code above would change the color of all the areas of the page where the item's name is "Bob" to green.

2.2 Advanced Concepts

This section covers a number of concepts that go beyond basic day-to-day usage of the RDFa API.

Advanced Queries

Querying by Type

Perhaps the most basic task is to select Projections of a particular type. The type of a Projection is set in RDFa via the special attribute typeof. For example, the following markup expresses a Projection of type Person in the Friend-of-a-Friend vocabulary:

<div typeof="foaf:Person">
  <span property="foaf:name">Albert Einstein</span>
</div>

To locate all Projections that are people, we could use the document.getProjections() method:

document.data.getProjections("rdf:type", "foaf:Person");
or we could do the same using the standard query interface to retrieve a Projection:

var people = document.data.rdfa.query({"rdf:type": "foaf:Person"}, 
   {"name": "foaf:name", "age": "foaf:age"});

While the query interface is more verbose for simple queries, it becomes necessary for more complex queries as demonstrated later in this section. Note that the Query object has access to the mappings provided via the document.data object, so they can also be used in queries. It is also possible to write the same query in a way that is independent of any prefix-mappings:

var people = document.data.rdfa.query( 
   { "http://www.w3.org/1999/02/22-rdf-syntax-ns#type": "http://xmlns.com/foaf/0.1/Person" },
   { "name": "http://xmlns.com/foaf/0.1/name", "age": "http://xmlns.com/foaf/0.1/age" });
Querying by Property Value

The previous query selected all Projections of a certain type, but it did so by indicating that the property rdf:type should have a specific value. Queries can also specify other properties. For example, given the following mark-up:

<div typeof="foaf:Person">
  <span property="foaf:name">Albert Einstein</span> -
  <span property="foaf:myersBriggs">INTP</span>
  <a rel="foaf:workInfoHomepage" href="http://en.wikipedia.org/wiki/Albert_Einstein">More...</span>
</div>
<div typeof="foaf:Person">
  <span property="foaf:name">Mother Teresa</span> -
  <span property="foaf:myersBriggs">ISFJ</span>
  <a rel="foaf:workInfoHomepage" href="http://en.wikipedia.org/wiki/Mother_Teresa">More...</span>
</div>
<div typeof="foaf:Person">
  <span property="foaf:name">Marie Curie</span> - 
  <span property="foaf:myersBriggs">INTP</span>
  <a rel="foaf:workInfoHomepage" href="http://en.wikipedia.org/wiki/Marie_Curie">More...</span>
</div>

The following query demonstrates how a developer would select and use all Projections of type Person that also have a Myers Brigg's personality type of "INTP" (aka: The Architect):

var architects = document.data.rdfa.query({
  "http://www.w3.org/1999/02/22-rdf-syntax-ns#type": "http://xmlns.com/foaf/0.1/Person",
  "http://xmlns.com/foaf/0.1/myersBriggs": "INTP" },
  { "name": "http://xmlns.com/foaf/0.1/name" });

var name = architects[0].name;

As before, prefix-mappings can also be used:

var architects = document.data.rdfa.query( 
   { "rdf:type": "foaf:Person", "foaf:myersBriggs": "INTP" },
   { "name": "foaf:name" });

var name = architects[0].name;
In this case, all of the "INTP" personality types are gleaned from the page and presented as Projections containing each person's name and blog page:

var architects = document.data.rdfa.query( 
   { "rdf:type": "foaf:Person", "foaf:myersBriggs": "INTP" },
   { "name": "foaf:name", "webpage": "foaf:workInfoHomepage" });

var name = architects[0].name;
var infoWebpage = architects[0].webpage;

Creating Projections

Developers may find that they need to be able to build custom, language-native objects to use with their code. These specialized language-native objects are called Projections, and can be built by utilizing Projection Templates.

There has been a complaint that this section comes from out of nowhere. The purpose of this section is to describe that Projections can be mapped to native language objects to ease development. We may need to elaborate more on this at this point in the document to help integrate this section with the flow of the document.

For example, assume our source document contains the following event, marked up using the Data Vocabulary Event format:

<div prefix="v: http://rdf.data-vocabulary.org/#" typeof="v:Event"> 
  <a rel="v:url" href="http://amyandtheredfoxies.example.com/events" 
     property="v:summary">Tour Info: Amy And The Red Foxies</a>
  
  <span rel="v:location">
  	<a typeof="v:Organization" rel="v:url" href="http://www.kammgarn.de/" property="v:name">Kammgarn</a>
  </span>
  <div rel="v:photo"><img src="foxies.jpg"/></div>
  <span property="v:summary">Hey K-Town, Amy And The Red Foxies will rock Kammgarn in October.</span>
  When: 
  <span property="v:startDate" content="20091015T19:00">15. Oct., 7:00 pm</span>-
  <span property="v:endDate" content="20091015T21:00">9:00 pm</span>
  </span>

  Category: <span property="v:eventType">concert</span>
</div>

To query for all Event Projections we know that we can do this:

var events = document.data.getProjections("rdf:type", "http://rdf.data-vocabulary.org/#Event");

However, to build a special Projection that contains the summary, start date and end date, we can also do this:

var events = document.data.rdfa.query(
   { "rdf:type": "http://rdf.data-vocabulary.org/#Event" },
   { "type": "rdf:type", "summary": "v:summary", 
     "start": "v:startDate", "end": "v:endDate" } );

The second parameter is a Projection Template. Each key-value pair specifies a Projection property to URI mapping. That is, the key is the name of the property to create in the Projection object. The value must exist in a triple, specifically as a property of the triple, in order to copy the the object value of the triple over to the value of the Projection object's property.

For more detailed information about queries and Projections see the DocumentData interface.

3. The Interfaces Specification

The following section contains all of the interfaces that RDFa API implementers are expected to provide as well as guidance to ensure that implementations are conformant.

3.1 Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words must, must not, required, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [RFC2119].

Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. In particular, the algorithms defined in this specification are intended to be easy to follow and are not necessarily intended to be performant.

User Agents may impose implementation-specific limits on otherwise unconstrained inputs, e.g. to prevent denial of service attacks, to guard against running out of memory, or to work around platform-specific limitations.

Implementations that use ECMAScript or Java to implement the APIs defined in this specification must implement them in a manner consistent with the respective ECMAScript or Java Bindings defined in the Web IDL specification [WEBIDL], as this specification uses that specification's terminology.

Implementations that use any other language to implement the APIs defined in this specification that do not have bindings defined in the Web IDL specification should attempt to map the API as closely as possible to the implementation language's native mechanisms and datatypes. Developers are encouraged to work with other developers who are providing the RDFa API in the same langauge to ensure that RDFa API implementations are modular and easily replaceable.

3.2 Projections

The Projection interface is used to build language-native objects that can be accessed in a way that is natural for the implementation language.

[NoInterfaceObject]
interface Projection {
    DOMString[] getProperties ();
    DOMString   getSubject ();
    any getter  get (in DOMString uriOrCurie);
    any[]       getAll (in DOMString uriOrCurie);
};

Methods

get
Retrieves the first property with the given name as a language-native datatype.
ParameterTypeNullableOptionalDescription
uriOrCurieDOMStringThe name of the property to retrieve. The argument can be either an absolute URI or a CURIE that will be resolved using the default document mapping.
No exceptions.
Return type: any getter
getAll
Retrieves the list of values for a property as an array of language-native datatypes.
ParameterTypeNullableOptionalDescription
uriOrCurieDOMStringThe name of the property to retrieve. The argument can be either a full URI or a CURIE that will be resolved using the default document mapping.
No exceptions.
Return type: any[]
getProperties
Retrieves the list of properties that are available on the Projection. Each property must be an absolute URI.
No parameters.
No exceptions.
Return type: DOMString[]
getSubject
Retrieves the subject URI of this Projection as a string, the value must be an absolute URI.
No parameters.
No exceptions.
Return type: DOMString

3.3 The Document Interface

The RDFa API is designed to provide a small, powerful set of document-based interfaces that a developer may use to retrieve Projections from a Web document. This section focuses on the extensions necessary to the DOM environment. These extensions are separated into four interfaces:

Document Interface Extensions

The following section describes all of the extensions that are necessary to enable manipulation of structured data within a Web Document.

Document implements DataDocument;
All instances of the DOM Document interface must implement DataDocument.

The DataDocument interface provides necessary extensions to the core DOM Document interface to enable the processing and storage of structured data.

[Supplemental, NoInterfaceObject]
interface DataDocument {
    readonly attribute DocumentData data;
    NodeList getElementsByType (in DOMString type);
    NodeList getElementsBySubject (in DOMString subject);
    NodeList getElementsByProperty (in DOMString property, in optional DOMString? value);
};
Attributes
data of type DocumentData, readonly
The DocumentData interface is useful for extracting and storing data that is associated with the Document.
No exceptions.
Methods
getElementsByProperty
Retrieves a list of Nodes objects based on the value of a given property.
ParameterTypeNullableOptionalDescription
propertyDOMStringA DOMString representing an IRI-based property. The string can either be a absolute URI or a CURIE.
valueDOMStringA DOMString representing the value to match against.
No exceptions.
Return type: NodeList
getElementsBySubject
Retrieves a NodeList consisting of Nodes that have explicitly specified the given subject.
ParameterTypeNullableOptionalDescription
subjectDOMStringA DOMString representing an IRI-based subject. The string can either be a absolute URI or a CURIE.
No exceptions.
Return type: NodeList
getElementsByType
Retrieves a list of Nodes based on the object type of the data that they specify.
ParameterTypeNullableOptionalDescription
typeDOMStringA DOMString representing an rdf:type to select against.
No exceptions.
Return type: NodeList

3.4 DOM Implementation Extensions

If the RDFa API is implemented in a DOM environment and a DOMImplementation interface is provided, the following additional requirements for the hasFeature() method must be met:

interface DOMImplementation {
    boolean hasFeature (in DOMString feature, in DOMString version);
};

Methods

hasFeature
Checks to see whether or not the DOM implementation has exposed all of the mandatory RDFa API features specified in this specification. An implementation that supports all of the mandatory features in this specification must return true for a feature string of "RDFaAPI" and a version string of "1.1".
ParameterTypeNullableOptionalDescription
featureDOMStringThe feature string to use when checking to see if the DOM environment exposes all of the RDFa API attributes and methods.
versionDOMStringThe version string to use when checking to see if the DOM environment exposes all of the RDFa API attributes and methods.
No exceptions.
Return type: boolean

3.5 Document Data

The DocumentData interface is used to access the structured data in the document.

[NoInterfaceObject]
interface DocumentData {
    attribute optional RDFEnvironment rdf;
    attribute RDFaEnvironment         rdfa;
    Projection            getProjection (in DOMString subject, in optional object template);
    Sequence <Projection> getProjections (in optional object template);
    Sequence <Projection> getProjections (in optional DOMString property, in optional DOMString? value, in optional object template);
    Sequence<DOMString>   getProperties (in optional DOMString? subject);
    Sequence<DOMString>   getSubjects (in optional DOMString? property, in optional DOMString? value);
    Sequence<any>         getValues (in optional DOMString? subject, in optional DOMString? property);
    DOMString             setMapping (in in DOMString mapping, in in DOMString uri);
};

Attributes

rdf of type optional RDFEnvironment
The interface to the RDF convenience methods and functionality. Implementations may omit access to the underlying RDF implementation. If implementations include this attribute, they must conform to the [RDF-API] specification.
No exceptions.
rdfa of type RDFaEnvironment
The RDFa Environment interface provides RDFa-specific capabilities.
No exceptions.

Methods

getProjection
Retrieves a Projection given a subject and an optional Projection template if the subject exists in the document. If the subject does not exist in the document, null is returned.
ParameterTypeNullableOptionalDescription
subjectDOMStringThe subject to use when matching against triples. The subject can be either an absolute URI or a CURIE. The subject is used to match against the URI in the first part of a triple. An implementation must coerce the DOMString to the same type as the triple's subject being compared. If the type coercion will result in a URI, the CURIE mappings must be queried first for a mapping and the given property expanded as a CURIE if a mapping is found. If the subject does not exist in the document, the return value must be null.
templateobjectThe Projection template is used to build the return value. The template consists of a key-value associative array where the key is the name of the property to create in the Projection and the value is the URI to use when matching against predicates in each triple.
No exceptions.
Return type: Projection
getProjections
Retrieves a list of all Projections in the document using the optional Projection template to build the Projections.
ParameterTypeNullableOptionalDescription
templateobjectThe Projection template is used to build the return value. The template consists of a key-value associative array where the key is the name of the property to create in the Projection and the value is the URI to use when matching against predicates in each triple.
No exceptions.
Return type: Sequence <Projection>
getProjections
Retrieves a list of Projections that match the given optional property and value, constructed using the given Projection template.
ParameterTypeNullableOptionalDescription
propertyDOMStringThe property to use when matching against triples. The property can be either an absolute URI or a CURIE. The property is used to match against the URI in the second part of a triple, also known as the predicate. An implementation must coerce the DOMString to the same type as the predicate being compared. If the type coercion will result in a URI, the CURIE mappings must be queried first for a mapping and the given property expanded as a CURIE if a mapping is found. If the value is null, the match is always positive.
valueDOMStringThe value to use when matching against triples. The value can be either an absolute URI or a CURIE. The value is used to match against the final part of a triple, also known as the object. An implementation must coerce the DOMString to the same type as the object being compared. If the type coercion will result in a URI, the CURIE mappings must be queried first for a mapping and the given value expanded as a CURIE if a mapping is found. If the value is null, the match is always positive.
templateobjectThe Projection template is used to build the return value. The template consists of a key-value associative array where the key is the name of the property to create in the Projection and the value is the URI to use when matching against predicates in each triple.
No exceptions.
Return type: Sequence <Projection>
getProperties
Retrieves a list of DOMStrings which are IRI identifiers for properties given an optional subject to match against.
ParameterTypeNullableOptionalDescription
subjectDOMStringThe subject to use when matching against triples. The subject is used to match against the URI in the first part of a triple. The subject can be either an absolute URI or a CURIE. The subject is used to match against the first part of a triple. An implementation must coerce the DOMString to the same type as the triple's subject that is being compared. If the type coercion will result in a URI, the CURIE mappings must be queried first for a mapping and the given property expanded as a CURIE if a mapping is found. If the given subject is null, the match is always positive.
No exceptions.
Return type: Sequence <DOMString>
getSubjects
Retrieves a list of DOMStrings which are IRI identifiers for subjects given an optional property and value to match against.
ParameterTypeNullableOptionalDescription
propertyDOMStringThe property to use when matching against triples. The property can be either an absolute URI or a CURIE. The property is used to match against the URI in the second part of a triple, also known as the predicate. An implementation must coerce the DOMString to the same type as the predicate being compared. If the type coercion will result in a URI, the CURIE mappings must be queried first for a mapping and the given property expanded as a CURIE if a mapping is found. If the value is null, the match is always positive.
valueDOMStringThe value to use when matching against triples. The value can be a number, a boolean, a DOMString, an absolute URI or a CURIE. The value is used to match against the final part of a triple, also known as the object. An implementation must coerce the DOMString to the same type as the triple object being compared. If the type coercion will result in a URI, the CURIE mappings must be queried first for a mapping and the given property expanded as a CURIE if a mapping is found. If the value is null, the match is always positive.
No exceptions.
Return type: Sequence <DOMString>
getValues
Retrieves a list of mixed types given an optional subject and property to match against.
ParameterTypeNullableOptionalDescription
subjectDOMStringThe subject to use when matching against triples. The subject can be either an absolute URI or a CURIE. The subject is used to match against the URI in the first part of a triple. An implementation must coerce the DOMString to the same type as the subject being compared. If the type coercion will result in a URI, the CURIE mappings must be queried first for a mapping and the given property expanded as a CURIE if a mapping is found. If the value is null, the match is always positive.
propertyDOMStringThe property to use when matching against triples. The property can be either an absolute URI or a CURIE. The property is used to match against the URI in the second part of a triple, also known as the predicate. An implementation must coerce the DOMString to the same type as the predicate being compared. If the type coercion will result in a URI, the CURIE mappings must be queried first for a mapping and the given property expanded as a CURIE if a mapping is found. If the value is null, the match is always positive.
No exceptions.
Return type: Sequence<any>
setMapping
Sets a mapping given a mapping and a URI to map.
ParameterTypeNullableOptionalDescription
mappingin DOMStringThe shortened form of the URI to map.
uriin DOMStringAn absolute URI that the mapping should expand to when used with any of the structured data APIs.
No exceptions.
Return type: DOMString

3.6 RDFa Environment

The RDFaEnvironment interface is used to perform RDFa-specific actions.

[NoInterfaceObject]
interface RDFaEnvironment {
    Sequence<Projection> query (in optional object? query, in optional object template);
};

Methods

query
Generates a sequence of Projections that match the given selection criteria.
ParameterTypeNullableOptionalDescription
queryobjectAn associative array containing properties as keys and strings to match as values. If the query is null, every item in the default storage mechanism is returned.
templateobjectA template describing the attributes to create in each Projection that is returned. The template is an associative array containing key-value pairs. Each key corresponds to a property that will be created in the Projection that is returned. Each value corresponds to a triple's property, also known as a predicate, whose value will be stored in the Projection as the value of the key specified in the template.
No exceptions.
Return type: Sequence<Projection>

4. The Initialization Process

The RDFa API must be initialized before the Web developer has access to any of the methods that are defined in this specification. To initialize the API environment in a Browser-based environment, an implementor must do the following:

  1. Initialize all of the interfaces in the DOM environment required by this specification.
Unless otherwise specified, the document base is effectively the value of window.location.toString().

5. Future Discussion

This section is non-normative.

The RDFa Working Group is currently discussing whether or not to include the following advanced functionality:

A. Change History

The following changes have been made since the First Public Working Draft:

B. Acknowledgements

At the time of publication, the members of the RDFa Working Group were:

C. References

C.1 Normative references

[HTML-RDFA]
Manu Sporny; et al. HTML+RDFa 04 March 2010. W3C Working Draft. URL: http://www.w3.org/TR/rdfa-in-html/
[RDF-API]
Nathan Rixham, Manu Sporny; et al. RDF API Latest. W3C Editor's Draft. URL: http://www.w3.org/2010/02/rdfa/sources/rdf-api/
[RDFA-CORE]
Shane McCarron; et al. RDFa Core 1.1: Syntax and processing rules for embedding RDF through attributes.31 March 2011. W3C Working Draft. URL: http://www.w3.org/TR/2011/WD-rdfa-core-20110331
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt
[WEBIDL]
Cameron McCormack, Sam Weinig. Web IDL 11 March 2010. W3C Editor's Draft. URL: http://dev.w3.org/2006/webapi/WebIDL/
[XHTML-RDFA]
Shane McCarron; et. al. XHTML+RDFa 1.1. 31 March 2011. W3C Working Draft. URL: http://www.w3.org/TR/2011/WD-xhtml-rdfa-20110331

C.2 Informative references

[DOM-LEVEL-1]
Vidur Apparao; et al. Document Object Model (DOM) Level 1. 1 October 1998. W3C Recommendation. URL: http://www.w3.org/TR/1998/REC-DOM-Level-1-19981001/
[ECMA-262]
ECMAScript Language Specification, Third Edition. December 1999. URL: http://www.ecma-international.org/publications/standards/Ecma-262.htm
[MICROFORMATS]
Microformats. URL: http://microformats.org
[RDF-CONCEPTS]
Graham Klyne; Jeremy J. Carroll. Resource Description Framework (RDF): Concepts and Abstract Syntax. 10 February 2004. W3C Recommendation. URL: http://www.w3.org/TR/2004/REC-rdf-concepts-20040210
[RDFA-PRIMER]
Mark Birbeck; Ben Adida. RDFa Primer. 14 October 2008. W3C Note. URL: http://www.w3.org/TR/2008/NOTE-xhtml-rdfa-primer-20081014
[RDFA-SYNTAX]
Ben Adida, et al. RDFa in XHTML: Syntax and Processing. 14 October 2008. W3C Recommendation. URL: http://www.w3.org/TR/2008/REC-rdfa-syntax-20081014
[SVGTINY12]
Scott Hayman; et al. Scalable Vector Graphics (SVG) Tiny 1.2 Specification. 22 December 2008. W3C Recommendation. URL: http://www.w3.org/TR/2008/REC-SVGTiny12-20081222
[TURTLE]
David Beckett, Tim Berners-Lee. Turtle: Terse RDF Triple Language January 2008. W3C Team Submission. URL: http://www.w3.org/TeamSubmission/turtle/