Copyright
©
2010
2010-2010
W3C
®
(
MIT
,
ERCIM
,
Keio
),
All
Rights
Reserved.
W3C
liability
,
trademark
and
document
use
rules
apply.
RDFa
[
RDFA-CORE
]
enables
authors
to
publish
structured
information
that
is
both
human-
and
machine-readable.
Concepts
that
have
traditionally
been
difficult
for
machines
to
detect,
like
people,
places,
events,
music,
movies,
and
recipes,
are
now
easily
marked
up
in
Web
documents.
While
publishing
this
data
is
vital
to
the
growth
of
Linked
Data
,
using
the
information
to
improve
the
collective
utility
of
the
Web
for
humankind
is
the
true
goal.
To
accomplish
this
goal,
it
must
be
simple
for
Web
developers
to
extract
and
utilize
structured
information
from
a
Web
document.
This
document
details
such
a
mechanism;
an
RDFa
Document
Object
Model
Application
Programming
Interface
(RDFa
DOM
API)
that
allows
simple
extraction
and
usage
of
structured
information
from
a
Web
document.
This section is non-normative.
This
document
is
a
detailed
specification
for
an
RDFa
DOM
API
.
The
document
is
primarily
intended
for
the
following
audiences:
For those looking for an introduction to the use of RDFa, or some real-world examples, please consult the RDFa Primer [ RDFA-PRIMER ].
If you are not familiar with RDF, you should read about the Resource Description Framework (RDF) [ RDF-CONCEPTS ] before reading this document. The [ RDF-CONCEPTS ] document outlines the core data model that is used by RDFa to express information.
If
you
are
not
familiar
with
RDFa,
you
should
read
and
understand
the
[
RDFA-CORE
]
specification.
It
describes
how
data
is
encoded
in
host
languages
using
RDFa.
A
solid
understanding
of
concepts
in
RDFa
Core
will
inevitably
help
you
understand
how
the
RDFa
DOM
API
works
in
concert
with
how
the
data
is
expressed
in
a
host
language.
If you are a Web developer and are already familiar with RDF and RDFa, and you want to programatically extract RDFa content from documents, then you will find the Concept Diagram and Developing with the API sections of most interest. It contains a handful of JavaScript examples on how to use the RDFa API .
Readers who are not familiar with the Terse RDF Triple Language [ TURTLE ] may want to read the specification in order to understand the short-hand RDF notation used in some of the examples.
This
document
uses
the
Web
Interface
Definition
Language
[
WEBIDL
]
to
specify
all
language
bindings.
If
you
intend
to
implement
the
RDFa
DOM
API
you
should
be
familiar
with
the
Web
IDL
language
[
WEBIDL
].
Examples may contain references to existing vocabularies and use abbreviations in CURIEs and source code. The following is a list of all vocabularies and their abbreviations, as used in this document:
rdf
,
e.g.,
rdf:type
)
xsd
,
e.g.,
xsd:integer
)
rdfs
,
e.g.,
rdfs:label
)
foaf
,
e.g.,
foaf:name
)
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
First
Public
Working
an
Editor's
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
Editor's
Draft
does
not
imply
endorsement
by
the
W3C
Membership.
This
is
a
draft
document
and
may
be
updated,
replaced
or
obsoleted
by
other
documents
at
any
time.
It
is
inappropriate
to
cite
this
document
as
other
than
work
in
progress.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy . W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy .
This section is non-normative.
RDFa provides a means to attach properties to elements in XML and HTML documents. Since the purpose of these additional properties is to provide information about real-world items, such as people, films, companies, events, and so on, properties are grouped into objects called Property Groups.
The
RDFa
DOM
API
provides
a
set
of
interfaces
that
make
it
easy
to
manipulate
DOM
objects
that
contain
information
that
is
also
part
of
a
Property
Group.
This
specification
defines
these
interfaces.
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 access to the data after it has been interpreted.
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 Property Group.
All
of
this
is
achieved
through
the
RDFa
DOM
API.
There
are
many
scenarios
in
which
the
RDFa
DOM
API
can
be
used
to
extract
information
from
a
Web
document.
The
following
sections
describe
a
few
of
these
scenarios.
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 JavaScript 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 Javascript tool. The Javascript 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:description">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>
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 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#"> <div about="#offering" typeof="gr:Offering"> <div property="rdfs:label" content="Harry Potter and the Deathly Hallows" xml:lang="en"></div> <div property="rdfs:comment" content="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." xml:lang="en"></div> <div rel="foaf:depiction" resource="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"> <div typeof="gr:UnitPriceSpecification"> <div property="gr:hasCurrency" content="USD" datatype="xsd:string"></div> <div property="gr:hasCurrencyValue" content="7.49" datatype="xsd:float"></div> </div> </div> <div rel="gr:acceptedPaymentMethods" resource="http://purl.org/goodrelations/v1#PayPal"></div> <div rel="gr:acceptedPaymentMethods" resource="http://purl.org/goodrelations/v1#MasterCard"></div> <div rel="foaf:page" resource="http://www.amazon.com/Harry-Potter-Deathly-Hallows-Book/dp/0545139708"></div> </div> </div>
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>
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
DOM
API.
<div prefix="dc: http://purl.org/dc/terms/ foaf: http://xmlns.com/foaf/0.1/" > <span 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 <span about="#me" rel="foaf:account"> <a href="http://twitter.com/bob" typeof="foaf:term_OnlineAccount" property="foaf:accountName">http://twitter.com/bob</a>. </p> </div>
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 to build on top of the structured data 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> <span property="vc:locality">London</span>, <span property="vc:country-name">United Kingdom</span> </span> <span property="vc:tel">020 74373071</span> </div>
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.
<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>
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
from
Web
documents
or
other
document
formats
that
utilize
RDFa.
The
RDFa
DOM
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
DOM
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
JavaScript
[
ECMA-262
],
the
implementation
of
the
RDFa
DOM
API
is
primarily
concerned
with
ensuring
that
concepts
covered
in
this
document
are
easily
utilized
in
JavaScript.
While
JavaScript
is
of
primary
concern,
the
RDFa
DOM
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
DOM
API
are
designed
to
work
as
seamlessly
as
possible
with
language-native
types,
operators,
and
program
flow
constructs.
The design goals that drove the creation of the APIs that are described in this document are:
document.getElementsBySubject()
,
which
mirrors
the
document.getElementsById()
functionality
that
is
a
part
of
[
DOM-LEVEL-1
].
The following diagram describes the relationship between all concepts discussed in this document.
Diagram
of
RDFa
DOM
API
Concepts
The lowest layer of the API defines the basic structures that are used to store information; IRI, Plain Literal, Typed Literal, Blank Node and finally the RDF Triple.
The next layer of the API, the Data Store, supports the storage of information.
The Data Parser and Data Query interfaces directly interact with the Data Store. The Data Parser is used to extract information from the Document and store the result in a Data Store. The Data Query interface is used to extract different views of data from the Data Store. The Property Group is an abstract, easily manipulable view of this information for developers. While Property Group objects can address most use cases, a developer also has access to the information in the Data Store at a basic level. Access to the raw data allows developers to create new views and ways of directly manipulating the data in a Data Store.
The highest layer to the API is the Document object and is what most web developers will use to retrieve Property Groups created from data stored in the document.
This section is non-normative.
This section is non-normative.
This API provides a number of interfaces to enable:
The
RDFa
DOM
API
has
a
number
of
advanced
methods
that
can
be
used
to
access
the
Data
Store,
Data
Parser
and
Data
Query
mechanisms.
Most
web
developers
will
not
need
to
use
the
advanced
methods
-
most
will
only
require
the
following
interfaces
for
most
of
their
day-to-day
development
activities.
document.getItemsByType(type)
foaf:Person
.
document.getItemBySubject(type)
http://example.org/people#bob
.
document.getItemsByProperty(property,
optional
value)
document.getElementsByType(type)
foaf:Person
.
document.getElementsBySubject(type)
http://example.org/people#bob
.
document.getElementsByProperty(property,
optional
value)
document.data.context.setMapping(prefix,
iri)
foaf:Person
to
http://xmlns.com/foaf/0.1/Person
.
document.data.query.select(query,
template)
document.data.store.filter(subject,
predicate,
object)
document.data.store.filter(pattern)
document.data.parser.iterate(iterFunction)
The
following
section
uses
the
markup
shown
below
to
demonstrate
how
to
extract
and
use
Property
Groups
using
the
RDFa
DOM
API.
The
following
markup
is
assumed
to
be
served
from
a
document
located
at
http://example.org/people
.
<div prefix="foaf: http://xmlns.com/foaf/0.1/" about="#albert" typeof="foaf:Person"> <span property="foaf:name">Albert Einstein</span> </div>
You can retrieve the object that is described above by doing the following:
var people = document.getItemsByType("http://xmlns.com/foaf/0.1/Person");or you can specify a short-cut to use when specifying the IRI:
document.data.context.setMapping("foaf", "http://xmlns.com/foaf/0.1/"); var people = document.getItemsByType("foaf:Person");
You can also get a Property Group by its subject:
var albert = document.getItemBySubject("http://example.org/people#albert");
You can also specify a relative IRI and the document IRI will be automatically pre-pended:
var albert = document.getItemBySubject("#albert");
You can get a list of Property Groups by their properties:
var peopleNamedAlbertEinstein = document.getItemByProperty("foaf:name", "Albert Einstein");
You can retrieve property values from Property Groups like so:
var albert = document.getItemBySubject("#albert"); var name = albert.get("foaf:name");
You can also specify values that you would like to map to Property Group attributes:
var albert = document.getItemBySubject("#albert", {"foaf:name": "name"}); var name = albert.name;
You can retrieve the DOM Node 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/"); var elements = document.getElementsByType("foaf:Person");
You can also get a list of Elements by the subject of data:
var elements = document.getElementsBySubject("http://example.org/people#albert");
You can also specify a relative IRI and the document IRI will be automatically pre-pended:
var elements = document.getElementsBySubject("#albert");
You can get a list of Elements by the properties and values that they declare:
var elements = document.getElementsByProperty("foaf:name", "Albert Einstein");
You can modify elements that are returned just like any other DOM Node, for example:
var elements = document.getElementsByProperty("foaf:name", "Bob"); for(i = 0; i <= elements.length; i++) { var e = elements[i]; e.style.setProperty('color', '#00cc00', null); }
The code above would change the color of all the areas of the page where the item's name is "Bob" to green.
This
section
covers
a
number
of
concepts
that
go
beyond
basic
everyday
usage
of
the
RDFa
DOM
API.
The
interfaces
to
the
DOM
API
allow
you
to
work
with
data
at
an
abstract
level,
or
query
structured
data
and
override
key
parts
of
the
software
stack
in
order
to
extend
the
functionality
that
the
API
provides.
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.
Perhaps
the
most
basic
task
is
to
select
Property
Groups
of
a
particular
type.
The
type
of
a
Property
Group
is
set
in
RDFa
via
the
special
attribute
@typeof
.
For
example,
the
following
markup
expresses
a
Property
Group
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 Property Groups that are people we would do the following:
var query = document.data.createQuery("rdfa", store); var ar = query.select( { "rdf:type": "foaf:Person" } );
Note that the Query object has access to the mappings provided via the document.data.context object, so they can also be used in queries. It is also possible to write the same query in a way that is independent of any prefix-mappings:
var ar = query.select( { "http://www.w3.org/1999/02/22-rdf-syntax-ns#type": "http://xmlns.com/foaf/0.1/Person" } );
The
previous
query
selected
all
Property
Groups
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 Property Groups of type Person that also have a Myers Brigg's personality type of "INTP" (aka: The Architect):
var architects = query.select( { "http://www.w3.org/1999/02/22-rdf-syntax-ns#type": "http://xmlns.com/foaf/0.1/Person", "http://xmlns.com/foaf/0.1/myersBriggs": "INTP" } ); var name = architects[0].get("http://xmlns.com/foaf/0.1/name");
As before, prefix-mappings can also be used:
var architects = query.select( {"rdf:type": "foaf:Person", "foaf:myersBriggs": "INTP"} ); var name = architects[0].get("foaf:name");
Directives to generate the Property Group object based on a template specified by the developer can also be used. In this case, all of the "INTP" personality types are gleaned from the page and presented as Property Groups 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 name = architects[0].name; var infoWebpage =architects[0].info;architects[0].webpage;
The
RDFa
DOM
API
allows
a
developer
to
not
only
query
the
Data
Store
at
via
the
Data
Query
mechanism,
it
also
allows
a
developer
to
get
to
the
underlying
data
structures
that
represent
the
structured
data
at
the
"atomic
level".
The
filter
interface
is
a
part
of
the
Data
Store
and
enables
a
developer
to
filter
a
series
of
triples
out
of
the
Data
Store.
For
example,
to
extract
all
triples
about
a
particular
subject,
the
developer
could
do
the
following:
var names =document.data.store.filter("http://example.org/people#benjamin");document.data.store.filter({"subject: "http://example.org/people#benjamin"});
Developers
could
also
combine
subject-predicate
subject-property
filters
by
doing
the
following:
var names =document.data.store.filter("http://example.org/people#benjamin",document.data.store.filter({"subject:", "http://example.org/people#benjamin", "property": "foaf:nick");
The query above would extract all known nicknames for the subject as triples.
A developer may also retrieve all triples in the Data Store by specifying no filter parameters:
var allTriples = document.data.store.filter();
The .iterate interface will almost certainly see large changes in the next version of the RDFa API specification. Implementers are warned to not implement the interface and wait for the next revision of this specification.
The
iterate
interface
can
be
used
to
process
triples
in
the
document
as
they
are
discovered.
This
interface
is
most
useful
for
processing
large
amounts
of
data
in
low-memory
environments.
var iter = document.data.parser.iterate("http://example.org/people#mark"); for(var triple = iter.next(); iter != null; triple = iter.next()) { // process each triple that is associated with http://example.org/people#mark }
The
major
modules
in
the
RDFa
DOM
API
are
meant
to
be
overridden
by
developers
in
order
to
extend
basic
functionality
as
well
as
innovate
new
interfaces
for
the
RDFa
DOM
API.
The API is designed such that a developer may override the default data store provided by the browser by providing their own. This is useful, for instance, if the developer wanted to create a permanent site-specific data store using Local Storage features in the browser, or allowing provenance information to be stored with each triple.
var mydatastore = new MyCustomDataStore(); document.data.store = mydatastore;
Developers may create and specify different parsers for parsing structured data from the document that builds upon RDFa, or parses other languages not related to RDFa. For example, Microformats-specific parsers could be created to extract structured hCard data and store it in an object that is compatible with the Data Store interface.
var hcardParser = new MyHCardParser(); document.data.parser = hcardParser;
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 . }");
The following section contains all of the interfaces that developers are expected to implement.
RDFa
is
a
syntax
for
expressing
the
RDF
Data
Model
[
RDF-CONCEPTS
]
in
Web
documents.
The
RDFa
DOM
API
is
designed
to
extract
the
RDF
Data
Model
from
Web
documents.
The
following
RDF
Resources
are
utilized
in
this
specification:
Plain
Literals
,
Typed
Literals
,
IRI
References
(as
defined
in
[
IRI
])
and
Blank
Nodes
.
The
interfaces
for
each
of
these
RDF
Resources
are
detailed
in
this
section.
The
types
as
exposed
by
the
RDFa
DOM
API
conform
to
the
same
data
and
comparison
restrictions
as
specified
in
the
RDF
concepts
specification
[
RDF-CONCEPTS
]
and
the
[
IRI
]
specification.
Each
RDF
interface
provides
access
to
both
the
extracted
RDFa
value
and
the
DOM
Node
from
which
the
value
was
extracted.
This
allows
developers
to
extract
and
use
RDF
triples
from
a
host
language
and
also
manipulate
the
DOM
based
on
the
associated
DOM
Node.
For
example,
an
agent
could
highlight
all
strings
that
are
marked
up
as
foaf:name
properties
in
a
Web
document.
The
basic
RDF
Resource
types
used
in
the
RDFa
DOM
API
are:
http://www.w3.org/2001/XMLSchema#string
.
"Harry
Potter
and
the
Half-Blood
Prince"@en
is
a
plain
literal
expressed
in
the
English
language.
"7"^^xsd:integer
is
a
typed
literal
with
a
value
of
type
xsd:integer
.
_:me
,
and
_:42
.
<http://example.org/hp>
rdfs:label
"Harry
Potter"
.
An
RDFa
DOM
API
implementer
must
provide
the
basic
types
as
described
in
this
specification.
An
implementer
may
provide
additional
types
and/or
a
deeper
type
or
class
hierarchy
that
includes
these
basic
types.
An
IRI
Reference
in
the
RDFa
DOM
API
points
to
a
resource
and
is
further
defined
in
[
IRI
].
[NoInterfaceObject]
interface IRI {
readonly attribute stringifier DOMString value;
};
value
of
type
stringifier
DOMString
,
readonly
An
RDF
Literal
is
an
RDF
Resource
that
represents
lexical
values
in
RDFa
data.
The
two
RDF
Literals
provided
via
the
RDFa
DOM
API
are
PlainLiterals
and
TypedLiterals.
For
a
given
RDF
Literal
,
either
language
or
type
information
can
be
provided.
If
the
type
is
set,
the
RDF
Literal
is
a
Typed
Literal
.
If
a
type
is
not
set,
it
is
a
Plain
Literal
.
'en'
,
'fr'
,
'de'
).
http://www.w3.org/2001/XMLSchema#DateTime
).
PlainLiterals have a string value and may specify a language.
[NoInterfaceObject]
interface PlainLiteral {
readonly attribute stringifier DOMString value;
readonly attribute DOMString language;
};
language
of
type
DOMString
,
readonly
value
of
type
stringifier
DOMString
,
readonly
This section is non-normative.
The following example demonstrates a few common use cases of the PlainLiteral type.
>> var literal = document.data.store.createPlainLiteral('Harry Potter and the Half-Blood Prince', 'en'); >> print(literal.toString()); Harry Potter and the Half-Blood Prince >> print(literal.value); Harry Potter and the Half-Blood Prince >> print(literal.language); en
A TypedLiteral has a string value and a datatype specified as an IRI Reference . TypedLiterals can be converted into native language datatypes of the implementing programming language by registering a Typed Literal Converter as defined later in the specification.
The
datatype's
IRI
reference
specifies
the
datatype
of
the
text
value,
e.g.,
xsd:DataTime
or
xsd:boolean
.
The
RDFa
DOM
API
provides
a
method
to
explicitly
convert
TypedLiteral
values
to
native
datatypes
supported
by
the
host
programming
language.
Developers
may
write
their
own
Typed
Literal
Converters
in
order
to
convert
an
RDFLiteral
into
a
native
language
type.
The
converters
are
registered
by
using
the
registerTypeConversion()
method.
Default
TypedLiteral
converters
must
be
supported
by
the
RDFa
DOM
API
implementation
for
the
following
XML
Schema
datatypes
:
[NoInterfaceObject]
interface TypedLiteral {
readonly attribute stringifier DOMString value;
readonly attribute IRI
type;
any valueOf ();
};
type
of
type
IRI
,
readonly
value
of
type
stringifier
DOMString
,
readonly
valueOf
Any
any
This section is non-normative.
The following example demonstrates how a TypedLiteral representing a date is automatically converted to JavaScript's native DateTime object.
>> var literal = document.data.store.createTypedLiteral('2010-12-24', "xsd:date"); >> print(literal.toString()); 2010-12-24 >> print(literal.value); 2010-12-24 >> print(literal.valueOf()); Fri Dec 24 2010 00:00:00 GMT+0100
A
BlankNode
is
an
RDF
resource
that
does
not
have
a
corresponding
IRI
reference,
as
defined
in
[
RDF-CONCEPTS
].
The
value
of
a
BlankNode
is
not
required
to
be
the
same
for
identical
documents
that
are
parsed
at
different
times.
The
purpose
of
a
BlankNode
is
to
ensure
that
RDF
Resources
in
the
same
document
can
be
compared
for
equivalence
by
ID.
The reasoning behind how we stringify BlankNodes should be explained in more detail.
BlankNodes are stringified by concatenating "_:" to BlankNode.value
[NoInterfaceObject]
interface BlankNode {
readonly attribute stringifier DOMString value;
};
value
of
type
stringifier
DOMString
,
readonly
Developers and authors must not assume that the value of a Blank Node will remain the same between two processing runs. Blank Node values are only valid for the most recent processing run on the document. Blank Nodes values will often be generated differently by different RDFa Processors.
This section is non-normative.
The following example demonstrates the use of a BlankNode in a JavaScript implementation that uses incrementing numbers for the identifier.
>> var bna = document.data.store.createBlankNode(); // create a new BlankNode A >> var bnb = document.data.store.createBlankNode(); // create a new BlankNode B >> print(bna.toString()); // Stringify BlankNode A _:1 >> print(bna.value); // print value of BlankNode A 1 >> print(bnb.value); // print value of BlankNode B 2
The
RDFTriple
interface
represents
an
RDF
triple
as
specified
in
[
RDF-CONCEPTS
].
RDFTriple
can
be
used
by
referring
to
properties,
such
as
subject
,
predicate
property
,
and
object
.
RDFTriple
can
also
be
used
by
referring
to
pre-defined
indexes.
The
stringification
of
RDFTriple
results
in
an
N-Triples-based
representation
as
defined
in
[
N3
RDF-TESTCASES
].
[NoInterfaceObject, Null=Null]
interface RDFTriple {
readonly attribute Object subject;
readonly attribute IRI
property;
readonly attribute Object object;
stringifier DOMString toString ();
};
toString
stringifier
DOMString
This section is non-normative.
The
following
examples
demonstrate
the
basic
usage
of
an
RDFTriple
object.
The
creation
of
the
triple
uses
the
foaf:name
CURIE,
which
is
transformed
into
an
IRI.
The
example
assumes
that
a
mapping
has
already
been
created
for
foaf
.
For
more
information
on
creating
RDFa
DOM
API
mappings,
see
the
section
on
IRI
Mappings
.
>> var triple = document.data.store.createTriple('http://www.example.com#foo', 'foaf:name', \ document.data.store.createPlainLiteral('foo')); //create a new RDFTriple >> print(triple.subject); // print the property subject of the RDFTriple http://www.example.com#foo >> print(triple.toString()); // stringify the RDFTriple <http://www.example.com#foo> <http://xmlns.com/foaf/0.1/name> "foo" .
A number of convenience objects and methods are provided by the RDFa DOM API to help developers manipulate RDF Resources more easily when writing Web applications.
The basic RDF interface types described earlier in this document are utilized by the following Structured Data Interfaces:
Processing RDF data involves the frequent use of unwieldy IRI references and frequent type conversion. The DataContext interface is provided in order to simplify contextual operations such as shortening IRIs and converting RDF data into native language datatypes.
It
is
assumed
that
this
interface
is
created
and
available
before
a
document
is
parsed
for
RDFa
data.
For
example,
while
operating
within
a
Browser
Context,
it
is
assumed
that
the
following
lines
of
code
are
executed
before
a
developer
has
access
to
the
RDFa
DOM
API
methods
on
the
document
object:
document.data.context = new DataContext(); document.data.context.setMapping("rdf", "http://www.w3.org/1999/02/22-rdf-syntax-ns#"); document.data.context.setMapping("xsd", "http://www.w3.org/2001/XMLSchema-datatypes#");
In general, when a CURIE is resolved by the RDFa API or a TypedLiteral is converted to a native language type, the current DataContext stored in the DocumentData object must be used to perform the action. This is to ensure that there is only one active DataContext in use by the RDFa API at any given time. The default DataContext stored in the DocumentData object may be changed at runtime.
All of the code that sets up the default type converters for Browser Contexts that use Javascript should probably be in the code snippet above.
The following interface allows IRI mappings to be easily created and used by Web Developers at run-time. It also allows for conversion of RDF data into native language datatypes.
interface DataContext {
void setMapping (in DOMString prefix, in DOMString iri);
void registerTypeConversion (in DOMString iri, in TypedLiteralConverter
converter);
IRI
resolveCurie (in DOMString curie);
};
registerTypeConversion
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
iri |
DOMString
|
✘ | ✘ |
A
string
specifying
the
IRI
datatype.
The
string
may
be
a
CURIE.
For
example:
http://www.w3.org/2001/XMLSchema-datatypes#integer
or
xsd:integer
.
|
converter |
|
✘ | ✘ |
|
void
resolveCurie
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
curie |
DOMString
| ✘ | ✘ | The CURIE that is to be resolved into an IRI. |
IRI
setMapping
foaf
IRI
mapping,
they
would
call
setMapping("foaf",
"http://xmlns.com/foaf/0.1/")
.
Calling
the
setMapping()
method
with
a
prefix
value
that
does
not
exist
results
in
the
creation
of
a
new
mapping.
Calling
the
method
with
a
null
IRI
value
will
remove
the
mapping.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
prefix |
DOMString
|
✘ | ✘ |
The
prefix
to
put
into
the
mapping
as
the
key.
(e.g.,
foaf
)
|
iri |
DOMString
|
✘ | ✘ |
The
IRI
reference
to
place
into
the
mapping
as
the
mapped
value
of
the
given
prefix.
(e.g.,
"http://xmlns.com/foaf/0.1/")
|
void
TypedLiteralConverter is a callable interface that transforms the value of a TypedLiteral into a native language type in the current programming language. The type IRI of the TypedLiteral is used to determine the best mapping to the native language type.
A TypedLiteralConverter may be implemented as a class, or as a language-native callback in languages like ECMAScript.
[NoInterfaceObject Callback]
interface TypedLiteralConverter {
any convertType (in DOMString value, in optional DOMString targetType);
};
convertType
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
value |
DOMString
|
✘ | ✘ | The value to convert that is associated with the RDFTypedLiteral. |
targetType |
DOMString
| ✘ | ✔ |
The
target
type
of
the
conversion.
The
string
is
a
free-form,
developer-specifed
string
that
is
used
by
the
developer-specified
convertType()
method.
It
is
currently
not
specified
how
the
targetType
is
specified
by
the
calling
code.
The
API
may
need
to
expose
the
targetType
at
a
higher
level
interface
or
provide
a
convert()
method
on
the
DataContext
interface
that
allows
the
specification
of
the
targetType.
|
Any
any
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);
IRI mappings for all terms in the following vocabularies must be included: rdf and xsd .
All
methods
that
accept
CURIEs
as
arguments
in
the
RDFa
DOM
API
must
use
the
algorithm
specified
in
RDFa
Core,
Section
7.4:
CURIE
and
URI
Processing
[
RDFA-CORE
]
for
TERMorCURIEorURI
.
The
prefix
and
term
mappings
are
provided
by
the
current
document.data.context
instance.
This section is non-normative.
The
following
examples
demonstrate
how
mappings
are
created
and
used
via
the
RDFa
DOM
API.
// create new IRI mapping document.data.context.setMapping("foaf", "http://xmlns.com/foaf/0.1/"); // The new IRI mapping is automatically used when CURIEs are expanded to IRIs var people = document.getItemsByType("foaf:Person");
In
the
example
above,
the
CURIE
"
foaf:Person
"
is
expanded
to
an
IRI
with
the
value
"
http://xmlns.com/foaf/0.1/Person
"
in
the
getItemsByType
method.
This section is non-normative.
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'); >> print(literal.toString()); 1 >> print(literal.value); 1 >> print(literal.valueOf()); true
The DataStore is a set of RDFTriple objects. It provides a basic getter as well as an indexed getter for retrieving individual items from the store. The Data Store can be used to create primitive types as well as store collections of them in the form of RDFTriples.
The forEach method is not properly defined in WebIDL - need to get input from the WebApps Working Group on how best to author this interface.
[NoInterfaceObject]
interface DataStore {
readonly attribute unsigned long size;
[IndexGetter]
Object get (in unsigned long index);
boolean add (in RDFTriple
triple);
IRI
createIRI (in DOMString iri, in optional Node node);
PlainLiteral
createPlainLiteral (in DOMString value, in optional DOMString? language);
TypedLiteral
createTypedLiteral (in DOMString value, in DOMString type);
BlankNode
createBlankNode (in optional DOMString name);
RDFTriple
createTriple (in Object subject, in IRI
property, in Object object);
[Null=Null]
DataStore
filter (in optional Object? pattern, in optional Node? element, in optional RDFTripleFilter
filter);
void clear ();
void forEach (in function callback);
boolean merge (in DataStore
store);
};
size
of
type
unsigned
long
,
readonly
add
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
triple |
|
✘ | ✘ | The triple to add to the Data Store. |
boolean
clear
void
createBlankNode
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
name |
DOMString
|
✘ | ✔ | The name of the Blank Node, which will be used when Stringifying the Blank Node. |
BlankNode
createIRI
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
iri |
DOMString
|
✘ | ✘ | The IRI reference's lexical value. |
node |
Node
|
✘ | ✔ | An optional DOM Node to associate with the IRI. |
IRI
createPlainLiteral
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
value |
DOMString
|
✘ | ✘ |
The
value
of
the
|
language |
DOMString
|
✔ | ✔ |
The
language
that
is
associated
with
the
Plain
Literal
encoded
according
to
the
rules
outlined
in
[
BCP47
|
PlainLiteral
createTriple
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
subject |
Object
|
✘ | ✘ | The subject value of the RDF Triple. The value must be either an IRI or a BlankNode. |
|
|
✘ | ✘ |
The
|
object |
Object
|
✘ | ✘ | The object value of the RDF Triple. The value must be an IRI, PlainLiteral, TypedLiteral, or BlankNode. |
RDFTriple
createTypedLiteral
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
value |
DOMString
|
✘ | ✘ | The value of the Typed Literal. |
type |
DOMString
|
✘ | ✘ | The IRI type of the Typed Literal. The argument can either be a full IRI or a CURIE. |
TypedLiteral
filter
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
|
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
The
subject
parameter
is
used
to
filter
RDFTriple
objects.
Values
can
be
of
type
DOMString,
IRI,
The
The
object
|
element |
Node
|
✔ | ✔ | The parent DOM Node where filtering should start. The implementation must only consider RDF triples on the current DOM Node and its children. |
filter |
|
✘ | ✔ | A user defined function, returning a true or false value, that determines whether or not an RDFTriple should be added to the final Array. |
DataStore
forEach
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
callback |
function
|
✘ | ✘ |
A
function
that
takes
the
following
arguments:
index,
subject,
|
void
get
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
index |
unsigned
long
|
✘ | ✘ | The index of the RDFTriple in the list to retrieve. The value must be a positive integer value greater than or equal to zero and less than DataStore::length. |
Object
merge
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
store |
| ✘ | ✘ | The external Data Store to merge into this Data Store. |
boolean
This section is non-normative.
The following examples demonstrate the three mechanisms that are available for navigating through a DataStore; index getter-based iteration, array index-based iteration, and callback-based/functional iteration.
>> var store = document.data.store.filter(); // select all RDF triples from the current Data Store >> print(store.size); // print the number of triples in the Data Store 3 >> for(var i=0; i<store.size; i++) { // loop through filtered RDF triples print(store.get(i)); // print RDF triple by using the explicit get method print(store[i]); // print RDF triple by using the indexed property method } <http://www.example.com#foo> <http://www.w3.org/2000/01/rdf-schema#label> "foo" . <http://www.example.com#foo> <http://www.w3.org/2000/01/rdf-schema#label> "foo" . <http://www.example.com#foo> <http://www.w3.org/2000/01/rdf-schema#label> "bar" . <http://www.example.com#foo> <http://www.w3.org/2000/01/rdf-schema#label> "bar" . <http://www.example.com#foo> <http://www.w3.org/2000/01/rdf-schema#label> "foobar" . <http://www.example.com#foo> <http://www.w3.org/2000/01/rdf-schema#label> "foobar" .>> function printObject(index, subject, predicate, object) { print(object) } // specify a callback function>> function printObject(index, subject, property, object) { print(object) } // specify a callback function >> store.forEach(printObject); // call the callback function for each item in the array foo bar foobar
The Data Parser is capable of processing a DOM Node and placing the parsing results into a Data Store. While this section specifies how one would parse RDFa data and place it into a Data Store, the interface is also intended to support the parsing and storage of various Microformats, eRDF, GRDDL, DC-HTML, and Microdata. Web developers that would like to write customer parsers may extend this interface.
[NoInterfaceObject]
interface DataParser {
attribute DataStore
store;
[Null=Null]
DataIterator
iterate (in optional Object? pattern, in optional Node? element, in optional RDFTripleFilter
filter);
boolean parse (in Element domElement);
};
store
of
type
DataStore
iterate
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
|
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
The
subject
parameter
is
used
to
filter
RDFTriple
objects.
Values
can
be
of
type
DOMString,
IRI,
The
The
object
|
element |
Node
|
✔ | ✔ |
The
parent
DOM
Node
where
filtering
should
start.
The
implementation
must
only
consider
RDF
|
filter |
|
✘ | ✔ |
A
user
defined
function,
returning
a
true
or
false
value,
that
determines
whether
or
not
an
RDFTriple
should
be
|
DataIterator
parse
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.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
domElement |
Element
|
✘ | ✘ | The DOM Element that should trigger triple generation. |
boolean
The DataIterator interface will almost certainly see large changes in the next version of the RDFa API specification. Implementers are warned to not implement the interface and wait for the next revision of this specification.
The DataIterator iterates through a DOM subtree and returns RDFTriples that match a filter function or triple pattern. A DOM Node can be specified so that only triples contained in the Node and its children will be a part of the iteration. The DataIterator is provided in order to allow implementers to provide a less memory intensive implementation for processing triples in very large documents.
A
DataIterator
is
created
by
calling
the
document.data.parser.iterate()
method.
[NoInterfaceObject]
interface DataIterator {
attribute DataStore
store;
readonly attribute Node root;
readonly attribute RDFTripleFilter
filter;
readonly attribute RDFTriple
triplePattern;
RDFTriple
next ();
};
filter
of
type
RDFTripleFilter
,
readonly
root
of
type
Node
,
readonly
store
of
type
DataStore
triplePattern
of
type
RDFTriple
,
readonly
next
RDFTriple
This section is non-normative.
The following examples describe the how various filter patterns can be applied to the DOM via document.data.parser.iterate().
>> var iter = document.data.parser.iterate(); // iterate over all RDF triples from current Web document as an DataIterator >> for(var triple = iter.next(); iter != null; triple = iter.next()) { // step through all RDF triples print(triple); // print current RDF triple } <http://www.example.com#foo> <http://www.w3.org/2000/01/rdf-schema#label> "foo" . <http://www.example.com#foo> <http://www.w3.org/2000/01/rdf-schema#label> "bar" . <http://www.example.com#foo> <http://www.w3.org/2000/01/rdf-schema#label> "foobar" . >> var iter2 = document.data.parser.iterate("http://www.example.com#foo"); // iterate over triples associated with a single subject >> var iter3 = document.data.parser.iterate(null, "foaf:name"); // iterate over all triples that contain a foaf:namepredicateproperty
The PropertyGroup interface provides a view on a particular subject contained in the Data Store. The PropertyGroup aggregates the RDFTriples as a single language-native object in order to provide a more natural programming primitive for developers.
PropertyGroup attributes can be accessed in the following ways in Javascript:
// creates a PropertyGroup for the given subject var person = document.getItemsBySubject("#bob"); // Access the property group attribute via complete IRI var name = person.get("http://xmlns.com/foaf/0.1/name"); // Access the property group attribute via CURIE var name = person.get("foaf:name");
[NoInterfaceObject]
interface PropertyGroup {
attribute Object info; attribute IRI
[] properties; Sequence get (in DOMString property);
};
origin
info
of
type
Element
that
originated
the
PropertyGroup
must
be
specified
in
a
property
called
source
in
the
info
attribute.
properties
of
type
array
of
IRI
get
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
|
DOMString
|
✘ | ✘ |
A
stringified
IRI
representing
a
http://xmlns.com/foaf/0.1/name
will
return
a
sequence
of
values
that
represent
FOAF
names
in
the
PropertyGroup.
The
given
|
Sequence[any]
Sequence
This section is non-normative.
The following examples demonstrate how to use the PropertyGroup interface.
>> document.data.context.setMapping("foaf", "http://xmlns.com/foaf/0.1/"); >> var ivan = document.getItemBySubject("http://www.ivan-herman.net/foaf#me"); // extract information about this subject as an PropertyGroup >> print(ivan.properties); // print all projected property names http://xmlns.com/foaf/0.1/name, http://xmlns.com/foaf/0.1/title, http://xmlns.com/foaf/0.1/surname, http://xmlns.com/foaf/0.1/givenname, http://xmlns.com/foaf/0.1/workInfoHomepage >> ivan.get("foaf:name"); // named property values of foaf:name ["Herman Iván", "Ivan Herman"] >> ivan.get("foaf:title"); // named property values of foaf:title ["Dr."] >> ivan.get("foaf:workInfoHomepage"); // named property values of foaf:workInfoHomepage ["http://www.iswsa.org/", "http://www.iw3c2.org", "http://www.w3.org/2001/sw/#activity"]
document.getItemsByType()
returns
a
list
of
Property
Groups
that
match
the
query.
By
default
there
is
always
a
property
called
on
the
Property
Group
and
all
of
its
properties,
which
refers
back
to
an
element
in
the
source
document.
origin
PropertyGroup.info.source
The
property
allows
programmers
to
manipulate
DOM
objects
based
on
the
embedded
metadata
that
they
refer
to.
For
example,
to
set
a
thin
blue
border
on
each
Person
,
we
could
do
this:
origin
PropertyGroup.info.source
var people = document.getItemsByType("foaf:Person"); for (var i = 0; i < people.length; i++) {people[i].origin.style.border = "1px solid blue";people[i].info.source.style.border = "1px solid blue"; }
A query can be used to retrieve not only basic Property Groups, but can also specify how Property Groups are built by utilizing Property Group Templates.
For example, assume our source document contains the following event, marked up using the Google Rich Snippet Event format (example taken from the Rich Snippet tutorial, and slightly modified):
<div vocab="http://rdf.data-vocabulary.org/#" typeof="Event"> <a href="http://www.example.com/events/spinaltap" rel="v:url" property="summary">Spinal Tap</a> <img src="spinal_tap.jpg" rel="v:photo" /> <span property="description">After their highly-publicized search for a new drummer, Spinal Tap kicks off their latest comeback tour with a San Francisco show. </span> When: <span property="startDate" content="20091015T1900Z">Oct 15, 7:00PM</span>— <span property="endDate" content="20091015T2100Z">9:00PM</span> </div>
To query for all Event Property Groups we know that we can do this:
var ar = query.select({ "rdf:type": "http://rdf.data-vocabulary.org/#Event" });
However, to build a special PropertyGroup that contains the summary, start date and end date, we need only do this:
var events = query.select({ "rdf:type": "http://rdf.data-vocabulary.org/#Event" }, {"rdf:type" : "type", "v:summary": "summary", "v:startDate": "start", "v:endDate": "end"} );
The second parameter is a PropertyGroup Template. Each key-value pair specifies an IRI to map to an attribute in the resulting PropertyGroup object.
Exposing the embedded data in each Property Group makes it easy to create an HTML anchor that will allow users to add the event to their Google Calendar, as follows:
var anchor, button, i, pg; for (i = 0; i < events.length; i++) { // Get the Property Group: pg = events[i]; // Create the anchor anchor = document.createElement("a"); // Point to Google Calendar anchor.href = "http://www.google.com/calendar/event?action=TEMPLATE" + "&text=" + pg.summary + "&dates=" + pg.start + "/" + pg.end; // Add the button button = document.createElement("img"); button.src = "http://www.google.com/calendar/images/ext/gc_button6.gif"; anchor.appendChild(button); // Add the link and button to the DOM objectpg.origin.appendChild(anchor);pg.info.source.appendChild(anchor); }
The
result
will
be
that
the
event
has
an
HTML
a
element
at
the
end
(and
any
Event
on
the
page
will
follow
this
pattern):
<div vocab="http://rdf.data-vocabulary.org/#" typeof="Event"> . . . <a href="http://www.google.com/calendar/event?action=TEMPLATE&text=Spinal+Tap&dates=20091015T1900Z/20091015T2100Z"> <img src="http://www.google.com/calendar/images/ext/gc_button6.gif" /> </a> </div>
For more detailed information about queries see the Data Query interface.
The Data Query interface provides a means to query a Data Store. While this interface provides a simple mechanism for querying a Data Store for RDFa, it is expected that developers will implement other query interfaces that conform to this Data Query interface for languages like SPARQL or other Domain Specific Language.
[NoInterfaceObject]
interface DataQuery {
attribute DataStore
store;
Sequence select (in Object? query, in optional Object template);
};
store
of
type
DataStore
select
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
query |
Object
|
✔ | ✘ |
An
associative
array
containing
|
template |
Object
|
✘ | ✔ |
A
template
describing
the
attributes
to
create
in
each
Property
Group
that
is
returned.
The
template
is
an
associative
array
containing
|
Sequence[PropertyGroup]
Sequence
The
RDFa
DOM
API
is
designed
to
provide
a
small,
powerful
set
of
interfaces
that
a
developer
may
use
to
retrieve
RDF
triples
from
a
Web
document.
The
core
interfaces
were
described
in
the
previous
two
sections.
This
section
focuses
on
the
final
RDFa
API
that
most
developers
will
utilize
to
generate
the
objects
that
are
described
in
the
RDF
Interfaces
and
the
Structured
Data
Interfaces
sections.
The
following
API
is
provided
by
this
specification:
The following section describes all of the extensions that are necessary to enable manipulation of structured data within a Web Document.
[Supplemental, NoInterfaceObject]
interface RDFaDocument {
readonly attribute DocumentData
data; DocumentData
createDocumentData (); PropertyGroupList getItemsByType (in DOMString type); PropertyGroupList getItemBySubject (in DOMString subject); PropertyGroupList getItemsByProperty (in DOMString property, in DOMString value); NodeList getElementsByType (in DOMString type); NodeList getElementsBySubject (in DOMString subject); NodeList getElementsByProperty (in DOMString property, in DOMString value);
};
data
of
type
DocumentData
,
readonly
createDocumentData
store
,
context
,
parser
and
query
attributes
initialized
to
sensible
defaults
that
would
allow
the
immediate
extraction
of
RDFa
data
from
the
current
document
by
calling
DocumentData.parser.parse(document)
.
DocumentData
getElementsByProperty
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
property |
DOMString
|
✘ | ✘ |
A
DOMString
representing
an
IRI-based
property.
The
string
can
either
be
a
full
IRI
or
a
CURIE.
|
value |
DOMString
|
✘ | ✘ | A DOMString representing the value to match against. |
NodeList
getElementsBySubject
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
subject |
DOMString
|
✘ | ✘ |
A
DOMString
representing
an
IRI-based
subject.
The
string
can
either
be
a
full
IRI
or
a
CURIE.
|
NodeList
getElementsByType
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
type |
DOMString
|
✘ | ✘ |
A
DOMString
representing
an
rdf:type
to
select
against.
|
NodeList
getItemBySubject
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
subject |
DOMString
|
✘ | ✘ |
A
DOMString
representing
an
IRI-based
subject.
The
string
can
either
be
a
full
IRI
or
a
CURIE.
|
PropertyGroupList
getItemsByProperty
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
property |
DOMString
|
✘ | ✘ |
A
DOMString
representing
an
IRI-based
property.
The
string
can
either
be
a
full
IRI
or
a
CURIE.
|
value |
DOMString
|
✘ | ✘ | A DOMString representing the value to match against. |
PropertyGroupList
getItemsByType
rdf:type
property.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
type |
DOMString
|
✘ | ✘ |
A
DOMString
representing
an
rdf:type
to
select
against.
|
PropertyGroupList
Document
implements
RDFaDocument
;
RDFaDocument
.
If
the
RDFa
API
is
implemented
in
a
DOM
environment
and
a
DOMImplementation
interface
is
provided,
the
following
additional
requirements
for
the
hasFeature()
method
must
be
met:
interface DOMImplementation { boolean hasFeature (in DOMString feature, in DOMString version);
};
hasFeature
true
for
a
feature
string
of
"
RDFaAPI
"
and
a
version
string
of
"
1.1
".
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
feature |
DOMString
|
✘ | ✘ |
The
feature
string
to
use
when
checking
to
see
if
the
|
version |
|
✘ | ✘ | The version string to use when checking to see if the DOM environment exposes all of the RDFa API attributes and methods. |
boolean
The DocumentData interface is used to create structured-data related context, storage, parsing and query objects.
interface DocumentData {
attribute DataStore
store;
attribute DataContext
context;
attribute DataParser
parser;
attribute DataQuery
query;
DataContext
createContext ();
DataStore
createStore (in optional DOMString type);
DataParser
createParser (in DOMString type, in DataStore
store);
DataQuery
createQuery (in DataStore
store);
};
context
of
type
DataContext
parser
of
type
DataParser
query
of
type
DataQuery
store
of
type
DataStore
createContext
DataContext
createParser
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
type |
DOMString
|
✘ | ✘ |
The
type
of
DataParser
to
create.
For
example:
"
rdfa
".
|
store |
|
✘ | ✘ | The DataStore to associate with the DataParser. |
DataParser
createQuery
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
store |
|
✘ | ✘ | The DataStore to associate with the DataQuery. |
DataQuery
createStore
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
type |
DOMString
|
✘ | ✔ |
The
type
of
DataStore
to
|
DataStore
An
important
goal
of
the
RDFa
DOM
API
is
to
help
Web
developers
filter
the
set
of
RDF
triples
in
a
document
down
to
only
the
ones
that
interest
them.
This
section
covers
pattern-based
filters.
Pattern
filters
trigger
off
of
one
or
more
of
the
subject,
predicate,
property,
or
object
properties
in
RDF
triples.
This
section
also
introduces
the
interfaces
for
the
other
filter
types.
Filter
criteria
may
also
be
defined
by
the
developer
as
a
filter
function.
The
RDFTripleFilter
is
a
callable
function
that
determines
whether
an
RDFTriple
should
be
included
in
the
set
of
output
triples.
[NoInterfaceObject, Callback, Null=Null]
interface RDFTripleFilter {
boolean match (in RDFTriple
triple);
};
match
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
triple |
|
✘ | ✘ | The triple to test against the filter. |
boolean
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 class="hilite"><span property="dbp:conventionalLongName">Federal Republic of Germany</span></span> </div> </div>
The parser.iterate() interface will almost certainly see large changes in the next version of the RDFa API specification. Implementers are warned to not implement the interface and wait for the next revision of this specification.
The following examples demonstrate the use of document.data.store.filter() and document.data.parser.iterate() in JavaScript.
>> var myFilter = new function(element, subject, property, object) { // create a filter function that filters if(subject.value.search(/http:\/\/xmlns.com\/foaf\/0\.1/) >= 0) { // triples with properties in the foaf namespace. return true; } } // start filtering at element with id=start >> var store = document.data.store.filter(null, null, null, document.getElementById("start"), myFilter); >> store.forEach(function (triple) { print(triple) } <http://dbpedia.org/resource/Albert_Einstein> <http://xmlns.com/foaf/0.1/name> "Albert Einstein" // start filtering by iterating at element with id=start >> var iter = document.data.parser.iterate(null, null, null, document.getElementById("start"), myFilter); >> for(var triple=iter.next(); triple != null; triple = iter.next()) { print(triple) } <http://dbpedia.org/resource/Albert_Einstein> <http://xmlns.com/foaf/0.1/name> "Albert Einstein"
The
RDFa
DOM
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:
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 the first four steps when a document loads, and then expose a Query interface to allow developers to access the Property Groups. 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.
To
create
a
store
the
createStore
method
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.
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 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 parser = document.data.createParser("rdfa1.0", store); var parser = 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 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.
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
Property
Groups
obtained
from
processing
the
document
are
now
available
in
the
variable
document.data.store
.
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 Property Groups from the RDFa parsing, as well as Property Groups from the hCard parsing.
(If
the
developer
wishes
to
reuse
the
store
but
clear
it
first,
then
the
Store.clear()
method
can
be
used.)
Diagram: Show the connection between a Property Group and the DOM.
Query objects are used to interrogate stores and obtain a list of DOM objects that are linked to Property Groups. 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);
This section is non-normative.
The
current
version
of
the
RDFa
DOM
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:
At the time of publication, the members of the RDFa Working Group were: