The RDFa DOM API

Table of Contents

• 1. Introduction
• 2. How to Read this Document
• 3. The RDFa DOM API
• 4. RDF Literals
  • 4.1 Attributes
  • 4.2 Methods
  • 4.3 Attributes
  • 4.4 Methods
  • 4.5 Methods
  • 4.6 Methods
• 5. URI Reference
  • 5.1 Attributes
  • 5.2 Methods
• 6. BlankNode
  • 6.1 Attributes
  • 6.2 Methods
• 7. RDFTriple
  • 7.1 Attributes
  • 7.2 Methods
• 8. Filtering RDF Triples
  • 8.1 Methods
  • 8.2 Methods
• 9. Iterating through RDF Triples
  • 9.1 Attributes
  • 9.2 Methods
• 10. RDF Triple List
  • 10.1 Attributes
  • 10.2 Methods
• A. Acknowledgements
• B. IDL Definitions
• C. References
  • C.1 Normative references
  • C.2 Informative references

1. Introduction

RDFa [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.

In an effort to ensure that browser-based applications are able to fully utilize RDFa, this specification outlines a set of interfaces that are capable of finding and extracting RDFa from web pages or other document formats that are based on the Document Object Model (DOM). The RDFa DOM API is designed with ease of use in mind. A deep understanding of RDFa is no longer necessary to extract and utilize the structured data embedded in RDFa documents.

TODO: Write more on: Why do we need an RDFa DOM API?

Most browser-based applications and browser extensions that utilize HTML documents are written in Javascript [ECMA-262]. For this reason, the RDFa DOM API is designed to be implemented and used primarily in Javascript in a browser environment. The RDFa DOM API specification is also easily implemented in other languages commonly used in Semantic Web applications, e.g., Python, Java, Perl, or Ruby.

2. How to Read this Document

The specification of the RDFa DOM API is written in the Web Interface Definition Language [WEBIDL].

TODO: List vocabularies used in examples.

The RDFa DOM API uses RDF as underlying data model [RDF-SYNTAX]. Therefore, it provides interface definitions for programming with plain and typed Literals, URI References and Blank nodes. These interfaces are the components to work with RDFTriples in the RDFa DOM API.

3. The RDFa DOM API

TODO: What features does an RDFa DOM API provide?
TODO: How does an RDFa DOM API provide those features?

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

TODO: Describe how RDFa DOM API extends Javascript use in browsers in order to extract RDF from DOM nodes. Describe the constant object rdfa.

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

TODO: Describe idea behind rdfa.filter, rdfa.list, rdfa.iterate

The RDFa DOM API uses a concept called a RDFTripleFilter to retrieve data from DOM nodes. Inspired by NodeFilters [DOM-LEVEL-2-TRAVERSAL-RANGE], RDFTripleFilters can be user defined and allow application programmers a highly flexible way to filter RDF triples.

In order to retrieve DOM nodes that contain RDFa content, the RDFa DOM API provides a method to test DOM nodes. RDFTripleFilters can be passed as an optional parameter to rdfa.containsRDFa() in order to test DOM nodes for RDF triples that match the given filter.

Finally, the following 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.

Basic Datatypes

The working group has not reached consensus whether or not a traditional object 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.

The basic types of the RDFa DOM API are DOMString, Plain RDF Literal, Typed RDF Literal, URI reference, and Blank Node. (The normative specification of these types is described in RDFa in XHTML: Syntax and Processing [RDFA-SYNTAX].)

4. RDF Literals

An RDF Literal represents lexical values in RDFa data. In RDF, literals may be either attached with language information about the given text given in form of a language tag (e.g., 'en', 'fr', 'de'), or a datatype given as URI reference (e.g., [xsd:DataTime]). The former concept is called plain literal. The latter concept is called typed literal.

The language tag is an identifier for a certain language as defined by [RFC-3066]. The datatype's URI reference defines the datatype of the text value, e.g., xsd:DataTime or xsd:boolean. 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.

The RDFa DOM API provides a method to explicitly cast TypedRDFLiteral values to datatypes that are specified in the native Programming language that implements the RDFa DOM API. Developers may write their own TypedLiteralConverter in order to convert RDFLiteral into prefered language constructs. As default standard converters for the following XML Scheme datatypes [XSD] are provided if corresponding datatypes exist the current programming language:

• xsd:string
• xsd:boolean
• xsd:float
• xsd:double
• xsd:boolean
• xsd:integer
• xsd:long
• xsd:date
• xsd:time
• xsd:dateTime

TypedLiteral

A TypedLiteral wraps a DOMString and adds type information about its content.

interface TypedLiteral {
    readonly attribute DOMString value;

    readonly attribute URI       type;
    DOMString toString ();
    DOMString valueOf ();

};

Example

Example use of TypedLiteral in Javascript

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

PlainLiteral

A PlainLiteral wraps a DOMString and adds optional language information about its content.

interface PlainLiteral {

    readonly attribute DOMString value;
    readonly attribute DOMString language;
    DOMString toString ();

    DOMString valueOf ();
};

Example

Example use of PlainLiteral in Javascript

>> var literal = new PlainLiteral('foo', 'en');
>> print(literal.toString());
foo
>> print(literal.valueOf());
foo

TypedLiteralConverter

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

interface TypedLiteralConverter {

    T convertType (in DOMString value);
};

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

};

