Work on this document has been put on hold indefinitely due to lack of interest. While a significant amount of design work went into this document, at present, there is only one known implementation of the specification. There are numerous design issues with this specification and it is not advised that developers implement this API unless they are fully familiar with the drawbacks present in the current design.

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 document is a detailed specification for an RDFa API. The document is primarily intended for the following audiences:

User Agent developers that are providing a mechanism to programatically extract RDF data from RDFa in a host language such as XHTML+RDFa [[XHTML-RDFA]], HTML+RDFa [[HTML-RDFA]] or SVG Tiny 1.2 [[SVGTINY12]],
DOM tool developers that want to provide a mechanism for extracting RDFa content via programming languages such as ECMAScript, Python, Ruby, or Perl, and
Developers that want to understand the inner workings and design criteria for the RDFa API.

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:

The RDF vocabulary (abbreviation: rdf, e.g., rdf:type)
The XSD vocabulary (abbreviation: xsd, e.g., xsd:integer)
The RDF schema vocabulary (abbreviation: rdfs, e.g., rdfs:label)
The Friend-Of-A-Friend vocabulary (abbreviation: foaf, e.g., foaf:name)

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 not 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 Interfaces defined in this specification must implement them in a manner consistent with the respective ECMAScript or Java Bindings defined in the Web IDL specification, as this specification uses that specification's terminology. [[!WEBIDL]]

Implementations that use any other language to implement the Interfaces defined in this specification that do not have bindings defined in the Web IDL specification should attempt to map the Interfaces 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 RDF Interfaces in the same langauge to ensure that implementations are modular and easily exchangable.

Introduction

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.

Design Considerations

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.

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. Graphs can be iterated over by providing an anonymous function or function pointer. 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.

Concept Diagram

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

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.

Developing with the API

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.

Basic Concepts

This API provides a number of interfaces to enable:

parsing Documents for RDFa metadata;
retrieving Elements containing RDFa metadata;
performing advanced queries on the Document and extracting application-specific Projections for use in Web Applications.

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.

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:

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.

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.

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.

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.

DOMString[] getProperties()

Retrieves the list of properties that are available on the Projection. Each property MUST be an absolute URI.

DOMString getSubject()

Retrieves the subject URI of this Projection as a string, the value MUST be an absolute URI.

any getter get()

Retrieves the first property with the given name as a language-native datatype.

DOMString uriOrCurie: The 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.

any[] getAll(in uriOrCurie)

Retrieves the list of values for a property as an array of language-native datatypes.

DOMString uriOrCurie: The 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.

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 — A set of basic extensions to the Document interface to help developers identify DOM Nodes containing structured data in Web documents.
DOM Implementation Extensions — An extension to the DOM Implementation that allows developers to query for functionality provided by the RDFa API.
Document Data — The high-level interface for providing access to structured data in documents.
RDFa Environment — The high-level interface for performing advanced queries and parsing of RDFa documents.

Document Interface Extensions

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

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.

readonly attribute DocumentData data

The DocumentData interface is useful for extracting and storing data that is associated with the Document.

NodeList getElementsByType (in DOMString type)

Retrieves a list of Nodes based on the object type of the data that they specify.

DOMString type: A DOMString representing an rdf:type to select against.

NodeList getElementsBySubject (in DOMString subject)

Retrieves a NodeList consisting of Nodes that have explicitly specified the given subject.

DOMString subject: A DOMString representing an IRI-based subject. The string can either be a absolute URI or a CURIE.

NodeList getElementsByProperty (in DOMString property, in optional DOMString? value)

Retrieves a list of Nodes objects based on the value of a given property.

DOMString property: A DOMString representing an IRI-based property. The string can either be a absolute URI or a CURIE.
optional DOMString? value: A DOMString representing the value to match against.

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:

boolean hasFeature (in DOMString feature, in optional DOMString version)

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

DOMString feature: The feature string to use when checking to see if the DOM environment exposes all of the RDFa API attributes and methods.
DOMString version: The version string to use when checking to see if the DOM environment exposes all of the RDFa API attributes and methods.

Document Data

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

attribute optional RDFEnvironment rdf

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.

attribute RDFaEnvironment rdfa

The RDFa Environment interface provides RDFa-specific capabilities.

Projection getProjection (in DOMString subject, in optional object template)

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.

DOMString subject: The 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.
optional object template: The 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.

Sequence <Projection> getProjections(in optional object? template)

Retrieves a list of all Projections in the document using the optional Projection template to build the Projections.

optional object template: The 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.

Sequence <Projection> getProjections (in optional DOMString property, in optional DOMString? value, in optional object template)

Retrieves a list of Projections that match the given optional property and value, constructed using the given Projection template.

optional DOMString property: The 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.
optional DOMString? value: The 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.
optional object template: The 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.

Sequence<DOMString> getProperties (in optional DOMString? subject)

Retrieves a list of DOMStrings which are IRI identifiers for properties given an optional subject to match against.

optional DOMString? subject: The 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.

Sequence<DOMString> getSubjects (in optional DOMString? property, in optional DOMString? value)

Retrieves a list of DOMStrings which are IRI identifiers for subjects given an optional property and value to match against.

optional DOMString? property: The 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.
optional DOMString? value: The 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.

Sequence<any> getValues (in optional DOMString? subject, in optional DOMString? property)

Retrieves a list of mixed types given an optional subject and property to match against.

optional DOMString? subject: The 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.
optional DOMString? property: The 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.

DOMString setMapping ()

Sets a mapping given a mapping and a URI to map.

in DOMString mapping: The shortened form of the URI to map.
in DOMString uri: An absolute URI that the mapping should expand to when used with any of the structured data APIs.

RDFa Environment

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

Sequence<Projection> query ()

Generates a sequence of Projections that match the given selection criteria.

optional object? query: An 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.
optional object template: A 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.