RDF enables information providers to attach general metadata to published web resources. This metadata intends to be machine-interpretable so that web developers can access it by programming languages in order to create applications for i.e., crawling, aggregating, summarizing, or highlighting contained information. While publishing RDF data on the web 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, the RDF Application Programming Interface (RDF API) defines a set of standardized interfaces for working with RDF data in a web-based programming environment.

How to Read this Document

This document is a detailed specification for the RDF API. The document is primarily intended for the following audiences:

RDF Library writers.
Advanced RDF users.
RDF API extension developers.

If you are not familiar with RDF, you should read about the Resource Description Framework (RDF) [[RDF-CONCEPTS]] before reading this document.

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 any part of the RDF 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 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.

Introduction

RDF provides a means to publish and exchange machine-readable data about resources on the Web. A Web document can be attached with metadata in RDF in order to add a machine-interpretable layer underneath the document's content which is intended to be read by humans. By publishing RDF conform to the principles of Linking Open Data metadata about resources can be interlinked across different Web servers. This enables web developers to process published metadata about for example a News article and combine it with additional information from other sources.

This specification defines the RDF API, which may be used by developers and Web Applications to access and work with RDF data on the Web, while programing in a Web environment. The RDF API is designed to define a standardized programming interface for processing RDF within a Browser environment. The primary target language for the RDF API is ECMAScript, although other languages may also be considered.

Design Considerations

More and more information providers put RDF data to published Web content. Although a variety of Web browsers have been extended to enable RDF support for viewing, browsing, collecting, and aggregating existing RDF data, a common programming interface for processing RDF data similarly across different programming languages, like it is possible for XML, is still missing.

This specification defines all necessary means for processing RDF within a Browser environment. The RDF API comprises the following functionalities:

Concept Stack for the RDF API

RDF Concept Interfaces

Represents and wraps the various RDF Concepts

RDF object wrappers

The RDF API provides data structures that wrap RDF language concept. This provides developers with an abstraction layer for processing native RDF language concepts such as IRIs, literals, triples, graphs with standardized object interfaces that can be declared by the programming language that implements the RDF API.

RDF graph storage

The graph storage allows developers to store and access objects holding RDF data within a single storage interface.

RDF Environment Interfaces

Provide all basic methods required to work with RDF data.

RDF factories

The factory interfaces allow developers to create new object that wrap native RDF data.

Convenient methods

Methods that allow developers to solve problems with minimal lines of code.

RDF Data Interfaces

Set of modular interfaces covering common areas of functionality.

RDF parser

The parser interface enables developers to transform native RDF data of various serializations such as RDFXML, NTriples, Turtle, RDF in JSON, or RDFa in HTML into objects of the programming language.

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.
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, 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.
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. The API should also provide short-cuts that reduce the amount of code that has to be repeated.
Compliance with RDF libraries: The RDF API is not the first API that allows the processing of RDF data within a programming language. The goal of this API collect and preserve the best practices in programming with RDF that were already approved in existing libraries and standardize these in a single specification.
Linking Open Data: The capability of combining RDF data from distributed web servers with standard Web technologies is seen as a grounding use case of the RDF API. This API is going to provide web developers with method to create linked data mashups within a minimal amount of lines of code.
Wrapping other data formats: The intention of the RDF API is not only to provide programming facilities to native RDF data, but also to transform parser results of other approved data formats such as Microdata and Microformats to RDF concepts.

Examples and use cases

The following list of examples outlines common use cases that can be solved by using the RDF API:

Render RDF data in HTML

Susan is a Web developer in a company that offers calendar solutions. She is responsible for creating a web client that connects with the REST API of her company's calendar server. This RESTful API uses RDF as input-output format. Susan wants to use the RDF API to parse the RDF data the system returns for each of her JSON requests. In detail, she wants to render an interactive timeline and populate it with events that are described in this RDF data.


//dictionary to store event objects
events = {}

// filter that create events  
createEvents = new function(graph) {
	graph.forEach( function(t) {
	  	events[t.subject][t.predicate] = t.object;	
	  });
}

// create term for URI
prefixes.cal = "http://www.w3.org/2002/12/cal#";

// Restful API endpoint to calendar service
apiEndpoint = "http://example.org/calendar/susan/events/";

// parse requested RDF result represented in TURTLE
turtle.parse(apiEndpoint, new function(graph) {
	graph.filter( rdf.filters.type( rdf.resolve("cal:Vevent") )
	    .forEach( function(t) {
	      // iterate over the results, creating a filtered graph for each subject 
	      // found of type Event and pass that graph to the createEvents() function
	      createEvents( graph.filter( rdf.filters.s(t.subject) );
	    
	      // pass created event objects to timeline function
	      renderHTMLTimeline(events);
	    });
});

Gather RDF data within a user session

Pete is an entrepeneur who owns a Web shop where he offers MP3 encoded songs and movies. The content management system thta Pete used as base technology creates RDFa markup for each offered product, product category, and user profiles. Now Pete wants to offer customers an RDF powered shopping cart and browsing history. While browsing through his shop, users can visit products and add these to their shopping cart. Pete plans to implement a recommender algorithms in Javascript that runs local on the customer's browser and processes the RDF data contained in the user's shopping cart and history. Customer's may link their user profile to those of friends. The algorithm also requests shopping histories of these linked friends in order to improve recommender results. Because all the programming logic runs client-side on the customers' browsers, Pete saves server costs and can advertise his job as preserving the customers' privacy. The RDF API offers Pete an all-in-one interface for developing the RDF related software modules.

TODO

Create linked data mashups

Max is a passionate crime author and Web developer. He offers his books in EPUB format and annotates places, persons, companies, and event in his stories with RDFa markup. Pete has developed a Web-based e-book reader and now plans to provide his fans with additional information about occuring scenes, persons, companies, or events by rendering maps, exciting vitas, company logos, etc. He wants to use the RDF API to request and handle background information from DBpedia, Freebase and other data providers.

TODO

The RDF API 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.

Terms, Prefixes and Profiles

Within a programming context, and within various RDF serializations, it is increasingly important to be able to simplify access to properties and refer to full IRIs by using CURIEs or Terms.

In order to accomplish this a Profile of Prefix and Term mappings is needed.

This specification includes the definition of three Interfaces which serve to address these needs:

PrefixMap - which is a map of prefixes to IRIs, and provides methods to turn one in to the other.
TermMap - which is a map of simple string terms to IRIs, and provides methods to turn one in to the other.
Profile - which contains a PrefixMap and a TermMap, and provides an easy to use context for negotiating between CURIEs, Terms and IRIs.

Prefix Maps

omittable getter DOMString get(in DOMString prefix)

DOMString prefix: The prefix MUST not contain any whitespace

omittable setter void set(in DOMString prefix, in DOMString iri)

DOMString prefix: The prefix MUST not contain any whitespace
DOMString iri: An IRI, as defined by [[!IRI]]

omittable deleter void remove(in DOMString prefix)

DOMString prefix: The prefix MUST contain any whitespace

DOMString resolve(in DOMString curie)

Given a valid CURIE for which a prefix is known (for example "rdfs:label"), this method will return the resulting IRI (for example "http://www.w3.org/2000/01/rdf-schema#label")

If the prefix is not known then this method will return null.

DOMString curie: The CURIE to resolve.

DOMString shrink(in DOMString iri)

Given an IRI for which a prefix is known (for example "http://www.w3.org/2000/01/rdf-schema#label") this method returns a CURIE (for example "rdfs:label"), if no prefix is known the original IRI is returned.

DOMString iri: The IRI to shrink to a CURIE

void setDefault(in DOMString iri)

DOMString iri: The iri to be used when resolving CURIEs without a prefix, for example ":this".

PrefixMap import(in PrefixMap prefixes, in optional boolean override)

This method returns the instance on which it was called.

PrefixMap prefixes: The PrefixMap to import.
optional boolean override: If true then conflicting prefixes will be overridden by those specified on the PrefixMap being imported, by default imported prefixes augment the existing set.

Example

This example illustrates how PrefixMap can be used to resolve known CURIEs to IRIs, shrink IRIs in to CURIEs, and how to specify and use a default prefix.

Term Maps

omittable getter DOMString get(in DOMString term)

DOMString term: The term MUST not contain any whitespace or the : (single-colon) character

omittable setter void set(in DOMString term, in DOMString iri)

DOMString term: The term MUST not contain any whitespace or the : (single-colon) character
DOMString iri: An IRI, as defined by [[!IRI]]

omittable deleter void remove(in DOMString term)

DOMString term: The term MUST not contain any whitespace or the : (single-colon) character

DOMString resolve(in DOMString term)

Given a valid term for which an IRI is known (for example "label"), this method will return the resulting IRI (for example "http://www.w3.org/2000/01/rdf-schema#label").

If no term is known and a default has been set, the IRI is obtained by concatenating the term and the default iri.

If no term is known and no default is set, then this method returns null.

DOMString term: The term to resolve.

DOMString shrink(in DOMString iri)

Given an IRI for which an term is known (for example "http://www.w3.org/2000/01/rdf-schema#label") this method returns a term (for example "label"), if no term is known the original IRI is returned.

DOMString iri: The IRI to shrink to an term

void setDefault(in DOMString iri)

DOMString iri: The default iri to be used when an term cannot be resolved, the resulting IRI is obtained by concatenating this iri with the term being resolved.

TermmMap import(in TermMap terms, in optional boolean override)

This method returns the instance on which it was called.

TermMap terms: The TermMap to import.
optional boolean override: If true then conflicting terms will be overridden by those specified on the TermMap being imported, by default imported terms augment the existing set.

Example

This example illustrates how TermMap can be used to resolve known terms to IRIs, shrink IRIs for known terms in to terms, and how to specify and use a default vocabulary for unknown terms.

Profiles

Profiles provide an easy to use context for negotiating between CURIEs, Terms and IRIs.

readonly attribute PrefixMap prefixes

An instance of PrefixMap

readonly attribute TermMap terms

An instance of TermMap

DOMString resolve(in DOMString toresolve)

Given an Term or CURIE this method will return an IRI, or null if it cannot be resolved.

If toresolve contains a : (colon) then this method returns the result of calling prefixes.resolve(toresolve)

otherwise this method returns the result of calling terms.resolve(toresolve)

DOMString toresolve: A string Term or CURIE.

void setDefaultVocabulary(in DOMString iri)

This method sets the default vocabulary for use when resolving unknown terms, it is identical to calling the setDefault method on terms.

DOMString iri: The IRI to use as the default vocabulary.

void setDefaultPrefix(in DOMString iri)

This method sets the default prefix for use when resolving CURIEs without a prefix, for example ":me", it is identical to calling the setDefault method on prefixes.

DOMString iri: The IRI to use as the default prefix.

void setTerm(in DOMString term, in DOMString iri)

This method associates an IRI with a term, it is identical to calling the set method on term.

DOMString term: The term to set, MUST not contain any whitespace or the : (single-colon) character
DOMString iri: The IRI to associate with the term.

void setPrefix(in DOMString prefix, in DOMString iri)

This method associates an IRI with a prefix, it is identical to calling the set method on prefixes.

DOMString prefix: The prefix to set, MUST not contain any whitespace.
DOMString iri: The IRI to associate with the prefix.

Profile importProfile(in Profile profile, in optional boolean override)

This method functions the same as calling prefixes.import(profile.prefixes, override) and terms.import(profile.terms, override), and allows easy updating and merging of different profiles, such as those exposed by parsers.

This method returns the instance on which it was called.

Profile profile: The Profile to import.
optional boolean override: If true then conflicting terms and prefixes will be overridden by those specified on the Profile being imported, by default imported terms and prefixes augment the existing set.

Projections

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.

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

DOMString[] getProperties()

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

DOMString getSubject()

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

any getter get()

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

DOMString uriOrCurie: The name of the property to retrieve. The argument can be either an absolute URI or a CURIE that will be resolved using the default document mapping.

any[] getAll(in uriOrCurie)

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

DOMString uriOrCurie: The name of the property to retrieve. The argument can be either a full URI or a CURIE that will be resolved using the default document mapping.

RDF Environment

The RDF Environment is an interface which exposes a high level API for working with RDF in a programming environment, an instance of this interface MUST be exposed by an rdf attribute by libraries implementing the RDF API. For example:

mylib.rdf
data.rdf

The RDF Environment interface extends Profile and provides the default context for working with CURIEs, Terms and IRIs, implementations are encouraged to offer rich prefix maps by default, and MUST instantiate the environment with the following prefixes defined:

Prefix	IRI
owl	http://www.w3.org/2002/07/owl#
rdf	http://www.w3.org/1999/02/22-rdf-syntax-ns#
rdfs	http://www.w3.org/2000/01/rdf-schema#
rdfa	http://www.w3.org/ns/rdfa#
xhv	http://www.w3.org/1999/xhtml/vocab#
xml	http://www.w3.org/XML/1998/namespace
xsd	http://www.w3.org/2001/XMLSchema#

This interface also exposes all methods required to create instances of TermMaps, PrefixMaps, Profiles and all the Concept Interfaces.

Implementations MUST expose all the methods defined on this interface, as defined by this specification.

Future RDF API extensions and modules SHOULD supplement this interface with methods and attributes which expose the functionality they define, in a manner consistent with this API.

Profile createProfile(in optional boolean empty)

optional boolean empty: If true is specified then a profile with an empty TermMap and PrefixMap will be returned, by default the Profile returned will contain populated term and prefix maps replicating those of the current RDF environment.

TermMap createTermMap(in optional boolean empty)

optional boolean empty: If true is specified then an empty TermMap will be returned, by default the TermMap returned will be populated with terms replicating those of the current RDF environment.

PrefixMap createPrefixMap(in optional boolean empty)

optional boolean empty: If true is specified then an empty PrefixMap will be returned, by default the PrefixMap returned will be populated with prefixes replicating those of the current RDF environment.

Document Data

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

attribute optional RDFEnvironment rdf

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-INTERFACE]] specification.

