W3C

RDFa API

An API for extracting structured data from Web documents

W3C Working Draft 23 September 2010 19 April 2011

This version:
http://www.w3.org/TR/2010/WD-rdfa-api-20100923/ http://www.w3.org/TR/2011/WD-rdfa-api-20110419/
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/2010/WD-rdfa-api-20100608/ http://www.w3.org/TR/2010/WD-rdfa-api-20100923/
Editors:
Manu Sporny , Digital Bazaar, Inc.
Benjamin Adrian , German Research Center for Artificial Intelligence GmbH
Authors:
Nathan Rixham , Invited Expert
Mark Birbeck , Backplane Ltd.
Author:
Ivan Herman , W3C
This document is also available in this non-normative format: diff to previous version .

Abstract

RDFa [ RDFA-CORE ] enables authors to publish structured information that is both human- and machine-readable. Concepts that have traditionally been difficult for machines to detect, like people, places, events, music, movies, and recipes, are now easily marked up in Web documents. While publishing this data is vital to the growth of Linked Data , using the information to improve the collective utility of the Web for humankind is the true goal. To accomplish this goal, it must be simple for Web developers to extract and utilize structured information from a Web document. This document details such a mechanism; an RDFa 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:

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:

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

The following changes have been made since the First Public Working Draft:

This document was published by the RDFa Working Group as a Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-rdfa-wg@w3.org ( subscribe , archives ). All feedback is welcome.

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

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

Table of Contents

1. Introduction

This section is non-normative.

RDFa provides a means to attach properties to elements enable machine-readable markup of structured data in XML and HTML human-readable Web documents. Since the purpose of these additional properties Structured data that is to provide information about real-world items, contained in documents, such as people, films, companies, events, and so on, properties are grouped into objects called PropertyGroup s. can provide an added layer of information to Web Applications. The RDFa API provides a set of interfaces that make it easy to manipulate DOM objects that contain information that is also part of a PropertyGroup . This specification defines these interfaces. 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 interpreted. 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 property collection, reflecting the final PropertyGroup . object.

All of this is achieved through This specification defines the RDFa API. There are many scenarios in API, which the RDFa API can may be used to extract information from a Web document. The following sections describe a few of these scenarios. 1.1 Importing Data Amy has enriched her band's web-site to include Google Rich Snippets event information. Google Rich Snippets are used to mark up information for the search engine to use when displaying enhanced search results. Amy also uses some ECMAScript code that she found on the web that automatically extracts the event information from a page and adds an entry into a personal calendar. Brian finds Amy's web-site through Google and opens the band's page. He decides that he wants to go to the next concert. Brian is able to add the details to his calendar by clicking on the link that is automatically generated by the ECMAScript tool. The ECMAScript extracts the RDFa from the web page and places the event into Brian's personal calendaring software - Google Calendar. <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="2009-10-15T19:00">15. Oct., 7:00 pm</span>- <span property="v:endDate" content="2009-10-15T21:00">9:00 pm</span> </span> Category: <span property="v:eventType">concert</span> </div> 1.2 Enhanced Browser Interfaces Dave is writing a browser plugin that filters product offers in a web page and displays an icon to buy the product or save it to a public wishlist. The plugin searches for any mention of product names, thumbnails, and offered prices. The information is listed in the URL bar as an icon, and upon clicking the icon, displayed in a sidebar in the browser. He can then add each item to a list that is managed by the browser plugin developers and published on a wishlist website. <div prefix="rdfs: http://www.w3.org/2000/01/rdf-schema# foaf: http://xmlns.com/foaf/0.1/ gr: http://purl.org/goodrelations/v1# xsd: http://www.w3.org/2001/XMLSchema#" xml:lang="en"> <div about="#offering" typeof="gr:Offering"> <div rel="foaf:page" resource="http://www.amazon.com/Harry-Potter-Deathly-Hallows-Book/dp/0545139708"></div> <div property="rdfs:label">Harry Potter and the Deathly Hallows</div> <div property="rdfs:comment">In this final, seventh installment of the Harry Potter series, J.K. Rowling unveils in spectactular fashion the answers to the many questions that have been so eagerly awaited. The spellbinding, richly woven narrative, which plunges, twists and turns at a breathtaking pace, confirms the author as a mistress of storytelling, whose books will be read, reread and read again.</div> <div rel="foaf:depiction"> <img src="http://ecx.images-amazon.com/images/I/51ynI7I-qnL._SL500_AA300_.jpg" /> </div> <div rel="gr:hasBusinessFunction" resource="http://purl.org/goodrelations/v1#Sell"></div> <div rel="gr:hasPriceSpecification">Buy for <span typeof="gr:UnitPriceSpecification"> <span property="gr:hasCurrency" content="USD" datatype="xsd:string">$</span> <span property="gr:hasCurrencyValue" datatype="xsd:float">7.49</span> </span> </div> Pay via: <span rel="gr:acceptedPaymentMethods" resource="http://purl.org/goodrelations/v1#PayPal">PayPal</span> <span rel="gr:acceptedPaymentMethods" resource="http://purl.org/goodrelations/v1#MasterCard">MasterCard</span> </div> </div> </div> 1.3 Data-based Web Page Modification Dale has a site that contains a number of images, showcasing his photography. He has already used RDFa to add licensing information about the images to his pages, following the instructions provided by Creative Commons. Dale would like to display the correct Creative Commons icons for each image so that people will be able to quickly determine which licenses apply to each image. <div prefix="cc: http://creativecommons.org/ns#"> <img src="http://dale.example.com/images/image1.png" rel="cc:license" resource="http://creativecommons.org/licenses/by/3.0/us/"/> <a href="http://dale.example.com" property="cc:attributionName" rel="cc:attributionURL">Dale</a> </div> 1.4 Automatic Summaries Mary is responsible for keeping the projects section of her company's home page up-to-date. She wants to display info-boxes that summarize details about the members associated with each project. The information should appear when hovering the mouse over the link to each member's homepage. Since each member's homepage is annotated with RDFa, Mary writes a script that requests the page's content and extracts necessary information via the RDFa API. <div prefix="dc: http://purl.org/dc/terms/ foaf: http://xmlns.com/foaf/0.1/"> <div about="#me" property="foaf:name" content="Bob">My<span> interests are: <ol about="#me" typeof="foaf:Person"> <li rel="foaf:interests"> <a href="facebook" rel="tag" property="dc:title">facebook</a> </li> <li rel="foaf:interests"> <a href="opengraph" rel="tag" property="dc:title">opengraph</a> </li> <li rel="foaf:interests"> <a href="semanticweb" rel="tag" property="dc:title">semanticweb</a> </li> </ol> <p>Please follow me on Twitter: <span about="#me" rel="foaf:account"> @<a typeof="foaf:OnlineAccount" property="foaf:accountName" href="http://twitter.com/bob">bob</a>. </span> </p> </div> 1.5 Data Visualization Richard has created a site that lists his favourite restaurants and their locations. He doesn't want to generate code specific to the various mapping services on the Web. Instead of creating specific markup for Yahoo Maps, Google Maps, MapQuest, and Google Earth, he instead adds address information via RDFa to each restaurant entry. This enables him Applications to build on top of the access structured data contained in the page as well as letting visitors to the site use the same data to create innovative new applications based on the address information in the page. <div prefix="vc: http://www.w3.org/2006/vcard/ns# foaf: http://xmlns.com/foaf/0.1/" typeof="vc:VCard"> <span property="vc:fn">Wong Kei</span> <span property="vc:street-address">41-43 Wardour Street</span> <span property="vc:locality">London</span>, <span property="vc:country-name">United Kingdom</span> <span property="vc:tel">020 74373071</span> </div> 1.6 Linked Data Mashups Marie is a chemist, researching the effects of ethanol on the spatial orientation of animals. She writes about her research on her blog and often makes references to chemical compounds. She would like any reference to these compounds to automatically have a picture of the compound's structure shown as a tooltip, and a link to the compound's entry on the National Center for Biotechnology Information [NCBI] Web site. Similarly, she would like visitors to be able to visualize the chemical compound in the page using a new HTML5 canvas widget she has found on the web that combines data from different chemistry websites. documents.

<div prefix="dbp: http://dbpedia.org/ontology/ fb: http://rdf.freebase.com/rdf/" > My latest study about the effects of <span about="[fb:en.ethanol]" typeof="[dbp:ChemicalCompound]" property="[fb:chemistry.chemical_compound.pubchem_id]" content="702">ethanol</span> on mice's spatial orientation show that ... </div>

2. 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 Triples data from Web documents or 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 RDFa API are designed to work as seamlessly as possible with language-native types, operators, and program flow constructs.

