The RDFa DOM API

Abstract

A document with RDFa data allow readers to extract semantics or at least structured information about from its content. The extraction of RDFa data bases on RDFa parsers. These parsers return RDFa data either in RDF-like [RDF-PRIMER] or more object-oriented structures. An important use case of RDFa is adding semantics to HTML or XHTML web pages. Browsers that render these documents provide users and developers with basic tool support to read the text content or process it in other ways. A problematic issue with existing RDFa parsers is the tedious integration into current browsers. Language incompatibilities of supported ECMA [ECMA-262] Versions and especially the implementations of ECMA are one reason amongst others.

This document defines an Application Programming Interface (API) for processing RDFa [RDFA-SYNTAX] data on the supposition that RDFa is part of an Document Object Model (DOM) [DOM-LEVEL-3-CORE]. RDFa data inside documents written in languages that are based on a DOM (e.g., SVG [SVGTINY12], XHTML [XHTML-RDFA], or HTML [[HTML+RDFA]]) can be extracted and retrieved by using this RDFa DOM API. The RDFa DOM API is intended to be implemented as browser extension or other forms of software libraries. The specification of the RDFa DOM API provides a uniform programming API for processing RDFa content across different versions and types of browser or other types of document processors.

RDFa is a serialization format of the Resource Description Framework (RDF) [RDF-SYNTAX]. The RDFa DOM API provides methods to extract RDF triples from RDFa content. The RDFa DOM API also provides methods to retrieve document parts that contain certain RDF triples.

This document is a detailed interface specification for an RDFa DOM API, aimed at:

those looking to create an RDFa Processor for extracting or visualizing RDFa content in documents,
those looking to extract RDF Linked Data data from web pages,

For those looking for an introduction to the use of RDFa and some real-world examples, please consult the RDFa Primer.

How to Read this Document

This section is non-normative.

First, if you are not familiar with either RDFa or RDF, but want to process RDFa in your documents, then it is recommended to look at the RDFa Primer [RDFA-PRIMER] as short introduction. However, the RDFa DOM API is designed to be used without deep knowledge about RDFa.

If you are already familiar with RDFa, and you want to process RDFa content in documents then you'll find the RDFa DOM API section of most interest. It contains a couple of example Javascript code for each part of the RDFa DOM API.

If you are not familiar with RDFa, but you are familiar with RDF, this document should contains no unknown concepts for you.

If you are not familiar with RDF, then you might want to take a look at the section on RDF Terminology of the RDFa CORE [RDFA-CORE] as short introduction. Although the RDFa DOM API is designed to be easy to develop with — and authors don't need to understand RDFa to use it — anyone consume RDFa content in documents should have at least a basic understanding of RDF.

The specification of the RDFa DOM API is written in the Web Interface Definition Language. If you intend to implement the RDFa DOM API you should hava a look at the Web IDL language [WEBIDL] to understand specifications about interfaces of the RDFa DOM API.

Examples may contain references to existing vocabularies and use abbreviations to refer to these. Such vocabularies and their abbreviations are:

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

The RDFa DOM API uses RDF as underlying data model [RDF-CONCEPTS]. Therefore, it provides interface definitions for programming with these RDF Resources: Typed Literals, Plain Literals, URI References and Blank nodes. You may want to take a look at the section on RDF Terminology of the RDFa CORE [RDFA-CORE] as short introduction about these basic types. Typed Literals, Plain Literals, URI References and Blank nodes are the components to work with RDFTriples in the RDFa DOM API.

2. The RDF Data Model

The working group has not reached consensus whether or not the traditional RDF model should be used to express the items returned by the RDFa DOM API, or if a simpler object representation format, such as a Javascript associative Array would be more appropriate for processing RDF data in Javascript. To compromise, in addition to standard RDF resources the interface RDFaObject was created.

In general, RDFa is a special syntax for expressing RDF triple and RDF graphs in documents. For this reason the RDFa DOM API uses RDF as basic data model and provides interface to extract RDF data from RDFa content and process it afterwards.

The basic RDF resource types of the RDFa DOM API are:

Plain RDF Literal — A typed string value with optional information about the language of its content. (e.g., "Harry Potter and the Half-Blood Prince"@en is a plain literal with an English text value. The literal value is specified in the Terse RDF Triple Language (TURTLE) [TURTLE] )
Typed RDF Literal — A typed string value with information about the datatype of its content. (e.g., "Harry Potter and the Half-Blood Prince"^^xsd:string is a typed literal with a value of type xsd:string. The literal value is also specified in TURTLE)
URI Reference — A type interface for processing absolute URI values [URI]. (e.g., <http://www.w3.org/2001/XMLSchema#string>, the URI value is specified in TURTLE )
Blank Node — A type interface for processing blank nodes. (e.g., _:me, _:42, the Blank Nodes' values are specified in TURTLE)

The RDFa DOM API leaves it open to developers to re-arrange these RDF resource types in further hierarchical structures.

RDF resources are the components of:

RDF Triple — Triples are the fundamental data model behind RDF. An RDF triple form statements in form of the RDF Resources: subject, predicate, and object. (e.g., an RDF triple in TURTLE syntax: _:123 rdfs:label "Harry Potter" .)
RDFa Object — An RDFaObject is a compound object that summarizes all statements about a single subject. Predicates of RDF triples about this subjects are concerned to be the attributes of an RDFaObject.

2.1 RDF Literals

An RDF Literal is an RDF Resource that represents lexical values in RDFa data. The RDF Literals used in the RDFa DOM API (i.e., PlainLiteral, TypedLiteral) behave like they are defined in RDF [RDF-CONCEPTS]. You may want to have a look into the the definition of literals in an RDF graph.

The RDFa DOM API separates between PlainLiteral and TypedLiteral. According to the RDF specification, for a given RDF Literal, either language or type information can be given. If the type is set, the RDF Literal conforms to the RDF specification of Typed Literal in [RDF-CONCEPTS]. Otherwise it conforms to be a Plain Literal.

PlainLiteral: RDF Literals with attached language information about the given text given in form of a language tag (e.g., 'en', 'fr', 'de').
TypedLiteral: RDF Literals with attached type information about the given text given in form of an URI reference (e.g., xsd:DateTime).

2.1.1 Plain Literals

PlainLiterals have a String value and optionally a language tag as defined in [RDF-CONCEPTS], normalized to lowercase.

[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;
};

2.1.1.1 Attributes

element of type Node, readonly: A node of the DOM tree. This PlainLiteral is contained as RDFa content in exactly this DOM node.
No exceptions.
language of type DOMString, readonly: A two characters long language tag as defined in [RDF-CONCEPTS], normalized to lowercase. If language is set, then the value of type is a URI with value rdf:Literal
No exceptions.
value of type DOMString, readonly: The lexical value of this literal encoded in the character encoding of the source document.
No exceptions.

2.1.1.2 Example

This section is non-normative.

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

Example use of PlainLiteral in Javascript

2.1.2 Typed Literals

A TypedLiteral has a String value and a datatype URI being an RDF URI reference. TypedLiterals can be converted into native language datatypes of the implementing programming language(please refer to Type conversion of Typed Literals for more information).

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

The RDFa DOM API provides a method to explicitly convert TypedRDFLiteral values to native datatypes of the implementing programming language. Developers may write their own TypedLiteralConverters in order to convert an RDFLiteral into a prefered language type. The converters are registered by using the registerTypeConversion() method of the RDFa DOM API. As default standard converters for the following XML Scheme datatypes are provided if a corresponding datatype exists the current programming language:

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 URI type), Constructor(in DOMString value, in URI type, in Node element), Stringifies=value]
interface TypedLiteral {

    readonly attribute DOMString value;
    readonly attribute URI       type;
    readonly attribute Node      element;

    Any valueOf ();
};

2.1.2.1 Attributes

element of type Node, readonly: A node of the DOM tree. This TypedLiteral is contained as RDFa content in exactly this DOM node.
No exceptions.
type of type URI, readonly: A datatype identified by an URI reference
No exceptions.
value of type DOMString, readonly: The lexical value of this literal encoded in the character encoding of the source document.
No exceptions.

2.1.2.2 Methods