attribute RDFaEnvironment rdfa

The RDFa Environment interface provides RDFa-specific capabilities.

Projection getProjection (in DOMString subject, in optional object template)

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.

DOMString subject: The subject to use when matching against triples. The subject can be either an absolute URI or a CURIE. The subject is used to match against the URI in the first part of a triple. An implementation MUST coerce the DOMString to the same type as the triple's subject being compared. If the type coercion will result in a URI, the CURIE mappings MUST be queried first for a mapping and the given property expanded as a CURIE if a mapping is found. If the subject does not exist in the document, the return value MUST be null.
optional object template: The Projection template is used to build the return value. The template consists of a key-value associative array where the key is the name of the property to create in the Projection and the value is the URI to use when matching against predicates in each triple.

Sequence <Projection> getProjections(in optional object? template)

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

optional object template: The Projection template is used to build the return value. The template consists of a key-value associative array where the key is the name of the property to create in the Projection and the value is the URI to use when matching against predicates in each triple.

Sequence <Projection> getProjections (in optional DOMString property, in optional DOMString? value, in optional object template)

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

optional DOMString property: The property to use when matching against triples. The property can be either an absolute URI or a CURIE. The property is used to match against the URI in the second part of a triple, also known as the predicate. An implementation MUST coerce the DOMString to the same type as the predicate being compared. If the type coercion will result in a URI, the CURIE mappings MUST be queried first for a mapping and the given property expanded as a CURIE if a mapping is found. If the value is null, the match is always positive.
optional DOMString? value: The value to use when matching against triples. The value can be either an absolute URI or a CURIE. The value is used to match against the final part of a triple, also known as the object. An implementation MUST coerce the DOMString to the same type as the object being compared. If the type coercion will result in a URI, the CURIE mappings MUST be queried first for a mapping and the given value expanded as a CURIE if a mapping is found. If the value is null, the match is always positive.
optional object template: The Projection template is used to build the return value. The template consists of a key-value associative array where the key is the name of the property to create in the Projection and the value is the URI to use when matching against predicates in each triple.