2.1 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
Each This high-level API is part of a larger family of lower-level APIs for interfacing with RDF data on the API is modular and pluggable, meaning Web. Special care has been taken to ensure that data storage, parsers and query modules may this API can be replaced by other developer-defined mechanisms as long as implemented without requiring the interfaces listed in larger family of APIs. If the larger family of APIs is available, however, this document are supported. 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 the document.getElementsById() document.getElementsByClassName() functionality that is a part of [ DOM-LEVEL-1 ].
Support for Non-RDFa Parsers Other languages that store data in the DOM are considered as first-class languages when it comes to extraction and support via the RDFa API. Mechanisms like DC-HTML, eRDF, Microformats, and Microdata can be used to express structured data in DOM-based languages. It is a goal of this API to ensure that information expressed in these languages can be extracted, using a developer-defined parser, and stored in the Data Store. Low-level Access and the Freedom to Tinker Providing an abstract API, while simpler, may not produce the kind of innovation that the semantics community would like to see. It is important to give developers access to the entire RDFa API stack in order to ensure that each layer of the stack can be improved independently of a standards body. A Modular RDF API The RDFa Working Group understood that in order to provide an RDFa API that an RDF API would have to be created. This specification details a low-level RDF API as well as a higher-level RDFa API. While it is not certain how many developers would require a stand-alone RDF API, the hope is that those that require one will be able to re-use the RDF API defined in this specification. This specification is an attempt to unify RDF APIs much like POSIX unified the mechanisms used to access operating system services across all vendors. 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, Property Groups Projection can be s are exposed as native objects or dynamically accessible, associative arrays. Data Stores language constructs. Graph s 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.
Macros 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 IRIs URIs to be expressed as CURIEs. The API should also provide short-cuts that reduce the amount of code that has to be repeated. Property Group Templates Projection Template s are one example of reducing repetitive code writing as it can be stored in a single variable and re-used for objects. when building Projetions.

2.2 1.3 Concept Diagram

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

The RDFa API Concept Stack

Diagram of Concept Stack for the RDFa API Concepts and RDF API

The lowest layer of the RDFa API defines the basic structures that are used to store information; IRI , PlainLiteral , TypedLiteral , BlankNode and finally the RDFTriple . The next layer is layered on top of concepts defined by the API, the DataStore , supports the storage of information. RDF API. The DataParser lowest level concepts are Triples, Graphs and DataQuery interfaces directly interact with the DataStore . The DataParser is used to extract information from the Document Projections. Triples, Graphs and store the result in a DataStore . The DataQuery interface is Projections are data structures used by Web Developers to extract different views of work with data from the DataStore . The PropertyGroup is an abstract, easily manipulable view of this information for developers. While PropertyGroup objects can address most use cases, a developer also has access to the information expressed in RDF languages. Working directly with the DataStore data structures can be cumbersome at a basic level. Access times, such as the requirement to use absolute URIs when accessing properties, thus Profiles are provided to support accessing the raw data allows developers using compact URIs (CURIEs). Data Parsers and Data Serializers provide mechanisms to create new views both read and ways of directly manipulating the write RDF data in a DataStore . variety of RDF languages. All of these concepts are provided via a high-level interface called the RDF Environment.

The highest layer to the API is implementers should note that only the Document object and is what most web developers will use portions of the RDF API that are directly used by this API need to retrieve PropertyGroup s created 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 stored 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.

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

3.1 2.1 Basic Concepts

This section is non-normative.

This API provides a number of interfaces to enable:

3.1.1

The Basic API

The RDFa API has a number of advanced methods that can be used to access the DataStore , DataParser and DataQuery mechanisms. Most Many web developers will not need to use find that the advanced methods - most will only require basic functionality provided by the following interfaces RDFa API is sufficient for most of their day-to-day development activities. programming tasks. Since developers typically work with object-oriented data structures, the basic API is geared toward building language-native objects called Projection s and returning them to the developer.

Retrieving PropertyGroups Data in the Document

document.getItemsByType(type) 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.
PropertyGroup document.data.getProperties(optional subject) s by their type, such as foaf:Person .
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.getItemBySubject(type) document.data.getValues(optional subject, optional property)
Retrieves a single 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.
PropertyGroup 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 its a particular subject, such as one could do the following: http://example.org/people#bob document.data.getProjection("http://example.com/people#bob") .
document.getItemsByProperty(property, document.data.getProjections(optional property, optional value) value, optional template)
Retrieves a list of PropertyGroup Projection s by a particular given an optional property and optional 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 Projection s that contain the PropertyGroup foaf:name contains. property, one could do the following: document.data.getProjections("foaf:name") .

Retrieving DOM Elements

document.getElementsByType(type)
Retrieves a list of DOM Nodes by given a type to match against. The type is the rdf:type expressed in the DOM Node. The type of data that they express, such as can be expressed via the foaf:Person . typeof , rel , rev or the property attribute.
document.getElementsBySubject(type) document.getElementsBySubject(subject)
Retrieves a list of DOM Nodes by the given a subject associated with to match against. The subject can be expressed via the data that they express, such as http://example.org/people#bob . about , href , src , or resource attribute.
document.getElementsByProperty(property, optional value)
Retrieves a list of DOM Nodes by given a particular property and an optional value that each expresses. to match against. Properties can be expressed via the typeof , rel , rev or property attribute.

IRI Mapping

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

Advanced Processing