valueOf: Returns a typed representation of this literal that follows a given type conversion from a URI reference of a datatype to datatypes of the current programming language.
No parameters.
No exceptions.
Return type: Any

2.1.2.3 Example

This section is non-normative.

>> var literal = new TypedLiteral('2010-12-24', new URI("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

Example use of TypedLiteral in Javascript

2.1.3 TypedLiteralConverter

This callable interface provides a function that concerts the value of a TypedLiteral into a corresponding type of the current programming language.

Specify TypedLiteralConverters

[Callback]
interface TypedLiteralConverter {

    Any convertType (in DOMString value);
};

2.1.3.1 Methods

convertType

Returns the value of the passed literal value as certain type.

Parameter	Type	Nullable	Optional	Description
value	`DOMString`	✘	✘	The value of the TypedRDFLiteral.

No exceptions.

Return type: Any

2.1.3.2 Register TypedLiteralConverters

interface rdfa {
    void registerTypeConversion (in URI type, in TypedLiteralConverter converter);

};

2.1.3.2.1 Methods

registerTypeConversion

Registers a new type conversion from an RDFS datatype to a dataype of the current programming language.

Parameter	Type	Nullable	Optional	Description
type	`URI`	✘	✘	An URI reference of the datatype type of the current TypedLiteral
converter	`TypedLiteralConverter`	✘	✘	A function that converts the literal's value into the correct type of the current programming language.

No exceptions.

Return type: void

2.1.3.3 Example

This section is non-normative.

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

Example use of TypedLiteralConverters in Javascript

2.2 URI Reference

A URI in the RDFa DOM API is a RDF URI reference as specified in RDF Concepts and Abstract Syntax [RDF-CONCEPTS].

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

};

2.2.1 Attributes

element of type Node, readonly: A node of the DOM tree. This URI is contained as RDFa content in exactly this DOM node.
No exceptions.
value of type DOMString, readonly: The lexical representation of the URI reference.
No exceptions.

2.2.2 URI Mapping

Processing RDF data involve a frequent use of URI references to single instances (e.g., http://dbpedia.org/resource/RDFa) , vocabulary properties (e.g., rdf:type) or classes (e.g., foaf:Person). For this reason the RDFa DOM API provides a method to make handling of commonly used URIs more convenient. The following vocabularies should be implemented as default in an implementaion of the RDFa DOM API: RDF and XSD.

interface rdfa {
    [NameGetter]
    any  get (in DOMString prefix);

    [NameSetter, NameCreator]
    void set (in DOMString prefix);
    void setMapping (in DOMString prefix, in DOMString value, in URI uri);

};

2.2.2.1 Methods

get

Returns the value of a named property called prefix. This prefix is the abbreviation of an existing namespace (e.g., let foaf map to http://xmlns.com/foaf/0.1/). The returned object is a map that contains named properties for each existing value created by calling rdfa:setMapping(prefix, value, uri). (e.g., the value name of a prefix foaf that maps to http://xmlns.com/foaf/0.1/name)

Parameter	Type	Nullable	Optional	Description
prefix	`DOMString`	✘	✘	The prefix value that identifies a maps that contains named properties for each existing value created by calling `rdfa:setMapping(prefix, value, uri)`. (e.g., let `foaf` be the name of a map of URIs in the namespace of `http://xmlns.com/foaf/0.1/`. (e.g., with a named property `Person` of value `http://xmlns.com/foaf/0.1/Person`)

No exceptions.

Return type: any

set

Creates the value of a named property called prefix. This prefix is the abbreviation of an existing namespace (e.g., let foaf map to http://xmlns.com/foaf/0.1/). The passed Object value is an object that also allows creationof named properties.)

Parameter	Type	Nullable	Optional	Description
prefix	`DOMString`	✘	✘	The prefix value that identifies a maps that contains named properties for each existing value created by calling `rdfa:setMapping(prefix, value, uri)`. (e.g., let `foaf` be the name of a map of URIs in the namespace of `http://xmlns.com/foaf/0.1/`. (e.g., with a named property `Person` of value `http://xmlns.com/foaf/0.1/Person`)

No exceptions.

Return type: void

setMapping

Registers a mapping from a prefix and value token to a URI Reference (e.g, let rdfa.foaf.Person map to a URI with value http://xmlns.com/foaf/0.1/Person). Calling setMapping with a prefix value that does not exist as named property results in the creation of such a property with the value of prefix as name. The value of this property is an object with a property whose name equals the DOMString passed with value. The value of this property is the URI passed with uri.

Parameter	Type	Nullable	Optional	Description
prefix	`DOMString`	✘	✘	The prefix that abbreviates the namespace of `uri` (e.g., `foaf` abbreviates `http://xmlns.com/foaf/0.1/` in URI `http://xmlns.com/foaf/0.1/Person`)
value	`DOMString`	✘	✘	The value of the URI. (e.g., `Person` in `http://xmlns.com/foaf/0.1/Person`)
uri	`URI`	✘	✘	The complete URI reference.

No exceptions.

Return type: void

2.2.3 Example

This section is non-normative.

>> var uri = new URI("http://www.example.com")        // create a new URI
>> print(uri.toString());                             // Stringify this URI
http://www.example.com
>> print(uri.value);                                  // print property value of this URI
http://www.example.com
>> rdfa.setMapping("foaf", "Person", new URI("http://xmlns.com/foaf/0.1/Person"));   // create new URI mapping
>> rdfa.setMapping("foaf", "name", new URI("http://xmlns.com/foaf/0.1/name"));       // create new URI mapping

>> print(rdfa.foaf.Person);             // get URI value of foaf:Person as named property of rdfa
http://xmlns.com/foaf/0.1/Person
>> print(rdfa.foaf.name);               // get URI value of foaf:name as named property of rdfa
http://xmlns.com/foaf/0.1/name
>> print(rdfa.foaf["Person"]);          // use bracket syntax to get URI value of foaf:Person as named property of rdfa
http://xmlns.com/foaf/0.1/Person
>> print(rdfa.foaf["name"]);            // use bracket syntax to get URI value of foaf:name as named property of rdfa
http://xmlns.com/foaf/0.1/name
>> rdfa.foaf = {"knows" : new URI("http://xmlns.com/foaf/0.1/knows")};     // create new URI mapping by setting a named property

Example use of URI in Javascript

2.3 BlankNode

A BlankNode is an anonymous RDF resource as defined in [RDF-CONCEPTS]. The RDFa DOM API makes no reference to any internal structure of blank nodes. Therefore, it is not necessary that serialized Blank Nodes in RDFa preserve the same value in an implementation of the RDFa DOM API. It has just to be assured to test if two BlankNodes are the same or not.

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

2.3.1 Attributes

value of type DOMString, readonly: The identifier of the BlankNode
No exceptions.

2.3.2 Example

This section is non-normative.

>> var bn = new BlankNode();          // create a new BlankNode
>> print(bn.toString());              // Stringify this BlankNode
_:42
>> print(bn.value);                   //  print property value of this BlankNode
42

Example use of a BlankNode in a Javascript implementation that uses running numbers as representation.

2.4 RDFTriple

In the RDFa DOM API, RDFTriple defines the data structure to represent an RDF triples as specified in [RDF-CONCEPTS]. RDFTriple exposes its properties subject, predicate object either in form of names and in form of indexes. The stringification of RDFTriple results in an N-Triples-based or Turtle-based serialization [TURTLE] of the represented RDF triple.

[Constructor(in URI subject,in URI predicate,in URI object),
 Constructor(in URI subject, in URI predicate, in PlainLiteral object),
 Constructor(in URI subject, in URI predicate, in TypedLiteral object),
 Constructor(in URI subject, in URI predicate, in BlankNode object),
 Constructor(in BlankNode subject, in URI predicate, in URI object),
 Constructor(in BlankNode subject, in URI predicate, in PlainLiteral object),
 Constructor(in BlankNode subject, in URI predicate, in TypedLiteral object),
 Constructor(in BlankNode subject, in URI predicate, in BlankNode object),
 Stringifies, Null=Null]
interface RDFTriple {

    const unsigned short LENGTH = 3;
    const unsigned short SUBJECT_INDEX = 0;

    const unsigned short PREDICATE_INDEX = 1;
    const unsigned short OBJECT_INDEX = 2;

    readonly attribute Object subject;
    readonly attribute Object predicate;
    readonly attribute Object object;

    [IndexGetter]
    Object getByIndex (in unsigned long index);
};

2.4.1 Attributes

object of type Object, readonly: Object value of an RDFTriple.
No exceptions.
predicate of type Object, readonly: Predicate value of an RDFTriple.
No exceptions.
subject of type Object, readonly: Subject value of an RDFTriple.
No exceptions.

2.4.2 Methods

getByIndex

Returns the RDFTriple object inside this list at position index.

Parameter Type Nullable Optional Description

index

unsigned long

✘

An index position with a positive integer value less than three. Index values are mapped to properties:

Index	Property
0	subject
1	predicate
2	object

No exceptions.

Return type: Object

2.4.3 Constants

LENGTH of type unsigned short
OBJECT_INDEX of type unsigned short
PREDICATE_INDEX of type unsigned short
SUBJECT_INDEX of type unsigned short

2.4.4 Example

This section is non-normative.

>> var triple = new RDFTriple(new URI('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 property subject of the RDFTriple
http://www.example.com#foo
>> print(triple.toString());     // Stringify the RDFTriple
http://www.example.com#foo http://www.w3.org/2000/01/rdf-schema#label foo

Example use of RDFTriple in Javascript

2.5 RDF Triple List

The RDFTripleList is a plain list of RDFTriple objects. Besides providing a RDFTripleList:get() method, RDFTripleList exposes its list content in style of arrays.

interface RDFTripleList {

    readonly attribute unsigned long length;
    RDFTriple get (in unsigned long index);

};

2.5.1 Attributes

length of type unsigned long, readonly: A positive integer value less than RDFTripleList::length that represents an index inside the RDFTripleList.
No exceptions.

2.5.2 Methods

get

Returns the RDFTriple object inside this list at position index.

Parameter	Type	Nullable	Optional	Description
index	`unsigned long`	✘	✘	A positive integer value less than RDFTripleList::length that represents an index inside the RDFTripleList

No exceptions.

Return type: RDFTriple

2.5.3 Example

This section is non-normative.

>> var rdfTripleList = rdfa.filter();            // filter all RDF triples from current web page as RDFTripleList
>> print(rdfTripleList.length);                  // print the count 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

2.6 RDF Triple Iterator

The RDFTripleIterator iterates through RDF triples that reside inside RDFa content of Nodes of the DOM tree. Compared to the RDFTripleList using the RDFTripleIterator is less memory consuming, as RDF triples are extracted while iterating.

interface RDFTripleIterator {
    readonly attribute Node            root;

    readonly attribute RDFTripleFilter filter;
    readonly attribute RDFTriple       triplePattern;
    RDFTriple previous ();

    RDFTriple next ();
};

2.6.1 Attributes

filter of type RDFTripleFilter, readonly: The RDFTripleFilter object that filters the Node objects in the subtree for certain RDFa content.
No exceptions.
root of type Node, readonly: The Node inside the DOM Tree taken as root node to start from the extraction of RDFa content.
No exceptions.
triplePattern of type RDFTriple, readonly: An RDF triple pattern is an additional filter parameter that can be passed to an RDFTripleFilter.
No exceptions.

2.6.2 Methods

next: Returns the next RDFTriple object that is found inside the subtree of DOM nodes or NULL if no more exist.
No parameters.
No exceptions.
Return type: RDFTriple
previous: Returns the previous RDFTriple object that is found inside the subtree of DOM nodes or NULL if no previous RDFTriples exist.
No parameters.
No exceptions.
Return type: RDFTriple

2.6.3 Example

This section is non-normative.

>> var iter = rdfa.iterate();    // filter all RDF triples from current web page as 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

2.7 RDFTripleProjection

The interface RDFTripleProjection provides a projection of all RDF triples in a document about a single subject. Furthermore the RDFTripleProjection aggregates these RDF triples as a single object. Predicate-object pairs of the existing RDF triples are projected to named properties of the created object.

RDFTripleProjection provides an user-friendly interface for getting all information bout a single subject in single object.

interface RDFTripleProjection {
    readonly attribute URI           subject;

    readonly attribute Sequence[URI] properties;
    [NameGetter]
    Sequence[any] get (in DOMString name);

};

2.7.1 Attributes

properties of type Sequence[URI], readonly: A sequence of predicate URIs of all aggregated RDF triples in this projection.
No exceptions.
subject of type URI, readonly: The URI of the subject all aggregated RDF triples have in this projection.
No exceptions.

2.7.2 Methods

get

Returns the object value as sequence of either URI, BlankNode, PlainLiteral, or TypedLiteral of projected RDf triples with a stringified URI value that equals the DOMString name.

Parameter	Type	Nullable	Optional	Description
name	`DOMString`	✘	✘	The DOMString value of name equals the String representation of the projected predicate values of aggregated RDF triples.

No exceptions.

Return type: Sequence[any]

2.7.3 Example

This section is non-normative.

>> var subject = new URI("http://www.ivan-herman.net/foaf#me");      // create URI for subject
>> var myRdfaObject = rdfa.extractObject(subject);                   // extract information about this subject as RDFTripleProjection from a web page
>> print(myRdfaObject.subject);                                      // print the subject of this RDFTripleProjection
http://www.ivan-herman.net/foaf#me
>> print(myRdfaObject.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
>> print(myRdfaObject[rdfa.foaf.name]);                              // print named property values of foaf:name
Herman Iván, Ivan Herman
>> print(myRdfaObject[rdfa.foaf.title]);                             // print named property values of foaf:title
Dr.

>> print(myRdfaObject[rdfa.foaf.workInfoHomepage]);                  // print named property values of foaf:workInfoHomepage
http://www.iswsa.org/, http://www.iw3c2.org, http://www.w3.org/2001/sw/#activity

3. The RDFa DOM API

The RDFa DOM API strives to be a simple set of methods that a developer may use to retrieve RDF triples and document parts containing these in a document.

The key mechanism for extracting either RDF data from DOM elements or DOM elements with RDFa content focuses on the use of filters. Filters are used to select RDF triple data as well as elements that are contained in the document.

Finally, the following methods of the RDFa DOM API allows a programmer to query the RDFa data expressed by a document and then make programmatic decisions based on the semantic data embedded in the page.

interface rdfa {

    const DOMString VERSION = "0.1";
};

3.1 Constants

VERSION of type DOMString: The current version of the RDFa DOM API

3.2 Filtering RDF Triples from RDFa content

The core interface of the RDFa DOM API provides a list of methods for filtering. It destincts between filtering RDF triples as RDFTripleList, and filtering RDF triples as RDFTripleIterator.

3.2.1 Filter Methods

interface rdfa {

    [Null=Null]
    RDFTripleList       filter ([Variadic] in Object? subject, in URI? predicate, in Object? object, in Node? element, in RDFTripleFilter? myfilter);

    [Null=Null]
    RDFTripleIterator   iterate ([Variadic] in Object? subject, in URI? predicate, in Object? object, in Node? element, in RDFTripleFilter? myfilter);

    RDFTripleProjection project (in URI subject);
};

3.2.1.1 Methods

filter

Returns an RDFTripleList that is a list of RDFTriple entries.

Parameter	Type	Nullable	Optional	Description
subject	`Object`	✔	✘	Subject pattern of an RDF triple that should be tested. Values can be of type URI, BlankNode, or Null. If subject is set to null, the filter does not consider subject values to deciding whether an RDFTriple is added to the result list or not.
predicate	`URI`	✔	✘	Predicate pattern of an RDF triple that should be tested. If predicate is set to null, the filter does not consider predicate values to deciding whether an RDFTriple is added to the result list or not.
object	`Object`	✔	✘	Object pattern of an RDF triple that should be tested. Values can be of type URI, BlankNode, TypedLiteral, PlainLiteral or Null. If object is set to null, the filter does not consider object values to deciding whether an RDFTriple is added to the result list or not.
element	`Node`	✔	✘	The part a the DOM tree with element as root that should be filtered for RDF triples.
myfilter	`RDFTripleFilter`	✔	✘	A user defined boolean function for deciding whether an RDFTriple is added to the result list or not.

No exceptions.

Return type: RDFTripleList

iterate

Returns an RDFTripleIterator. RDFTripleIterator may be used in documents with a large amount of triples. The online filtering of RDF triples during iteration is less memory consuming than storing all filtered RDFTriples in an RDFTripleList.

Parameter	Type	Nullable	Optional	Description
subject	`Object`	✔	✘	Subject pattern of an RDF triple that should be tested. Values can be of type URI, BlankNode, or Null. If subject is set to null, the filter does not consider subject values to deciding whether an RDFTriple is added to the result list or not.
predicate	`URI`	✔	✘	Predicate pattern of an RDF triple that should be tested. If predicate is set to null, the filter does not consider predicate values to deciding whether an RDFTriple is added to the result list or not.
object	`Object`	✔	✘	Object pattern of an RDF triple that should be tested. Values can be of type URI, BlankNode, TypedLiteral, PlainLiteral or Null. If object is set to null, the filter does not consider object values to deciding whether an RDFTriple is added to the result list or not.
element	`Node`	✔	✘	The part a the DOM tree with element as root that should be filtered for RDF triples.
myfilter	`RDFTripleFilter`	✔	✘	A user defined boolean function for deciding whether an RDFTriple is added to the result list or not.

No exceptions.

Return type: RDFTripleIterator

project

The methods creates an object that aggregates a projection of extracted RDF triples that share the same subject. Predicate-object pairs of RDF triples are projected to named properties of the created object.

Parameter	Type	Nullable	Optional	Description
subject	`URI`	✘	✘	The subject to collect infromation about.

No exceptions.

Return type: RDFTripleProjection

3.2.2 User defined Filter Functions

Filter criterias can also be user-defined as RDFTripleFilter by developers. These callable functions check if an RDFTriple should be inserted into a resulting list or iterator.

[Callback, Null=Null]
interface RDFTripleFilter {

    boolean match ([Variadic] in Node? element, in Object? subject, in URI? predicate, in Object? object);

};

3.2.2.1 Methods

match

This callable function returns true if the passed RDFTriple triple is tested as valid. Otherwise it returns false.

Parameter	Type	Nullable	Optional	Description
element	`Node`	✔	✘	The part a the DOM tree with element as root that should be filtered for RDF triples.
subject	`Object`	✔	✘	Subject pattern of an RDF triple that should be tested. Values can be of type URI, BlankNode, or Null. If subject is set to null, the filter does not consider subject values to deciding whether an RDFTriple is added to the result list or not.
predicate	`URI`	✔	✘	Predicate pattern of an RDF triple that should be tested. If predicate is set to null, the filter does not consider predicate values to deciding whether an RDFTriple is added to the result list or not.
object	`Object`	✔	✘	Object pattern of an RDF triple that should be tested. Values can be of type URI, BlankNode, TypedLiteral, PlainLiteral or Null. If object is set to null, the filter does not consider object values to deciding whether an RDFTriple is added to the result list or not.

No exceptions.

Return type: boolean

3.2.3 Example

This section is non-normative.

The following examples refer to this 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>

Example use of rdfa.filter and rdfa.iterate in Javascript

>> 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 tripleList = rdfa.filter(null, null, null, document.getElementById("start"), myFilter);    // start filtering at element with id=start
>> 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"



>> var iter = rdfa.iterate(null, null, null, document.getElementById("start"), myFilter);          // start filtering by iterating at element with id=start
>> 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"

Example use of rdfa.project in Javascript

>> var einstein = rdfa.project(new URI("http://dbpedia.org/resource/Albert_Einstein"));
>> print(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

3.3 Filtering DOM elements with RDFa content

In addition to filter RDF triples from RDFa content, the RDFa DOM API also provides methods for filtering DOM elements that contain specific RDFa data.

interface rdfa {
    NodeList getElements ([Variadic] in Object? subject, in URI? predicate, in Object? object, in RDFTripleFilter? myfilter);

    boolean  containsRDFa ([Variadic] in Node? element, in Object? subject, in URI? predicate, in Object? object, in RDFTripleFilter? myfilter);

};

3.3.1 Methods

containsRDFa

Tests a node and its descendants if it contains RDFa content.

Parameter	Type	Nullable	Optional	Description
element	`Node`	✔	✘	The part a the DOM tree with element as root that should be filtered for RDF triples.
subject	`Object`	✔	✘	Subject pattern of an RDF triple that should be tested. Values can be of type URI, BlankNode, or Null. If subject is set to null, the filter does not consider subject values to deciding whether an RDFTriple is added to the result list or not.
predicate	`URI`	✔	✘	Predicate pattern of an RDF triple that should be tested. If predicate is set to null, the filter does not consider predicate values to deciding whether an RDFTriple is added to the result list or not.
object	`Object`	✔	✘	Object pattern of an RDF triple that should be tested. Values can be of type URI, BlankNode, TypedLiteral, PlainLiteral or Null. If object is set to null, the filter does not consider object values to deciding whether an RDFTriple is added to the result list or not.
myfilter	`RDFTripleFilter`	✔	✘	A user defined boolean function for deciding whether an RDFTriple is added to the result list or not.

No exceptions.

Return type: boolean

getElements

Return a NodeList od DOM nodes that match with their RDFa content and given filter cirteria.

Parameter	Type	Nullable	Optional	Description
subject	`Object`	✔	✘	Subject pattern of an RDF triple that should be tested. Values can be of type URI, BlankNode, or Null. If subject is set to null, the filter does not consider subject values to deciding whether an RDFTriple is added to the result list or not.
predicate	`URI`	✔	✘	Predicate pattern of an RDF triple that should be tested. If predicate is set to null, the filter does not consider predicate values to deciding whether an RDFTriple is added to the result list or not.
object	`Object`	✔	✘	Object pattern of an RDF triple that should be tested. Values can be of type URI, BlankNode, TypedLiteral, PlainLiteral or Null. If object is set to null, the filter does not consider object values to deciding whether an RDFTriple is added to the result list or not.
myfilter	`RDFTripleFilter`	✔	✘	A user defined boolean function for deciding whether an RDFTriple is added to the result list or not.

No exceptions.

Return type: NodeList

3.3.2 Example

This section is non-normative.

The following examples refer to this 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>

Example use of rdfa.containsRDFa and rdfa.getElements in Javascript

>> var germany = new URI("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

The RDFa DOM API

An API for extracting RDFa data from a DOM

W3C Editor's Draft 23 April 2010

Abstract

How to Read this Document

Status of This Document

Table of Contents

1. Motivation

2. The RDF Data Model

2.1 RDF Literals

2.1.1 Plain Literals

2.1.1.1 Attributes

2.1.1.2 Example

2.1.2 Typed Literals

2.1.2.1 Attributes

2.1.2.2 Methods

2.1.2.3 Example

2.1.3 TypedLiteralConverter

Specify TypedLiteralConverters

2.1.3.1 Methods

2.1.3.2 Register TypedLiteralConverters

2.1.3.2.1 Methods

2.1.3.3 Example

2.2 URI Reference

2.2.1 Attributes

2.2.2 URI Mapping

2.2.2.1 Methods

2.2.3 Example

2.3 BlankNode

2.3.1 Attributes

2.3.2 Example

2.4 RDFTriple

2.4.1 Attributes

2.4.2 Methods

2.4.3 Constants

2.4.4 Example

2.5 RDF Triple List

2.5.1 Attributes

2.5.2 Methods

2.5.3 Example

2.6 RDF Triple Iterator

2.6.1 Attributes

2.6.2 Methods

2.6.3 Example

2.7 RDFTripleProjection

2.7.1 Attributes

2.7.2 Methods

2.7.3 Example

3. The RDFa DOM API

3.1 Constants

3.2 Filtering RDF Triples from RDFa content

3.2.1 Filter Methods

3.2.1.1 Methods

3.2.2 User defined Filter Functions

3.2.2.1 Methods

3.2.3 Example

3.3 Filtering DOM elements with RDFa content

3.3.1 Methods

3.3.2 Example

4. Outlook

A. Acknowledgements

B. IDL Definitions

C. Javascript Conversion

D. References

D.1 Normative references

D.2 Informative references