RDFa API

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:

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

For those looking for an introduction to the use of RDFa, or some real-world examples, please consult the RDFa Primer [ RDFA-PRIMER ].

If you are not familiar with RDF, you should read about the Resource Description Framework (RDF) [ RDF-CONCEPTS ] before reading this document. The [ RDF-CONCEPTS ] document outlines the core data model that is used by RDFa to express information.

If you are not familiar with RDFa, you should read and understand the [ RDFA-CORE ] specification. It describes how data is encoded in host languages using RDFa. A solid understanding of concepts in RDFa Core will inevitably help you understand how the RDFa ~~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 Concept Diagram and Developing with the API sections of most interest. It contains a handful of ~~JavaScript~~ ECMAScript examples on how to use the RDFa API .

Readers who are not familiar with the Terse RDF Triple Language [ TURTLE ] may want to read the specification in order to understand the short-hand RDF notation used in some of the examples.

This document uses the Web Interface Definition Language [ WEBIDL ] to specify all language bindings. If you intend to implement the RDFa ~~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:

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

3. Developing with the API

This section is non-normative.

3.1 Basic Concepts

This section is non-normative.

This API provides a number of interfaces to enable:

parsing of DOM objects that contain embedded metadata;
extraction of the embedded metadata into a data store;
querying a data store in order to retrieve ~~Property Groups~~ PropertyGroup s from the data store.

3.1.1 The Basic API

The RDFa ~~DOM~~ API has a number of advanced methods that can be used to access the ~~Data Store, Data Parser~~ DataStore,DataParser and ~~Data Query~~ DataQuery mechanisms. Most web developers will not need to use the advanced methods - most will only require the following interfaces for most of their day-to-day development activities.

Retrieving Property Groups PropertyGroups

document.getItemsByType(type): Retrieves a list of ~~Property Groups~~ PropertyGroup s by their type, such as foaf:Person.
document.getItemBySubject(type): Retrieves a single ~~Property Group~~ PropertyGroup by its subject, such as http://example.org/people#bob.
document.getItemsByProperty(property, optional value): Retrieves a list of ~~Property Groups~~ PropertyGroup s by a particular property and optional value that the ~~Property Group~~ PropertyGroup contains.

Retrieving DOM Elements

document.getElementsByType(type): Retrieves a list of DOM Nodes by the type of data that they express, such as foaf:Person.
document.getElementsBySubject(type): Retrieves a list of DOM Nodes by the subject associated with the data that they express, such as http://example.org/people#bob.
document.getElementsByProperty(property, optional value): Retrieves a list of DOM Nodes by a particular property and optional value that each expresses.

IRI Mapping

document.data.context.setMapping(prefix, iri): Gets and sets short-hand IRI mappings that are used by the API, such as expanding foaf:Person to http://xmlns.com/foaf/0.1/Person.

Advanced Processing

document.data.query.select(query, template): Retrieves an array of ~~Property Groups~~ PropertyGroup s based on a set of selection criteria.
document.data.store.filter(subject, predicate, object) document.data.store.filter(pattern): Filters a given ~~Data Store~~ DataStore by matching a given triple pattern.
document.data.parser.iterate(iterFunction) document.data.parser.iterate(pattern): Iterates through a DOM, ~~passing every data item to the iteration function that is passed into~~ using a low-memory, stream-based approach, matching on the ~~method.~~ given triple pattern.

3.1.2 Using the Basic API

The following section uses the markup shown below to demonstrate how to extract and use ~~Property Groups~~ PropertyGroup s using the RDFa ~~DOM~~ API. The following markup is assumed to be served from a document located at http://example.org/people.

~~<div prefix="foaf: http://xmlns.com/foaf/0.1/" about="#albert" typeof="foaf:Person">~~

<div prefix="foaf: http://xmlns.com/foaf/0.1/" about="#albert" typeof="foaf:Person">

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

Working with Property Groups

Retrieving Property Groups PropertyGroups by Type

You can retrieve the object that is described above by doing the following:

var
people
=
document.getItemsByType("http://xmlns.com/foaf/0.1/Person");

or you can specify a short-cut to use when specifying the IRI: ~~document.data.context.setMapping("foaf", "http://xmlns.com/foaf/0.1/");~~

document.data.context.setMapping("foaf", "http://xmlns.com/foaf/0.1/");

var
people
=
document.getItemsByType("foaf:Person");

Retrieving Property Groups PropertyGroups by Subject

You can also get a ~~Property Group~~ PropertyGroup by its subject:

var
albert
=
document.getItemBySubject("http://example.org/people#albert");

You can also specify a relative IRI and the document IRI will be automatically pre-pended:

var
albert
=
document.getItemBySubject("#albert");

Retrieving Property Groups PropertyGroups by Property

You can get a list of ~~Property Groups~~ PropertyGroup s by their properties:

var
peopleNamedAlbertEinstein
=
document.getItemByProperty("foaf:name",
"Albert
Einstein");

Using Property Groups PropertyGroups

You can retrieve property values from ~~Property Groups~~ PropertyGroup s like so:

~~var albert = document.getItemBySubject("#albert");~~

var albert = document.getItemBySubject("#albert");

var
name
=
albert.get("foaf:name");

You can also specify values that you would like to map to ~~Property Group~~ PropertyGroup attributes:

~~var albert = document.getItemBySubject("#albert", {"foaf:name": "name"});~~

var albert = document.getItemBySubject("#albert", {"foaf:name": "name"});

var
name
=
albert.name;

Managing Elements with Data

Retrieving Elements Containing Data by Type

You can retrieve the DOM ~~Node~~ Element that is described above by doing the following:

var
elements
=
document.getElementsByType("http://xmlns.com/foaf/0.1/Person");

or you can specify a short-cut to use when specifying the IRI: ~~document.data.context.setMapping("foaf", "http://xmlns.com/foaf/0.1/");~~

document.data.context.setMapping("foaf", "http://xmlns.com/foaf/0.1/");

var
elements
=
document.getElementsByType("foaf:Person");

Retrieving Elements Containing Data by Subject

You can also get a list of Elements by the subject of data:

var
elements
=
document.getElementsBySubject("http://example.org/people#albert");

You can also specify a relative IRI and the document IRI will be automatically pre-pended:

var
elements
=
document.getElementsBySubject("#albert");

Retrieving Elements by Property

You can get a list of Elements by the properties and values that they declare:

var
elements
=
document.getElementsByProperty("foaf:name",
"Albert
Einstein");

Modifying DOM Elements

You can modify elements that are returned just like any other DOM Node, for example:

The mechanism to access the DOM Element associated with in-document data is being redesigned for the next draft version of the RDFa API.

var elements = document.getElementsByProperty("foaf:name", "Bob");
for(i = 0; i <= elements.length; i++)
{
   var e = elements[i];
   e.style.setProperty('color', '#00cc00', null);
}

The code above would change the color of all the areas of the page where the item's name is "Bob" to green.

3.2 Advanced Concepts

This section covers a number of concepts that go beyond basic everyday usage of the RDFa ~~DOM~~ API. The interfaces to the ~~DOM~~ API allow you to work with data at an abstract level, or query structured data and override key parts of the software stack in order to extend the functionality that the API provides.

3.2.1 Advanced Queries

The features available via a Query object will depend on the implementation. However, all conforming processors will provide the basic element selection mechanisms described here.

Querying by Type

Perhaps the most basic task is to select ~~Property Groups~~ PropertyGroup s of a particular type. The type of a ~~Property Group~~ PropertyGroup is set in RDFa via the special attribute @typeof. For example, the following markup expresses a ~~Property Group~~ PropertyGroup of type Person in the Friend-of-a-Friend vocabulary:

~~<div typeof="foaf:Person">~~

<div typeof="foaf:Person">

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

To locate all ~~Property Groups~~ PropertyGroup s that are ~~people~~ people, we ~~would~~ could use the document.getItemsByType() method:


document.getItemsByType("http://xmlns.com/foaf/0.1/Person");

or we could do the ~~following:~~ same using the


DataQuery

interface:

~~var query = document.data.createQuery("rdfa", store);~~

var query = document.data.createQuery("rdfa", store);

var
ar

people

=
query.select(
{
"rdf:type":
"foaf:Person"
}
);

While the query interface is more verbose for simple queries, it becomes necessary for more complex queries as demonstrated later in this section. Note that the Query object has access to the mappings provided via the document.data.context object, so they can also be used in queries. It is also possible to write the same query in a way that is independent of any prefix-mappings:

var
ar

people

=
query.select(
{
"http://www.w3.org/1999/02/22-rdf-syntax-ns#type":
"http://xmlns.com/foaf/0.1/Person"
}
);

Querying by Property Value

The previous query selected all ~~Property Groups~~ PropertyGroup s of a certain type, but it did so by indicating that the property rdf:type should have a specific value. Queries can also specify other properties. For example, given the following mark-up:

~~<div typeof="foaf:Person">~~

<div typeof="foaf:Person">

  <span property="foaf:name">Albert Einstein</span> -
  <span property="foaf:myersBriggs">INTP</span>
  <a rel="foaf:workInfoHomepage" href="http://en.wikipedia.org/wiki/Albert_Einstein">More...</span>
</div>
<div typeof="foaf:Person">
  <span property="foaf:name">Mother Teresa</span> -
  <span property="foaf:myersBriggs">ISFJ</span>
  <a rel="foaf:workInfoHomepage" href="http://en.wikipedia.org/wiki/Mother_Teresa">More...</span>
</div>
<div typeof="foaf:Person">
  <span property="foaf:name">Marie Curie</span> - 
  <span property="foaf:myersBriggs">INTP</span>
  <a rel="foaf:workInfoHomepage" href="http://en.wikipedia.org/wiki/Marie_Curie">More...</span>
</div>

The following query demonstrates how a developer would select and use all ~~Property Groups~~ PropertyGroup s of type Person that also have a Myers Brigg's personality type of "INTP" (aka: The Architect):

~~var architects = query.select( {~~

var architects = query.select( {

  "http://www.w3.org/1999/02/22-rdf-syntax-ns#type": "http://xmlns.com/foaf/0.1/Person",
  "http://xmlns.com/foaf/0.1/myersBriggs": "INTP"
} );
var
name
=
architects[0].get("http://xmlns.com/foaf/0.1/name");

As before, prefix-mappings can also be used:

~~var architects = query.select( {"rdf:type": "foaf:Person", "foaf:myersBriggs": "INTP"} );~~

var architects = query.select( {"rdf:type": "foaf:Person", "foaf:myersBriggs": "INTP"} );

var
name
=
architects[0].get("foaf:name");

Directives to generate the ~~Property Group~~ PropertyGroup object based on a template specified by the developer can also be used. In this case, all of the "INTP" personality types are gleaned from the page and presented as ~~Property Groups~~ PropertyGroup s containing each person's name and blog page:

~~var architects = query.select( {"rdf:type": "foaf:Person", "foaf:myersBriggs": "INTP"}, {"foaf:name": "name", "foaf:workInfoHomepage", "info" } );~~

var architects = query.select( {"rdf:type": "foaf:Person", "foaf:myersBriggs": "INTP"},
                               {"foaf:name": "name", "foaf:workInfoHomepage", "webpage"} );

var name = architects[0].name;
var
infoWebpage
=
architects[0].info;

architects[0].webpage;

3.2.2 Direct Access to the Data Store

The RDFa ~~DOM~~ API allows a developer to not only query the ~~Data Store~~ DataStore at via the ~~Data Query~~ DataQuery mechanism, it also allows a developer to get to the underlying data structures that represent the structured data at the "atomic level".

The filter interface is a part of the ~~Data Store~~ DataStore and enables a developer to filter a series of triples out of the ~~Data Store.~~ DataStore. For example, to extract all triples about a particular subject, the developer could do the following:

var
names
=
document.data.store.filter("http://example.org/people#benjamin");

document.data.store.filter(
{"subject":
"http://example.org/people#benjamin"}
);

Developers could also combine ~~subject-predicate~~ subject-property filters by doing the following:

var
names
=
document.data.store.filter("http://example.org/people#benjamin",
"foaf:nick");

document.data.store.filter(
{"subject:",
"http://example.org/people#benjamin",
"property":
"foaf:nick"}
);

The query above would extract all known nicknames for the subject as triples.

A developer may also retrieve all triples in the DataStore by specifying no filter parameters:


var
allTriples
=
document.data.store.filter();

3.2.3 Direct Access to the Parser Stream

The .iterate interface will almost certainly see large changes in the next version of the RDFa API specification. Implementers are warned to not implement the interface and wait for the next revision of this specification.

The iterate interface can be used to process triples in the document as they are discovered. This interface is most useful for processing large amounts of data in low-memory environments.

~~var iter = document.data.parser.iterate("http://example.org/people#mark"); for(var triple = iter.next(); iter != null; triple = iter.next())~~

var iter = document.data.parser.iterate( {"subject": "http://example.org/people#mark"} );
for(var triple = iter.next(); triple != null; triple = iter.next())

{
   // process each triple that is associated with http://example.org/people#mark

   // process each triple that is associated with http://example.org/people#mark
}

3.2.4 Overriding the Defaults

The ~~major modules~~ sub-modules in the RDFa ~~DOM~~ API are meant to be overridden by developers in order to extend basic functionality as well as innovate new interfaces for the RDFa ~~DOM~~ API.

Overriding the Data Store DataStore

The API is designed such that a developer may override the default data store provided by the browser by providing their own. This is useful, for instance, if the developer wanted to create a permanent site-specific data store using Local Storage features in the browser, or allowing provenance information to be stored with each triple.

~~var mydatastore = new MyCustomDataStore();~~

var mydatastore = new MyCustomDataStore();

document.data.store
=
mydatastore;

Overriding the Data Parser

Developers may create and specify different parsers for parsing structured data from the document that builds upon RDFa, or parses other languages not related to RDFa. For example, Microformats-specific parsers could be created to extract structured hCard data and store it in an object that is compatible with the ~~Data Store~~ DataStore interface.

~~var hcardParser = new MyHCardParser();~~

var hcardParser = new MyHCardParser();

document.data.parser
=
hcardParser;

Overriding the Data Query

The query mechanism for the API can be overridden to provide different or more powerful query mechanisms. For example, by replacing the standard query mechanism, developers could provide a full SPARQL query mechanism:

~~var sparqlQuery = new MySparqlEngine();~~

var sparqlQuery = new MySparqlEngine();

document.data.query = sparqlQuery;
var
books
=
document.data.query.select("SELECT
?book
?title
WHERE
{
?book
<http://purl.org/dc/elements/1.1/title>
?title
.
}");

var books = document.data.query.select("SELECT ?book ?title WHERE { ?book <http://purl.org/dc/elements/1.1/title> ?title . }",
{"?book":
"subject",
"?title":
"title"}
);

4. The Interfaces Specification

The following section contains all of the interfaces that developers are expected to ~~implement.~~ implement as well as implementation guidance.

4.1 Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words must , must not , required , should , should not , recommended , may , and optional in this specification are to be interpreted as described in [ RFC2119 ].

Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.

User agents may impose implementation-specific limits on otherwise unconstrained inputs, e.g. to prevent denial of service attacks, to guard against running out of memory, or to work around platform-specific limitations.

Implementations that use ECMAScript or Java to implement the APIs defined in this specification must implement them in a manner consistent with the respective ECMAScript or Java Bindings defined in the Web IDL specification, as this specification uses that specification's terminology. [ WEBIDL ]

Implementations that use any other language to implement the APIs defined in this specification that do not have bindings defined in the Web IDL specification should attempt to map the API as closely as possible to the implementation language's native mechanisms and datatypes. Developers are encouraged to work with other developers who are providing the RDFa API in the same langauge to ensure that RDFa Processors are modular and easily exchangable.

4.2 The RDF Interfaces

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 ,~~ PlainLiteral s, TypedLiteral s, IRI References (as defined in [ IRI ]) and ~~Blank Nodes .~~ BlankNode s. 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:

IRI Reference — A reference to a resource as defined in International Resource Identifier [ IRI ]. Example: http://www.w3.org/2001/XMLSchema#string.
~~Plain Literal~~ PlainLiteral — A string value with optional information about the language of its content. Example: "Harry Potter and the Half-Blood Prince"@en is a plain literal expressed in the English language.
Typed Literal — A typed string value with information about the datatype of its content. Example: "7"^^xsd:integer is a typed literal with a value of type xsd:integer.
Blank Node — A blank node is a reference to a resource that does not have a corresponding IRI. Examples of ~~Blank Nodes~~ BlankNode s include _:me, and _:42.
RDF Triple — Triples are the basic data structure utilized by RDF to express logical statements. An RDF triple is a 3-item ordered set consisting of a subject , a ~~predicate~~ property , and an object . Example: <http://example.org/hp> rdfs:label "Harry Potter" .

A class diagram of all of the basic RDF classes, attributes, methods and linkages in the sections to follow

Diagram of RDF Classes, Attributes, Methods and linkages.

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.

4.1.1 4.2.1 IRI References RDFNode and RDFResource

An ~~IRI Reference in~~ RDFNode is an anything that can be an object of an RDFTriple. It is also the ~~RDFa DOM API points to a resource~~ base class of PlainLiteral, and ~~is further defined in [ IRI ].~~ TypedLiteral.

~~Constructor(in DOMString value), Constructor(in DOMString value, in Node origin), Stringifies=value] interface {~~

[NoInterfaceObject]
interface RDFNode {
    readonly attribute stringifier DOMString value;
};

Attributes

origin value of type ~~Node~~ stringifier DOMString , readonly: The ~~node~~ value of an RDFNode is either a literal's lexical value or a lexical identifier of an IRI or BlankNode. Note that ~~specifies~~ the ~~IRI's~~ value in attribute is marked with a stringifier decorator. In [ WEBIDL ], this means that the ~~RDFa markup.~~ value is used as the return value if toString() is called on an object that inherits from this type. The stringifier can be overridden by the re-specification of the toString() method on a subclass of this type.
No exceptions.

An RDFResource is an anything that can be a subject of an RDFTriple.

[NoInterfaceObject]
interface RDFResource : RDFNode {
    readonly attribute stringifier DOMString value;
};

Attributes

value of type stringifier DOMString , readonly: The ~~lexical representation~~ value of ~~the~~ an RDFResource is either a string that represents an IRI ~~reference.~~ or an identifier of a BlankNode.
No exceptions.

4.2.2 IRI References

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

[NoInterfaceObject]
interface IRI : RDFResource {
};

4.1.2 4.2.3 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~~ PlainLiteral s and ~~TypedLiterals.~~ TypedLiteral s. 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.

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

~~Plain Literals~~

PlainLiterals

~~PlainLiterals~~ PlainLiteral s 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 origin), Stringifies=value] interface {

[NoInterfaceObject]
interface PlainLiteral : RDFNode {
    readonly attribute stringifier DOMString value;    readonly attribute DOMString             language;
};

Attributes

language of type DOMString , readonly: A ~~two character~~ language string as defined in [ BCP47 ], normalized to lowercase.
No exceptions.
value of type stringifier 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 = document.data.store.createPlainLiteral('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

// Create a new PlainLiteral using the DataStore's createPlainLiteral interface
var literal = document.data.store.createPlainLiteral("Harry Potter and the Half-Blood Prince", "en");
// The API supports conversion of PlainLiterals to native language string types
var str = literal.toString();
// At this point, str is equivalent to "Harry Potter and the Half-Blood Prince"// The API supports attribute-based access of PlainLiteral values, the native type// of a PlainLiteral value is a DOMString.
var val = literal.value
// At this point, val is equivalent to "Harry Potter and the Half-Blood Prince"// The API supports attribute-based access of PlainLiteral language values, the// native type of a PlainLiteral language value is a DOMString
var lang = literal.language;

//
At
this
point,
lang
is
equivalent
to
"en"

Typed Literals

A TypedLiteral has a string value and a datatype specified as an IRI Reference . ~~TypedLiterals~~ TypedLiteral s 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 origin), Stringifies=value] interface {~~

[NoInterfaceObject]
interface TypedLiteral : RDFNode {
    readonly attribute stringifier DOMString value;    readonly attribute IRI                   type;    any valueOf ();
};

Attributes

type of type IRI , readonly: A datatype identified by an IRI reference
No exceptions.
value of type stringifier 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 any

Example

This section is non-normative.

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

~~>> var literal = document.data.store.createTypedLiteral('2010-12-24', "xsd:date"); >> print(literal.toString()); 2010-12-24 >> print(literal.value); 2010-12-24 >> print(literal.valueOf());~~

// Create a new TypedLiteral using the DataStore's createTypedLiteral interface
var literal = document.data.store.createTypedLiteral("2010-12-24", "xsd:date");
// The value attribute stores the data in the raw format as specified via the// createTypedLiteral interface or in the document text
var value = literal.value;
// At this point, value is equivalent to "2010-12-24"// The toString() method will convert the TypedLiteral into a language-native // string value of "2010-12-24". This value may be different from the raw format// stored in the literal.value attribute
var str = literal.toString();
// At this point, str is equivalent to "2010-12-24"// The valueOf() method will convert the TypedLiteral into a language-native// datatype. In ECMAScript, the return value of valueOf() will be a // Date object.
var date = literal.valueOf();
// At this point, date will be a Date object with a value of 
//

Fri
Dec
24
2010
00:00:00
GMT+0100

GMT+0000

4.1.3 4.2.4 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~~ BlankNode s should be explained in more detail.

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

~~] interface {~~

[NoInterfaceObject]
interface BlankNode : RDFResource {
    readonly attribute stringifier DOMString value;
};

Attributes

value of type stringifier DOMString , readonly: The temporary identifier of the ~~BlankNode.~~ 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~~ BlankNode will remain the same between two processing runs. ~~Blank Node~~ BlankNode values are only valid for the most recent processing run on the document. ~~Blank Nodes~~ BlankNode s values will often be generated differently by different RDFa Processors.

Example

This section is non-normative.

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

>> var bna = document.data.store.createBlankNode(); // create a new BlankNode A >> var bnb = document.data.store.createBlankNode(); // 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

// Create two new BlankNodes - A and B
var bna = document.data.store.createBlankNode();
var bnb = document.data.store.createBlankNode();
// BlankNode stringification changes from implementation to implementation// and between structured data extraction runs. Developers must not depend on // the stringified names of BlankNodes to be the same between implementations // or two different processing runs of a structured data processor.
var stra = bna.toString();
// The stringified representation of the BlankNode at this point could be// "_:1", "_:a", "_:blank_node_alpha", or any other unique identifier starting// with "_:"// Extract the unique values associated with BlankNode A and BlankNode B
var bnavalue = bna.value;
var bnbvalue = bnb.value;
// The two values above, bnavalue and bnbvalue, must not ever be allowed to// be the same. The values can be strings, integers or any other value that
//
easily
establishes
a
unique
identifier
for
the
BlankNode.

4.1.4 4.2.5 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~~ property , 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 RDF-TESTCASES ].

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]

[NoInterfaceObject, Null=Null]
interface RDFTriple {
    const unsigned long size = 3;
    readonly attribute RDFResource subject;
    readonly attribute IRI         property;
    readonly attribute RDFNode     object;
    getter RDFNode        get (in unsigned long index);
    stringifier DOMString toString ();
};

Attributes

object of type ~~Object~~ RDFNode , readonly: The object associated with the ~~RDFTriple.~~ RDFTriple.
No exceptions.
predicate property of type ~~Object~~ IRI , readonly: The ~~predicate~~ property associated with the ~~RDFTriple.~~ RDFTriple.
No exceptions.
subject of type ~~Object~~ RDFResource , readonly: The subject associated with the ~~RDFTriple.~~ RDFTriple.
No exceptions.

Methods

get

An index method to access subject, predicate, and object with indices from zero to two, respectively.

Parameter	Type	Nullable	Optional	Description
index	`unsigned long`	✘	✘

No exceptions.

Return type:


getter
RDFNode

toString

Converts this triple into a string in N-Triples notation.

No parameters.

No exceptions.

Return type:


stringifier
DOMString

Constants

size of type unsigned long: A constant used to define an RDFTriple as array of length three.

Example

This section is non-normative.

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

>> var triple = document.data.store.createTriple('http://www.example.com#foo', 'foaf:name', \ document.data.store.createPlainLiteral('foo')); //create a new RDFTriple >> print(triple.subject); // print the property subject of the RDFTriple http://www.example.com#foo >> print(triple.toString()); // stringify the RDFTriple <http://www.example.com#foo>

// Create a new RDFTriple with a PlainLiteral as the object
var triple = document.data.store.createTriple("http://www.example.com#manu", "foaf:name", \
   document.data.store.createPlainLiteral("Manu Sporny"));
// Adding the RDFTriple's subject to a string will automatically call the// toString() method for the RDFResource, which will serialize the IRI value// to a language-native string
var str = "Triple subject: " + triple.subject;
// At this point, str will be "Triple subject: http://www.example.com#manu"// You can also convert the entire triple to N-Triples format by making the// language implementation call the underlying toString() interface for RDFTriple.
var tstr = "N-Triples: " + triple;

//
At
this
point,
tstr
will
be
'N-Triples:
<http://www.example.com#manu>

<http://xmlns.com/foaf/0.1/name>
"foo"
.

"Manu
Sporny"
.'

4.2 4.3 The Structured Linked Data 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 Structured Data Interfaces:

~~Data Context~~ DataContext — A mechanism that greatly reduces the amount of code a developer must write to express IRIs and convert data.
~~Data Store~~ DataStore — An store containing a set of RDFTriple objects.
~~Data Parser~~ DataParser — An parser that is capable of parsing DOM Nodes and placing extracted data into a ~~Data Store.~~ DataStore.
~~Data Iterator~~ DataIterator — An iterator capable of incrementally filtering triples discovered via a ~~Data Parser.~~ DataParser.
~~Property Group~~ PropertyGroup — An associative array of all statements in a document about a single subject.
~~Data Query~~ DataQuery — Provides the capability of using a particular language to query and extract values from a ~~Data Store.~~ DataStore.

A class diagram of all of the basic Linked Data classes, attributes, methods and linkages in the sections to follow

Diagram of Linked Data Classes, Attributes, Methods and linkages.

4.2.1 4.3.1 Data Context

Processing RDF data involves the frequent use of unwieldy IRI references and frequent type conversion. The DataContext interface is provided in order to simplify contextual operations such as shortening IRIs and converting RDF data into native language datatypes.

It is assumed that this interface is created and available before a document is parsed for RDFa data. For example, while operating within a Browser Context, it is assumed that the following lines of code are executed before a developer has access to the RDFa ~~DOM~~ API methods on the document object:

~~document.data.context = new DataContext();~~

document.data.context = new DataContext();

document.data.context.setMapping("rdf", "http://www.w3.org/1999/02/22-rdf-syntax-ns#");
document.data.context.setMapping("xsd",
"http://www.w3.org/2001/XMLSchema-datatypes#");

In general, when a CURIE is resolved by the RDFa API or a TypedLiteral is converted to a native language type, the current DataContext stored in the DocumentData object must be used to perform the action. This is to ensure that there is only one active DataContext in use by the RDFa API at any given time. The default DataContext stored in the DocumentData object may be changed at runtime.

All of the code that sets up the default type converters for Browser Contexts that use ~~Javascript~~ ECMAScript should probably be in the code snippet above.

The following interface allows IRI mappings to be easily created and used by Web Developers at run-time. It also allows for conversion of RDF data into native language datatypes.

{

interface DataContext {
    void setMapping (in DOMString prefix, in DOMString iri);
    void registerTypeConversion (in DOMString iri, in TypedLiteralConverter converter);
    IRI  resolveCurie (in DOMString curie);
    any  convertType (in DOMString value, in optional DOMString inputType, in optional DOMString modifier);
};

Methods

convertType

Returns the native language value of the passed literal value as a language-native type. If the given value cannot be converted, the given value must be returned.

The return value upon conversion failure is being actively discussed in the RDFa WG. There are proposals to raise exceptions upon conversion failure, proposals to return tuples containing conversion success/failure and the converted value, as well as other mechanisms that would allow the signalling of a conversion failure from the method to calling code.

Parameter	Type	Nullable	Optional	Description
value	`DOMString`	✘	✘	The value to convert that is associated with the `TypedLiteral`.
inputType	`DOMString`	✘	✔	The input type for the `TypedLiteral` passed as a string. For example, `xsd:string` or `xsd:integer`.
modifier	`DOMString`	✘	✔	The developer-supplied modifier for the conversion. The string is a free-form, string that is used by the `TypedLiteralConverter` that is associated with the `inputType`. The RDFa Working Group is still discussing whether or not having a modifier is a good idea as 90% of use cases will never use it and the remaining use cases could provide the functionality with an external switch to the conversion function.

No exceptions.

Return type:

any

registerTypeConversion

Registers a type converter from given IRI datatype to a native language dataype in the current programming language.

Parameter	Type	Nullable	Optional	Description
iri	`DOMString`	✘	✘	A string specifying the IRI datatype. The string may be a CURIE. For example: `http://www.w3.org/2001/XMLSchema-datatypes#integer` or `xsd:integer`.
converter	`TypedLiteralConverter`	✘	✘	~~A function that converts~~ Converts the ~~TypedLiteral's~~ `TypedLiteral` 's value into a native language datatype in the current programming language.

No exceptions.

Return type:



void

resolveCurie

Resolves a given CURIE. If successful, returns an IRI or Null if the CURIE could not be resolved.

Parameter	Type	Nullable	Optional	Description
curie	`DOMString`	✘	✘	The CURIE that is to be resolved into an IRI.

No exceptions.

Return type:

IRI

setMapping

Registers a mapping from a prefix to an IRI . The given IRI must be a full IRI. For example, if a developer wants to specify the


foaf

IRI mapping, they would call


setMapping("foaf",
"http://xmlns.com/foaf/0.1/")

. Calling the


setMapping()

method with a prefix value that does not exist results in the creation of a new mapping. Calling the method with a null IRI value will remove the mapping.

Parameter	Type	Nullable	Optional	Description
prefix	`DOMString`	✘	✘	The prefix to put into the mapping as the key. (e.g., `foaf` )
iri	`DOMString`	✘	✘	The IRI reference to place into the mapping as the mapped value of the given prefix. (e.g., `"http://xmlns.com/foaf/0.1/")`

No exceptions.

Return type:



void

Easy IRI Mapping

All methods that accept CURIEs as arguments in the RDFa API must use the algorithm specified in RDFa Core, Section 7.4: CURIE and URI Processing [ RDFA-CORE ] for TERMorCURIEorURI . The prefix and term mappings are provided by the current document.data.context instance.

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

// Create a new mapping for the Friend-of-a-Friend vocabulary
document.data.context.setMapping("foaf", "http://xmlns.com/foaf/0.1/");
// The new mapping is automatically used when CURIEs are expanded to IRIs,// the following statement will return all the people in the document
var people = document.getItemsByType("foaf:Person");
// The following statement will result in the exact same list of PropertyGroups// as returned by the previous getItemsByType() call. Note that the only// difference is that this call uses a full IRI, while the call above uses a// CURIE
var
people2
=
document.getItemsByType("http://xmlns.com/foaf/0.1/Person");

In the example above, the CURIE " foaf:Person " is expanded to an IRI with the value " http://xmlns.com/foaf/0.1/Person " in the getItemsByType method.

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

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.

Specifing Typed Literal Converters

]

A TypedLiteralConverter may be implemented as a class, or as a language-native callback in languages like ECMAScript.

[NoInterfaceObject Callback]
interface TypedLiteralConverter {
    any convert (in DOMString value, in optional IRI inputType, in optional DOMString modifier);
};

Methods

convertType convert

Returns the native language value of the passed literal value as a language-native type. If the given value cannot be converted, the given value must be returned.

Parameter	Type	Nullable	Optional	Description
value	`DOMString`	✘	✘	The value to convert that is associated with the ~~RDFTypedLiteral.~~ `TypedLiteral`.
inputType	`IRI`	✘	✔	The input type for the `TypedLiteral` passed as an `IRI`. For example, `http://www.w3.org/2001/XMLSchema#string` or `http://www.w3.org/2001/XMLSchema#integer`.
modifier	`DOMString`	✘	✔	A developer-specified modifier used during the conversion. The string is a free-form string that is used by the developer-specified `convert()` method.

No exceptions.

Return type:



Any

any

Examples

~~IRI mappings for all terms in the~~ The following ~~vocabularies must be included: rdf~~ example demonstrates how a developer could register and ~~xsd . Easy IRI Mapping All methods that accept CURIEs as arguments in the RDFa DOM API must~~ use ~~the algorithm specified in RDFa Core, Section 7.4: CURIE and URI Processing [ RDFA-CORE ] for TERMorCURIEorURI . The prefix and term mappings are provided by the current~~ a document.data.context TypedLiteralConverter ~~instance.~~ .

~~Example~~

// Register a new type converter for the "xsd:boolean" type
document.data.context.registerTypeConversion("xsd:boolean", function(value) {return new Boolean(value);});

// Create a new TypedLiteral of type "xsd:boolean" with a string value of "1"
var literal = document.data.store.createTypedLiteral("1", "xsd:boolean");

This
section

// Convert the literal to a string
var lstr = literal.toString();
var lvalue = literal.value;
// At this point, lstr and lvalue will both be "1"// Get the language-native value of the literal
var lnvalue = literal.valueOf();
// At this point, the language-native value of the lnvalue variable will 
//
be
a
Boolean
type
whose
value

is
non-normative.

'true'.

The following ~~examples demonstrate~~ example demonstrates how ~~mappings are created~~ to create and ~~used via the RDFa DOM API. // create new IRI mapping document.data.context.setMapping("foaf", "http://xmlns.com/foaf/0.1/");~~ pass a // The new IRI mapping is automatically used when CURIEs are expanded to IRIs var people = document.getItemsByType("foaf:Person"); In the example above, the CURIE " foaf:Person " is expanded to an IRI with the value " http://xmlns.com/foaf/0.1/Person TypedLiteralConverter " function in ~~the getItemsByType method.~~ ECMAScript:

~~Example~~

var converter = function (value) { return new String(value) };
document.data.context.registerTypeConverter("xsd:string",
converter);

A ~~This section is non-normative.~~ TypedLiteralConverter ~~The following example demonstrates how a developer could register and use~~ can also specify a ~~TypedLiteralConverter.~~ target type for the converter so that one converter can be used for multiple types:

>> document.data.context.registerTypeConversion('xsd:boolean', function(value) {return new Boolean(value);}); >> var literal = document.data.store.createTypedLiteral('1', 'xsd:boolean'); >> print(literal.toString()); 1 >> print(literal.value); 1 >> print(literal.valueOf()); true

var converter = function(value, inputType, modifier) 
{
   if(inputType == "http://www.w3.org/2001/XMLSchema#integer")
   {
      // if the input type is xsd:integer, convert to an ECMAScript integer
      return parseInt(value);
   }
   else if(modifier == "caps")
   {
      // if the modifier is "caps" convert to a string and uppercase the       // return value
      return new String(value).toUpperCase();
   }
   else
   {
      // in all other cases, convert to a string
      return new String(value);
   }
};
// register the converter
document.data.context.registerTypeConverter("xsd:string", converter);
document.data.context.registerTypeConverter("xsd:integer", converter);
// Use the developer-defined TypedLiteralConverter to resolve the value to// a language-native type. In this example, airport codes are commonly// upper-cased values, so specify that the conversion should be capitalized.
var airportCode = document.data.context.convertType("wac", "xsd:string", "caps");

//
At
this
point,
the
value
of
airportCode
should
be
"WAC"

4.2.2 4.3.2 Data Store

The DataStore is a set of RDFTriple objects. It provides a basic getter as well as an indexed getter for retrieving individual items from the store. The ~~Data Store~~ DataStore can be used to create primitive types as well as store collections of them in the form of ~~RDFTriples.~~ RDFTriple s.

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.

{

[NoInterfaceObject]
interface DataStore {

    readonly attribute unsigned long size;
]
    

    getter RDFTriple get (in unsigned long index);
    boolean          add (in RDFTriple triple);
    IRI              createIRI (in DOMString iri, in optional Node node);
    PlainLiteral     createPlainLiteral (in DOMString value, in optional DOMString? language);
    TypedLiteral     createTypedLiteral (in DOMString value, in DOMString type);
    BlankNode        createBlankNode (in optional DOMString name);
    RDFTriple        createTriple (in RDFResource subject, in IRI property, in RDFNode object);
    [Null=Null]
    

    DataStore        filter (in optional Object? pattern, in optional Element? element, in optional RDFTripleFilter filter);
    void             clear ();
    void             forEach (in DataStoreIterator iterator);
    boolean          merge (in DataStore store);
};

Attributes

size of type unsigned long , readonly: A non-negative integer that specifies the size, in ~~RDFTriples,~~ RDFTriple s, of the store.
No exceptions.

Methods

add

Adds an


RDFTriple

to the ~~Data Store.~~


DataStore

. Returns True if the


RDFTriple

was added to the store successfully. Adding an


RDFTriple

that already exists in the


DataStore

must return True and must not store two duplicate triples in the


DataStore

Parameter	Type	Nullable	Optional	Description
triple	`RDFTriple`	✘	✘	The triple to add to the ~~Data Store.~~ `DataStore`.

No exceptions.

Return type:



boolean

clear

Clears all data from the store.

No parameters.

No exceptions.

Return type:



void

createBlankNode

Creates a ~~Blank Node~~


BlankNode

given an optional name value.

Parameter	Type	Nullable	Optional	Description
name	`DOMString`	✘	✔	The name of the ~~Blank Node,~~ `BlankNode`, which will be used when Stringifying the ~~Blank Node.~~ `BlankNode`.

No exceptions.

Return type:




BlankNode

createIRI

Creates an IRI given a value and an optional Node.

Parameter	Type	Nullable	Optional	Description
iri	`DOMString`	✘	✘	The IRI reference's lexical value.
node	`Node`	✘	✔	An optional DOM Node to associate with the IRI.

No exceptions.

Return type:

IRI

createPlainLiteral

Creates a ~~Plain Literal~~


PlainLiteral

given a ~~value, an optional language~~ value and an optional ~~DOM origin Node.~~ language.

Parameter	Type	Nullable	Optional	Description
value	`DOMString`	✘	✘	The value of the ~~IRI. The value can be either a full IRI or~~ `PlainLiteral`, which is usually a ~~CURIE.~~ human-readable string.
language	`DOMString`	✔	✔	The language that is associated with the ~~Plain Literal~~ `PlainLiteral` encoded according to the rules outlined in [ BCP47 ~~]. origin Node~~ ~~✘ ✔ The DOM Node that should be associated with the Plain Literal~~ ].

No exceptions.

Return type:




PlainLiteral

createTriple

Creates an ~~RDF Triple~~


RDFTriple

given a subject, ~~predicate~~ property and object. If any incoming value does not match the requirements listed below, a Null value must be returned by this method.

Parameter	Type	Nullable	Optional	Description
subject	`Object RDFResource`	✘	✘	The subject value of the ~~RDF Triple.~~ `RDFTriple`. The value must be either an IRI or a ~~BlankNode.~~ `BlankNode`.
~~predicate~~ property	`Object IRI`	✘	✘	The ~~predicate~~ property value of the ~~RDF Triple.~~ `RDFTriple`.
object	`Object RDFNode`	✘	✘	The object value of the ~~RDF Triple.~~ `RDFTriple`. The value must be an ~~IRI, PlainLiteral, TypedLiteral,~~ `IRI`,`PlainLiteral`,`TypedLiteral`, or ~~BlankNode.~~ `BlankNode`.

No exceptions.

Return type:




RDFTriple

createTypedLiteral

Creates a ~~Typed Literal~~


TypedLiteral

given a ~~value, a type~~ value and ~~an optional associated DOM Node.~~ a type. ~~origin Node ✘ ✔ The DOM Node to associate with the Typed Literal.~~

Parameter	Type	Nullable	Optional	Description
value	`DOMString`	✘	✘	The value of the ~~Typed Literal.~~ `TypedLiteral`.
type	`DOMString`	✘	✘	The IRI type of the ~~Typed Literal.~~ `TypedLiteral`. The argument can either be a full IRI or a CURIE.

No exceptions.

Return type:




TypedLiteral

filter

Returns an ~~DataStore,~~


DataStore

, which consists of zero or more


RDFTriple

objects.

The RDFa Working Group is debating whether the return value of the filter method should be a


DataStore

or a Sequence of


RDFTriple

s. DataStores allow much higher-level functions to be carried out versus a simple Sequence of


RDFTriple

s. However,


DataStore

s may be very memory intensive to construct and manage.

✘

Parameter Type Nullable Optional Description

Parameter	Type	Nullable	Optional	Description
~~subject~~ pattern	`Object`	✔	✔	~~The subject~~ A filter pattern that determines which triples to select from the `DataStore`. The filter pattern is provided to make it easy to perform complex filtering on subject, property and object by providing a very flexible data container to convey selection information. The implementation of the `pattern` parameter is designed to be easily implemented by data dictionaries or associative arrays, but should be done in a way that is natural to the implementation language. To ensure a similar programming environment, the variables to convey subject, property and object parameters should use keys or variables named "subject", "property" and "object", respectively. The subject parameter is used to filter `RDFTriple` objects. Values can be of type ~~IRI, BlankNode,~~ DOMString, `IRI`, or ~~Null.~~ `BlankNode`. If a DOMString is supplied, the API must convert the value into an IRI or `BlankNode` before comparison is performed. If the subject is ~~a non-Null value,~~ specified, the `RDFTriple` must not be placed in the final output Array unless the given subject matches the ~~RDFTriple's~~ `RDFTriple` 's subject. If a subject parameter is ~~set to Null,~~ not specified, the ~~filter~~ function must not reject any triple based on the ~~subject. predicate~~ subject unless specified by the `IRI ✔ ✔ RDFTripleFilter`. The ~~predicate filter pattern which~~ property parameter is used to filter `RDFTriple` objects. Values can be of type ~~IRI~~ DOMString or ~~Null.~~ `IRI`. If a DOMString is supplied, the ~~predicate~~ API must convert the value into an IRI before comparison is ~~a non-Null value,~~ performed. If the property is specified, the `RDFTriple` must not be placed in the final output Array unless the given ~~predicate~~ property matches the ~~RDFTriple's predicate.~~ `RDFTriple` 's property. If ~~predicate~~ a property parameter is ~~set to Null,~~ not specified, the ~~filter~~ function must not reject any triple based on the ~~predicate. object~~ property unless specified by the `Object ✔ ✔ RDFTripleFilter`. The object ~~filter pattern which~~ parameter is used to filter `RDFTriple` objects. Values can be of type ~~IRI, TypedLiteral, PlainLiteral, BlankNode,~~ DOMString, `BlankNode`,`PlainLiteral`,`TypedLiteral` or ~~Null.~~ `IRI`. If a DOMString is supplied, the API must convert the value into a `PlainLiteral` before comparison is performed. If the object is ~~a non-Null value,~~ specified, the `RDFTriple` must not be placed in the final output Array unless the given object matches the ~~RDFTriple's~~ `RDFTriple` 's object. If an object parameter is ~~set to Null,~~ not specified, the ~~filter~~ function must not reject any triple based on ~~object.~~ the object unless specified by the `RDFTripleFilter`.
element	`Node Element`	✔	✔	The parent DOM ~~Node~~ Element where filtering should start. The implementation must only consider RDF triples on the current DOM ~~Node~~ Element and its children.
filter	`RDFTripleFilter`	✘	✔	A user defined function, returning a true or false value, that determines whether or not an `RDFTriple` should be added to the final Array.

~~subject~~ pattern



Object

✔

~~The subject~~

A filter pattern that determines which triples to select from the DataStore. The filter pattern is provided to make it easy to perform complex filtering on subject, property and object by providing a very flexible data container to convey selection information. The implementation of the pattern parameter is designed to be easily implemented by data dictionaries or associative arrays, but should be done in a way that is natural to the implementation language. To ensure a similar programming environment, the variables to convey subject, property and object parameters should use keys or variables named "subject", "property" and "object", respectively.

The subject parameter is used to filter RDFTriple objects. Values can be of type ~~IRI, BlankNode,~~ DOMString, IRI, or ~~Null.~~ BlankNode. If a DOMString is supplied, the API must convert the value into an IRI or BlankNode before comparison is performed. If the subject is ~~a non-Null value,~~ specified, the RDFTriple must not be placed in the final output Array unless the given subject matches the ~~RDFTriple's~~ RDFTriple 's subject. If a subject parameter is ~~set to Null,~~ not specified, the ~~filter~~ function must not reject any triple based on the ~~subject. predicate~~ subject unless specified by the IRI ✔ ✔ RDFTripleFilter.

The ~~predicate filter pattern which~~ property parameter is used to filter RDFTriple objects. Values can be of type ~~IRI~~ DOMString or ~~Null.~~ IRI. If a DOMString is supplied, the ~~predicate~~ API must convert the value into an IRI before comparison is ~~a non-Null value,~~ performed. If the property is specified, the RDFTriple must not be placed in the final output Array unless the given ~~predicate~~ property matches the ~~RDFTriple's predicate.~~ RDFTriple 's property. If ~~predicate~~ a property parameter is ~~set to Null,~~ not specified, the ~~filter~~ function must not reject any triple based on the ~~predicate. object~~ property unless specified by the Object ✔ ✔ RDFTripleFilter.

The object ~~filter pattern which~~ parameter is used to filter RDFTriple objects. Values can be of type ~~IRI, TypedLiteral, PlainLiteral, BlankNode,~~ DOMString, BlankNode,PlainLiteral,TypedLiteral or ~~Null.~~ IRI. If a DOMString is supplied, the API must convert the value into a PlainLiteral before comparison is performed. If the object is ~~a non-Null value,~~ specified, the RDFTriple must not be placed in the final output Array unless the given object matches the ~~RDFTriple's~~ RDFTriple 's object. If an object parameter is ~~set to Null,~~ not specified, the ~~filter~~ function must not reject any triple based on ~~object.~~ the object unless specified by the RDFTripleFilter.

element Node Element ✔ ✔ The parent DOM ~~Node~~ Element where filtering should start. The implementation must only consider RDF triples on the current DOM ~~Node~~ Element and its children.

filter RDFTripleFilter ✘ ✔ A user defined function, returning a true or false value, that determines whether or not an RDFTriple should be added to the final Array.

No exceptions.

Return type:




DataStore

forEach

Calls the given callback for each item in the ~~Data Store.~~


DataStore

While the


forEach()

method is intended to provide a functional mechanism for iterating through a


DataStore

, it has been questioned whether the interface would be useful for developers since there is already a procedural array-index-based iteration mechanism built into a DataStore.

Parameter	Type	Nullable	Optional	Description
~~callback~~ iterator	`function DataStoreIterator`	✘	✘	A function that takes the following arguments: index, subject, ~~predicate,~~ property, object. The function is called for each item in the ~~Data Store.~~ `DataStore`.

No exceptions.

Return type:



void

get

Returns the


RDFTriple

object at the given index in the list.

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 ~~DataStore::length.~~ `DataStore`::length.

No exceptions.

Return type:



Object

getter
RDFTriple

merge

Merges all triples in an external


DataStore

into this


DataStore

. Duplicate triples must not be inserted into the same data store. Returns True if all triples were merged into the store successfully.

Parameter	Type	Nullable	Optional	Description
store	`DataStore`	✘	✘	The external `DataStore` to merge into this `DataStore`.

No exceptions.

Return type:


boolean

The DataStoreIterator interface is used by the forEach() method on the DataStore when processing all of the triples in a DataStore.

[NoInterfaceObject, Callback, Null=Null]
interface DataStoreIterator {
    void process (in int index, in RDFResource subject, in IRI property, in RDFNode object);
};

Methods

process

A callable function that takes an array index, subject, property, and object as arguments and processes each based on a developer-supplied algorithm.

Parameter	Type	Nullable	Optional	Description
index	`int`	✘	✘	The offset into the `DataStore` that contains the current `RDFTriple` being processed.
subject	`RDFResource`	✘	✘	The subject of the `RDFTriple` being processed.
property	`IRI`	✘	✘	The property associated with the `RDFTriple` being processed.
object	`RDFNode`	✘	✘	The object associated with the `RDFTriple` being processed.

No exceptions.

Return type:


void

~~Example~~

Examples

This section is non-normative.

The following examples ~~demonstrate the three~~ demonstrates two mechanisms that are available for navigating through a ~~DataStore;~~ DataStore ; index getter-based ~~iteration,~~ iteration and array index-based ~~iteration, and callback-based/functional~~ iteration.

>> var store = document.data.store.filter(); // select all RDF triples from the current Data Store >> print(store.size); // print the number of triples in the Data Store 3 >> for(var i=0; i<store.size; i++) { // loop through filtered RDF triples print(store.get(i)); // print RDF triple by using the explicit get method print(store[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 >> store.forEach(printObject); // call the callback function for each item in the array foo bar foobar

// Get all triples in the document.data.store object
var store = document.data.store.filter(); 
// Loop through the DataStore
for(var i = 0; i < store.size; i++) 
{
   // a developer may use the get() interface to retrieve a triple. This    // approach is called index getter-based iteration.
   var t1 = store.get(i);
   
   // alternatively, a developer may use the indexed-method of retrieving a   // triple from the DataStore. This approach is called array index-based   // iteration.
   var t2 = store[i];
}

The following example demonstrates a more functional mechanism that can be used to process each triple in a DataStore:

// Specify a callback function as defined by the DataStoreIterator// interface
function alertTriple(index, subject, property, object)
{
   alert("DataStore subject: " + subject + ", property: " + property + ", object: " + object);
}
// Iterate over the DataStore, executing the alertObject callback for each // triple in the DataStore.
document.data.store.forEach(alertTriple);

4.2.3 4.3.3 Data Parser

The ~~Data Parser~~ DataParser is capable of processing a DOM ~~Node~~ Element and placing the parsing results into a ~~Data Store.~~ DataStore. While this section specifies how one would parse RDFa data and place it into a ~~Data Store,~~ DataStore, the interface is also intended to support the parsing and storage of various Microformats, eRDF, GRDDL, DC-HTML, and Microdata. Web developers that would like to write customer parsers ~~may~~ should extend this interface.

{

[NoInterfaceObject]
interface DataParser {

    attribute DataStore store;
    [Null=Null]
    

    DataIterator iterate (in optional Object? pattern, in optional Element? element, in optional RDFTripleFilter filter);
    boolean      parse (in Element domElement);
};

Attributes

store of type DataStore: The DataStore that is associated with the ~~DataParser.~~ DataParser. The results of each parsing run will be placed into the store.
No exceptions.

Methods

iterate

Returns an ~~DataIterator,~~


DataIterator

, which is capable of iterating through a set of RDF triples, one


RDFTriple

at a time. The


DataIterator

is most useful in small memory footprint environments, or in documents that contain a very large number of triples.

It has been noted that having an stream-based mechanism of processing triples via the


iterate()

method, and a process-and-store-based mechanism for storing triples via the


parse()

method on the same interface is confusing. Each mechanism provides an alternate way of processing triples in a document. In the future,


iterate()

and


parse()

may be separated out into two distinct interfaces.

✘

Parameter Type Nullable Optional Description

Parameter	Type	Nullable	Optional	Description
~~subject~~ pattern	`Object`	✔	✔	~~The subject~~ A filter pattern that determines which triples to select from the `DataStore`. The filter pattern is provided to make it easy to perform complex filtering on subject, property and object by providing a very flexible data container to convey selection information. The implementation of the `pattern` parameter is designed to be easily implemented by data dictionaries or associative arrays, but should be done in a way that is natural to the implementation language. To ensure a similar programming environment, the variables to convey subject, property and object parameters should use keys or variables named "subject", "property" and "object", respectively. The subject parameter is used to filter `RDFTriple` objects. Values can be of type ~~IRI, BlankNode,~~ DOMString, `IRI`, or ~~Null.~~ `BlankNode`. If a DOMString is supplied, the API must convert the value into an IRI or `BlankNode` before comparison is performed. If the subject is ~~a non-Null value,~~ specified, the `RDFTriple` must not be ~~output via~~ placed in the ~~DataIterator~~ final output Array unless the given subject matches the ~~RDFTriple's~~ `RDFTriple` 's subject. ~~An IRI value must be either a full IRI or a CURIE.~~ If a subject parameter is ~~set to Null,~~ not specified, the ~~filter~~ function must not reject any triple based on the ~~subject. predicate~~ subject unless specified by the `DOMString ✔ ✔ RDFTripleFilter`. The ~~predicate filter pattern which~~ property parameter is used to filter `RDFTriple` objects. Values can be of type ~~IRI~~ DOMString or ~~Null.~~ `IRI`. If a DOMString is supplied, the ~~predicate~~ API must convert the value into an IRI before comparison is ~~a non-Null value,~~ performed. If the property is specified, the `RDFTriple` must not be ~~output via~~ placed in the ~~DataIterator~~ final output Array unless the given ~~predicate~~ property matches the ~~RDFTriple's predicate. An IRI value must be either a full IRI or a CURIE.~~ `RDFTriple` 's property. If ~~predicate~~ a property parameter is ~~set to Null,~~ not specified, the ~~filter~~ function must not reject any triple based on the ~~predicate. object~~ property unless specified by the `Object ✔ ✔ RDFTripleFilter`. The object ~~filter pattern which~~ parameter is used to filter `RDFTriple` objects. Values can be of type ~~IRI, TypedLiteral, PlainLiteral, BlankNode,~~ DOMString, `BlankNode`,`PlainLiteral`,`TypedLiteral` or ~~Null.~~ `IRI`. If a DOMString is supplied, the API must convert the value into a `PlainLiteral` before comparison is performed. If the object is ~~a non-Null value,~~ specified, the `RDFTriple` must not be ~~output via~~ placed in the ~~DataIterator~~ final output Array unless the given object matches the ~~RDFTriple's~~ `RDFTriple` 's object. ~~An IRI value must be either a full IRI or a CURIE.~~ If an object parameter is ~~set to Null,~~ not specified, the ~~filter~~ function must not reject any triple based on ~~object.~~ the object unless specified by the `RDFTripleFilter`.
element	`Node Element`	✔	✔	The parent DOM ~~Node~~ Element where filtering should start. The implementation must only consider RDF ~~Triples~~ triples on the current DOM ~~Node~~ Element and its children.
filter	`RDFTripleFilter`	✘	✔	A user defined function, returning a true or false value, that determines whether or not an `RDFTriple` should be ~~output via~~ added to the ~~DataIterator.~~ final Array.

~~subject~~ pattern



Object

✔

~~The subject~~

The subject parameter is used to filter RDFTriple objects. Values can be of type ~~IRI, BlankNode,~~ DOMString, IRI, or ~~Null.~~ BlankNode. If a DOMString is supplied, the API must convert the value into an IRI or BlankNode before comparison is performed. If the subject is ~~a non-Null value,~~ specified, the RDFTriple must not be ~~output via~~ placed in the ~~DataIterator~~ final output Array unless the given subject matches the ~~RDFTriple's~~ RDFTriple 's subject. ~~An IRI value must be either a full IRI or a CURIE.~~ If a subject parameter is ~~set to Null,~~ not specified, the ~~filter~~ function must not reject any triple based on the ~~subject. predicate~~ subject unless specified by the DOMString ✔ ✔ RDFTripleFilter.

The ~~predicate filter pattern which~~ property parameter is used to filter RDFTriple objects. Values can be of type ~~IRI~~ DOMString or ~~Null.~~ IRI. If a DOMString is supplied, the ~~predicate~~ API must convert the value into an IRI before comparison is ~~a non-Null value,~~ performed. If the property is specified, the RDFTriple must not be ~~output via~~ placed in the ~~DataIterator~~ final output Array unless the given ~~predicate~~ property matches the ~~RDFTriple's predicate. An IRI value must be either a full IRI or a CURIE.~~ RDFTriple 's property. If ~~predicate~~ a property parameter is ~~set to Null,~~ not specified, the ~~filter~~ function must not reject any triple based on the ~~predicate. object~~ property unless specified by the Object ✔ ✔ RDFTripleFilter.

The object ~~filter pattern which~~ parameter is used to filter RDFTriple objects. Values can be of type ~~IRI, TypedLiteral, PlainLiteral, BlankNode,~~ DOMString, BlankNode,PlainLiteral,TypedLiteral or ~~Null.~~ IRI. If a DOMString is supplied, the API must convert the value into a PlainLiteral before comparison is performed. If the object is ~~a non-Null value,~~ specified, the RDFTriple must not be ~~output via~~ placed in the ~~DataIterator~~ final output Array unless the given object matches the ~~RDFTriple's~~ RDFTriple 's object. ~~An IRI value must be either a full IRI or a CURIE.~~ If an object parameter is ~~set to Null,~~ not specified, the ~~filter~~ function must not reject any triple based on ~~object.~~ the object unless specified by the RDFTripleFilter.

element Node Element ✔ ✔ The parent DOM ~~Node~~ Element where filtering should start. The implementation must only consider RDF ~~Triples~~ triples on the current DOM ~~Node~~ Element and its children.

filter RDFTripleFilter ✘ ✔ A user defined function, returning a true or false value, that determines whether or not an RDFTriple should be ~~output via~~ added to the ~~DataIterator.~~ final Array.

No exceptions.

Return type:




DataIterator

parse

Parses starting at the given DOM Element and populates the


store

with the information that is discovered. If a starting element isn't specified, or the value of the starting element is Null, then the


document

object must be used as the starting element.

Even though a specific DOM Element can be specified to start the process of placing ~~RDFTriples~~


RDFTriple

s into the ~~DataStore,~~


DataStore

, the entire document must be processed by an RDFa Processor due to context that may affect the generation of a set of triples. Specifying the DOM Element is useful when a subset of the document data is to be stored in the ~~Data Store.~~


DataStore

There are two ways to approach this mechanism. The first is to only parse the sub-tree, ignoring the context of the greater document. The second is to parse the entire document, but only store triples that are a part of the sub-tree.

Parameter	Type	Nullable	Optional	Description
domElement	`Element`	✘	✘	The DOM Element that should trigger triple generation.

No exceptions.

Return type:



boolean

4.2.4 4.3.4 Data Iterator

The DataIterator interface ~~will almost certainly see large~~ may undergo changes in the next version of the RDFa API specification. Implementers are warned to not implement the interface and wait for the next revision of this specification.

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

A DataIterator is created by calling the document.data.parser.iterate() method.

{

[NoInterfaceObject]
interface DataIterator {

             attribute DataStore       store;
    readonly attribute Element         root;
    readonly attribute RDFTripleFilter filter;
    readonly attribute RDFTriple       triplePattern;
    RDFTriple next ();
};

Attributes

filter of type RDFTripleFilter , readonly: The RDFTripleFilter is a function that is provided by developers to filter ~~RDFTriples~~ RDFTriple s in a subtree.
No exceptions.
root of type ~~Node~~ Element , readonly: The DOM ~~Node~~ Element that was used as the starting point for extracting ~~RDFTriples.~~ RDFTriple s.
No exceptions.
store of type DataStore: The DataStore that is associated with the ~~DataIterator.~~ DataIterator.
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.

Methods

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

No exceptions.

Return type: RDFTriple

Example

This section is non-normative.

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

>> var iter = document.data.parser.iterate(); // iterate over all RDF triples from current Web document as an DataIterator >> 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 = document.data.parser.iterate("http://www.example.com#foo"); // iterate over triples associated with a single subject >>

// Get a DataIterator via the DataParser interface. A DataIterator allows 
// stream-based access to document data and does not store the matched
// triples into a DataStore. DataIterators are useful in environments where 
// memory is not plentiful and stream-based processing would reduce memory 
// usage.
var iter1 = document.data.parser.iterate();
// Iterate through each triple matched by the iterator
for(var triple = iter1.next(); triple != null; triple = iter1.next()) 
{
   // do something with the RDFTriple
}
// A developer may provide a pattern filter to use when filtering on subject.// The following iterator would only iterate on triples with a subject// of "http://www.example.com#foo"
var iter2 = document.data.parser.iterate( {"subject": "http://www.example.com#foo"} );
// A developer may also provide a pattern filter to use when filtering on property.// The following iterator would only iterate on triples with a property// of "http://xmlns.com/foaf/0.1/name"
var
iter3
=
document.data.parser.iterate(null,
"foaf:name");
//
iterate
over
all
triples
that
contain
a
foaf:name
predicate

document.data.parser.iterate(
{"property":
"foaf:name"}
);

4.2.5 4.3.5 Property Group

The PropertyGroup interface provides a view on a particular subject contained in the ~~Data Store.~~ DataStore. The PropertyGroup aggregates the ~~RDFTriples~~ RDFTriple s as a single language-native object in order to provide a more natural programming primitive for developers.

PropertyGroup attributes can be accessed in the following ways in ~~Javascript:~~ ECMAScript:

~~// creates a PropertyGroup for the given subject var person = document.getItemsBySubject("#bob");~~

// Retrieves a PropertyGroup for the given subject - since the IRI is
// fragment-relative, the document's IRI is used as the base IRI.
var person = document.getItemBySubject("#bob");

// Access the property group attribute via complete IRI
var name = person.get("http://xmlns.com/foaf/0.1/name");

// Access the PropertyGroup's name attribute via an IRI
var name1 = person.get("http://xmlns.com/foaf/0.1/name");
// Access the PropertyGroup's name attribute via a CURIE
var name2 = person.get("foaf:name");

//
At
this
point
name1
and
name2
are
equivalent

// Access the property group attribute via CURIE
var
name
=
person.get("foaf:name");

{

[NoInterfaceObject]
interface PropertyGroup {
    attribute Object info;    attribute IRI[]  properties;    Sequence get (in DOMString property);
};

Attributes

origin info of type ~~Element~~ Object: A developer-specific info object to associate with the PropertyGroup. The ~~DOM~~ info object must provide a property-based accessor mechanism for languages that support it, such as ECMAScript. For DOM-based environments, the Element that originated the PropertyGroup must be specified in a property called source in the ~~first type definition for this PropertyGroup.~~ info attribute.
No exceptions.
properties of type array of ~~Sequence[IRI]~~ IRI: A list of all attributes that are available via this ~~PropertyGroup.~~ PropertyGroup.
No exceptions.

Methods

get

Returns a sequence of IRIs, ~~BlankNodes, PlainLiterals,~~


BlankNode


PlainLiteral

s, and/or ~~TypedLiterals~~


TypedLiteral

s in the projection that have a ~~predicate~~ property IRI that is equivalent to the given value.

Parameter	Type	Nullable	Optional	Description
~~predicate~~ property	`DOMString`	✘	✘	A stringified IRI representing a ~~predicate~~ property whose values are to be retrieved from the ~~PropertyGroup.~~ `PropertyGroup`. For example, using a ~~predicate~~ property of `http://xmlns.com/foaf/0.1/name` will return a sequence of values that represent FOAF names in the ~~PropertyGroup.~~ `PropertyGroup`. The given ~~predicate~~ property may also be a CURIE.

No exceptions.

Return type:



Sequence[any]

Sequence

Example

This section is non-normative.

The following examples demonstrate how to use the PropertyGroup interface.

>> document.data.context.setMapping("foaf", "http://xmlns.com/foaf/0.1/"); >> var ivan = document.getItemBySubject("http://www.ivan-herman.net/foaf#me"); // extract information about this subject as an PropertyGroup >> print(ivan.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 >> ivan.get("foaf:name"); // named property values of foaf:name ["Herman Iván", "Ivan Herman"] >> ivan.get("foaf:title"); // named property values of foaf:title ["Dr."] >> ivan.get("foaf:workInfoHomepage"); // named property values of foaf:workInfoHomepage ["http://www.iswsa.org/", "http://www.iw3c2.org", "http://www.w3.org/2001/sw/#activity"]

// Get a PropertyGroup by subject. In this case, the PropertyGroup will 
// represent Ivan Herman, the current Semantic Web Activity Lead at the
// World Wide Web Consortium
var ivan = document.getItemBySubject("http://www.ivan-herman.net/foaf#me");
// Set the context mapping for the foaf prefix so that we can retrieve // properties using CURIEs
document.data.context.setMapping("foaf", "http://xmlns.com/foaf/0.1/");
// Get the names associated with Ivan Herman
var names = ivan.get("foaf:name");
// At this point, names will be a list containing two items, // ["Herman Iván", "Ivan Herman"], Ivan's Westernized name and Ivan's // native name.// Get the titles associated with Ivan Herman
var titles = ivan.get("foaf:title");
// At this point, the titles list will contain only a single item - ["Dr."]// Get all of the work homepages associated with Ivan
var pages = ivan.get("foaf:workInfoHomepage");
// At this point, the pages list will contain three entries:// "http://www.iswsa.org/", "http://www.iw3c2.org", and
//
"http://www.w3.org/2001/sw/#activity"

The Origin Source Pointer

~~document.getItemsByType() returns a list of Property Groups that match the query. By default there~~

The RDFa Working Group is ~~always a property called origin on~~ currently discussing the ~~Property Group and all~~ best mechanism to enable access to the DOMNode that contains a particular subject, predicate or object. While there have been several mechanisms that have been proposed, none of ~~its properties, which refers back~~ them are easy or straighforward to ~~an element~~ use. This mechanism will be modified heavily in the ~~source document. The origin property allows programmers to manipulate DOM objects based on~~ next version of the ~~embedded metadata that they refer to. For example,~~ document in order to ~~set~~ allow easier access to the DOMNode associated with a ~~thin blue border on each Person , we could do this:~~ particular piece of structured data:

~~var people = document.getItemsByType("foaf:Person");~~

var people = document.getItemsByType("foaf:Person");

 
for (var i = 0; i < people.length; i++) {
  people[i].origin.style.border = "1px solid blue";

  people[i].info("foaf:name", "source")[0].style.border = "1px solid blue";

}

Property Group Templates

A query can be used to retrieve not only basic ~~Property Groups,~~ PropertyGroup s, but can also specify how ~~Property Groups~~ PropertyGroup s are built by utilizing ~~Property Group~~ PropertyGroup Templates.

There has been a complaint that this section comes from out of nowhere. The purpose of this section is to describe that PropertyGroups can be mapped to native language objects to ease development. We may need to elaborate more on this at this point in the document to help integrate this section with the flow of the document.

For example, assume our source document contains the following event, marked up using the Google Rich Snippet Event format (example taken from the Rich Snippet tutorial, and slightly modified):

<div vocab="http://rdf.data-vocabulary.org/#" typeof="Event"> <a href="http://www.example.com/events/spinaltap" rel="v:url" property="summary">Spinal Tap</a> <img src="spinal_tap.jpg" rel="v:photo" /> <span property="description">After their highly-publicized search for a new drummer, Spinal Tap kicks off their latest comeback tour with a San Francisco show. </span> When: <span property="startDate" content="20091015T1900Z">Oct 15, 7:00PM</span>â€” <span property="endDate" content="20091015T2100Z">9:00PM</span>

<div prefix="v: http://rdf.data-vocabulary.org/#" typeof="v:Event"> 
  <a rel="v:url" href="http://amyandtheredfoxies.example.com/events" 
     property="v:summary">Tour Info: Amy And The Red Foxies</a>
  
  <span rel="v:location">
  	<a typeof="v:Organization" rel="v:url" href="http://www.kammgarn.de/" property="v:name">Kammgarn</a>
  </span>
  <div rel="v:photo"><img src="foxies.jpg"/></div>
  <span property="v:summary">Hey K-Town, Amy And The Red Foxies will rock Kammgarn in October.</span>
  When: 
  <span property="v:startDate" content="20091015T19:00">15. Oct., 7:00 pm</span>-
  <span property="v:endDate" content="20091015T21:00">9:00 pm</span>
  </span>
  Category: <span property="v:eventType">concert</span>

</div>

To query for all Event ~~Property Groups~~ PropertyGroup s we know that we can do this:

var
ar
=
query.select({
"rdf:type":
"http://rdf.data-vocabulary.org/#Event"
});

However, to build a special PropertyGroup that contains the summary, start date and end date, we need only do this:

~~var events = query.select({ "rdf:type": "http://rdf.data-vocabulary.org/#Event" },~~

var events = query.select({ "rdf:type": "http://rdf.data-vocabulary.org/#Event" },

                          {"rdf:type" : "type", "v:summary": "summary", 
"v:startDate":
"start",
"v:endDate":
"end"}
);

The second parameter is a ~~PropertyGroup~~ Property Group Template. Each key-value pair specifies an IRI to map to an attribute in the resulting PropertyGroup object.

Exposing the embedded data in each ~~Property Group~~ PropertyGroup makes it easy to create an HTML anchor that will allow users to add the event to their Google Calendar, as follows:

~~var anchor, button, i, pg;~~

var anchor, button, i, pg;

 
for (i = 0; i < events.length; i++) {
  // Get the Property Group:
  pg = events[i];

  // Get the PropertyGroup
  var event = events[i];

 
  // Create the anchor

  // Create the anchor
  anchor = document.createElement("a");
 
  // Point to Google Calendar

  // Point to Google Calendar
  anchor.href = "http://www.google.com/calendar/event?action=TEMPLATE"
    + "&text=" + pg.summary + "&dates=" + pg.start + "/" + pg.end;

    + "&text=" + event.summary + "&dates=" + event.start + "/" + event.end;

 
  // Add the button

  // Add the button
  button = document.createElement("img");
  button.src = "http://www.google.com/calendar/images/ext/gc_button6.gif";
  anchor.appendChild(button);
 
  // Add the link and button to the DOM object
  pg.origin.appendChild(anchor);

  // Add the link and button to the DOM object
  // NOTE: The next call will likely change in the next version of the RDF
  //       API specification as it is too difficult to use for most developers.
  event.info("rdf:type", "source")[0].appendChild(anchor);

}

The result will be that the event has an HTML a element at the end (and any Event on the page will follow this pattern):

~~<div vocab="http://rdf.data-vocabulary.org/#" typeof="Event">~~

<div vocab="http://rdf.data-vocabulary.org/#" typeof="Event">

  .
  .
  .
  <a href="http://www.google.com/calendar/event?action=TEMPLATE&text=Spinal+Tap&dates=20091015T1900Z/20091015T2100Z">

  <a href="http://www.google.com/calendar/event?action=TEMPLATE& →
text=Hey+K-Town,+Amy+And+The+Red+Foxies+will+rock+Kammgarn+in+October.&dates=20091015T1900Z/20091015T2100Z">

    <img src="http://www.google.com/calendar/images/ext/gc_button6.gif" />
  </a>
</div>

For more detailed information about queries see the ~~Data Query~~ DataQuery interface.

4.2.6 4.3.6 Data Query

The ~~Data Query~~ DataQuery interface provides a means to query a ~~Data Store.~~ DataStore. While this interface provides a simple mechanism for querying a ~~Data Store~~ DataStore for RDFa, it is expected that developers will implement other query interfaces that conform to this ~~Data Query~~ DataQuery interface for languages like SPARQL or other Domain Specific Language.

{

[NoInterfaceObject]
interface DataQuery {

    attribute DataStore store;
    Sequence select (in Object? query, in optional Object template);
};

Attributes

store of type DataStore: The DataStore that is associated with the ~~DataQuery.~~ DataQuery.
No exceptions.

Methods

select

Generates a sequence of ~~Property Groups~~


PropertyGroup

s that matches the given selection criteria.

Parameter	Type	Nullable	Optional	Description
query	`Object`	✔	✘	An associative array containing ~~predicates~~ properties as keys and objects to match as values. If the query is null, every item in the ~~Data Store~~ `DataStore` that the query is associated with must returned.
template	`Object`	✘	✔	A template describing the attributes to create in each ~~Property Group~~ `PropertyGroup` that is returned. The template is an associative array containing ~~predicates~~ properties as keys and attribute names that should be created in the returned `PropertyGroup` as values.

No exceptions.

Return type:



Sequence[PropertyGroup]

Sequence

4.3 4.4 The Document Interface

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 the Structured Data Interfaces sections. The following API is provided by this specification:

Document Interface Extensions — A set of extensions to the Document interface to help developers manage structured data in Web documents.
Document Data — The abstract container object for managing structured data in a Document.

4.3.1 4.4.1 Document Interface Extensions

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

{

[Supplemental, NoInterfaceObject]
interface RDFaDocument {
    readonly attribute DocumentData data;    DocumentData            createDocumentData ();    Sequence getItemsByType (in DOMString type);    PropertyGroup           getItemBySubject (in DOMString subject);    Sequence getItemsByProperty (in DOMString property, in DOMString value);    NodeList                getElementsByType (in DOMString type);    NodeList                getElementsBySubject (in DOMString subject);    NodeList                getElementsByProperty (in DOMString property, in DOMString value);
};

Attributes

data of type DocumentData , readonly: The DocumentData interface is useful for extracting and storing data that is associated with the Document.
No exceptions.

Methods

createDocumentData

Creates a


DocumentData

object and returns it. The object that is returned must have the


store


context


parser

and


query

attributes initialized to sensible defaults that would allow the immediate extraction of RDFa data from the current document by calling


DocumentData
.parser.parse(document)

No parameters.

No exceptions.

Return type:


DocumentData

getElementsByProperty

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

Parameter	Type	Nullable	Optional	Description
property	`DOMString`	✘	✘	A DOMString representing an IRI-based property. The string can either be a full IRI or a CURIE. ~~If the string is a CURIE, the DataContext will be used to resolve the value.~~
value	`DOMString`	✘	✘	A DOMString representing the value to match against.

No exceptions.

Return type:



NodeList

getElementsBySubject

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

Parameter	Type	Nullable	Optional	Description
subject	`DOMString`	✘	✘	A DOMString representing an IRI-based subject. The string can either be a full IRI or a CURIE. ~~If the string is a CURIE, the DataContext will be used to resolve the value.~~

No exceptions.

Return type:



NodeList

getElementsByType

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

Parameter	Type	Nullable	Optional	Description
type	`DOMString`	✘	✘	A DOMString representing an `rdf:type` to select against.

No exceptions.

Return type:



NodeList

getItemBySubject

Retrieves a


PropertyGroup

object based on its subject.

Parameter	Type	Nullable	Optional	Description
subject	`DOMString`	✘	✘	A DOMString representing an IRI-based subject. The string can either be a full IRI or a CURIE. ~~If the string is a CURIE, the DataContext will be used to resolve the value.~~

No exceptions.

Return type:


PropertyGroupList



PropertyGroup

getItemsByProperty

Retrieves a list of


PropertyGroup

objects based on the values of a property.

Parameter	Type	Nullable	Optional	Description
property	`DOMString`	✘	✘	A DOMString representing an IRI-based property. The string can either be a full IRI or a CURIE. ~~If the string is a CURIE, the DataContext will be used to resolve the value.~~
value	`DOMString`	✘	✘	A DOMString representing the value to match against.

No exceptions.

Return type:



PropertyGroupList

Sequence

getItemsByType

Retrieves a list of


PropertyGroup

objects based on their


rdf:type

property.

Parameter	Type	Nullable	Optional	Description
type	`DOMString`	✘	✘	A DOMString representing an `rdf:type` to select against.

No exceptions.

Return type:



PropertyGroupList

Sequence



Document

implements

RDFaDocument

;

All instances of the DOM Document interface must implement


RDFaDocument

4.4.2 DOMImplementation Extensions

If the RDFa API is implemented in a DOM environment and a DOMImplementation interface is provided, the following additional requirements for the hasFeature() method must be met:

interface DOMImplementation {    boolean hasFeature (in DOMString feature, in DOMString version);
};

Methods

hasFeature

Checks to see whether or not the ~~document object~~ DOM implementation has exposed all of the mandatory RDFa ~~DOM~~ API ~~feature.~~ features specified in this specification. An implementation that supports all of the mandatory features in this specification must return


true

for a feature string of "


RDFaAPI

" and a version string of "

1.1

Parameter	Type	Nullable	Optional	Description
feature	`DOMString`	✘	✘	The feature string to use when checking to see if the ~~Document interface has~~ DOM environment exposes all of the RDFa ~~DOM~~ API ~~interfaces. This value should be "~~ attributes and methods.
version	`rdfa 1.1 DOMString` ".	✘	✘	The version string to use when checking to see if the DOM environment exposes all of the RDFa API attributes and methods.

No exceptions.

Return type:



boolean

4.3.2 4.4.3 Document Data

The DocumentData interface is used to create structured-data related context, storage, parsing and query objects.

{

interface DocumentData {
    attribute DataStore   store;
    attribute DataContext context;
    attribute DataParser  parser;
    attribute DataQuery   query;
    DataContext createContext ();
    DataStore   createStore (in optional DOMString type);
    DataParser  createParser (in DOMString type, in DataStore store);
    DataQuery   createQuery (in DOMString type, in DataStore store);
};

Attributes

context of type DataContext ~~, readonly~~: The default DataContext for the document.
No exceptions.
parser of type DataParser ~~, readonly~~: The default DataParser for the document.
No exceptions.
query of type DataQuery ~~, readonly~~: The default DataQuery for the document.
No exceptions.
store of type DataStore ~~, readonly~~: The default DataStore for the document.
No exceptions.

Methods

createContext

Creates a


DataContext

and returns it.

No parameters.

No exceptions.

Return type:




DataContext

createParser

Creates a


DataParser

of the given type and returns it.

Parameter	Type	Nullable	Optional	Description
type	`DOMString`	✘	✘	The type of `DataParser` to create. ~~For example:~~ A value of " `rdfa` ". " must be accepted for all conforming implementations of this specification.
store	`DataStore`	✘	✘	The `DataStore` to associate with the ~~DataParser.~~ `DataParser`.

No exceptions.

Return type:




DataParser

createQuery

Creates a


DataQuery

for the given store.

Parameter	Type	Nullable	Optional	Description
type	`DOMString`	✘	✘	The type of query to create for the given store. A value of " `rdfa` " must be accepted for all conforming implementations of this specification. Implementations may provide alternative query interfaces, such as SPARQL, SQL, HQL, GQL, or other query languages to enable innovative new ways of querying the underlying storage mechanism.
store	`DataStore`	✘	✘	The `DataStore` to associate with the ~~DataQuery.~~ `DataQuery`.

No exceptions.

Return type:




DataQuery

createStore

Creates a


DataStore
of
the
given
type

and returns it. If the type is not specified, a


DataStore

must be created and returned. Alternatively, developers may provide other


DataStore

implementations such as persisted triple stores, quad stores, distributed graph stores and other more advanced storage mechanisms. The type determines the underlying


DataStore

that will be created. ✘

Parameter	Type	Nullable	Optional	Description
type	`DOMString`	✘	✔	The type of `DataStore` to create. A value of "triple" must be accepted for all conforming implementations of this specification. If the type is omitted, a value of "triple" must be assumed.

No exceptions.

Return type:




DataStore

4.3.3 4.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,~~ property, or object properties in RDF triples. This section also introduces the interfaces for the other filter types.

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.

]

[NoInterfaceObject, Callback, Null=Null]
interface RDFTripleFilter {
    boolean match (in RDFTriple triple);
};

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.

Parameter	Type	Nullable	Optional	Description
triple	`RDFTriple`	✘	✘	The triple to test against the filter.

No exceptions.

Return type:



boolean

Example

This section is non-normative.

The examples below use the following HTML code:

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

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

    <span property="dbp:conventionalLongName">Federal Republic of Germany</span>

  </div>
</div>

The parser.iterate() interface will almost certainly see large changes in the next version of the RDFa API specification. Implementers are warned to not implement the interface and wait for the next revision of this specification.

The following examples demonstrate the use of document.data.store.filter() and document.data.parser.iterate() in ~~JavaScript.~~ ECMAScript.

>> 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 store = document.data.store.filter(null, null, null, document.getElementById("start"), myFilter); >> store.forEach(function (triple) { print(triple)

// create a filter function that filters on triples with properties in the 
// foaf namespace.
function myFilter(element, subject, property, object)
{
   if(subject.value.search(/http:\/\/xmlns.com\/foaf\/0\.1/) >= 0)
   {
      return true;

   }
<http://dbpedia.org/resource/Albert_Einstein> <http://xmlns.com/foaf/0.1/name> "Albert Einstein"

}

// start filtering at the element with the id attribute whose value is "start"
// using the DataStore's filter() method
var store = document.data.store.filter({}, document.getElementById("start"), myFilter);
store.forEach(function (index, subject, property, object) { alert(object); });
// The code above will display one alert dialog box containing the following // text: "Albert Einstein".
// start filtering by iterating at element with id=start
>> var iter = document.data.parser.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>

// start filtering at the element with the id attribute whose value is "start"
// using the DataParser's iterate() method
var iter = document.data.parser.iterate({}, document.getElementById("start"), myFilter);
for(var triple=iter.next(); triple != null; triple = iter.next())
{
   alert(triple.object);
}
// The code above will display one alert dialog box containing the following 
//
text:

"Albert
Einstein"

Einstein".

RDFa API

An API for extracting structured data from Web documents

W3C Working Draft 08 June 23 September 2010

Abstract

How to Read this Document

Status of This Document

Table of Contents

1. Introduction

1.1 Importing Data

1.2 Enhanced Browser Interfaces

1.3 Data-based Web Page Modification

1.4 Automatic Summaries

1.5 Data Visualization

1.6 Linked Data Mashups

2. Design Considerations

2.1 Goals

2.2 Concept Diagram

3. Developing with the API

3.1 Basic Concepts

3.1.1 The Basic API

Retrieving Property Groups PropertyGroups

Retrieving DOM Elements

IRI Mapping

Advanced Processing

3.1.2 Using the Basic API

Working with Property Groups

Retrieving Property Groups PropertyGroups by Type

Retrieving Property Groups PropertyGroups by Subject

Retrieving Property Groups PropertyGroups by Property

Using Property Groups PropertyGroups

Managing Elements with Data

Retrieving Elements Containing Data by Type

Retrieving Elements Containing Data by Subject

Retrieving Elements by Property

Modifying DOM Elements

3.2 Advanced Concepts

3.2.1 Advanced Queries

Querying by Type

Querying by Property Value

3.2.2 Direct Access to the Data Store

3.2.3 Direct Access to the Parser Stream

3.2.4 Overriding the Defaults

Overriding the Data Store DataStore

Overriding the Data Parser

Overriding the Data Query

4. The Interfaces Specification

4.1 Conformance

4.2 The RDF Interfaces

4.1.1 4.2.1 IRI References RDFNode and RDFResource

Attributes

Attributes

4.2.2 IRI References

4.1.2 4.2.3 RDF Literals

PlainLiterals

Attributes

Example

Typed Literals

Attributes

Methods

Example

4.1.3 4.2.4 Blank Nodes

Attributes

Example

4.1.4 4.2.5 RDF Triples

Attributes

Methods

Constants

Example

4.2 4.3 The Structured Linked Data Interfaces

4.2.1 4.3.1 Data Context

Methods

Easy IRI Mapping

Automatic Type Conversion

Specifing Typed Literal Converters

Methods

Examples

4.2.2 4.3.2 Data Store

Attributes

Methods

Methods