document.data.query.select(query, document.data.rdfa.query(query, optional template)
Retrieves an array of PropertyGroup Projection s based on a set of selection criteria. document.data.store.filter(pattern) Filters a given DataStore by matching a given triple pattern. document.data.parser.iterate(pattern) Iterates through a DOM, using The template is used to build a low-memory, stream-based approach, matching on language-native object that is specific to the given triple pattern. needs of the developer and the application.
3.1.2

Using the Basic API

The following section uses the markup shown below to demonstrate how to extract and use PropertyGroup subject, properties, values and Projection s 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 .

<div prefix="foaf: http://xmlns.com/foaf/0.1/" about="#albert" typeof="foaf:Person">
  <span property="foaf:name">Albert Einstein</span>
</div>
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 Projection s in the next section.

Working with Property Groups Projections

Retrieving PropertyGroups Projections by Type

You can retrieve the object A Projection is an object-oriented view of a particular subject that is described above by doing 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.getItemsByType("http://xmlns.com/foaf/0.1/Person");

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

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

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.getItemsByType("foaf:Person");

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

Retrieving PropertyGroups Projections by Subject

You can also get a PropertyGroup Projection by its subject:

var
albert
=
document.getItemBySubject("http://example.org/people#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.getItemBySubject("#albert");

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

Retrieving PropertyGroups Projections by Property

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

var
peopleNamedAlbertEinstein

peopleNamedAlbert

=
document.getItemByProperty("foaf:name",

document.data.getProjections("foaf:name",

"Albert
Einstein");

Using PropertyGroups Projections

You can retrieve property values from PropertyGroup Projection s like so:

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

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

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

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

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

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.context.setMapping("foaf", "http://xmlns.com/foaf/0.1/");

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:

The mechanism to access the DOM Element associated with in-document data is being redesigned for the next draft version of the RDFa API.
var elements = document.getElementsByProperty("foaf:name", "Bob");
for(i = 0; i <= elements.length; i++)
{
   var e = elements[i];
   e.style.setProperty('color', '#00cc00', null);
}

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

3.2 2.2 Advanced Concepts

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

3.2.1

Advanced Queries

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

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

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

To locate all PropertyGroup Projection s that are people, we could use the document.getItemsByType() document.getProjections() method:

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

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

or we could do the same using the DataQuery interface: standard query interface to retrieve a Projection :

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

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.context 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
=
query.select(

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

{
"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 PropertyGroup Projection s of a certain type, but it did so by indicating that the property rdf:type should have a specific value. Queries can also specify other properties. For example, given the following mark-up:

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

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

var architects = query.select( {

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"
} );

  "http://xmlns.com/foaf/0.1/myersBriggs": "INTP" },
  { "name": "http://xmlns.com/foaf/0.1/name" });

var
name
=
architects[0].get("http://xmlns.com/foaf/0.1/name");

architects[0].name;

As before, prefix-mappings can also be used:

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

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

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

architects[0].name;

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

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

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;
3.2.2 Direct Access to the Data Store

Creating Projections

The RDFa API allows a developer Developers may find that they need to not only query the DataStore 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. at via the DataQuery mechanism, it also allows

There has been a developer to get to the underlying data structures complaint that represent the structured data at the "atomic level". this section comes from out of nowhere. The filter interface is a part purpose of the DataStore and enables a developer this section is to filter a series of triples out of 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 DataStore . For example, document to extract all triples about a particular subject, help integrate this section with the developer could do flow of the following: document.

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

Developers could also combine subject-property filters by doing For example, assume our source document contains the following: following event, marked up using the Data Vocabulary Event format:

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

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

The To query above would extract all known nicknames for the subject as triples. A developer may also retrieve all triples in the DataStore Event Projection by specifying no filter parameters: s we know that we can do this:

var
allTriples

events

=
document.data.store.filter();

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

3.2.3 Direct Access to the Parser Stream The .iterate interface will almost certainly see large changes in the next version of the RDFa API specification. Implementers are warned

However, to not implement build a special Projection that contains the interface summary, start date and wait for the next revision of this specification. 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 iterate interface can be used second parameter is a Projection Template. Each key-value pair specifies a Projection property to process triples in URI mapping. That is, the document as they are discovered. This interface key is most useful for processing large amounts the name of data the property to create in low-memory environments. var iter = document.data.parser.iterate( {"subject": "http://example.org/people#mark"} ); for(var triple = iter.next(); triple != null; triple = iter.next()) { } 3.2.4 Overriding the Defaults Projection object. The sub-modules value must exist in a triple, specifically as a property of the RDFa API are meant to be overridden by developers triple, in order to extend basic functionality as well as innovate new interfaces for the RDFa API. Overriding the DataStore The API is designed such that a developer may override copy the default data store provided by the browser by providing their own. This is useful, for instance, if object value of the developer wanted triple over to create a permanent site-specific data store using Local Storage features in the browser, or allowing provenance information to be stored with each triple. var mydatastore = new MyCustomDataStore(); document.data.store = mydatastore; Overriding value of the Data Parser Projection object's property.

Developers may create and specify different parsers for parsing structured data from the document that builds upon RDFa, or parses other languages not related to RDFa. For example, Microformats-specific parsers could be created to extract structured hCard data more detailed information about queries and store it in an object that is compatible with Projection s see the DataStore DocumentData interface.

var hcardParser = new MyHCardParser(); document.data.parser = hcardParser; Overriding the Data Query The query mechanism for the API can be overridden to provide different or more powerful query mechanisms. For example, by replacing the standard query mechanism, developers could provide a full SPARQL query mechanism: var sparqlQuery = new MySparqlEngine(); document.data.query = sparqlQuery; var books = document.data.query.select("SELECT ?book ?title WHERE { ?book <http://purl.org/dc/elements/1.1/title> ?title . }", {"?book": "subject", "?title": "title"} );

4. 3. The Interfaces Specification

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

4.1 3.1 Conformance

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

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

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

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

Implementations that use ECMAScript or Java to implement the APIs defined in this specification must implement them in a manner consistent with the respective ECMAScript or Java Bindings defined in the Web IDL specification, as this specification uses that specification's terminology. [ WEBIDL ] ], 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 Processors API implementations are modular and easily exchangable. replaceable.

4.2 3.2 The RDF Interfaces Projections

RDFa is a syntax for expressing the RDF Data Model [ RDF-CONCEPTS ] in Web documents. The RDFa API is designed to extract the RDF Data Model from Web documents. The following RDF Resources are utilized in this specification: PlainLiteral s, TypedLiteral s, IRI References (as defined in [ IRI ]) and BlankNode s. The interfaces for each of these RDF Resources are detailed in this section. The types as exposed by the RDFa API conform to the same data and comparison restrictions as specified in the RDF concepts specification [ RDF-CONCEPTS ] and the [ IRI ] specification. Each RDF Projection interface provides access to both the extracted RDFa value and the DOM Node from which the value was extracted. This allows developers to extract and use RDF triples from a host language and also manipulate the DOM based on the associated DOM Node. For example, an agent could highlight all strings that are marked up as foaf:name properties in a Web document. The basic RDF Resource types used in the RDFa API are: IRI Reference — A reference to a resource as defined in International Resource Identifier [ IRI ]. Example: http://www.w3.org/2001/XMLSchema#string . PlainLiteral — A string value with optional information about the language of its content. Example: "Harry Potter and the Half-Blood Prince"@en is a plain literal expressed in the English language. Typed Literal — A typed string value with information about the datatype of its content. Example: "7"^^xsd:integer is a typed literal with a value of type xsd:integer . Blank Node — A blank node is a reference to a resource that does not have a corresponding IRI. Examples of BlankNode s include _:me , and _:42 . RDF Triple — Triples are the basic data structure utilized by RDF used to express logical statements. An RDF triple is a 3-item ordered set consisting of a subject , a property , and an object . Example: <http://example.org/hp> rdfs:label "Harry Potter" . Diagram of RDF Classes, Attributes, Methods and linkages. An RDFa API implementer must provide the basic types as described in this specification. An implementer may provide additional types and/or a deeper type or class hierarchy that includes these basic types. 4.2.1 RDFNode and RDFResource An RDFNode is an anything build language-native objects that can be an object of an RDFTriple . It is also the base class of PlainLiteral , and TypedLiteral . ] interface { }; Attributes value of type stringifier DOMString , readonly The value of an RDFNode is either a literal's lexical value or a lexical identifier of an IRI or BlankNode . Note that the value attribute is marked with accessed in a stringifier decorator. In [ WEBIDL ], this means way that the value is used as the return value if toString() is called on an object that inherits from this type. The stringifier can be overridden by the re-specification of natural for the toString() method on a subclass of this type. No exceptions. An RDFResource is an anything that can be a subject of an RDFTriple . implementation language.

]
interface  {

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

Methods

value get of type stringifier DOMString , readonly
The value of an RDFResource is either a string that represents an IRI or an identifier of a BlankNode . No exceptions. 4.2.2 IRI References An IRI Reference in the RDFa API points to a resource and is further defined in [ IRI ]. ] interface { }; 4.2.3 RDF Literals An RDF Literal is an RDF Resource that represents lexical values in RDFa data. The two RDF Literals provided via the RDFa API are PlainLiteral s and TypedLiteral s. For a given RDF Literal , either language or type information can be provided. If the type is set, Retrieves the RDF Literal is a Typed Literal . If a type is not set, it is a PlainLiteral . PlainLiteral RDF Literals that may contain language information about first property with the given text. The language is specified name as a text string as specified in [ BCP47 ] (e.g., 'en' , 'fr' , 'de' ). language-native datatype. TypedLiteral RDF Literals that contain type information about the given text. The type is always specified in the form of an IRI Reference (e.g., http://www.w3.org/2001/XMLSchema#DateTime ). PlainLiterals PlainLiteral s have a string value and may specify a language. ] interface { }; Attributes has a string value and a datatype specified as an IRI Reference . TypedLiteral s can be converted into native language datatypes of the implementing programming language by registering a Typed Literal Converter as defined later in the specification. No parameters.
Parameter Type Nullable Optional Description
uriOrCurie language of type DOMString , readonly A language string as defined in [ BCP47 ], normalized to lowercase. No exceptions. value of type stringifier DOMString , readonly The lexical value of the literal encoded in the character encoding of the source document. The value is extracted from an RDFa document using the algorithm defined in the RDFa Core Specification [ RDFA-CORE ], Section 7.5: Sequence , Step 11. No exceptions. Example This section is non-normative. The following example demonstrates a few common use cases of the PlainLiteral type. var literal = document.data.store.createPlainLiteral("Harry Potter and the Half-Blood Prince", "en"); var str = literal.toString(); var val = literal.value var lang = literal.language; // At this point, lang is equivalent to "en" Typed Literals A TypedLiteral The datatype's IRI reference specifies the datatype name of the text value, e.g., xsd:DataTime or xsd:boolean . The RDFa API provides a method to explicitly convert TypedLiteral values to native datatypes supported by the host programming language. Developers may write their own Typed Literal Converters in order property to convert an RDFLiteral into a native language type. retrieve. The converters are registered by using the registerTypeConversion() method. Default TypedLiteral converters must argument can be supported by the RDFa API implementation for the following XML Schema datatypes : xsd:string xsd:boolean xsd:float xsd:double xsd:boolean xsd:integer xsd:long xsd:date xsd:time xsd:dateTime ] interface { }; Attributes type of type IRI , readonly A datatype identified by an IRI reference No exceptions. value of type stringifier DOMString , readonly The lexical value of the literal encoded in the character encoding of the source document. The value is extracted from either an RDFa document using the algorithm defined in the RDFa Core Specification [ RDFA-CORE ], Section 7.5: Sequence , Step 11. No exceptions. Methods valueOf Returns absolute URI or a native language representation of this literal. The type conversion should CURIE that will be performed by translating the value of the literal resolved using the IRI reference of the datatype to the closest native datatype in the programming language. default document mapping.
No exceptions.
Return type: any getter
Example This section is non-normative. The following example demonstrates how a TypedLiteral representing a date is automatically converted to ECMAScript's native DateTime object. var literal = document.data.store.createTypedLiteral("2010-12-24", "xsd:date"); var value = literal.value; var str = literal.toString(); var date = literal.valueOf(); // Fri Dec 24 2010 00:00:00 GMT+0000 4.2.4 Blank Nodes A BlankNode is an RDF resource that does not have a corresponding IRI reference, as defined in [ RDF-CONCEPTS ]. The value of a BlankNode is not required to be the same for identical documents that are parsed at different times. The purpose of a BlankNode is to ensure that RDF Resources in the same document can be compared for equivalence by ID. The reasoning behind how we stringify BlankNode s should be explained in more detail. BlankNode s are stringified by concatenating "_:" to BlankNode .value ] interface { }; Attributes
value getAll of type stringifier DOMString , readonly
The temporary identifier of the BlankNode . The value must not be relied upon in any way between two separate RDFa processing runs of the same document. No exceptions. Developers and authors must not assume that Retrieves the value list of a BlankNode will remain the same between two processing runs. BlankNode values are only valid for the most recent processing run on the document. BlankNode s values will often be generated differently by different RDFa Processors. Example This section is non-normative. The following example demonstrates the use of a BlankNode in a ECMAScript implementation that uses incrementing numbers for the identifier. var bna = document.data.store.createBlankNode(); var bnb = document.data.store.createBlankNode(); var stra = bna.toString(); var bnavalue = bna.value; var bnbvalue = bnb.value; // easily establishes a unique identifier for the BlankNode. 4.2.5 RDF Triples The RDFTriple interface represents an RDF triple as specified in [ RDF-CONCEPTS ]. RDFTriple can be used by referring to properties, such as subject , property , and object . RDFTriple can also be used by referring to pre-defined indexes. The stringification of RDFTriple results in an N-Triples-based representation as defined in [ RDF-TESTCASES ]. ] interface { }; Attributes object of type RDFNode , readonly The object associated with the RDFTriple . No exceptions. property of type IRI , readonly The property associated with the RDFTriple . No exceptions. subject an array of type RDFResource , readonly The subject associated with the RDFTriple . No exceptions. Methods get An index method to access subject, predicate, and object with indices from zero to two, respectively. language-native datatypes.
Parameter Type Nullable Optional Description
index uriOrCurie unsigned long DOMString 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.
No exceptions.
Return type: getter RDFNode any []
toString getProperties
Converts this triple into a string in N-Triples notation. Retrieves the list of properties that are available on the Projection . Each property must be an absolute URI.
No parameters.
No exceptions.
Return type: stringifier DOMString []
Constants
size getSubject of type unsigned long
A constant used to define an RDFTriple Retrieves the subject URI of this Projection as array of length three. a string, the value must be an absolute URI.
No parameters.
Example
This section is non-normative. No exceptions. The following examples demonstrate the basic usage of an
Return type: RDFTriple DOMString object. The creation of the triple uses the foaf:name CURIE, which is transformed into an IRI. The example assumes that a mapping has already been created for foaf . For more information on creating RDFa DOM API mappings, see the section on IRI Mappings . var triple = document.data.store.createTriple("http://www.example.com#manu", "foaf:name", \ document.data.store.createPlainLiteral("Manu Sporny")); var str = "Triple subject: " + triple.subject;
var tstr = "N-Triples: " + triple; // At this point, tstr will be 'N-Triples: <http://www.example.com#manu> <http://xmlns.com/foaf/0.1/name> "Manu Sporny" .'

4.3 3.3 The Linked Data Interfaces Document Interface

A number of convenience objects and methods are provided by the The RDFa DOM API is designed to help developers manipulate RDF Resources more easily when writing Web applications. The basic RDF interface types described earlier in this document are utilized by the following Structured Data Interfaces: DataContext — A mechanism that greatly reduces the amount provide a small, powerful set of code document-based interfaces that a developer must write may use to express IRIs and convert data. DataStore retrieve Projection — An store containing s from a set of RDFTriple objects. Web document. This section focuses on the extensions necessary to the DOM environment. These extensions are separated into four interfaces:

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

Document Interface Extensions

Processing RDF data involves the frequent use of unwieldy IRI references and frequent type conversion. The DataContext interface is provided in order to simplify contextual operations such as shortening IRIs and converting RDF data into native language datatypes. It is assumed that this interface is created and available before a document is parsed for RDFa data. For example, while operating within a Browser Context, it is assumed that the following lines section describes all of code the extensions that are executed before a developer has access necessary to the RDFa API methods on the document object: document.data.context = new DataContext(); document.data.context.setMapping("rdf", "http://www.w3.org/1999/02/22-rdf-syntax-ns#"); document.data.context.setMapping("xsd", "http://www.w3.org/2001/XMLSchema-datatypes#"); In general, when a CURIE is resolved by the RDFa API or enable manipulation of structured data within a TypedLiteral Web Document.



Document


is
converted
to
a
native
language
type,
the
current

implements


DataContext

DataDocument



stored
in
the

;

DocumentData

All instances of the DOM Document object interface must be used to perform the action. This is to ensure that there is only one active DataContext in use by the RDFa API at any given time. The default DataContext stored in the implement DocumentData DataDocument object may be changed at runtime. All of the code that sets up the default type converters for Browser Contexts that use ECMAScript should probably be in the code snippet above. .

The following DataDocument interface allows IRI mappings provides necessary extensions to be easily created the core DOM Document interface to enable the processing and used by Web Developers at run-time. It also allows for conversion storage of RDF data into native language datatypes. structured data.

 {

[Supplemental, NoInterfaceObject]
interface DataDocument {
    readonly attribute DocumentData data;    NodeList getElementsByType (in DOMString type);    NodeList getElementsBySubject (in DOMString subject);    NodeList getElementsByProperty (in DOMString property, in optional DOMString? value);
};
Methods
Attributes
convertType data Returns the native language value of the passed literal value as a language-native type. If the given value cannot be converted, the given value must be returned. The return value upon conversion failure is being actively discussed in the RDFa WG. There are proposals to raise exceptions upon conversion failure, proposals to return tuples containing conversion success/failure and the converted value, as well as other mechanisms that would allow the signalling of a conversion failure from the method to calling code. Parameter Type Nullable Optional Description value DOMString ✘ ✘ The value to convert that is associated with the TypedLiteral . inputType DOMString ✘ ✔ The input type for the TypedLiteral passed as a string. For example, xsd:string DocumentData or xsd:integer . modifier DOMString ✘ ✔ , readonly
The developer-supplied modifier for the conversion.
The string is a free-form, string that is used by the TypedLiteralConverter DocumentData interface is useful for extracting and storing data that is associated with the inputType . The RDFa Working Group is still discussing whether or not having a modifier is a good idea as 90% of use cases will never use it and the remaining use cases could provide the functionality with an external switch to the conversion function. Document.
No exceptions.
Return type:
any
Methods
registerTypeConversion getElementsByProperty
Registers a type converter from given IRI datatype to Retrieves a native language dataype in list of Nodes objects based on the current programming language. value of a given property.
Parameter Type Nullable Optional Description
iri property DOMString A string specifying the IRI datatype. DOMString representing an IRI-based property. The string may can either be a CURIE. For example: http://www.w3.org/2001/XMLSchema-datatypes#integer absolute URI or xsd:integer . a CURIE.
converter value TypedLiteralConverter DOMString Converts A DOMString representing the TypedLiteral 's value into a native language datatype in the current programming language. to match against.
No exceptions.
Return type: void NodeList
resolveCurie getElementsBySubject
Resolves Retrieves a given CURIE. If successful, returns an IRI or Null if NodeList consisting of Nodes that have explicitly specified the CURIE could not be resolved. given subject.
Parameter Type Nullable Optional Description
curie subject DOMString A DOMString representing an IRI-based subject. The CURIE that is to string can either be resolved into an IRI. a absolute URI or a CURIE.
No exceptions.
Return type: IRI NodeList
setMapping getElementsByType
Registers a mapping from a prefix to an IRI . The given IRI must be a full IRI. For example, if a developer wants to specify the foaf IRI mapping, they would call setMapping("foaf", "http://xmlns.com/foaf/0.1/") . Calling the setMapping() method with Retrieves a prefix value that does not exist results in the creation list of a new mapping. Calling Nodes based on the method with a null IRI value will remove object type of the mapping. data that they specify.
Parameter Type Nullable Optional Description
prefix type DOMString The prefix to put into the mapping as the key. (e.g., foaf ) iri A DOMString ✘ ✘ The IRI reference to place into the mapping as the mapped value of the given prefix. (e.g., representing an "http://xmlns.com/foaf/0.1/") rdf:type to select against.
No exceptions.
Return type: void NodeList
Easy IRI Mapping All methods that accept CURIEs as arguments in the RDFa API must use the algorithm specified in RDFa Core, Section 7.4: CURIE and URI Processing [ RDFA-CORE

] for TERMorCURIEorURI . The prefix and term mappings are provided by the current document.data.context instance. 3.4 DOM Implementation Extensions

The following examples demonstrate how mappings are created and used via If the RDFa API. document.data.context.setMapping("foaf", "http://xmlns.com/foaf/0.1/"); var people = document.getItemsByType("foaf:Person"); var people2 = document.getItemsByType("http://xmlns.com/foaf/0.1/Person"); In the example above, the CURIE " foaf:Person " API is expanded to an IRI with the value " http://xmlns.com/foaf/0.1/Person " in the getItemsByType method. IRI mappings for all terms implemented in the following vocabularies must be included: rdf and xsd . Automatic Type Conversion TypedLiteralConverter is a callable interface that transforms the value of DOM environment and a TypedLiteral into a native language type in the current programming language. The type IRI of the TypedLiteral DOMImplementation interface is used to determine provided, the best mapping to following additional requirements for the native language type. Specifing Typed Literal Converters A TypedLiteralConverter hasFeature() may method must be implemented as a class, or as a language-native callback in languages like ECMAScript. met:

]
interface  {

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

Methods

convert hasFeature
Returns Checks to see whether or not the native language value DOM implementation has exposed all of the passed literal value as a language-native type. If the given value cannot be converted, the given value must be returned. The return value upon conversion failure is being actively discussed in the mandatory RDFa WG. There are proposals to raise exceptions upon conversion failure, proposals to return tuples containing conversion success/failure and the converted value, as well as other mechanisms API features specified in this specification. An implementation that would allow supports all of the signalling mandatory features in this specification must return true for a feature string of " RDFaAPI " and a conversion failure from the method to calling code. version string of " 1.1 ".
Parameter Type Nullable Optional Description
value feature DOMString The value feature string to convert that is associated with use when checking to see if the TypedLiteral . inputType IRI ✘ ✔ The input type for DOM environment exposes all of the TypedLiteral passed as an IRI . For example, http://www.w3.org/2001/XMLSchema#string or http://www.w3.org/2001/XMLSchema#integer . RDFa API attributes and methods.
modifier version DOMString A developer-specified modifier used during the conversion. The version string is a free-form string that is used by to use when checking to see if the developer-specified convert() method. DOM environment exposes all of the RDFa API attributes and methods.
No exceptions.
Return type: any boolean
Examples The following example demonstrates how a developer could register and use a TypedLiteralConverter . document.data.context.registerTypeConversion("xsd:boolean", function(value) {return new Boolean(value);}); var literal = document.data.store.createTypedLiteral("1", "xsd:boolean"); var lstr = literal.toString(); var lvalue = literal.value; var lnvalue = literal.valueOf(); // be a Boolean type whose value is 'true'. The following example demonstrates how to create and pass a TypedLiteralConverter function in ECMAScript: var converter = function (value) { return new String(value) }; document.data.context.registerTypeConverter("xsd:string", converter); A TypedLiteralConverter can also specify a target type for the converter so that one converter can be used for multiple types: var converter = function(value, inputType, modifier) { if(inputType == "http://www.w3.org/2001/XMLSchema#integer") { return parseInt(value); } else if(modifier == "caps") { return new String(value).toUpperCase(); } else { return new String(value); } }; document.data.context.registerTypeConverter("xsd:string", converter); document.data.context.registerTypeConverter("xsd:integer", converter); var airportCode = document.data.context.convertType("wac", "xsd:string", "caps"); // At this point, the value of airportCode should be "WAC"

4.3.2 3.5 Document Data Store

The DataStore DocumentData interface is a set of RDFTriple objects. It provides a basic getter as well as an indexed getter for retrieving individual items from the store. The DataStore can be used to create primitive types as well as store collections of them in access the form of RDFTriple s. The forEach method is not properly defined structured data in WebIDL - need to get input from the WebApps Working Group on how best to author this interface. document.

]
interface  {
]
    

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

Attributes

size rdf of type unsigned long , readonly A non-negative integer that specifies the size, in RDFTriple optional RDFEnvironment s, of the store. No exceptions. Methods add
Adds an RDFTriple The interface to the DataStore . Returns True if the RDFTriple was added RDF convenience methods and functionality. Implementations may omit access to the store successfully. Adding an RDFTriple that already exists in the DataStore underlying RDF implementation. If implementations include this attribute, they must return True and must not store two duplicate triples in the DataStore . Parameter Type Nullable Optional Description triple RDFTriple ✘ ✘ The triple to add conform to the DataStore . No exceptions. Return type: [ boolean RDF-API clear Clears all data from the store. No parameters. ] specification.
No exceptions.
Return type: void
createBlankNode Creates a BlankNode given an optional name value. Parameter Type Nullable Optional Description name
DOMString rdfa ✘ ✔ The name of the BlankNode , which will be used when Stringifying the BlankNode . No exceptions. Return type: type BlankNode RDFaEnvironment createIRI
Creates an IRI given a value and an optional Node. Parameter Type Nullable Optional Description iri DOMString ✘ ✘ The IRI reference's lexical value. node Node ✘ ✔ An optional DOM Node to associate with the IRI. RDFa Environment interface provides RDFa-specific capabilities.
No exceptions.
Return type:
IRI

Methods

createPlainLiteral getProjection
Creates Retrieves a PlainLiteral Projection given a value subject and an optional language. Parameter Type Nullable Optional Description value DOMString ✘ ✘ The value of the PlainLiteral , which is usually a human-readable string. language DOMString ✔ ✔ The language that is associated with the PlainLiteral encoded according to Projection template if the rules outlined subject exists in [ BCP47 ]. No exceptions. Return type: PlainLiteral createTriple Creates an RDFTriple given a subject, property and object. the document. If any incoming value does not match the requirements listed below, a Null value must be returned by this method. Parameter Type Nullable Optional Description subject RDFResource ✘ ✘ The subject value of the RDFTriple . The value must be either an IRI or a BlankNode . property IRI ✘ ✘ The property value of the RDFTriple . object RDFNode ✘ ✘ The object value of does not exist in the RDFTriple . The value must be an IRI , PlainLiteral , TypedLiteral , or BlankNode . No exceptions. Return type: RDFTriple createTypedLiteral Creates a document, TypedLiteral null given a value and a type. is returned.
Parameter Type Nullable Optional Description
value DOMString ✘ ✘ The value of the TypedLiteral . type subject DOMString The IRI type of the TypedLiteral . subject to use when matching against triples. The argument subject can either be a full IRI or a CURIE. No exceptions. Return type: TypedLiteral filter Returns either an DataStore , which consists of zero or more RDFTriple objects. The RDFa Working Group is debating whether the return value of the filter method should be a DataStore or a Sequence of RDFTriple s. DataStores allow much higher-level functions to be carried out versus a simple Sequence of RDFTriple s. However, DataStore s may be very memory intensive to construct and manage. Parameter Type Nullable Optional Description pattern Object ✔ ✔ A filter pattern that determines which triples to select from the DataStore . The filter pattern is provided to make it easy to perform complex filtering on subject, property and object by providing a very flexible data container to convey selection information. The implementation of the pattern parameter is designed to be easily implemented by data dictionaries absolute URI or associative arrays, but should be done in a way that is natural to the implementation language. To ensure a similar programming environment, the variables to convey subject, property and object parameters should use keys or variables named "subject", "property" and "object", respectively. CURIE. The subject parameter is used to filter RDFTriple objects. Values can be of type DOMString, IRI , or BlankNode . If a DOMString is supplied, the API must convert the value into an IRI or BlankNode before comparison is performed. If the subject is specified, match against the RDFTriple must not be placed URI in the final output Array unless the given subject matches the RDFTriple 's subject. If first part of a subject parameter is not specified, the function triple. An implementation must not reject any triple based on the subject unless specified by coerce the RDFTripleFilter . The property parameter is used to filter RDFTriple objects. Values can be of type DOMString or IRI . If a DOMString is supplied, to the API must convert same type as the value into an IRI before comparison is performed. triple's subject being compared. If the property is specified, the RDFTriple must not be placed type coercion will result in the final output Array unless the given property matches the RDFTriple 's property. If a property parameter is not specified, URI, the function CURIE mappings must not reject any triple based on the property unless specified by the RDFTripleFilter . The object parameter is used to filter RDFTriple objects. Values can be of type DOMString, BlankNode , PlainLiteral , TypedLiteral or IRI . If queried first for a DOMString is supplied, the API must convert mapping and the value into given property expanded as a PlainLiteral before comparison CURIE if a mapping is performed. found. If the object is specified, the RDFTriple must subject does not be placed exist in the final output Array unless the given object matches the RDFTriple 's object. If an object parameter is not specified, document, the function return value must not reject any triple based on the object unless specified by the be RDFTripleFilter null .
element template Element ✔ ✔ The parent DOM Element where filtering should start. The implementation must only consider RDF triples on the current DOM Element and its children. filter RDFTripleFilter object A user defined function, returning a true or false value, that determines whether or not an RDFTriple The Projection should be added template is used to build the final Array. No exceptions. Return type: DataStore forEach Calls return value. The template consists of a key-value associative array where the given callback for each item in key is the DataStore . While name of the forEach() method is intended property to provide a functional mechanism for iterating through a DataStore , it has been questioned whether create in the interface would be useful for developers since there is already a procedural array-index-based iteration mechanism built into a DataStore. Parameter Type Nullable Optional Description iterator DataStoreIterator Projection ✘ ✘ A function that takes and the following arguments: index, subject, property, object. The function value is called for each item in the DataStore . URI to use when matching against predicates in each triple.
No exceptions.
Return type: void Projection
get getProjections
Returns the RDFTriple Retrieves a list of all Projection object at the given index s in the list. document using the optional Projection template to build the Projection s.
Parameter Type Nullable Optional Description
index template unsigned long object The index of the RDFTriple Projection in the list template is used to retrieve. build the return value. The value must be template consists of a positive integer value greater than or equal key-value associative array where the key is the name of the property to zero and less than DataStore ::length. No exceptions. Return type: getter RDFTriple merge Merges all triples create in an external DataStore the Projection into this DataStore . Duplicate triples must not be inserted into and the same data store. Returns True if all triples were merged into value is the store successfully. Parameter Type Nullable Optional Description store DataStore ✘ ✘ The external DataStore URI to merge into this DataStore . use when matching against predicates in each triple.
No exceptions.
Return type: boolean Sequence
The DataStoreIterator interface is used by the forEach() method on the DataStore when processing all of the triples in a DataStore . ] interface { }; Methods
process getProjections
A callable function Retrieves a list of Projection s that takes an array index, subject, property, and object as arguments match the given optional property and processes each based on a developer-supplied algorithm. value, constructed using the given Projection template.
Parameter Type Nullable Optional Description
index property int ✘ ✘ The offset into the DataStore that contains the current RDFTriple being processed. subject RDFResource DOMString The subject of the RDFTriple being processed. property IRI ✘ ✘ to use when matching against triples. The property associated with the RDFTriple being processed. object RDFNode ✘ ✘ The object associated with the RDFTriple being processed. No exceptions. Return type: void Examples This section is non-normative. The following examples demonstrates two mechanisms that are available for navigating through a DataStore ; index getter-based iteration and array index-based iteration. var store = document.data.store.filter(); for(var i = 0; i < store.size; i++) { var t1 = store.get(i); var t2 = store[i]; } The following example demonstrates a more functional mechanism that can be used to process each triple in either an absolute URI or a DataStore : function alertTriple(index, subject, property, object) { alert("DataStore subject: " + subject + ", property: " + property + ", object: " + object); } document.data.store.forEach(alertTriple); 4.3.3 Data Parser CURIE. The DataParser property is capable used to match against the URI in the second part of processing a DOM Element and placing triple, also known as the parsing results into a DataStore . While this section specifies how one would parse RDFa data and place it into a DataStore , predicate. An implementation must coerce the interface is also intended DOMString to support the parsing and storage of various Microformats, eRDF, GRDDL, DC-HTML, and Microdata. Web developers that would like to write customer parsers should extend this interface. ] interface { ] }; Attributes store of same type DataStore The DataStore that is associated with as the DataParser . The results of each parsing run will be placed into predicate being compared. If the store. No exceptions. Methods iterate Returns an DataIterator , which is capable of iterating through a set of RDF triples, one RDFTriple at a time. The DataIterator is most useful in small memory footprint environments, or type coercion will result in documents that contain a very large number of triples. It has been noted that having an stream-based mechanism of processing triples via URI, the iterate() method, CURIE mappings must be queried first for a mapping and the given property expanded as a process-and-store-based mechanism for storing triples via CURIE if a mapping is found. If the value is parse() method on null , the same interface match is confusing. Each mechanism provides an alternate way of processing triples in a document. In the future, iterate() and parse() may be separated out into two distinct interfaces. Parameter Type Nullable Optional Description always positive.
pattern value Object DOMString A filter pattern that determines which triples to select from the DataStore . The filter pattern is provided to make it easy to perform complex filtering on subject, property and object by providing a very flexible data container to convey selection information. The implementation of the pattern parameter is designed to be easily implemented by data dictionaries or associative arrays, but should be done in a way that is natural to the implementation language. To ensure a similar programming environment, the variables value to convey subject, property and object parameters should use keys or variables named "subject", "property" and "object", respectively. when matching against triples. The subject parameter is used to filter RDFTriple objects. Values value can be of type DOMString, IRI , either an absolute URI or BlankNode . If a DOMString is supplied, the API must convert the CURIE. The value into an IRI or BlankNode before comparison is performed. If the subject is specified, the RDFTriple must not be placed in used to match against the final output Array unless the given subject matches the RDFTriple 's subject. If part of a subject parameter is not specified, triple, also known as the function object. An implementation must not reject any triple based on the subject unless specified by coerce the RDFTripleFilter . The property parameter is used to filter RDFTriple objects. Values can be of type DOMString or IRI . If a DOMString is supplied, to the API must convert same type as the value into an IRI before comparison is performed. object being compared. If the property is specified, the RDFTriple must not be placed type coercion will result in the final output Array unless the given property matches the RDFTriple 's property. If a property parameter is not specified, URI, the function CURIE mappings must not reject any triple based on the property unless specified by the RDFTripleFilter . The object parameter is used to filter RDFTriple objects. Values can be of type DOMString, BlankNode , PlainLiteral , TypedLiteral or IRI . If queried first for a DOMString is supplied, the API must convert mapping and the given value into expanded as a PlainLiteral before comparison CURIE if a mapping is performed. found. If the object value is specified, the RDFTriple must not be placed in the final output Array unless the given object matches null , the RDFTriple 's object. If an object parameter match is not specified, the function must not reject any triple based on the object unless specified by the RDFTripleFilter . always positive.
element template Element ✔ ✔ The parent DOM Element where filtering should start. The implementation must only consider RDF triples on the current DOM Element and its children. filter RDFTripleFilter object A user defined function, returning a true or false value, that determines whether or not an RDFTriple The Projection should be added template is used to build the final Array. 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: DataIterator Sequence
parse getProperties
Parses starting at the given DOM Element and populates the store with the information that is discovered. If a starting element isn't specified, or the value of the starting element is Null, then the document object must be used as the starting element. Even though a specific DOM Element can be specified to start the process of placing RDFTriple s into the DataStore , the entire document must be processed by an RDFa Processor due to context that may affect the generation of a set of triples. Specifying the DOM Element is useful when Retrieves a subset list of the document data is to be stored in the DataStore . There DOMStrings which are two ways to approach this mechanism. The first is to only parse the sub-tree, ignoring the context of the greater document. The second is IRI identifiers for properties given an optional subject to parse the entire document, but only store triples that are a part of the sub-tree. match against. No parameters.
Parameter Type Nullable Optional Description
domElement subject Element DOMString The DOM Element that should trigger triple generation. No exceptions. Return type: boolean 4.3.4 Data Iterator subject to use when matching against triples. The DataIterator interface may undergo changes in the next version of the RDFa API specification. Implementers are warned subject is used to not implement match against the interface and wait for URI in the next revision first part of this specification. The DataIterator iterates through a DOM subtree and returns RDFTriple s that match a filter function or triple pattern. A DOM Element triple. The subject can be specified so that only triples contained in the Element and its children will be either an absolute URI or a part of the iteration. CURIE. The DataIterator subject is provided in order to allow implementers used to provide a less memory intensive implementation for processing triples in very large documents. A DataIterator is created by calling match against the document.data.parser.iterate() method. ] interface { }; Attributes filter first part of type RDFTripleFilter , readonly The RDFTripleFilter is a function that is provided by developers to filter RDFTriple s in a subtree. No exceptions. triple. An implementation must root of coerce the DOMString to the same type Element , readonly The DOM Element that was used as the starting point for extracting RDFTriple s. No exceptions. store of type DataStore The DataStore triple's subject that is associated with being compared. If the DataIterator . No exceptions. triplePattern of type RDFTriple , readonly An RDF triple pattern is coercion will result in a set of filter parameters that can be passed to an RDFTripleFilter to match particular triple patterns. No exceptions. URI, the CURIE mappings must Methods next Returns be queried first for a mapping and the next RDFTriple object that given property expanded as a CURIE if a mapping is found in found. If the DOM subtree or NULL if no more given subject is RDFTriple s match null , the filtering criteria. match is always positive.
No exceptions.
Return type: RDFTriple Sequence
Example This section is non-normative. The following examples describe the how various filter patterns can be applied to the DOM via document.data.parser.iterate(). var iter1 = document.data.parser.iterate(); for(var triple = iter1.next(); triple != null; triple = iter1.next()) { } var iter2 = document.data.parser.iterate( {"subject": "http://www.example.com#foo"} ); var iter3 = document.data.parser.iterate( {"property": "foaf:name"} ); 4.3.5 Property Group The PropertyGroup interface provides a view on a particular subject contained in the DataStore . The PropertyGroup aggregates the RDFTriple s as a single language-native object in order to provide a more natural programming primitive for developers. PropertyGroup attributes can be accessed in the following ways in ECMAScript: var person = document.getItemBySubject("#bob"); var name1 = person.get("http://xmlns.com/foaf/0.1/name"); var name2 = person.get("foaf:name"); // At this point name1 and name2 are equivalent ] interface { }; Attributes
info getSubjects of type Object
A developer-specific info object to associate with the PropertyGroup . The info object must provide a property-based accessor mechanism for languages that support it, such as ECMAScript. For DOM-based environments, the Element that originated the PropertyGroup must be specified in Retrieves a property called source in the info attribute. No exceptions. properties of type array of IRI A list of all attributes that DOMStrings which are available via this PropertyGroup . No exceptions. Methods get Returns a sequence of IRIs, BlankNode s, PlainLiteral s, and/or TypedLiteral s in the projection that have a property IRI that is equivalent to the identifiers for subjects given value. an optional property and value to match against.
Parameter Type Nullable Optional Description
property DOMString A stringified IRI representing a The property whose values are to be retrieved from the PropertyGroup . For example, using a property of http://xmlns.com/foaf/0.1/name will return a sequence of values that represent FOAF names in the PropertyGroup . use when matching against triples. The given property may also can be either an absolute URI or a CURIE. No exceptions. Return type: Sequence<RDFNode> Example This section is non-normative. The following examples demonstrate how to use the PropertyGroup interface. var ivan = document.getItemBySubject("http://www.ivan-herman.net/foaf#me"); document.data.context.setMapping("foaf", "http://xmlns.com/foaf/0.1/"); var names = ivan.get("foaf:name"); var titles = ivan.get("foaf:title"); var pages = ivan.get("foaf:workInfoHomepage"); // "http://www.w3.org/2001/sw/#activity" The Source Pointer The RDFa Working Group property is currently discussing the best mechanism to enable access used to match against the DOMNode that contains a particular subject, predicate or object. While there have been several mechanisms that have been proposed, none of them are easy or straighforward to use. This mechanism will be modified heavily URI in the next version second part of the document in order to allow easier access to the DOMNode associated with a particular piece of structured data: var people = document.getItemsByType("foaf:Person"); for (var i = 0; i < people.length; i++) { people[i].info("foaf:name", "source")[0].style.border = "1px solid blue"; } Property Group Templates A query can be used to retrieve not only basic PropertyGroup s, but can triple, also specify how PropertyGroup s are built by utilizing PropertyGroup Templates. There has been a complaint that this section comes from out of nowhere. The purpose of this section is to describe that PropertyGroups can be mapped to native language objects to ease development. We may need to elaborate more on this at this point in the document to help integrate this section with the flow of the document. For example, assume our source document contains the following event, marked up using known as the Google Rich Snippet Event format (example taken from predicate. An implementation must coerce the Rich Snippet tutorial, and slightly modified): <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 PropertyGroup s we know that we can do this: var ar = query.select({ "rdf:type": "http://rdf.data-vocabulary.org/#Event" }); However, DOMString to build a special PropertyGroup that contains the summary, start date and end date, we need only do this: var events = query.select({ "rdf:type": "http://rdf.data-vocabulary.org/#Event" }, {"rdf:type" : "type", "v:summary": "summary", "v:startDate": "start", "v:endDate": "end"} ); The second parameter is a Property Group Template. Each key-value pair specifies an IRI to map to an attribute in same type as the resulting PropertyGroup object. Exposing predicate being compared. If the embedded data in each PropertyGroup makes it easy to create an HTML anchor that type coercion will allow users to add the event to their Google Calendar, as follows: var anchor, button, i, pg; for (i = 0; i < events.length; i++) { var event = events[i]; anchor = document.createElement("a"); anchor.href = "http://www.google.com/calendar/event?action=TEMPLATE" + "&text=" + event.summary + "&dates=" + event.start + "/" + event.end; button = document.createElement("img"); button.src = "http://www.google.com/calendar/images/ext/gc_button6.gif"; anchor.appendChild(button); event.info("rdf:type", "source")[0].appendChild(anchor); } The result will be that the event has an HTML in a element at URI, the end (and any Event CURIE mappings must on the page will follow this pattern): <div vocab="http://rdf.data-vocabulary.org/#" typeof="Event"> . . . <a href="http://www.google.com/calendar/event?action=TEMPLATE& → text=Hey+K-Town,+Amy+And+The+Red+Foxies+will+rock+Kammgarn+in+October.&dates=20091015T1900Z/20091015T2100Z"> <img src="http://www.google.com/calendar/images/ext/gc_button6.gif" /> </a> </div> For more detailed information about queries see the DataQuery interface. 4.3.6 Data Query The DataQuery interface provides a means to query a DataStore . While this interface provides a simple mechanism for querying a DataStore for RDFa, it is expected that developers will implement other query interfaces that conform to this DataQuery interface be queried first for languages like SPARQL or other Domain Specific Language. ] interface { }; Attributes store of type DataStore The DataStore that is associated with the DataQuery . No exceptions. Methods select Generates a sequence of PropertyGroup s that matches mapping and the given selection criteria. Parameter Type Nullable Optional Description query Object ✔ ✘ An associative array containing properties as keys and objects to match property expanded as values. a CURIE if a mapping is found. If the query value is null, every item in the DataStore that null , the query match is associated with must returned. always positive.
template value Object DOMString A template describing the attributes The value to create in each PropertyGroup that is returned. use when matching against triples. The template is an associative array containing properties as keys and attribute names that should value can be created in the returned PropertyGroup as values. No exceptions. Return type: Sequence<PropertyGroup> 4.4 The Document Interface The RDFa API is designed to provide a small, powerful set of interfaces that number, a developer may use to retrieve RDF triples from boolean, a Web document. The core interfaces were described in the previous two sections. This section focuses on the final RDFa API that most developers will utilize to generate the objects that are described in the RDF Interfaces and the Structured Data Interfaces sections. DOMString, an absolute URI or a CURIE. The following API value is provided by this specification: Document Interface Extensions — A set of extensions to the Document interface used to help developers manage structured data in Web documents. Document Data — The abstract container object for managing structured data in a Document. 4.4.1 Document Extensions The following section describes all of match against the extensions that are necessary to enable manipulation final part of structured data within a Web Document. ] interface { }; Attributes data of type DocumentData , readonly The DocumentData interface is useful for extracting and storing data that is associated with triple, also known as the Document. No exceptions. Methods createDocumentData Creates a DocumentData object and returns it. The object that is returned object. An implementation must have coerce the store , context , parser and query attributes initialized DOMString to sensible defaults that would allow the immediate extraction of RDFa data from same type as the current document by calling DocumentData .parser.parse(document) . No parameters. No exceptions. Return type: DocumentData getElementsByProperty Retrieves triple object being compared. If the type coercion will result in a list of Nodes objects based on URI, the value of CURIE mappings must be queried first for a mapping and the given property. Parameter Type Nullable Optional Description property DOMString ✘ ✘ A DOMString representing an IRI-based property. The string can either be expanded as a full IRI or CURIE if a CURIE. mapping is found. If the value is DOMString ✘ ✘ A DOMString representing null , the value to match against. is always positive.
No exceptions.
Return type: NodeList Sequence
getElementsBySubject getValues
Retrieves a NodeList consisting list of Nodes that have explicitly specified the mixed types given subject. an optional subject and property to match against.
Parameter Type Nullable Optional Description
subject DOMString A DOMString representing an IRI-based subject. The string subject to use when matching against triples. The subject can either be a full IRI either an absolute URI or a CURIE. No exceptions. Return type: NodeList getElementsByType Retrieves a list of Nodes based on The subject is used to match against the object type URI in the first part of a triple. An implementation must coerce the data that they specify. Parameter Type Nullable Optional Description type DOMString ✘ ✘ A DOMString representing an rdf:type to select against. No exceptions. Return type: NodeList getItemBySubject Retrieves a PropertyGroup object based on its subject. Parameter Type Nullable Optional Description the same type as the subject DOMString ✘ ✘ A DOMString representing an IRI-based subject. The string can either being compared. If the type coercion will result in a URI, the CURIE mappings must be queried first for a full IRI or mapping and the given property expanded as a CURIE. No exceptions. Return type: PropertyGroup getItemsByProperty Retrieves CURIE if a list of mapping is found. If the value is PropertyGroup objects based on null , the values of a property. Parameter Type Nullable Optional Description match is always positive.
property DOMString A DOMString representing an IRI-based property. The string property to use when matching against triples. The property can either be a full IRI either an absolute URI or a CURIE. value DOMString ✘ ✘ A DOMString representing the value The property is used to match against. No exceptions. against the URI in the second part of a triple, also known as the predicate. An implementation must Return type: 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 Sequence<PropertyGroup> getItemsByType Retrieves be queried first for a list of PropertyGroup objects based on their rdf:type property. Parameter Type Nullable Optional Description type DOMString ✘ ✘ A DOMString representing an mapping and the given property expanded as a CURIE if a mapping is found. If the value is rdf:type to select against. null , the match is always positive.
No exceptions.
Return type: Sequence<PropertyGroup> Document implements RDFaDocument ; Sequence All instances of the DOM Document interface must implement RDFaDocument .
4.4.2 DOMImplementation Extensions If the RDFa API is implemented in a DOM environment and a DOMImplementation interface is provided, the following additional requirements for the hasFeature() method must be met: { }; Methods
hasFeature setMapping
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 Sets a feature string of " RDFaAPI " mapping given a mapping and a version string of " 1.1 ". URI to map.
Parameter Type Nullable Optional Description
feature mapping in DOMString The feature string to use when checking to see if the DOM environment exposes all shortened form of the RDFa API attributes and methods. URI to map.
version uri in DOMString The version string An absolute URI that the mapping should expand to use when checking to see if the DOM environment exposes all used with any of the RDFa API attributes and methods. structured data APIs.
No exceptions.
Return type: boolean DOMString