Sequence<DOMString> getProperties (in optional DOMString? subject)

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

optional DOMString? subject: The subject to use when matching against triples. The subject is used to match against the URI in the first part of a triple. The subject can be either an absolute URI or a CURIE. The subject is used to match against the first part of a triple. An implementation MUST coerce the DOMString to the same type as the triple's subject that is being compared. If the type coercion will result in a URI, the CURIE mappings MUST be queried first for a mapping and the given property expanded as a CURIE if a mapping is found. If the given subject is null, the match is always positive.

Sequence<DOMString> getSubjects (in optional DOMString? property, in optional DOMString? value)

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

optional DOMString? property: The property to use when matching against triples. The property can be either an absolute URI or a CURIE. The property is used to match against the URI in the second part of a triple, also known as the predicate. An implementation MUST coerce the DOMString to the same type as the predicate being compared. If the type coercion will result in a URI, the CURIE mappings MUST be queried first for a mapping and the given property expanded as a CURIE if a mapping is found. If the value is null, the match is always positive.
optional DOMString? value: The value to use when matching against triples. The value can be a number, a boolean, a DOMString, an absolute URI or a CURIE. The value is used to match against the final part of a triple, also known as the object. An implementation MUST coerce the DOMString to the same type as the triple object being compared. If the type coercion will result in a URI, the CURIE mappings MUST be queried first for a mapping and the given property expanded as a CURIE if a mapping is found. If the value is null, the match is always positive.

Sequence<any> getValues (in optional DOMString? subject, in optional DOMString? property)

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

optional DOMString? subject: The subject to use when matching against triples. The subject can be either an absolute URI or a CURIE. The subject is used to match against the URI in the first part of a triple. An implementation MUST coerce the DOMString to the same type as the subject being compared. If the type coercion will result in a URI, the CURIE mappings MUST be queried first for a mapping and the given property expanded as a CURIE if a mapping is found. If the value is null, the match is always positive.
optional DOMString? property: The property to use when matching against triples. The property can be either an absolute URI or a CURIE. The property is used to match against the URI in the second part of a triple, also known as the predicate. An implementation MUST coerce the DOMString to the same type as the predicate being compared. If the type coercion will result in a URI, the CURIE mappings MUST be queried first for a mapping and the given property expanded as a CURIE if a mapping is found. If the value is null, the match is always positive.

DOMString setMapping ()

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

in DOMString mapping: The shortened form of the URI to map.
in DOMString uri: An absolute URI that the mapping should expand to when used with any of the structured data APIs.

How to Read this Document

Introduction

Design Considerations

RDF Concept Interfaces

RDF Environment Interfaces

RDF Data Interfaces

Goals

Examples and use cases

Render RDF data in HTML

Gather RDF data within a user session

Create linked data mashups

The RDF API Specification

Terms, Prefixes and Profiles

Prefix Maps

Example

Term Maps

Example

Profiles

Projections

Retrieving Projections by Subject

Retrieving Projections by Property

Using Projections

RDF Environment

Document Data

Acknowledgements