RDFa API (original) (raw)

An API for extracting structured data from Web documents

W3C Working Group Note 05 July 2012

This version:

http://www.w3.org/TR/2012/NOTE-rdfa-api-20120705/

Latest published version:

http://www.w3.org/TR/rdfa-api/

Latest editor's draft:

http://www.w3.org/2010/02/rdfa/sources/rdfa-api/

Previous version:

http://www.w3.org/TR/2011/WD-rdfa-api-20110419/

Editors:

Manu Sporny, Digital Bazaar, Inc.

Benjamin Adrian, German Research Center for Artificial Intelligence GmbH

Authors:

Nathan Rixham, Invited Expert

Mark Birbeck, Sidewinder Labs

Ivan Herman, W3C

Copyright © 2010-2012 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.

Abstract

This document is not finished. Due to the lack of time, the RDF Web Applications Working Group was unable to complete work on this document before the end of their charter. At the time of publication of this document, it was not known whether W3C will continue this work on the Recommendation track in another Working Group. While a significant amount of design work went into this document, at present there is only one known implementation of the specification. A number of design issues have not been completely resolved. Developers wishing to implement this API should be aware of incomplete nature of the specification.

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 Application Programming Interface (RDFa 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 API. The document is primarily intended for the following audiences:

• User Agent developers that are providing a mechanism to programatically extract RDF data 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 ECMAScript, Python, Ruby, or Perl, and
• Developers that want to understand the inner workings and design criteria for the RDFa 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 API works in concert with how the data is expressed in a host language.

If you are not familiar with the RDF API, you should read about the Resource Description Framework Application Programming Interface [RDF-API] which is the base specification for this document. The [RDF-API] specification outlines fundamental programming concepts for working with Web-based data.

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

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 Interfaces 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 Interfaces defined in this specification that do not have bindings defined in the Web IDL specification should attempt to map the Interfaces 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 RDF Interfaces in the same langauge to ensure that implementations are modular and easily exchangable.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This document was published by the RDF Web Applications Working Group as a Note. If you wish to make comments regarding this document, please send them to public-rdfa@w3.org (subscribe, archives). All feedback is welcome.

Publication as a Working Group Note does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of Contents

• 1. Introduction
  • 1.1 Design Considerations
  • 1.2 Goals
  • 1.3 Concept Diagram
• 2. Developing with the API
  • 2.1 Basic Concepts
  • 2.2 Advanced Concepts
• 3. The Interfaces Specification
  • 3.1 Projections
  • 3.2 The Document Interface
  • 3.3 DOM Implementation Extensions
  • 3.4 Document Data
  • 3.5 RDFa Environment
• 4. The Initialization Process
• 5. Future Discussion
• A. Acknowledgements
• B. References
  • B.1 Normative references
  • B.2 Informative references

1. Introduction

This section is non-normative.

RDFa provides a means to enable machine-readable markup of structured data in human-readable Web documents. Structured data that is contained in documents, such as people, films, companies, events, and so on, can provide an added layer of information to Web Applications. The RDFa API provides a set of interfaces that make it easy to access structured data in Web documents.

A document that contains RDFa effectively provides two data layers. The first layer is the information about the document itself, such as the relationship between the elements, the value of its attributes, the origin of the document, and so on, and this information is usually provided by the Document Object Model, or DOM [DOM-LEVEL-1].

The second data layer comprises information provided by embedded metadata, such as company names, film titles, ratings, and so on, and this is usually provided by RDFa [RDFA-CORE], Microformats [MICROFORMATS], DC-HTML, GRDDL, or Microdata.

Whilst this embedded information could be accessed via the usual DOM interfaces -- for example, by iterating through child elements and checking attribute values -- the potentially complex interrelationships between the data mean that it is more efficient for developers if they have direct access to the data after it has been extracted.

For example, a document may contain the name of a person in one section and the phone number of the same person in another; whilst the basic DOM interfaces provide access to these two pieces of information through normal navigation, it is more convenient for authors to have these two pieces of information available in one object.

This specification defines the RDFa API, which may be used by developers and Web Applications to access structured data contained in Web documents.

1.1 Design Considerations

This section is non-normative.

RDFa 1.0 [RDFA-SYNTAX] has seen substantial growth since it became an official W3C Recommendation in October 2008. It has seen wide adoption among search companies, e-commerce sites, governments, and content management systems. There are numerous interoperable implementations and growth is expected to continue to rise with the latest releases of RDFa 1.1 [RDFA-CORE], XHTML+RDFa 1.1 [XHTML-RDFA], and HTML+RDFa 1.1 [HTML-RDFA].

In an effort to ensure that Web applications are able to fully utilize RDFa, this specification outlines an API and a set of interfaces that extract RDF data from Web documents and other document formats that utilize RDFa. The RDFa API is designed with maximum code expressiveness and ease of use in mind. Furthermore, a deep understanding of RDF and RDFa is not necessary in order to extract and utilize the structured data embedded in RDFa documents.

Since there are many Web browsers and programming environments for the Web, the rapid adoption of RDFa requires an interoperable API that Web document designers can count on being available in all Web browsers. The RDFa API provides a uniform and developer-friendly interface for extracting RDFa from Web documents.

Since most browser-based applications and browser extensions that utilize Web documents are written in ECMAScript [ECMA-262], the implementation of the RDFa API is primarily concerned with ensuring that concepts covered in this document are easily utilized in ECMAScript.

While ECMAScript is of primary concern, the _RDFa API_specification is language independent and is designed such that DOM tool developers may implement it in many of the other common Web programming languages such as Python, Java, Perl, and Ruby. Objects that are defined by the RDFa API are designed to work as seamlessly as possible with language-native types, operators, and program flow constructs.

1.2 Goals

The design goals that drove the creation of the APIs that are described in this document are:

Ease of Use and Expressiveness

While this should be a design goal for all APIs, special care is taken to ensure that developers can accomplish common tasks using a minimal amount of code. While execution speed is always an important factor to consider, it is secondary to minimizing the amount of work a developer must perform to extract and use data contained in the document.

Modularity and Pluggability

This high-level API is part of a larger family of lower-level APIs for interfacing with RDF data on the Web. Special care has been taken to ensure that this API can be implemented without requiring the larger family of APIs. If the larger family of APIs is available, however, this API fits in nicely with those RDF APIs.

DOM Orthogonality

Interfaces defined on the Document should match programming paradigms that are familiar to developers. For example, if one were to attempt to retrieve Element Nodes by Subject, the name of the method should be document.getElementsBySubject(), which roughly mirrors thedocument.getElementsByClassName() functionality that is a part of [DOM-LEVEL-1].

Native Language Constructs

Data is exposed and processed in a way that is natural for ECMAScript and many other Web programming languages like Python, Ruby and even C++. For example, Projections are exposed as native language constructs. Graphs can be iterated over by providing an anonymous function or function pointer. By ensuring that programming language constructs are considered in the design of the API, we ensure that the API won't fight the language and thus, the developer.

CURIEs and Templates

Some of the mechanisms that underpin RDF are difficult to use in everyday programming. For example, having to type out an entire URI is not only laborious for a programmer, but also error prone and overly-verbose. RDFa Core [RDFA-CORE] introduces the concept of a Compact URI Expression, or CURIE. This API builds on the CURIE concept and allows URIs to be expressed as CURIEs. The API should also provide short-cuts that reduce the amount of code that has to be repeated. Projection Templates are one example of reducing repetitive code writing as it can be stored in a single variable and re-used when building Projetions.

1.3 Concept Diagram

The following diagram describes the relationship between all concepts discussed in this document.

Concept Stack for the RDFa API and RDF API

The RDFa API is layered on top of concepts defined by the RDF API. The lowest level concepts are Triples, Graphs and Projections. Triples, Graphs and Projections are data structures used by Web Developers to work with data expressed in RDF languages. Working directly with the data structures can be cumbersome at times, such as the requirement to use absolute URIs when accessing properties, thus Profiles are provided to support accessing the data using compact URIs (CURIEs). Data Parsers and Data Serializers provide mechanisms to both read and write RDF data in a variety of RDF languages. All of these concepts are provided via a high-level interface called the RDF Environment.

API implementers should note that only the portions of the RDF API that are directly used by this API need to be implemented for a conforming RDFa API implementation. That is, only Projections are required to be implemented from the RDF API for a fully conformant RDFa API implementation.

The higher-level RDFa API provides two interfaces for accessing data in the document. Simple queries for DOM data may be performed using the Document interface, while more complex queries for structured data may be performed using the Document Data interface.

2. Developing with the API

This section is non-normative.

The following section provides an overview of the basic RDFa API that developers may find most useful in day-to-day programming exercises. An overview of the more advanced RDFa API is also provided, which may help developers when tackling some of the more complex RDFa programming tasks.

2.1 Basic Concepts

This section is non-normative.

This API provides a number of interfaces to enable:

• parsing Documents for RDFa metadata;
• retrieving Elements containing RDFa metadata;
• performing advanced queries on the Document and extracting application-specific Projections for use in Web Applications.

The Basic API

Many web developers will find that the basic functionality provided by the RDFa API is sufficient for day-to-day programming tasks. Since developers typically work with object-oriented data structures, the basic API is geared toward building language-native objects called Projections and returning them to the developer.

Retrieving Data in the Document

document.data.getSubjects(optional property, optional value)

Retrieves a list of all subjects expressed in the document that match the given arguments. If no arguments are provided, all subjects expressed in the document are returned.

document.data.getProperties(optional subject)

Retrieves a list of all properties expressed in the document that match the given subject. If a subject isn't provided, all properties expressed in the document are returned.

document.data.getValues(optional subject, optional property)

Retrieves a list of all values expressed in the document that match the given subject and property. If no arguments are provided, all values expressed in the document are returned.

document.data.getProjection(subject, optional template)

Retrieves a single Projection given a subject and an optional template. The template is used for the purposes of building the Projection in an application-specific way. To retrieve a Projection by a particular subject, one could do the following: document.data.getProjection("http://example.com/people#bob").

document.data.getProjections(optional property, optional value, optional template)

Retrieves a list of Projections given an optional property and value to match against. A template can be provided for the purposes of building the Projection in an application-specific way. To retrieve a list of Projections that contain the foaf:name property, one could do the following:document.data.getProjections("foaf:name").

Retrieving DOM Elements

document.getElementsByType(type)

Retrieves a list of DOM Nodes given a type to match against. The type is the rdf:type expressed in the DOM Node. The type can be expressed via the typeof, rel, rev or the property attribute.

document.getElementsBySubject(subject)

Retrieves a list of DOM Nodes given a subject to match against. The subject can be expressed via the about, href, src, or resource attribute.

document.getElementsByProperty(property, optional value)

Retrieves a list of DOM Nodes given a property and an optional value to match against. Properties can be expressed via the typeof, rel, rev or property attribute.

IRI Mapping

document.data.setMapping(mapping, iri)

Gets and sets short-hand IRI mappings that are used by the API. These mappings allow values such as foaf to be mapped to a longer IRI, for example: http://xmlns.com/foaf/0.1/. This mapping ensures that when a developer specifies a compact URI like foaf:Person, that it is expanded tohttp://xmlns.com/foaf/0.1/Person before it is used by the underlying API.

Advanced Processing

document.data.rdfa.query(query, optional template)

Retrieves an array of Projections based on a set of selection criteria. The template is used to build a language-native object that is specific to the needs of the developer and the application.

Using the Basic API

The following section uses the markup shown below to demonstrate how to extract and use subject, properties, values and Projections using the RDFa API. The following markup is used for the examples in this section and is assumed to be served from a document located at http://example.org/people.

Retrieving Basic Data

Often, developers must determine whether or not a document contains the type of data that they are interested in processing. The RDFa API provides a simple mechanism to extract things like subjects, properties and values from the current document. The return types for subjects and properties are always sequences of strings. Values are typically converted into language-native types. Strings and language-native types are used in order to make processing the data easier on the developer.

For example to get all of the subjects expressed in a document, one can use the following call:

var subjects = document.data.getSubjects();

To get the list of properties for each subject retrieved above, a developer could process each subject in a loop, like so:

for(var i = 0; i < subjects.length; i++) { var subject = subjects[i]; var properties = document.data.getProperties(subject); // ... process the properties ... }

To retrieve only subjects containing a particular property, such as a name property, a developer could do the following:

var subjectsWithNames = document.data.getSubjects("http://xmlns.com/0.1/foaf/name");

Once the subjects containing a particular property are known, queries can be done on each subject to retrieve the values of properties:

var namedSubject = subjectsWithNames[0]; var names = document.data.getValues(namedSubject, "http://xmlns.com/0.1/foaf/name");

To retrieve all values for a particular property, such as all of the names listed in the document, the following code could be executed:

var allNames = document.data.getValues(null, "http://xmlns.com/0.1/foaf/name");

There are many more combinations of arguments passed to the basic getter methods for subjects, properties and values that allow high-level querying of data in the document. While this method of working with data may be useful to many developers, others may want to construct this data into a more object-oriented view of the data. In order to support this scenario, the RDFa API introduces Projections in the next section.

Working with Projections

Retrieving Projections by Type

A Projection is an object-oriented view of a particular subject that is expressed in the document. For example, to get all projections that express people in a document, a developer can do the following:

var people = document.data.getProjections("http://www.w3.org/1999/02/22-rdf-syntax-ns#type", "http://xmlns.com/foaf/0.1/Person");

A developer can also specify short-cuts to use when specifying the URI:

document.data.setMapping("rdf", "http://www.w3.org/1999/02/22-rdf-syntax-ns#type"); document.data.setMapping("foaf", "http://xmlns.com/foaf/0.1/"); var people = document.data.getProjections("rdf:type", "foaf:Person");

Retrieving Projections by Subject

You can also get a Projection by its subject:

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

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

var albert = document.data.getProjection("#albert");

Retrieving Projections by Property

You can get a list of Projections by their properties:

var peopleNamedAlbert = document.data.getProjections("foaf:name", "Albert Einstein");

Using Projections

You can retrieve property values from Projections like so:

var albert = document.data.getProjection("#albert"); var name = albert.get("foaf:name");

You can specify values that you would like to map to a Projection:

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

The DOM may change between calls to any of the RDFa API data retrieval methods. These changes may cause subsequent calls to the same methods to return different results. As with any call against a DOM that is changing, developers are advised to program accordingly in order to avoid race conditions and other issues resulting from a changing data set.

Managing Elements with Data

Retrieving Elements Containing Data by Type

You can retrieve the DOM 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.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 the 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:

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.

2.2 Advanced Concepts

This section covers a number of concepts that go beyond basic day-to-day usage of the RDFa API.

Advanced Queries

Querying by Type

Perhaps the most basic task is to select Projections of a particular type. The type of a Projection is set in RDFa via the special attribute typeof. For example, the following markup expresses a Projection of type Person in the Friend-of-a-Friend vocabulary:

To locate all Projections that are people, we could use thedocument.getProjections() method:

document.data.getProjections("rdf:type", "foaf:Person");

or we could do the same using the standard query interface to retrieve aProjection:

var people = document.data.rdfa.query({"rdf:type": "foaf:Person"}, {"name": "foaf:name", "age": "foaf:age"});

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 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 people = document.data.rdfa.query( { "http://www.w3.org/1999/02/22-rdf-syntax-ns#type": "http://xmlns.com/foaf/0.1/Person" }, { "name": "http://xmlns.com/foaf/0.1/name", "age": "http://xmlns.com/foaf/0.1/age" });

Querying by Property Value

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

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

var architects = document.data.rdfa.query({ "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" }, { "name": "http://xmlns.com/foaf/0.1/name" });

var name = architects[0].name;

As before, prefix-mappings can also be used:

var architects = document.data.rdfa.query( { "rdf:type": "foaf:Person", "foaf:myersBriggs": "INTP" }, { "name": "foaf:name" });

var name = architects[0].name;

In this case, all of the "INTP" personality types are gleaned from the page and presented as Projections containing each person's name and blog page:

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

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

Creating Projections

Developers may find that they need to be able to build custom, language-native objects to use with their code. These specialized language-native objects are called _Projection_s, and can be built by utilizing Projection Templates.

There has been a complaint that this section comes from out of nowhere. The purpose of this section is to describe that Projections 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 Data Vocabulary Event format:

Tour Info: Amy And The Red Foxies Kammgarn

Hey K-Town, Amy And The Red Foxies will rock Kammgarn in October. When: 15. Oct., 7:00 pm- 9:00 pm

Category: concert

To query for all Event Projections we know that we can do this:

var events = document.data.getProjections("rdf:type", "http://rdf.data-vocabulary.org/#Event");

However, to build a special Projection that contains the summary, start date and end date, we can also do this:

var events = document.data.rdfa.query( { "rdf:type": "http://rdf.data-vocabulary.org/#Event" }, { "type": "rdf:type", "summary": "v:summary", "start": "v:startDate", "end": "v:endDate" } );

The second parameter is a Projection Template. Each key-value pair specifies a Projection property to URI mapping. That is, the key is the name of the property to create in the Projection object. The value must exist in a triple, specifically as a property of the triple, in order to copy the the object value of the triple over to the value of the Projection object's property.

For more detailed information about queries and Projections see the DocumentData interface.

3. The Interfaces Specification

The following section contains all of the interfaces that RDFa API implementers are expected to provide as well as guidance to ensure that implementations are conformant.

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 are not necessarily 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 [WEBIDL], as this specification uses that specification's terminology.

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 API implementations are modular and easily replaceable.

3.1 Projections

The Projection interface is used to build language-native objects that can be accessed in a way that is natural for the implementation language.

[NoInterfaceObject] interface Projection { DOMString[] getProperties (); DOMString getSubject (); any getter get (DOMString uriOrCurie); any[] getAll (DOMString uriOrCurie); };

Methods

get

Retrieves the first property with the given name as a language-native datatype.

getAll

Retrieves the list of values for a property as an array of language-native datatypes.

Return type: any[]

getProperties

Retrieves the list of properties that are available on the Projection. Each property must be an absolute URI.

No parameters.

getSubject

Retrieves the subject URI of this Projection as a string, the value must be an absolute URI.

No parameters.

3.2 The Document Interface

The RDFa API is designed to provide a small, powerful set of document-based interfaces that a developer may use to retrieve Projections from a Web document. This section focuses on the extensions necessary to the DOM environment. These extensions are separated into four interfaces:

• Document Interface Extensions — A set of basic extensions to the Document interface to help developers identify DOM Nodes containing structured data in Web documents.
• DOM Implementation Extensions — An extension to the DOM Implementation that allows developers to query for functionality provided by the RDFa API.
• Document Data — The high-level interface for providing access to structured data in documents.
• RDFa Environment — The high-level interface for performing advanced queries and parsing of RDFa documents.

Document Interface Extensions

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

Document implements DataDocument;

All instances of the DOM Document interface must implement DataDocument.

The DataDocument interface provides necessary extensions to the core DOM Document interface to enable the processing and storage of structured data.

[Supplemental, NoInterfaceObject] interface DataDocument { readonly attribute DocumentData data; NodeList getElementsByType (DOMString type); NodeList getElementsBySubject (DOMString subject); NodeList getElementsByProperty (DOMString property, optional DOMString? value); };

Attributes

data of type DocumentData, readonly

The DocumentData interface is useful for extracting and storing data that is associated with the Document.

Methods

getElementsByProperty

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

getElementsBySubject

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

getElementsByType

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

3.3 DOM Implementation 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 (DOMString feature, DOMString version); };

Methods

hasFeature

Checks to see whether or not the DOM implementation has exposed all of the mandatory RDFa API 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".

3.4 Document Data

The DocumentData interface is used to access the structured data in the document.

[NoInterfaceObject] interface DocumentData { attribute optional RDFEnvironment rdf; attribute RDFaEnvironment rdfa; Projection getProjection (DOMString subject, optional object template); Sequence getProjections (optional object template); Sequence getProjections (optional DOMString property, optional DOMString? value, optional object template); Sequence getProperties (optional DOMString? subject); Sequence getSubjects (optional DOMString? property, optional DOMString? value); Sequence getValues (optional DOMString? subject, optional DOMString? property); DOMString setMapping (in DOMString mapping, in DOMString uri); };

Attributes

rdf of type optional RDFEnvironment

The interface to the RDF convenience methods and functionality. Implementations may omit access to the underlying RDF implementation. If implementations include this attribute, they must conform to the [RDF-API] specification.

rdfa of type RDFaEnvironment

The RDFa Environment interface provides RDFa-specific capabilities.

Methods

getProjection

Retrieves a Projection given a subject and an optional Projection template if the subject exists in the document. If the subject does not exist in the document, null is returned.

Return type: [Projection](#idl-def-Projection)

getProjections

Retrieves a list of all Projections in the document using the optional Projection template to build the Projections.

getProjections

Retrieves a list of Projections that match the given optional property and value, constructed using the given Projection template.

getProperties

Retrieves a list of DOMStrings which are IRI identifiers for properties given an optional subject to match against.

getSubjects

Retrieves a list of DOMStrings which are IRI identifiers for subjects given an optional property and value to match against.

getValues

Retrieves a list of mixed types given an optional subject and property to match against.

setMapping

Sets a mapping given a mapping and a URI to map.

3.5 RDFa Environment

The RDFaEnvironment interface is used to perform RDFa-specific actions.

[NoInterfaceObject] interface RDFaEnvironment { Sequence query (optional object? query, optional object template); };

Methods

query

Generates a sequence of Projections that match the given selection criteria.

4. The Initialization Process

The RDFa API must be initialized before the Web developer has access to any of the methods that are defined in this specification. To initialize the API environment in a Browser-based environment, an implementor must do the following:

1. Initialize all of the interfaces in the DOM environment required by this specification.

Unless otherwise specified, the document base is effectively the value of window.location.toString().

5. Future Discussion

This section is non-normative.

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

• An event mechanism for receiving Triple modification notifications, if changes occur in the DOM.
• A mechanism for adding RDFa data into existing DOM content other than the direct modification of elements to add RDFa attributes.

A. Acknowledgements

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

• Ben Adida, Mozilla
• Benjamin Adrian, German Research Center for Artificial Intelligence (DFKI) Gmbh
• Mark Birbeck, webBackplane.com (Invited Expert)
• Markus Gylling, DAISY Consortium
• Ivan Herman, W3C
• Toby Inkster (Invited Expert)
• Shane McCarron, Applied Testing and Technology, Inc. (Invited Expert)
• Knud Möller, DERI Galway at the National University of Ireland
• John O'Donovan, British Broadcasting Corporation
• Steven Pemberton, Centre for Mathematics and Computer Science (CWI)
• Nathan Rixham (Invited Expert)
• Manu Sporny, Digital Bazaar (Chair, Invited Expert)
• Thomas Steiner, Google
• Robert Weir, IBM Corporation

B. References