W3C

RDFa DOM API 1.1

An API for extracting structured data from Web documents

W3C Working Draft 29 April 2010

This version:
http://www.w3.org/TR/2010/WD-rdfa-dom-api-20100429/
Latest published version:
http://www.w3.org/TR/rdfa-dom-api/
Latest editor's draft:
http://www.w3.org/2010/02/rdfa/sources/rdfa-dom-api/
Editors:
Benjamin Adrian, German Research Center for Artificial Intelligence GmbH
Manu Sporny, Digital Bazaar, Inc.


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 Document Object Model Application Programming Interface (RDFa DOM 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 DOM 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 DOM API works in concert with how the data is expressed in a host language.

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 RDFa API section of most interest. It contains a handful of JavaScript examples on how to use the RDFa DOM 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 DOM 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 published by the RDFa Working Group as a First Public 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. Motivation

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 Triples from Web documents or other document formats that utilize RDFa. The RDFa DOM 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 DOM 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 JavaScript [ECMA-262], the implementation of the RDFa DOM API is primarily concerned with ensuring that concepts covered in this document are easily utilized in JavaScript. While JavaScript is of primary concern, the RDFa DOM 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 DOM API are designed to work as seamlessly as possible with language-native types, operators, and program flow constructs.

2. The RDF Interfaces

The RDFa Working Group is still discussing whether or not concepts in the traditional RDF model should be used to express the objects returned by the RDFa DOM API. The alternative would be to use a simpler object representation format, such as a JavaScript associative Array. The section below assumes the former; a small subset of RDF core concepts will be used to express objects returned by the RDFa DOM API.

RDFa is a syntax for expressing the RDF Data Model [RDF-CONCEPTS] in Web documents. The RDFa DOM API is designed to extract the RDF Data Model from Web documents. The following RDF Resources are utilized in this specification: Plain Literals, Typed Literals, IRI References (as defined in [IRI]) and Blank Nodes. The interfaces for each of these RDF Resources are detailed in this section. The types as exposed by the RDFa DOM API conform to the same data and comparison restrictions as specified in the RDF concepts specification [RDF-CONCEPTS] and the [IRI] specification.

Each RDF interface provides access to both the extracted RDFa value and the DOM Node from which the value was extracted. This allows developers to extract and use RDF triples from a host language and also manipulate the DOM based on the associated DOM Node. For example, an agent could highlight all strings that are marked up as foaf:name properties in a Web document.

The basic RDF Resource types used in the RDFa DOM API are:

An RDFa DOM API implementer must provide the basic types as described in this specification. An implementer may provide additional types and/or a deeper type or class hierarchy that includes these basic types.

2.1 IRI References

An IRI Reference in the RDFa DOM API points to a resource and is further defined in [IRI].

[Constructor(in DOMString value), 
 Constructor(in DOMString value, in Node element), 
 Stringifies=value]
interface IRI {
    readonly attribute DOMString value;
    readonly attribute Node      element;
};

2.1.1 Attributes

element of type Node, readonly
The node that specifies the IRI's value in the RDFa markup.
No exceptions.
value of type DOMString, readonly
The lexical representation of the IRI reference.
No exceptions.

2.2 RDF Literals

An RDF Literal is an RDF Resource that represents lexical values in RDFa data. The two RDF Literals provided via the RDFa DOM API are PlainLiterals and TypedLiterals. For a given RDF Literal, either language or type information can be provided. If the type is set, the RDF Literal is a Typed Literal. If a type is not set, it is a Plain Literal.

PlainLiteral
RDF Literals that may contain language information about the given text. The language is specified as a text string as specified in [BCP47] (e.g., 'en', 'fr', 'de').
TypedLiteral
RDF Literals that contain type information about the given text. The type is always specified in the form of an IRI Reference (e.g., http://www.w3.org/2001/XMLSchema#DateTime).

2.2.1 Plain Literals

PlainLiterals have a string value and may specify a language.

The RDFa Working Group is considering whether plain literals should express literal values as UTF-8, or whether the encoding of the source document should be used instead. This section assumes that the encoding from the source document should be used.

[Constructor(in DOMString value), 
 Constructor(in DOMString value, in DOMString language), 
 Constructor(in DOMString value, in DOMString language, in Node element), 
 Stringifies=value]
interface PlainLiteral {
    readonly attribute DOMString value;
    readonly attribute DOMString language;
    readonly attribute Node      element;
};
Attributes
element of type Node, readonly
The first node in the DOM tree that is associated with this PlainLiteral.
No exceptions.
language of type DOMString, readonly
A two character language string as defined in [BCP47], normalized to lowercase.
No exceptions.
value of type DOMString, readonly
The lexical value of the literal encoded in the character encoding of the source document. The value is extracted from an RDFa document using the algorithm defined in the RDFa Core Specification [RDFA-CORE], Section 7.5: Sequence, Step 11.
No exceptions.
Example

This section is non-normative.

The following example demonstrates a few common use cases of the PlainLiteral type.

>> var literal = new PlainLiteral('Harry Potter and the Half-Blood Prince', 'en');
>> print(literal.toString());
Harry Potter and the Half-Blood Prince
>> print(literal.value);
Harry Potter and the Half-Blood Prince
>> print(literal.language);
en

2.2.2 Typed Literals

A TypedLiteral has a string value and a datatype specified as an IRI Reference. TypedLiterals can be converted into native language datatypes of the implementing programming language by registering a Typed Literal Converter as defined later in the specification.

The datatype's IRI reference specifies the datatype of the text value, e.g., xsd:DataTime or xsd:boolean.

The RDFa DOM API provides a method to explicitly convert TypedLiteral values to native datatypes supported by the host programming language. Developers may write their own Typed Literal Converters in order to convert an RDFLiteral into a native language type. The converters are registered by using the registerTypeConversion() method. Default TypedLiteral converters must be supported by the RDFa DOM API implementation for the following XML Schema datatypes:

  • xsd:string
  • xsd:boolean
  • xsd:float
  • xsd:double
  • xsd:boolean
  • xsd:integer
  • xsd:long
  • xsd:date
  • xsd:time
  • xsd:dateTime
[Constructor(in DOMString value, in IRI type), 
 Constructor(in DOMString value, in IRI type, in Node element), 
 Stringifies=value]
interface TypedLiteral {
    readonly attribute DOMString value;
    readonly attribute IRI       type;
    readonly attribute Node      element;
    Any valueOf ();
};
Attributes
element of type Node, readonly
The first node in the DOM tree that is associated with this TypedLiteral.
No exceptions.
type of type IRI, readonly
A datatype identified by an IRI reference
No exceptions.
value of type DOMString, readonly
The lexical value of the literal encoded in the character encoding of the source document. The value is extracted from an RDFa document using the algorithm defined in the RDFa Core Specification [RDFA-CORE], Section 7.5: Sequence, Step 11.
No exceptions.
Methods
valueOf
Returns a native language representation of this literal. The type conversion should be performed by translating the value of the literal using the IRI reference of the datatype to the closest native datatype in the programming language.
No parameters.
No exceptions.
Return type: Any
Example

This section is non-normative.

The following example demonstrates how a TypedLiteral representing a date is automatically converted to JavaScript's native DateTime object.

>> var literal = new TypedLiteral('2010-12-24', new IRI("http://www.w3.org/2001/XMLSchema#date"));
>> print(literal.toString());
2010-12-24
>> print(literal.value);
2010-12-24
>> print(literal.valueOf());
Fri Dec 24 2010 00:00:00 GMT+0100

2.3 Blank Nodes

A BlankNode is an RDF resource that does not have a corresponding IRI reference, as defined in [RDF-CONCEPTS]. The value of a BlankNode is not required to be the same for identical documents that are parsed at different times. The purpose of a BlankNode is to ensure that RDF Resources in the same document can be compared for equivalence by ID.

The reasoning behind how we stringify BlankNodes should be explained in more detail.

BlankNodes are stringified by concatenating "_:" to BlankNode.value

[Constructor, Stringifies]
interface BlankNode {
    readonly attribute DOMString value;
};

2.3.1 Attributes

value of type DOMString, readonly
The temporary identifier of the BlankNode. The value must not be relied upon in any way between two separate RDFa processing runs of the same document.
No exceptions.

Developers and authors must not assume that the value of a Blank Node will remain the same between two processing runs. Blank Node values are only valid for the most recent processing run on the document. Blank Nodes values will often be generated differently by different RDFa Processors.

2.3.2 Example

This section is non-normative.

The following example demonstrates the use of a BlankNode in a JavaScript implementation that uses incrementing numbers for the identifier.

>> var bna = new BlankNode();          // create a new BlankNode A
>> var bnb = new BlankNode();          // create a new BlankNode B
>> print(bna.toString());              // Stringify BlankNode A
_:1
>> print(bna.value);                   //  print value of BlankNode A
1
>> print(bnb.value);                   //  print value of BlankNode B
2

2.4 RDF Triples

The RDFTriple interface represents an RDF triple as specified in [RDF-CONCEPTS]. RDFTriple can be used by referring to properties, such as subject, predicate, and object. RDFTriple can also be used by referring to pre-defined indexes. The stringification of RDFTriple results in an N-Triples-based representation as defined in [N3].

[Constructor(in IRI subject, in IRI predicate, in IRI object),
 Constructor(in IRI subject, in IRI predicate, in PlainLiteral object),
 Constructor(in IRI subject, in IRI predicate, in TypedLiteral object),
 Constructor(in IRI subject, in IRI predicate, in BlankNode object),
 Constructor(in BlankNode subject, in IRI predicate, in IRI object),
 Constructor(in BlankNode subject, in IRI predicate, in PlainLiteral object),
 Constructor(in BlankNode subject, in IRI predicate, in TypedLiteral object),
 Constructor(in BlankNode subject, in IRI predicate, in BlankNode object),
 Stringifies, Null=Null]
interface RDFTriple {
    const unsigned char LENGTH = 3;
    const unsigned char SUBJECT_INDEX = 0;
    const unsigned char PREDICATE_INDEX = 1;
    const unsigned char OBJECT_INDEX = 2;
    readonly attribute Object subject;
    readonly attribute Object predicate;
    readonly attribute Object object;
    [IndexGetter]
    Object get (in unsigned char index);
};

2.4.1 Attributes

object of type Object, readonly
The object associated with the RDFTriple.
No exceptions.
predicate of type Object, readonly
The predicate associated with the RDFTriple.
No exceptions.
subject of type Object, readonly
The subject associated with the RDFTriple.
No exceptions.

2.4.2 Methods

get
Returns the RDFTriple property at the given index.
ParameterTypeNullableOptionalDescription
indexunsigned charA property index in the range of 0 to 2. The following index values are mapped to the following RDFTriple properties:
Index Alias Property
0 SUBJECT_INDEX subject
1 PREDICATE_INDEX predicate
2 OBJECT_INDEX object
No exceptions.
Return type: Object

2.4.3 Constants

LENGTH of type unsigned char
The maximum value of an RDF Triple index value.
OBJECT_INDEX of type unsigned char
The index value for the RDF Triple object.
PREDICATE_INDEX of type unsigned char
The index value for the RDF Triple predicate.
SUBJECT_INDEX of type unsigned char
The index value for the RDF Triple subject.

2.4.4 Example

This section is non-normative.

The following examples demonstrate the basic usage of an RDFTriple object. The creation of the triple uses the rdfa.foaf.name mapping, which translates to an IRI. The example assumes that a mapping has already been created for rdfa.foaf. For more information on creating RDFa DOM API mappings, see the section on IRI Mappings.

>> var triple = new RDFTriple(new IRI('http://www.example.com#foo'), rdfa.foaf.name, \
   new PlainLiteral('foo')]);    //create a new RDFTriple
>> print(triple.subject);        // print the property subject of the RDFTriple
http://www.example.com#foo
>> print(triple[0]);             // use the index getter to print the subject of the RDFTriple
http://www.example.com#foo
>> print(triple.toString());     // stringify the RDFTriple
<http://www.example.com#foo> <http://xmlns.com/foaf/0.1/name> "foo" .

3. The RDFa Interfaces

A number of convenience objects and methods are provided by the RDFa DOM API to help developers manipulate RDF Resources more easily when writing Web applications.

The basic RDF interface types described earlier in this document are utilized by the following RDFa Interfaces:

3.1 RDF Triple List

The RDFTripleList is an ordered sequence of RDFTriple objects. It provides a basic getter as well as an indexed getter for retrieving individual items from the list.

The RDFa Working Group is considering implementing this as a pure Array. One of the down-sides to implementing as a pure Array is implementation of the forEach method. Assuming a Web developer would like to apply a function to an array of triples, they may want to have the Array object split the incoming data to the function by the following (or equally useful) quad: (index, subject, predicate, object). Splitting into a quad is not possible in languages that don't support array destructuring, so we define forEach in such a way as to support all languages that support function pointers.

The forEach method is not properly defined in WebIDL - need to get input from the WebApps Working Group on how best to author this interface.

interface RDFTripleList {
    readonly attribute unsigned long length;
    [IndexGetter]
    Object get (in unsigned long index);
    void   forEach (in function callback);
};

3.1.1 Attributes

length of type unsigned long, readonly
An integer greater than zero that specifies the length of the list.
No exceptions.

3.1.2 Methods

forEach
Calls the given callback for each item in the RDF Triple List.
ParameterTypeNullableOptionalDescription
callbackfunctionA function that takes the following arguments: index, subject, predicate, object. The function is called for each item in the RDFTripleList.
No exceptions.
Return type: void
get
Returns the RDFTriple object at the given index in the list.
ParameterTypeNullableOptionalDescription
indexunsigned longThe index of the RDFTriple in the list to retrieve. The value must be a positive integer value greater than or equal to zero and less than RDFTripleList::length.
No exceptions.
Return type: Object

3.1.3 Example

This section is non-normative.

The following examples demonstrate the three mechanisms that are available for iterating through an RDFTripleList; index getter-based iteration, array index-based iteration, and callback-based/functional iteration.

>> var rdfTripleList = rdfa.filter();            // select all RDF triples from current Web document
>> print(rdfTripleList.length);                  // print the number of filtered RDF triples
3
>> for(var i=0; i<rdfTripleList.length; i++) {   // loop through filtered RDF triples
     print(rdfTripleList.get(i));                // print RDF triple by using the explicit get method
     print(rdfTripleList[i]);                    // print RDF triple by using the indexed property method
   }
<http://www.example.com#foo> <http://www.w3.org/2000/01/rdf-schema#label> "foo" .
<http://www.example.com#foo> <http://www.w3.org/2000/01/rdf-schema#label> "foo" .
<http://www.example.com#foo> <http://www.w3.org/2000/01/rdf-schema#label> "bar" .
<http://www.example.com#foo> <http://www.w3.org/2000/01/rdf-schema#label> "bar" .
<http://www.example.com#foo> <http://www.w3.org/2000/01/rdf-schema#label> "foobar" .
<http://www.example.com#foo> <http://www.w3.org/2000/01/rdf-schema#label> "foobar" .
>> function printObject(index, subject, predicate, object) { print(object) } // specify a callback function
>> rdfTripleList.forEach(printObject);           // call the callback function for each item in the array
foo
bar
foobar

3.2 RDF Triple Iterator

The RDFTripleIterator iterates through a DOM subtree and returns RDFTriples that match a filter function or triple pattern. A DOM Node can be specified so that only triples contained in the Node and its children will be a part of the iteration. The RDFTripleIterator is provided in order to allow implementers to provide a less memory intensive implementation for processing triples in very large documents.

interface RDFTripleIterator {
    readonly attribute Node            root;
    readonly attribute RDFTripleFilter filter;
    readonly attribute RDFTriple       triplePattern;
    RDFTriple next ();
};

3.2.1 Attributes

filter of type RDFTripleFilter, readonly
The RDFTripleFilter is a function that is provided by developers to filter RDFTriples in a subtree.
No exceptions.
root of type Node, readonly
The DOM Node that was used as the starting point for extracting RDFTriples.
No exceptions.
triplePattern of type RDFTriple, readonly
An RDF triple pattern is a set of filter parameters that can be passed to an RDFTripleFilter to match particular triple patterns.
No exceptions.

3.2.2 Methods

next
Returns the next RDFTriple object that is found in the DOM subtree or NULL if no more RDFTriples match the filtering criteria.
No parameters.
No exceptions.
Return type: RDFTriple

3.2.3 Example

This section is non-normative.

The following examples describe the how various filter patterns can be applied to the DOM via rdfa.iterate().

>> var iter = rdfa.iterate();    // iterate over all RDF triples from current Web document as an RDFTripleIterator
>> for(var triple = iter.next(); iter != null; triple = iter.next()) {      // step through all RDF triples
     print(triple);              // print current RDF triple
   }
<http://www.example.com#foo> <http://www.w3.org/2000/01/rdf-schema#label> "foo" .
<http://www.example.com#foo> <http://www.w3.org/2000/01/rdf-schema#label> "bar" .
<http://www.example.com#foo> <http://www.w3.org/2000/01/rdf-schema#label> "foobar" .
>> var iter2 = rdfa.iterate(new IRI("http://www.example.com#foo")); // iterate over triples associated with a single subject
>> var iter3 = rdfa.iterate(null, rdfa.foaf.name); // iterate over all triples that contain a foaf:name predicate

3.3 RDF Projection

The RDFProjection interface provides a projection of all RDF triples in a document about a single subject. The RDFProjection aggregates these RDF triples as a single language-native object in order to provide a more natural programming primitive for developers.

interface RDFProjection {
    readonly attribute IRI           subject;
    readonly attribute Sequence[IRI] properties;
    [NameGetter]
    Sequence[any] get (in DOMString name);
};

3.3.1 Attributes

properties of type Sequence[IRI], readonly
A sequence of predicate IRIs for all aggregated RDF triples in this projection.
No exceptions.
subject of type IRI, readonly
The IRI of the subject that all RDF triples in the object share.
No exceptions.

3.3.2 Methods

get
Returns the a sequence of IRIs, BlankNodes, PlainLiterals, and/or TypedLiterals that have a stringified IRI that is equivalent to name.
ParameterTypeNullableOptionalDescription
nameDOMStringA stringified IRI representing a predicate whose values are to be retrieved from the RDFProjection. For example, using a name value of "http://xmlns.com/foaf/0.1/name" will return a sequence of values that represent FOAF names in the RDFProjection.
No exceptions.
Return type: Sequence[any]

3.3.3 Example

This section is non-normative.

The following examples demonstrate how to use the RDFaProjection interface.

>> var subject = new IRI("http://www.ivan-herman.net/foaf#me");    // create IRI for subject
>> var projection = rdfa.projection(subject);                      // extract information about this subject as an RDFProjection
>> print(projection.subject);                                      // print the subject of this RDFProjection
http://www.ivan-herman.net/foaf#me
>> print(projection.properties);                                   // print all projected property names
http://xmlns.com/foaf/0.1/name, 
http://xmlns.com/foaf/0.1/title, 
http://xmlns.com/foaf/0.1/surname, 
http://xmlns.com/foaf/0.1/givenname, 
http://xmlns.com/foaf/0.1/workInfoHomepage
>> projection[rdfa.foaf.name]                                      // named property values of foaf:name
["Herman Iván", "Ivan Herman"]
>> projection[rdfa.foaf.title]                                     // named property values of foaf:title
["Dr."]
>> projection[rdfa.foaf.workInfoHomepage]                          // named property values of foaf:workInfoHomepage
["http://www.iswsa.org/", "http://www.iw3c2.org", "http://www.w3.org/2001/sw/#activity"]

4. The RDFa API

The RDFa DOM API is designed to provide a small, powerful set of interfaces that a developer may use to retrieve RDF triples from a Web document. The core interfaces were described in the previous two sections. This section focuses on the final RDFa API that most developers will utilize to generate the objects that are described in the RDF Interfaces and RDFa Interfaces sections. The following high-level API is provided by this specification:

interface rdfa {
    const DOMString VERSION = "1.1";
};

4.1 Constants

VERSION of type DOMString
The latest supported version of the RDFa DOM API

4.2 Convenient IRI Mapping

Processing RDF data involves the frequent use of unwieldy IRI references (e.g., http://dbpedia.org/resource/RDFa), vocabulary properties (e.g., http://www.w3.org/1999/02/22-rdf-syntax-ns#type) and vocabulary classes (e.g., http://xmlns.com/foaf/0.1/Person). In order to reduce the amount of source code that a developer must write, a convenient IRI mapping interface is provided. A developer may initialize the rdfa interface with a number of IRI mappings to ease the implementation burden. Ideally, one would use a mnemonic like rdfa.xsd.integer instead of being required to specify the full IRI: http://www.w3.org/2000/01/rdf-schema#integer. The following interface allows IRI mappings to be easily created at run-time:

interface rdfa {
    [NameGetter]
    any  get (in DOMString prefix);
    [NameSetter, NameCreator]
    void set (in DOMString prefix);
    void setMapping (in DOMString prefix, in DOMString reference, in DOMString iri);
};

4.2.1 Methods

get
Returns the map for the property named prefix. The prefix is the abbreviation of an existing namespace (e.g., foaf). The returned map contains reference-to-IRI mappings. These mappings are created by calling rdfa.setMapping(prefix, reference, IRI). Thus, specifying rdfa.foaf.Person in JavaScript would return the following: IRI("http://xmlns.com/foaf/0.1/Person").
ParameterTypeNullableOptionalDescription
prefixDOMStringThe prefix value that identifies the map that contains reference to IRI mappings created by rdfa.setMapping(prefix, reference, IRI).
No exceptions.
Return type: any
set
Creates or sets the value for a named property as specified by prefix. The prefix is an abbreviation of an existing namespace (e.g., foaf). The value Object is an associative array containing reference-to-IRI mappings.
ParameterTypeNullableOptionalDescription
prefixDOMStringThe prefix value that identifies the map that contains the reference-to-IRI mappings.
No exceptions.
Return type: void
setMapping
Registers a mapping from a prefix and reference to an IRI Reference. For example, if a developer wants to specify the rdfa.foaf.Person IRI mapping, they would call setMapping("foaf", "Person", "http://xmlns.com/foaf/0.1/Person"). Calling the setMapping() method with a prefix value that does not exist results in the creation of a new mapping.
ParameterTypeNullableOptionalDescription
prefixDOMString
referenceDOMString
iriDOMString
No exceptions.
Return type: void

Convenience IRI mappings for all terms in the following vocabularies must be included: rdf and xsd.

4.2.2 Example

This section is non-normative.

The following examples demonstrate how mappings are created and used via the RDFa DOM API.

>> var iri = new IRI("http://www.example.com")        // create a new IRI
>> print(iri.toString());                             // Stringify this IRI
http://www.example.com
>> print(iri.value);                                  // print property value of this IRI
http://www.example.com
>> rdfa.setMapping("foaf", "Person", "http://xmlns.com/foaf/0.1/Person");   // create new IRI mapping
>> rdfa.setMapping("foaf", "name", "http://xmlns.com/foaf/0.1/name");       // create new IRI mapping
>> rdfa.foaf.Person instanceof IRI      // Mappings return IRIs
true
>> print(rdfa.foaf.Person);             // get IRI value of foaf:Person
http://xmlns.com/foaf/0.1/Person
>> print(rdfa.foaf.name);               // get IRI value of foaf:name
http://xmlns.com/foaf/0.1/name
>> print(rdfa.foaf["Person"]);          // use bracket syntax to get IRI value of foaf:Person
http://xmlns.com/foaf/0.1/Person
>> print(rdfa.foaf["name"]);            // use bracket syntax to get IRI value of foaf:name
http://xmlns.com/foaf/0.1/name
>> rdfa.foaf = {"knows" : new IRI("http://xmlns.com/foaf/0.1/knows")};     // create new IRI mapping by setting a named property
>> print(rdfa.foaf.knows);              // get IRI value for foaf:knows
http://xmlns.com/foaf/0.1/knows

4.3 Automatic Type Conversion

TypedLiteralConverter is a callable interface that transforms the value of a TypedLiteral into a native language type in the current programming language. The type IRI of the TypedLiteral is used to determine the best mapping to the native language type.

4.3.1 Specifing Typed Literal Converters

[Callback]
interface TypedLiteralConverter {
    Any convertType (in DOMString value);
};
Methods
convertType
Returns the native language value of the passed literal value as certain type.
ParameterTypeNullableOptionalDescription
valueDOMStringThe value of the TypedRDFLiteral.
No exceptions.
Return type: Any

4.3.2 Registering Typed Literal Converters

interface rdfa {
    void registerTypeConversion (in IRI type, in TypedLiteralConverter converter);
};
Methods
registerTypeConversion
Registers a type converter from given IRI datatype to a native language dataype in the current programming language.
ParameterTypeNullableOptionalDescription
typeIRIAn IRI reference to the datatype of the TypedLiteral.
converterTypedLiteralConverterA function that converts the TypedLiteral's value into a native language datatype in the current programming language.
No exceptions.
Return type: void

4.3.3 Example

This section is non-normative.

The following example demonstrates how a developer could register and use a TypedLiteralConverter.

>> rdfa.registerTypeConversion(rdfa.xsd.boolean, function(value) {return new Boolean(value);});
>> var literal = new TypedLiteral('1', rdfa.xsd.boolean);
>> print(literal.toString());
1
>> print(literal.value);
1
>> print(literal.valueOf());
true

4.4 Pattern Filters

An important goal of the RDFa DOM API is to help Web developers filter the set of RDF triples in a document down to only the ones that interest them. This section covers pattern-based filters. Pattern filters trigger off of one or more of the subject, predicate, or object properties in RDF triples. This section also introduces the interfaces for the other filter types.

4.4.1 Filter Methods

interface rdfa {
    [Null=Null]
    RDFTripleList     filter ([Variadic] in Object? subject, in IRI? predicate, in Object? object, in Node? element, in RDFTripleFilter? filter);
    [Null=Null]
    RDFTripleIterator iterate ([Variadic] in Object? subject, in IRI? predicate, in Object? object, in Node? element, in RDFTripleFilter? filter);
    RDFProjection     project (in Object subject);
};
Methods
filter
Returns an RDFTripleList, which consists of zero or more RDFTriple objects.
ParameterTypeNullableOptionalDescription
subjectObjectThe subject filter pattern which is used to filter RDFTriple objects. Values can be of type IRI, BlankNode, or Null. If the subject is a non-Null value, the RDFTriple must not be placed in the final output RDFTripleList unless the given subject matches the RDFTriple's subject. If subject is set to Null, the filter must not reject any triple based on the subject.
predicateIRIThe predicate filter pattern which is used to filter RDFTriple objects. Values can be of type IRI or Null. If the predicate is a non-Null value, the RDFTriple must not be placed in the final output RDFTripleList unless the given predicate matches the RDFTriple's predicate. If predicate is set to Null, the filter must not reject any triple based on the predicate.
objectObjectThe object filter pattern which is used to filter RDFTriple objects. Values can be of type IRI, TypedLiteral, PlainLiteral, BlankNode, or Null. If the object is a non-Null value, the RDFTriple must not be placed in the final output RDFTripleList unless the given object matches the RDFTriple's object. If object is set to Null, the filter must not reject any triple based on object.
elementNodeThe parent DOM Node where filtering should start. The implementation must only consider RDF triples on the current DOM Node and its children.
filterRDFTripleFilterA user defined function, returning a true or false value, that determines whether or not an RDFTriple should be added to the final RDFTripleList.
No exceptions.
Return type: RDFTripleList
iterate
Returns an RDFTripleIterator, which is capable of iterating through a set of RDF triples, one RDFTriple at a time. The RDFTripleIterator is most useful in small memory footprint environments, or in documents that contain a very large number of triples.
ParameterTypeNullableOptionalDescription
subjectObjectThe subject filter pattern which is used to filter RDFTriple objects. Values can be of type IRI, BlankNode, or Null. If the subject is a non-Null value, the RDFTriple must not be output via the RDFTripleIterator unless the given subject matches the RDFTriple's subject. If subject is set to Null, the filter must not reject any triple based on the subject.
predicateIRIThe predicate filter pattern which is used to filter RDFTriple objects. Values can be of type IRI or Null. If the predicate is a non-Null value, the RDFTriple must not be output via the RDFTripleIterator unless the given predicate matches the RDFTriple's predicate. If predicate is set to Null, the filter must not reject any triple based on the predicate.
objectObjectThe object filter pattern which is used to filter RDFTriple objects. Values can be of type IRI, TypedLiteral, PlainLiteral, BlankNode, or Null. If the object is a non-Null value, the RDFTriple must not be output via the RDFTripleIterator unless the given object matches the RDFTriple's object. If object is set to Null, the filter must not reject any triple based on object.
elementNodeThe parent DOM Node where filtering should start. The implementation must only consider RDF triples on the current DOM Node and its children.
filterRDFTripleFilterA user defined function, returning a true or false value, that determines whether or not an RDFTriple should be output via the RDFTripleIterator.
No exceptions.
Return type: RDFTripleIterator
project
This method creates a convenience object that aggregates all RDFTriples that share the same subject. Predicate-object pairs of RDF triples are projected on to named properties in a language native Object.
ParameterTypeNullableOptionalDescription
subjectObjectThe subject of the projection, which can be a Blank Node or an IRI, will be used to generate the language native Object.
No exceptions.
Return type: RDFProjection

4.4.2 Function Filters

Filter criteria may also be defined by the developer as a filter function. The RDFTripleFilter is a callable function that determines whether an RDFTriple should be included in the set of output triples.

[Callback, Null=Null]
interface RDFTripleFilter {
    boolean match ([Variadic] in Node? element, in IRI? predicate, in Object? object);
};
Methods
match
A callable function that returns true if the input RDFTriple should be included in the output set, or false if the input RDFTriple should be rejected from the output set.
ParameterTypeNullableOptionalDescription
elementNodeThe DOM Node where filtering should start.
predicateIRIThe predicate, which can be used to accept or reject the RDFTriple. Values can be of type IRI or Null.
objectObjectThe object, which can be used to accept or reject the RDFTriple. Values can be of type IRI, TypedLiteral, PlainLiteral, BlankNode, or Null.
No exceptions.
Return type: boolean

4.4.3 Example

This section is non-normative.

The examples below use the following HTML code:

<div id="start" about="http://dbpedia.org/resource/Albert_Einstein">

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

  <span property="dbp:dateOfBirth" datatype="xsd:date">1879-03-14</span>
  <div rel="dbp:birthPlace" resource="http://dbpedia.org/resource/Germany">
    <span class="hilite"><span property="dbp:conventionalLongName">Federal Republic of Germany</span></span>
  </div>
</div>

The following examples demonstrate the use of rdfa.filter() and rdfa.iterate() in JavaScript.

>> var myFilter = new function(element, subject, predicate, object) {         // create a filter function that filters 
     if(subject.value.search(/http:\/\/xmlns.com\/foaf\/0\.1/) >= 0) {        // triples with predicates in the foaf namespace.
         return true;	
	   } 
   }
   
// start filtering at element with id=start
>> var tripleList = rdfa.filter(null, null, null, document.getElementById("start"), myFilter);
>> for(var i=0; i < tripleList.length; i++) {
      print(tripleList[i])
   }
<http://dbpedia.org/resource/Albert_Einstein> <http://xmlns.com/foaf/0.1/name> "Albert Einstein"


// start filtering by iterating at element with id=start
>> var iter = rdfa.iterate(null, null, null, document.getElementById("start"), myFilter);          
>> for(var triple=iter.next(); triple != null; triple = iter.next()) {
      print(triple)
   }
<http://dbpedia.org/resource/Albert_Einstein> <http://xmlns.com/foaf/0.1/name> "Albert Einstein"

The following example demonstrates how a developer may use the rdfa.project() API call to extract information from a document:

>> var einstein = rdfa.project(new IRI("http://dbpedia.org/resource/Albert_Einstein"));
>> einstein.properties
["http://xmlns.com/foaf/0.1/name", "http://dbpedia.org/property/dateOfBirth", 
 "http://dbpedia.org/property/birthPlace", "http://dbpedia.org/property/conventionalLongName"]
>> print(einstein[rdfa.dbp.dateOfBirth]);
1879-03-14
>> print(einstein[rdfa.dbp.birthPlace]);
http://dbpedia.org/resource/Germany

4.5 DOM Node Filters

In addition to filtering RDFTriple objects based on triple patterns, the RDFa DOM API also provides a mechanism to filter DOM Nodes that contain certain triple patterns.

interface rdfa {
    NodeList getElements ([Variadic] in Object? subject, in IRI? predicate, in Object? object, in Node? element, in RDFTripleFilter? filter);
    boolean  containsRDFa (in Node? element, [Variadic] in Object? subject, in IRI? predicate, in Object? object, in RDFTripleFilter? filter);
};

4.5.1 Methods

containsRDFa
Tests a node and its descendants to see if it contains RDFa matching any of the provided filters.
ParameterTypeNullableOptionalDescription
elementNodeThe parent DOM Node where testing should start. Only RDF triples on the given DOM Node and its children are considered.
subjectObjectThe subject filter pattern which is used to detect RDFTriple objects. Values can be of type IRI, BlankNode, or Null. If the subject is a non-Null value, the RDFTriple must not be a match unless the given subject matches the RDFTriple's subject. If subject is set to Null, any RDFTriple must result in a match.
predicateIRIThe predicate filter pattern which is used to detect RDFTriple objects. Values can be of type IRI or Null. If the predicate is a non-Null value, the RDFTriple must not be a match unless the given predicate matches the RDFTriple's predicate. If predicate is set to Null, any RDFTriple must result in a match.
objectObjectThe object filter pattern which is used to detect RDFTriple objects. Values can be of type IRI, TypedLiteral, PlainLiteral, BlankNode, or Null. If the object is a non-Null value, the RDFTriple must not be a match unless the given object matches the RDFTriple's object. If object is set to Null, any RDFTriple must result in a match.
filterRDFTripleFilterA user defined function, returning a true or false value, that determines whether or not an RDFTriple should be considered a match.
No exceptions.
Return type: boolean
getElements
Return a NodeList of DOM nodes that are filtered by their RDFa content.
ParameterTypeNullableOptionalDescription
subjectObjectThe subject filter pattern which is used to filter DOM Nodes. Values can be of type IRI, BlankNode, or Null. If the subject is a non-Null value, the DOM Node must not be placed in the final output NodeList unless the given subject matches the RDFTriple's subject. If subject is set to Null, the filter must not reject any triple based on the subject.
predicateIRIThe predicate filter pattern which is used to filter DOM Nodes. Values can be of type IRI or Null. If the predicate is a non-Null value, the DOM Node must not be placed in the final output NodeList unless the given predicate matches the RDFTriple's predicate. If predicate is set to Null, the filter must not reject any triple based on the predicate.
objectObjectThe object filter pattern which is used to filter DOM Nodes. Values can be of type IRI, TypedLiteral, PlainLiteral, BlankNode, or Null. If the object is a non-Null value, the DOM Node must not be placed in the final output NodeList unless the given object matches the RDFTriple's object. If object is set to Null, the filter must not reject any triple based on object.
elementNodeThe parent DOM Node where filtering should start. The implementation must only consider RDF triples on the current DOM Node and its children.
filterRDFTripleFilterA user defined function, returning a true or false value, that determines whether or not a DOM Node should be added to the final NodeList.
No exceptions.
Return type: NodeList

4.5.2 Example

This section is non-normative.

The examples below refer to the following HTML code:

<div id="start" about="http://dbpedia.org/resource/Albert_Einstein">

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

  <span property="dbp:dateOfBirth" datatype="xsd:date">1879-03-14</span>
  <div rel="dbp:birthPlace" resource="http://dbpedia.org/resource/Germany">
    <span class="hilite"><span property="dbp:conventionalLongName">Federal Republic of Germany</span></span>
  </div>
</div>

The following examples demonstrate the usage of rdfa.containsRDFa() and rdfa.getElements() in JavaScript:

>> var germany = new IRI("http://dbpedia.org/resource/Germany")
>> print(rdfa.containsRDFa(document.getElementById("start"), null, null, germany)));  // lookup if html contains RDFa about Germany
true
>> var myFilter = new function(element, subject, predicate, object) {         // create a filter function that filter 
     if(subject.value.search(/http:\/\/xmlns.com\/foaf\/0\.1/) >= 0) {        // for triples with predicates in the foaf namespace.
         return true;	
	   } 
   }
>> var nodelist = rdfa.getElements(null, null, null, myFilter);       // filter DOM elements for foaf statements 
>> print(nodelist.length); 
1

5. Future Discussion

This section is non-normative.

The current version of the RDFa DOM API focuses on filtering RDF triples. It also provides methods for filtering DOM Nodes that contain certain types of RDF triples.

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

A. Acknowledgements

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

B. IDL Definitions

This section is non-normative.

This document contains the Web IDL definitions of the RDFa DOM API: rdfa_dom_api.idl

C. JavaScript Conversion

This section is non-normative.

This document contains the JavaScript Conversion of the RDFa DOM API:rdfa_dom_api.js

The API documentation of the JavaScript Conversion is provided here: JSDoc API

D. References

D.1 Normative references

[BCP47]
A. Phillips, M. Davis. Tags for Identifying Languages September 2009. IETF Best Current Practice. URL: http://tools.ietf.org/rfc/bcp/bcp47.txt
[HTML-RDFA]
Manu Sporny; et al. HTML+RDFa 04 March 2010. W3C Working Draft. URL: http://www.w3.org/TR/rdfa-in-html/
[IRI]
M. Duerst, M. Suignard. Internationalized Resource Identifiers (IRI). January 2005. Internet RFC 3987. URL: http://www.ietf.org/rfc/rfc3987.txt
[N3]
Tim Berners-Lee; Dan Connolly. Notation3 (N3): A readable RDF syntax. 14 January 2008. W3C Team Submission. URL: http://www.w3.org/TeamSubmission/2008/SUBM-n3-20080114/
[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-CORE]
Shane McCarron; et al. RDFa Core 1.1: Syntax and processing rules for embedding RDF through attributes.22 April 2010. W3C Working Draft. URL: http://www.w3.org/TR/2010/WD-rdfa-core-20100422
[XHTML-RDFA]
Shane McCarron; et. al. XHTML+RDFa 1.1. 22 April 2010. W3C Working Draft. URL: http://www.w3.org/TR/xhtml-rdfa

D.2 Informative references

[ECMA-262]
ECMAScript Language Specification, Third Edition. December 1999. URL: http://www.ecma-international.org/publications/standards/Ecma-262.htm
[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/
[WEBIDL]
Cameron McCormack. Web IDL. 19 December 2008. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2008/WD-WebIDL-20081219