4.4.3 3.6 Document Data RDFa Environment

The DocumentData RDFaEnvironment interface is used to create structured-data related context, storage, parsing and query objects. perform RDFa-specific actions.

 {

[NoInterfaceObject]
interface RDFaEnvironment {
    Sequence query (in optional object? query, in optional object template);
};
Attributes context of type DataContext The default DataContext for the document. No exceptions. parser of type DataParser The default DataParser for the document. No exceptions. query of type DataQuery The default DataQuery for the document. No exceptions. store of type DataStore The default DataStore for the document. No exceptions.

Methods

createContext Creates a DataContext and returns it. No parameters. No exceptions. Return type: DataContext
createParser query
Creates Generates a DataParser of the given type and returns it. Parameter Type Nullable Optional Description type DOMString ✘ ✘ The type of DataParser to create. A value of " rdfa " must be accepted for all conforming implementations sequence of this specification. store DataStore ✘ ✘ The DataStore to associate with the DataParser . No exceptions. Return type: DataParser createQuery Creates a DataQuery Projection for s that match the given store. selection criteria.
Parameter Type Nullable Optional Description
type query DOMString object The type of query An associative array containing properties as keys and strings to create for the given store. A value of " rdfa " must be accepted for all conforming implementations of this specification. Implementations may provide alternative query interfaces, such match as SPARQL, SQL, HQL, GQL, or other values. If the query languages to enable innovative new ways of querying is null, every item in the underlying default storage mechanism. store DataStore ✘ ✘ The DataStore to associate with the DataQuery . No exceptions. Return type: DataQuery createStore Creates a DataStore and returns it. If the type mechanism is not specified, a DataStore must be created and returned. Alternatively, developers may provide other DataStore implementations such as persisted triple stores, quad stores, distributed graph stores and other more advanced storage mechanisms. The type determines the underlying DataStore that will be created. Parameter Type Nullable Optional Description
type template DOMString object The type of DataStore to create. A value of "triple" must be accepted for all conforming implementations of this specification. If template describing the type attributes to create in each Projection that is omitted, returned. The template is an associative array containing key-value pairs. Each key corresponds to a value of "triple" must property that will be assumed. No exceptions. Return type: DataStore 4.4.4 Pattern Filters An important goal of created in the RDFa API Projection that is returned. Each value corresponds to help Web developers filter the set of RDF triples in a document down to only the ones that interest them. This section covers pattern-based filters. Pattern filters trigger off of one or more of the subject, triple's property, or object properties in RDF triples. This section also introduces the interfaces for the other filter types. Function Filters Filter criteria may also be defined by the developer known as a filter function. The RDFTripleFilter is a callable function that determines whether an RDFTriple should predicate, whose value will be included stored in the set of output triples. ] interface { }; Methods match A callable function that returns true if the input RDFTriple Projection should be included in the output set, or false if as the input RDFTriple should be rejected from value of the output set. Parameter Type Nullable Optional Description triple RDFTriple ✘ ✘ The triple to test against key specified in the filter. template.
No exceptions.
Return type: boolean Sequence
Example This section is non-normative. The examples below use the following HTML code: <div id="start" about="http://dbpedia.org/resource/Albert_Einstein"> <span property="foaf:name">Albert Einstein</span> <span property="dbp:dateOfBirth" datatype="xsd:date">1879-03-14</span> <div rel="dbp:birthPlace" resource="http://dbpedia.org/resource/Germany"> <span property="dbp:conventionalLongName">Federal Republic of Germany</span> </div> </div> The following examples demonstrate the use of document.data.store.filter() and document.data.parser.iterate() in ECMAScript. function myFilter(element, subject, property, object) { if(subject.value.search(/http:\/\/xmlns.com\/foaf\/0\.1/) >= 0) { return true; } } var store = document.data.store.filter({}, document.getElementById("start"), myFilter); store.forEach(function (index, subject, property, object) { alert(object); }); var iter = document.data.parser.iterate({}, document.getElementById("start"), myFilter); for(var triple=iter.next(); triple != null; triple = iter.next()) { alert(triple.object); } // text: "Albert Einstein".

5. 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. create a default Store object, which will hold information obtained from parsing; create a defaul Parser object, passing it a pointer to a store; initiate parsing, to extract information from some object -- usually a DOM object -- and place it into the store; create a default Query object which can be used to interrogate Initialize all of the information placed interfaces in the store; DOM environment required by this specification.
Some platforms may merge one or more of these steps as a convenience to developers. For example, a browser that supports this API may carry out Unless otherwise specified, the first four steps when a document loads, and then expose a Query interface to allow developers to access the PropertyGroup s. Some approaches to this will be discussed in the next section, but before we look at those, we'll give a brief overview of how each of these phases would normally be accomplished. 5.1 Creating the Data Store To create a store the createStore method base is called: document.data.store = document.data.createStore(); The store object created supports the Store interfaces providing methods to add metadata to the store. These methods are used during parsing to populate the store but they can also be used directly to add additional information. Examples of this are shown later. 5.2 Creating the Data Parser Once a store has been created, the implementor should create a default parser: document.data.parser = document.data.createParser("rdfa", store); Note that an implementation may support many types of parser, so effectively the specific parser required needs to be specified. For example, an implementation may also support a Microformats hCard parser: var parser = document.data.createParser("hCard", store); Implementations may also support different versions of a parser, for example: var parser1 = document.data.createParser("rdfa1.0", store); var parser2 = document.data.createParser("rdfa1.1", store); Probably should have a URI to identify parsers rather than a string, since not only are there many different Microformats, but also, people may end up wanting to add parsers for RDF/XML, different varieties value of JSON, and so on. However, if we treat the parameter here as a CURIE, then we can avoid having long strings. If we do that, then the version number would need to be elided with the language type: "rdfa1.0", "rdfa1.1", and so on. 5.3 Parsing the DOM Once we have a parser, we can use it to extract information from sources that contain embedded data. In the following example we extract data from the Document object: parser.parse( document ); Since the parser is connected to a store, the PropertyGroup s obtained from processing the document are now available in the variable document.data.store window.location.toString() . A store can be used more than once for parsing. For example, if we wanted to apply an hCard Microformat parser to the same document, and put the extracted data into the same store, we could do this: var store = document.data.createStore(); document.data.createParser("rdfa", store).parse(); document.data.createParser("hCard", store).parse(); The store will now contain PropertyGroup s from the RDFa parsing, as well as PropertyGroup s from the hCard parsing. If the developer wishes to reuse the store but clear it first, then the clear() method on the DataStore interface can be used. Diagram: Show the connection between a PropertyGroup and the DOM. 5.4 Creating the Data Query Query objects are used to interrogate stores and obtain a list of DOM objects that are linked to PropertyGroup s. Since there are a number of languages and techniques that can be used to express queries, we need to specify the type of query object that we'd like: var query = document.data.createQuery("rdfa", store);

6. 5. Future Discussion

This section is non-normative.

The current version of the RDFa API focuses on filtering RDF triples. It also provides methods for filtering DOM Nodes that contain certain types of RDF triples. The RDFa Working Group is currently discussing whether or not to include the following advanced functionality:

A. Acknowledgements

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

B. References

B.1 Normative references

[BCP47] A. Phillips, M. Davis. Tags for Identifying Languages September 2009. IETF Best Current Practice. URL: http://tools.ietf.org/rfc/bcp/bcp47.txt
[HTML-RDFA]
Manu Sporny; et al. HTML+RDFa 04 March 2010. W3C Working Draft. URL: http://www.w3.org/TR/rdfa-in-html/
[IRI] M. Duerst, M. Suignard. Internationalized Resource Identifiers (IRI). January 2005. Internet RFC 3987. URL: http://www.ietf.org/rfc/rfc3987.txt [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 [RDF-TESTCASES]
[RDF-API]
Jan Grant; Dave Beckett. Nathan Rixham, Manu Sporny; et al. RDF Test Cases. API 10 February 2004. Latest. W3C Recommendation. Editor's Draft. URL: http://www.w3.org/TR/2004/REC-rdf-testcases-20040210 http://www.w3.org/2010/02/rdfa/sources/rdf-api/
[RDFA-CORE]
Shane McCarron; et al. RDFa Core 1.1: Syntax and processing rules for embedding RDF through attributes. 3 August 2010. 31 March 2011. W3C Working Draft. URL: http://www.w3.org/TR/2010/WD-rdfa-core-20100803 http://www.w3.org/TR/2011/WD-rdfa-core-20110331
[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/
[XHTML-RDFA]
Shane McCarron; et. al. XHTML+RDFa 1.1. 3 August 2010. 31 March 2011. W3C Working Draft. URL: http://www.w3.org/TR/WD-xhtml-rdfa-20100803 http://www.w3.org/TR/2011/WD-xhtml-rdfa-20110331

B.2 Informative references

[DOM-LEVEL-1]
Vidur Apparao; et al. Document Object Model (DOM) Level 1. 1 October 1998. W3C Recommendation. URL: http://www.w3.org/TR/1998/REC-DOM-Level-1-19981001/
[ECMA-262]
ECMAScript Language Specification, Third Edition. December 1999. URL: http://www.ecma-international.org/publications/standards/Ecma-262.htm
[MICROFORMATS]
Microformats . URL: http://microformats.org
[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
[RDFA-PRIMER]
Mark Birbeck; Ben Adida. RDFa Primer. 14 October 2008. W3C Note. URL: http://www.w3.org/TR/2008/NOTE-xhtml-rdfa-primer-20081014
[RDFA-SYNTAX]
Ben Adida, et al. RDFa in XHTML: Syntax and Processing. 14 October 2008. W3C Recommendation. URL: http://www.w3.org/TR/2008/REC-rdfa-syntax-20081014
[SVGTINY12]
Scott Hayman; et al. Scalable Vector Graphics (SVG) Tiny 1.2 Specification. 22 December 2008. W3C Recommendation. URL: http://www.w3.org/TR/2008/REC-SVGTiny12-20081222
[TURTLE]
David Beckett, Tim Berners-Lee. Turtle: Terse RDF Triple Language January 2008. W3C Team Submission. URL: http://www.w3.org/TeamSubmission/turtle/