Example

Example use of PlainLiteral in Javascript

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

5. URI Reference

interface URI {
    readonly attribute DOMString value;

    DOMString toString ();
    DOMString valueOf ();
};

Example

Example use of URI in Javascript

>> var uri = new URI("http://www.example.com");
>> print(uri.toString());
http://www.example.com
>> print(uri.valueOf());
http://www.example.com

6. BlankNode

interface BlankNode {
    readonly attribute DOMString value;
    DOMString toString ();

    DOMString valueOf ();
};

Example

Example use of BlankNode in Javascript

>> var bn = new BlankNode(":_42");
>> print(bn.toString());
:_42
>> print(bn.valueOf());
:_42

7. RDFTriple

In the RDFa DOM API, RDFTriple defines the data structure to represent an RDF triples as specified in [RDF-CONCEPTS]. The RDFa DOM API is intended to extract RDFTriple objects from the source document.

interface RDFTriple {
    readonly attribute Object subject;
    readonly attribute Object predicate;

    readonly attribute Object object;
    DOMString toString ();
    DOMString valueOf ();

};

Example

Example use of RDFTriple in Javascript

>> var triple = new RDFTriple([new URI('http://www.example.com#foo'), RDFS['foo'], new PlainLiteral('foo')]);
>> print(triple.subject);
http://www.example.com#foo
>> print(triple.toString());
http://www.example.com#foo http://www.w3.org/2000/01/rdf-schema#label foo
>> print(triple.valueOf());
http://www.example.com#foo http://www.w3.org/2000/01/rdf-schema#label foo

8. Filtering RDF Triples

The RDFa DOM API provides these RDF filters for testing a RDFTriple instance for certain citeria.

Which filter functions should be provided?

rdfa

interface rdfa {
    Object[]          filter (in Object? subject, in Object? predicate, in Object? object, in Node? node, in RDFTripleFilter? myfilter);

    RDFTripleList     list (in Object? subject, in Object? predicate, in Object? object, in Node? node, in RDFTripleFilter? myfilter);

    RDFTripleIterator iterate (in Object? subject, in Object? predicate, in Object? object, in Node? node, in RDFTripleFilter? myfilter);

    boolean           containsRDFa (in Object? subject, in Object? predicate, in Object? object, in Node? node, in RDFTripleFilter? myfilter);

    boolean           getRDFTriples (in Object? subject, in Object? predicate, in Object? object, in Node? node);

};

Example

Example use of rdfa.(filter|list|iterate) in Javascript

RDFTripleFilter

Criterias can also be specified by application developers. An RDFTripleFilter may be created with a default RDF triple used as dynamic filter pattern. RDFTripleFilters are helpful when a developer may want to retrieve a subset of triples from the structured data in the page. For example, if one wanted to retrieve all subjects that have the rdf:type of foaf:Person, as well as all subjects that have the rdf:type of foaf:Organization, one could either create two filter functions, or one RDFTripleFilter. the following triple filter (null, rdf:type, foaf:Person).

interface RDFTripleFilter {
    boolean match (in Node? node, in Object? subject, in Object? predicate, in Object? object);

};

Example

Example use of RDFTripleFilter in Javascript

9. Iterating through RDF Triples

The RDFTripleIterator is an Iterator through RDFa content inside Nodes of the DOM tree.

interface RDFTripleIterator {
    readonly attribute Node            root;
    readonly attribute RDFTripleFilter filter;

    readonly attribute RDFTriple       triplePattern;
    RDFTriple         previousRDFTriple ();
    RDFTriple         nextRDFTriple ();

    RDFTripleIterator RDFTripleIterator (in Node root, in Object? subject, in Object? predicate, in Object? object, in RDFTripleFilter filter);

};

Example

10. RDF Triple List

The RDFTripleList is a plain list of RDFTriple objects.

interface RDFTripleList {

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

};

Example