W3C

RDF API

W3C Editor's Draft 11 May 2011

This version:
http://www.w3.org/2010/02/rdfa/sources/rdf-api/
Latest published version:
http://www.w3.org/TR/rdf-api/
Latest editor's draft:
http://www.w3.org/2010/02/rdfa/sources/rdf-api/
Previous version:
none
Editors:
Nathan Rixham
Manu Sporny, Digital Bazaar, Inc.
Benjamin Adrian, German Research Center for Artificial Intelligence GmbH
Authors:
Nathan Rixham
Manu Sporny, Digital Bazaar, Inc.
Mark Birbeck, Backplane Ltd.
Ivan Herman, W3C
Benjamin Adrian, German Research Center for Artificial Intelligence GmbH

Abstract

RDF enables providers to publish various types of data on the Web in a unified format. This data 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 the Semantic Web, using the information to improve the collective utility of the Web is the true goal of the Semantic Web. 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.

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 an Editor's Draft. If you wish to make comments regarding this document, please send them to public-rdfa-wg@w3.org (subscribe, archives). All feedback is welcome.

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

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

Table of Contents

1. Introduction

This section is non-normative.

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.

1.1 How to Read this Document

This section is non-normative.

This document is a detailed specification for the RDF API. The document is primarily intended for web developers who want to process RDF data in a browser environment.

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

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:

1.2 Design Considerations

This section is non-normative.

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:

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

2.1 Projections

This section is non-normative.

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 an RDF document, a developer can do the following:

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

2.1.1 Retrieving Projections by Subject

This section is non-normative.

You can also get a Projection by its subject:

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

Retrieving Projections by Property

You can get a list of Projection s by their properties:

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

2.1.2 Using Projections

This section is non-normative.

You can retrieve property values from Projection s like so:

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

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

var albert = data.getProjection("http://example.org/people#albert", {"name": "foaf:name"});
var name = albert.name;

2.1.3 Queries

This section is non-normative.

In order to retrieve a list of all Projection s in the document that are similar to a Projection pattern, developers can use the query method.

For example, assume our source document contains the following event, marked up using the Data Vocabulary Event format:

<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 Projection s we know that we can do this:

var events = 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 = data.query(
   { "rdf:type": "http://rdf.data-vocabulary.org/#Event" },
   { "type": "rdf:type", "summary": "v:summary", 
     "start": "v:startDate", "end": "v:endDate" } );

2.1.4 Projection Specification

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

    getter any    get (in DOMString uriOrCurie);
    setter object set (in DOMString uriOrCurie, in object value);

    any[]         getAll (in DOMString uriOrCurie);
};
Methods
get
Retrieves the first property with the given name as a language-native datatype.
ParameterTypeNullableOptionalDescription
uriOrCurieDOMStringThe 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.
No exceptions.
Return type: getter any
getAll
Retrieves the list of values for a property as an array of language-native datatypes.
ParameterTypeNullableOptionalDescription
uriOrCurieDOMStringThe 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.
No exceptions.
Return type: any[]
getProperties
Retrieves the list of properties that are available on the Projection . Each property must be an absolute URI.
No parameters.
No exceptions.
Return type: DOMString[]
getSubject
Retrieves the subject URI of this Projection as a string, the value must be an absolute URI.
No parameters.
No exceptions.
Return type: DOMString
set
Sets the value of a property with the given name as a language-native datatype.
ParameterTypeNullableOptionalDescription
uriOrCurieDOMStringThe name of the property to set the value. The argument can be either an absolute URI or a CURIE that will be resolved using the default document mapping.
valueobjectThe value of the property as a language-native datatype.
No exceptions.
Return type: setter object

2.2 RDF Parsers

The RDFParser is a generic RDF document parser which can be used to parse the triples serialized within an RDF document in to a list of Projections

[NoInterfaceObject]
interface RDFParser {
    readonly attribute Projection[] processorGraph;

    boolean parse (in any toparse, in optional ParserCallback callback, in optional DOMString base, in optional Projection filter, in optional object template);

};

2.2.1 Attributes

processorGraph of type array of Projection, readonly
An optional list of Projections produced by RDF Parsers containing additional parsing information and errors.
No exceptions.

2.2.2 Methods

parse

Parses the triples serialized within an input RDF document in to a Sequence of Projection s, then executes a given ParserCallback on the populated Sequence .

If a Projection is passed to the parser as pattern, then each RDF data found in the document will only be added to the output Sequence of Projection s if it matches the null values used as wildcarts in the passed pattern.

A boolean response is given indicating if the parse was successful or not.

