Copyright © 2010 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
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.
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:
rdf
, e.g., rdf:type
)xsd
, e.g., xsd:integer
)rdfs
, e.g., rdfs:label
)foaf
, e.g., foaf:name
)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.
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.
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:
http://www.w3.org/2001/XMLSchema#string
.
"Harry Potter and the Half-Blood
Prince"@en
is a plain literal expressed in the English language."7"^^xsd:integer
is a typed literal with a value of type
xsd:integer
.
_:me
, and _:42
.<http://example.org/hp>
rdfs:label "Harry Potter" .
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.
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;
};
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.
'en'
, 'fr'
, 'de'
).http://www.w3.org/2001/XMLSchema#DateTime
).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;
};
element
of type Node, readonlylanguage
of type DOMString, readonlyvalue
of type DOMString, readonlyThis 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
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:
[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 ();
};
element
of type Node, readonlytype
of type IRI
, readonlyvalue
of type DOMString, readonlyvalueOf
Any
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
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;
};
value
of type DOMString, readonlyDevelopers 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.
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
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);
};
get
Parameter | Type | Nullable | Optional | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
index | unsigned char | ✘ | ✘ | A property index in the range of 0 to 2. The following index values
are mapped to the following RDFTriple properties:
|
Object
LENGTH
of type unsigned charOBJECT_INDEX
of type unsigned charPREDICATE_INDEX
of type unsigned charSUBJECT_INDEX
of type unsigned charThis 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" .
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:
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);
};
length
of type unsigned long, readonlyforEach
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
callback | function | ✘ | ✘ | A function that takes the following arguments: index, subject, predicate, object. The function is called for each item in the RDFTripleList. |
void
get
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
index | unsigned long | ✘ | ✘ | The 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. |
Object
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
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 ();
};
filter
of type RDFTripleFilter
, readonlyroot
of type Node, readonlytriplePattern
of type RDFTriple
, readonlynext
RDFTriple
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
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);
};
properties
of type Sequence[IRI], readonlysubject
of type IRI
, readonlyget
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
name | DOMString | ✘ | ✘ | A 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. |
Sequence[any]
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"]
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";
};
VERSION
of type DOMStringProcessing 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);
};
get
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")
.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
prefix | DOMString | ✘ | ✘ | The prefix value that identifies the map that contains
reference to IRI mappings created by rdfa.setMapping(prefix,
reference, IRI) . |
any
set
foaf
). The value Object is an associative array
containing reference-to-IRI mappings.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
prefix | DOMString | ✘ | ✘ | The prefix value that identifies the map that contains the reference-to-IRI mappings. |
void
setMapping
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.Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
prefix | DOMString | ✘ | ✘ | |
reference | DOMString | ✘ | ✘ | |
iri | DOMString | ✘ | ✘ |
void
Convenience IRI mappings for all terms in the following vocabularies must be included: rdf and xsd.
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
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.
[Callback]
interface TypedLiteralConverter {
Any convertType (in DOMString value);
};
interface rdfa {
void registerTypeConversion (in IRI
type, in TypedLiteralConverter
converter);
};
registerTypeConversion
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
type |
| ✘ | ✘ | An IRI reference to the datatype of the TypedLiteral. |
converter |
| ✘ | ✘ | A function that converts the TypedLiteral's value into a native language datatype in the current programming language. |
void
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
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.
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);
};
filter
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
subject | Object | ✔ | ✘ | The 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. |
predicate |
| ✔ | ✘ | The 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. |
object | Object | ✔ | ✘ | The 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. |
element | Node | ✔ | ✘ | The parent DOM Node where filtering should start. The implementation must only consider RDF triples on the current DOM Node and its children. |
filter |
| ✔ | ✘ | A user defined function, returning a true or false value, that determines whether or not an RDFTriple should be added to the final RDFTripleList. |
RDFTripleList
iterate
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
subject | Object | ✔ | ✘ | The 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. |
predicate |
| ✔ | ✘ | The 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. |
object | Object | ✔ | ✘ | The 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. |
element | Node | ✔ | ✘ | The parent DOM Node where filtering should start. The implementation must only consider RDF triples on the current DOM Node and its children. |
filter |
| ✔ | ✘ | A user defined function, returning a true or false value, that determines whether or not an RDFTriple should be output via the RDFTripleIterator. |
RDFTripleIterator
project
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
subject | Object | ✘ | ✘ | The subject of the projection, which can be a Blank Node or an IRI, will be used to generate the language native Object. |
RDFProjection
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);
};
match
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
element | Node | ✔ | ✘ | The DOM Node where filtering should start. |
predicate |
| ✔ | ✘ | The predicate, which can be used to accept or reject the RDFTriple. Values can be of type IRI or Null. |
object | Object | ✔ | ✘ | The object, which can be used to accept or reject the RDFTriple. Values can be of type IRI, TypedLiteral, PlainLiteral, BlankNode, or Null. |
boolean
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
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);
};
containsRDFa
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
element | Node | ✔ | ✘ | The parent DOM Node where testing should start. Only RDF triples on the given DOM Node and its children are considered. |
subject | Object | ✔ | ✘ | The 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. |
predicate |
| ✔ | ✘ | The 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. |
object | Object | ✔ | ✘ | The 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. |
filter |
| ✔ | ✘ | A user defined function, returning a true or false value, that determines whether or not an RDFTriple should be considered a match. |
boolean
getElements
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
subject | Object | ✔ | ✘ | The 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. |
predicate |
| ✔ | ✘ | The 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. |
object | Object | ✔ | ✘ | The 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. |
element | Node | ✔ | ✘ | The parent DOM Node where filtering should start. The implementation must only consider RDF triples on the current DOM Node and its children. |
filter |
| ✔ | ✘ | A user defined function, returning a true or false value, that determines whether or not a DOM Node should be added to the final NodeList. |
NodeList
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
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:
At the time of publication, the members of the RDFa Working Group were:
This section is non-normative.
This document contains the Web IDL definitions of the RDFa DOM API: rdfa_dom_api.idl
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