ParameterTypeNullableOptionalDescription
toparseany The document to parse, the type of argument required may further be constrained by implementations of this interface, for instance an RDFa parser may require an instance of Document , whilst a Turtle parser may require a String .
callbackParserCallback The ParserCallback to execute once the parse has completed, the ParserCallback will be passed a single argument which is the created Sequence of Projection s.
baseDOMStringAn optional base to be used by the parser when resolving relative IRI references.
filterProjection The Projection filter is used as a filter definition. Null values of projected entries are processed as wildcards.
templateobject 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.
No exceptions.
Return type: boolean

2.2.3 ParserCallback

The ParserCallback interface is used by the parse method of the RDFParser interface.

[NoInterfaceObject, Callback]
interface ParserCallback {
    void run (in sequence<Projection> projections);

};
Methods
run
A function to be executed on a Graph produced by a parse operation on an RDF Document.
ParameterTypeNullableOptionalDescription
projectionssequence<Projection>
No exceptions.
Return type: void

3. Data environment

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

[NoInterfaceObject]
interface Data {

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

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

    sequence<DOMString>  getProperties (in optional DOMString? subject);
    sequence<DOMString>  getSubjects (in optional DOMString? property, in optional DOMString? value);

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

    sequence<Projection> query (in object pattern, in object template);

    DOMString            setMapping (in DOMString mapping, in DOMString uri);

    boolean              parse (in RDFParser parser, in any toparse, in ParserCallback callback, in optional DOMString base, in optional Projection filter, in optional object template);

};

3.1 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 RDF document, null is returned.
ParameterTypeNullableOptionalDescription
subjectDOMString 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 RDF document, the return value must be null .
templateobject 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.
No exceptions.
Return type: Projection
getProjections
Retrieves a list of all Projection s in the document using the optional Projection template to build the Projection s.
ParameterTypeNullableOptionalDescription
templateobject 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.
No exceptions.
Return type: sequence<Projection>
getProjections
Retrieves a list of Projection s that match the given optional property and value, constructed using the given Projection template.
ParameterTypeNullableOptionalDescription
propertyDOMString 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.
valueDOMString 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.
templateobject 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.
No exceptions.
Return type: sequence<Projection>
getProperties
Retrieves a list of DOMStrings which are IRI identifiers for properties given an optional subject to match against.
ParameterTypeNullableOptionalDescription
subjectDOMString 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.
No exceptions.
Return type: sequence<DOMString>
getSubjects
Retrieves a list of DOMStrings which are IRI identifiers for subjects given an optional property and value to match against.
ParameterTypeNullableOptionalDescription
propertyDOMString 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.
valueDOMString 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.
No exceptions.
Return type: sequence<DOMString>
getValues
Retrieves a list of mixed types given an optional subject and property to match against.
ParameterTypeNullableOptionalDescription
subjectDOMString 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.
propertyDOMString 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.
No exceptions.
Return type: sequence<any>
parse
Sets a mapping given a mapping and a URI to map.

A boolean response is given indicating if the parse was successful or not.

ParameterTypeNullableOptionalDescription
parserRDFParserThe parser used to read the passed document.
toparseany The document to parse, the type of argument required may further be constrained by implementations of this interface, for instance an RDFa parser may require an instance of Document , whilst a Turtle parser may require a String .
callbackParserCallback The ParserCallback to execute once the parse has completed, the ParserCallback will be passed a single argument which is the created Sequence of Projection s.
baseDOMStringAn optional base to be used by the parser when resolving relative IRI references.
filterProjection The Projection filter is used as a filter definition. Null values of projected entries are processed as wildcards.
templateobject 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.
No exceptions.
Return type: boolean
query
Retrieves a list of all Projection s in the document that match with a passed Projection pattern using the optional Projection template to build the Projection s.
ParameterTypeNullableOptionalDescription
patternobject The Projection pattern is used as a query definition.
templateobject 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.
No exceptions.
Return type: sequence<Projection>
setMapping
Sets a mapping given a mapping and a URI to map.
ParameterTypeNullableOptionalDescription
mappingDOMStringThe shortened form of the URI to map.
uriDOMStringAn absolute URI that the mapping should expand to when used with any of the structured data APIs.
No exceptions.
Return type: DOMString

A. Acknowledgements

At the time of publication, the members of the RDF Web Application Working Group were:

B. References

B.1 Normative references

[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt
[WEBIDL]
Cameron McCormack, Sam Weinig. Web IDL 11 March 2010. W3C Editor's Draft. URL: http://dev.w3.org/2006/webapi/WebIDL/

B.2 Informative references

[RDF-CONCEPTS]
Graham Klyne; Jeremy J. Carroll. Resource Description Framework (RDF): Concepts and Abstract Syntax. 10 February 2004. W3C Recommendation. URL: http://www.w3.org/TR/2004/REC-rdf-concepts-20040210