Status of This Document
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This document is an experimental work in progress. The concepts described herein are intended to help
provide guidance for a future working group. Implementations of this specification, either producers
or consumers, should note that it is likely to change significantly prior to any publication as a Working
Draft.
This document was published by the HTML Data Task Force as an Editor's Draft. If you wish to make comments regarding this document, please send them to public-html-data-tf@w3.org (subscribe, archives). All feedback is welcome.
Publication as a Editor's Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
3. Vocabulary Registry
This section is non-normative.
In a perfect world, all processors would be able to generate the same output for a given input
without regards to the requirements of a particular vocabulary. However, microdata doesn't
provide sufficient syntactic help in making these decisions. Different vocabularies have different
needs.
The registry is located at the namespace defined for microdata: http://www.w3.org/ns/md in
a variety of formats.
The registry associates a URI prefix with one or more key-value pairs denoting
processor behavior. A hypothetical JSON representation of such a registry might be the following:
{
"http://schema.org/": {
"propertyURI": "vocabulary",
"multipleValues": "unordered",
"properties": {
"tracks": {"multipleValues": "list"}
}
},
"http://microformats.org/profile/hcard": {
"propertyURI": "vocabulary",
"multipleValues": "list",
"properties" {
"url": {"multipleValues": "unordered"}
}
}
}
This structure associates mappings for two URIs, http://schema.org/ and
http://microformats.org/profile/hcard. Items having an item type with a URI
prefix from this registry use the the rules described for that prefix within the scope of that
item type. This mapping currently defines two rules: propertyURI and
multipleValues with values to indicate specific behavior. It also allows overrides
on a per-property basis; the properties key associates an individual name
with overrides for default behavior.
The interpretation of these
rules is defined in the following sections. If an item has no current type or the
registry contains no URI prefix matching current type, a conforming
processor must use the default values defined for these rules.
The concept of a registry, including a hypothetical format, location and updating rules
is presented as an abstract concept useful for describing the function of a microdata processor.
There are issues surrounding update
frequency, URL naming, and how updates are authorized. This spec
just considers the semantic content of such a registry and how it can be used to affect processing without
defining its representation or update policies.
Richard Ciganiak has
pointed out that
"Registry" may be the wrong term, as the proposed registry doesn't assign identifiers or manage
namespace, it simply provides a mapping between URI prefixss and processor behavior and suggests the term
"Whitelist". As more than two values are required, and it describes more than binary behavior, this term
isn't appropriate either.
3.3 Value Typing
This section is non-normative.
In microdata, all values are strings. In RDF, values may be resources
or may be typed with an appropriate datatype.
In some cases, the type of a microdata value can be determined from the
element on which it is specified. In particular:
- URL property elements provide URLs
time element provides dates and times
Using information about the content of the document where the microdata
is marked up might be a violation of the spirit of the microdata specification, though it does not explicitly say in
normative text that consumers cannot use other information from the HTML DOM to interpret microdata.
Additionally, one possible use of a registry would allow vocabularies to be marked with datatype information,
so that a dc:time value, for example, would be understood to represent a literal with datatype
xsd:date. This could be done by adding information for each property in the vocabulary requiring
special treatment.
This might be represented using a syntax such as the following:
{
"http://schema.org/": {
"propertyURI": "vocabulary",
"multipleValues": "unordered",
"properties": {
"dateCreated": {"datatype": "http://www.w3.org/2001/XMLSchema#date"}
}
}
}
The datatype identifies a URI to be used in constructing a typed literal.
In most cases, the relevant datatype for a value can be derived from
knowledge of what property the value is for and the syntax of the value
itself. Thus, values can be given datatypes in a post-processing step
after the mapping of microdata to RDF described by this specification.
However, where there is information in the HTML markup, such as knowledge
of what element was used to mark up the value, which can help with
determining its datatype, that information is used by this specification.
This concept is not explored further at this time, but could be developed further in
a future revision of this document.
4. Algorithm
Transformation of Microdata to RDF makes use of general processing rules described in [MICRODATA]
for the treatment of items.
4.1 Algorithm Terms
- absolute URL
-
The term absolute URL
is defined in [HTML5].
- blank node
-
A blank node is a node in a graph that is neither a URI reference nor a literal.
Items without a global identifier have a blank node allocated to them.
(See [RDF-CONCEPTS]).
- document base
-
The base address of the document being processed, as defined in Resolving URLs in
[HTML5].
- evaluation context
-
A data structure including the following elements:
- memory
-
a mapping of items to subjects, initially empty;
- current name
-
an absolute URL for the in-scope name, used for generating URIs
for properties of items without an item type;
current name is required for the
contextual property URI generation
scheme. Without this scheme, this evaluation context component would not be required.
- current type
-
an absolute URL for the current type, used when an item does not
contain an item type;
- current vocabulary
-
an absolute URL for the current vocabulary, from the registry.
- item
-
An item is described by an element containing an @itemscope attribute. The list
of top-level microdata items may be retrieved using the
Microdata DOM API
document.getItems
method.
- item properties
-
The mechanism for finding the properties of an item The list
of item properties items may be retrieved using the
Microdata DOM API
element.properties
attribute.
- fragment-escape
-
The term fragment-escape
is defined in [HTML5]. This involves transforming elements added to URLs to ensure that the result
remains a valid URL. The following characters are subject to percent escaping:
- U+0022 QUOTATION MARK character (")
- U+0023 NUMBER SIGN character (#)
- U+0025 PERCENT SIGN character (%)
- U+003C LESS-THAN SIGN character (<)
- U+003E GREATER-THAN SIGN character (>)
- U+005B LEFT SQUARE BRACKET character ([)
- U+005C REVERSE SOLIDUS character (\)
- U+005D RIGHT SQUARE BRACKET character (])
- U+005E CIRCUMFLEX ACCENT character (^)
- U+007B LEFT CURLY BRACKET character ({)
- U+007C VERTICAL LINE character (|)
- U+007D RIGHT CURLY BRACKET character (})
- global identifier
-
The value of an item's @itemid attribute, if it has one. (See Items in
[MICRODATA]).
- literal
-
Literals are values such as strings and dates, including typed literals and
plain literals.
(See [RDF-CONCEPTS]).
- property
-
Each name identifies a property of an item.
An item may have multiple elements sharing the same name, creating
a multi-valued property.
- property names
-
The tokens of an element's @itemprop attribute. Each token is a name.
(See Names: the
itemprop attribute in [MICRODATA]).
- property value
-
The property value of a name-value pair added by an element with an @itemprop
attribute depends on the element.
- If the element has no @itemprop attribute
- The value is null and no triple should be generated.
- If the element creates an item (by having an @itemscope attribute)
-
The value is the URI reference or blank node returned from
generate the triples for that item.
- If the element is a URL property element (
a, area, audio,
embed, iframe, img, link, object,
source, track or video)
-
The value is a URI reference created from
element.itemValue.
(See relevant attribute descriptions in [HTML5]).
- If the element is a
time element.
- The value is a literal made from
element.itemValue.
-
-
If the value has the lexical form of xsd:date [RDF-SCHEMA].
-
The value is a typed literal composed of the value and
http://www.w3.org/2001/XMLSchema#date.
-
If the value has the lexical form of xsd:time [RDF-SCHEMA].
-
The value is a typed literal composed of the value and
http://www.w3.org/2001/XMLSchema#time.
-
If the value has the lexical form of xsd:dateTime [RDF-SCHEMA].
-
The value is a typed literal composed of the value and
http://www.w3.org/2001/XMLSchema#dateTime.
- Otherwise
-
The value is a plain literal created from the value with language information set from the lang IDL attribute
of the property element.
See
The time element
in [HTML5].
The content model of the time element is subject to change, and may include
more content types, such as xsd:duration, xsd:gYear, xsd:gYearMonth
and xsd:monthDay in the future.
- Otherwise
- The value is a plain literal created from
element.itemValue
with language information set from the
lang
IDL attribute of the property element.
- top-level item
-
An item which does not contain an @itemprop attribute.
Available through the Microdata DOM API as
document.getItems.
(See Associating names with items in [MICRODATA]).
- URI reference
-
URI references are suitable to be used in subject, predicate or object positions
within an RDF triple, as opposed to a literal value that may contain a string representation of a
URI. (See [RDF-CONCEPTS]).
The HTML5/microdata content model for @href, @src,
@data, @itemtype and @itemprop and @itemid is that of
a URL, not a URI or IRI.
A proposed mechanism for specifying the range of property values to be URI reference or IRI could
allow these to be specified as subject or object using a @content attribute.
- vocabulary
-
A vocabulary is a collection of URIs, suitable for use as an @itemtype or @itemprop
value, that share a common URI prefix. That prefix is the vocabulary URI. A vocabulary URI is not
allowed to be a prefix of another vocabulary URI.
This definition differs from the language in the HTML spec and is just for the purpose of this
document. In HTML, a vocabulary is a specification, and doesn't have a URI. In our view, if one
specification defines ten
@itemtypes, then these could be treated as one vocabulary or as ten
distinct vocabularies; it is entirely up to the vocabulary creator.
4.2 RDF Conversion Algorithm
A HTML document containing microdata may be converted to any other RDF-compatible document
format using the algorithm specified in this section.
A conforming microdata processor implementing RDF conversion must implement a
processing algorithm that results in the equivalent triples to those that the following
algorithm generates:
Set item list to an empty list.
- For each element that is also a top-level item run the following algorithm:
-
Generate the triples for an item item, using the
evaluation context.
Let result be the (URI reference or blank node) subject returned.
-
Append result to item list.
-
Generate an RDF Collection list from the ordered list of values.
Set value to the value returned from generate an RDF
Collection.
-
Generate the following triple:
- subject
- Document base
- predicate
http://www.w3.org/ns/md#item- object
- value
4.3 Generate the triples
When the user agent is to Generate triples for an item item, given an
Evaluation Context, it must run the following steps:
This algorithm has undergone substantial change from the original microdata specification [MICRODATA].
-
If there is an entry for item in memory, then let subject be the subject of
that entry. Otherwise, if item has a global identifier and that
global identifier is an absolute URL, let subject be that
global identifier. Otherwise, let subject be a new blank node.
- Add a mapping from item to subject in memory
-
For each type returned from
element.itemType
of the element defining the item.
- If type is an absolute URL, generate the following triple:
- subject
- subject
- predicate
http://www.w3.org/1999/02/22-rdf-syntax-ns#type- object
- type (as a URI reference)
-
Set type to the first value returned from
element.itemType
of the element defining the item.
-
If type is not an absolute URL, set it to current type from the
Evaluation Context if not empty.
- If the registry contains a URI prefix that is a character for character match of type
up to the length of the URI prefix, set vocab as that URI prefix.
- Otherwise, if type is not empty, construct vocab by removing everything following the last
SOLIDUS U+002F ("/") or NUMBER SIGN U+0023 ("#") from type.
- Update evaluation context setting current vocabulary to vocab.
-
Set property list to an empty array mapping properties to one or more
values as established below.
-
For each element element that has one or more property names and is one of the
properties of the item item, in the order those elements
are given by the algorithm that returns the properties of the item,
run the following substep:
-
For each name in the element's property names, run the following substeps:
-
Let context be a copy of evaluation context with current type set
to type.
-
Let predicate be the result of generate predicate URI
using context and name.
Update context by setting current name to predicate.
-
Let value be the property value of element.
-
If value is an item, then generate the
triples for value using context. Replace value by the subject returned
from those steps.
-
Add value to property list for predicate.
-
For each predicate in property list:
- Generate property values subject, predicate and
the list of values associated with predicate from property list as values.
- Return subject
4.4 Generate Predicate URI
Predicate URI generation makes use of current type, current name,
and current vocabulary from an evaluation context context
along with name.
- If name is an absolute URL, return name
as a URI reference.
- If current type from context is null, there can be no current vocabulary.
Return the URI reference that is the document base with its fragment set to the fragment-escaped value
of name
This rule is intended to allow for a the case where no type is set, and therefore there is no
vocabulary from which to extract rules. For example, if there is a
document base of
http://example.org/doc and an
@itemprop of 'title', a URI will be constructed
to be
http://example.org/doc#title.
- Otherwise, if current vocabulary from context is not null
and registry has an entry for current vocabulary having a
propertyURI entry that is not null, set that as scheme. Otherwise,
set scheme to
vocabulary.
- If scheme is
vocabulary return the URI reference constructed
by appending the fragment-escaped value of name to current vocabulary,
separated by a U+0023 NUMBER SIGN character (#) unless the current vocabulary ends
with either a U+0023 NUMBER SIGN character (#) or SOLIDUS U+002F (/).
- If scheme is
contextual, return the URI reference
constructed as follows:
- Let s be current type from context.
- If
http://www.w3.org/ns/md?type= is a prefix of s,
return the concatenation of s, a U+002E FULL STOP character (.) and
the fragment-escaped value of name.
- Otherwise, return the concatenation of
http://www.w3.org/ns/md?type=,
the fragment-escaped value of s, the string &prop=,
and the fragment-escaped value of name.
4.5 Generate Property Values
Property value serialization makes use of subject, predicate and values.
- If the registry contains a URI prefix that is a character for character match of
predicate up to the length of the URI prefix, set vocab as that URI prefix.
Otherwise set vocab to null.
- If vocab is not null
and registry has an entry for vocab that is a JSON Object, let
registry object be that value. Otherwise set registry object to null.
- If registry object is not null and registry object contains key
properties
which has a JSON Object value, let properties be that value. Otherwise, set properties
to null.
- If properties is not null, and properties contains a key, which after
Generate Predicate URI expansion has a value which is a JSON Object, let
property override be that value. Otherwise, set property override to null.
- If property override contains the key
multipleValues, set that as method.
- Otherwise, if registry object con contains the key
multipleValues, set that as method.
- Otherwise, set method to
unordered.
- If method is
unordered,
for each value in values, generate the following triple:
- subject
- subject
- predicate
- predicate
- object
- value
- Otherwise, if method is
list:
- Set value to the value returned from generate an RDF
Collection.
-
Generate the following triple:
- subject
- subject
- predicate
- predicate
- object
- value
4.6 Generate RDF Collection
An RDF Collection is a mechanism for defining ordered sequences of objects in RDF (See RDF Collections in
[RDF-SCHEMA]). As the RDF data-model is that of an unordered graph, a linking method using properties
rdf:first and rdf:next is required to be able to specify a particular order.
In the microdata to RDF mapping, RDF Collections are used when an item has more than one value
associated with a given property to ensure that the original document order is maintained. The following
procedure should be used to generate triples when an item property has more than one value
(contained in list):
-
Create a new array array containing a blank node for every value in list.
-
For each pair of bnode from array and value from list the following
triple is generated:
- subject
- bnode
- predicate
http://www.w3.org/1999/02/22-rdf-syntax-ns#first- object
- value
-
For each bnode in array the following triple is generated:
- subject
- bnode
- predicate
http://www.w3.org/1999/02/22-rdf-syntax-ns#rest- object
-
next bnode in array or, if that does not exist,
http://www.w3.org/1999/02/22-rdf-syntax-ns#nil
-
Return the first blank node from array.
A. Markup Examples
This section is non-normative.
The microdata example below expresses book information as an FRBR Work item.
<dl itemscope
itemtype="http://purl.org/vocab/frbr/core#Work"
itemid="http://books.example.com/works/45U8QJGZSQKDH8N"
lang="en">
<dt>Title</dt>
<dd><cite itemprop="http://purl.org/dc/terms/title">Just a Geek</cite></dd>
<dt>By</dt>
<dd><span itemprop="http://purl.org/dc/terms/creator">Wil Wheaton</span></dd>
<dt>Format</dt>
<dd itemprop="http://purl.org/vocab/frbr/core#realization"
itemscope
itemtype="http://purl.org/vocab/frbr/core#Expression"
itemid="http://books.example.com/products/9780596007683.BOOK">
<link itemprop="http://purl.org/dc/terms/type" href="http://books.example.com/product-types/BOOK">
Print
</dd>
<dd itemprop="http://purl.org/vocab/frbr/core#realization"
itemscope
itemtype="http://purl.org/vocab/frbr/core#Expression"
itemid="http://books.example.com/products/9780596802189.EBOOK">
<link itemprop="http://purl.org/dc/terms/type" href="http://books.example.com/product-types/EBOOK">
Ebook
</dd>
</dl>
Assuming that registry contains a an entry for http://purl.org/vocab/frbr/core#
with propertyURI set to vocabulary,
this is equivalent to the following Turtle:
@prefix dc: <http://purl.org/dc/terms/> .
@prefix md: <http://www.w3.org/ns/md#> .
@prefix frbr: <http://purl.org/vocab/frbr/core#> .
<> md:item (<http://books.example.com/works/45U8QJGZSQKDH8N>) .
<http://books.example.com/works/45U8QJGZSQKDH8N> a frbr:Work ;
dc:creator "Wil Wheaton"@en ;
dc:title "Just a Geek"@en ;
frbr:realization <http://books.example.com/products/9780596007683.BOOK>,
<http://books.example.com/products/9780596802189.EBOOK> .
<http://books.example.com/products/9780596007683.BOOK> a frbr:Expression ;
dc:type <http://books.example.com/product-types/BOOK> .
<http://books.example.com/products/9780596802189.EBOOK> a frbr:Expression ;
dc:type <http://books.example.com/product-types/EBOOK> .
The following snippet of HTML has microdata for two people with the same address. This illustrates two
items referencing a third item, and how only a single RDF resource definition is created
for that third item.
<p>
Both
<span itemscope="" itemtype="http://microformats.org/profile/hcard" itemref="home">
<span itemprop="fn"
><span itemprop="n" itemscope=""
><span itemprop="given-name">Princeton</span></span></span>
</span>
and
<span itemscope="" itemtype="http://microformats.org/profile/hcard" itemref="home">
<span itemprop="fn"
><span itemprop="n" itemscope=""
><span itemprop="given-name">Trekkie</span></span></span>
</span>
live at
<span id="home" itemprop="adr" itemscope="">
<span itemprop="street-address">Avenue Q</span>.
</span>
</p>
Assuming that registry contains a an entry for http://microformats.org/profile/hcard
with propertyURI set to vocabulary,
it generates these triples expressed in Turtle:
@prefix md: <http://www.w3.org/ns/md#> .
@prefix hcard: <http://microformats.org/profile/hcard#> .
<> md:item (
[ a <http://microformats.org/profile/hcard>;
hcard:fn "Princeton";
hcard:n [ hcard:given-name "Princeton" ];
hcard:adr _:a
]
[ a <http://microformats.org/profile/hcard>;
hcard:fn "Trekkie";
hcard:n [ hcard:given-name "Trekkie" ];
hcard:adr _:a
]) .
_:a hcard:street-address "Avenue Q" .
The following snippet of HTML has microdata for a playlist, and illustrates overriding a property
to place elements in an RDF Collection:
<div itemscope="" itemtype="http://schema.org/MusicPlaylist">
<span itemprop="name">Classic Rock Playlist</span>
<meta itemprop="numTracks" content="2"/>
<p>Including works by
<span itemprop="byArtist">Lynard Skynard</span> and
<span itemprop="byArtist">AC/DC</span></p>.
<div itemprop="tracks" itemscope="" itemtype="http://schema.org/MusicRecording">
1.<span itemprop="name">Sweet Home Alabama</span> -
<span itemprop="byArtist">Lynard Skynard</span>
<link href="sweet-home-alabama" itemprop="url" />
</div>
<div itemprop="tracks" itemscope="" itemtype="http://schema.org/MusicRecording">
2.<span itemprop="name">Shook you all Night Long</span> -
<span itemprop="byArtist">AC/DC</span>
<link href="shook-you-all-night-long" itemprop="url" />
</div>
</div>
Assuming that registry contains a an entry for http://schema.org/
with propertyURI set to vocabulary,
multipleValues set to unordered with the properties
track and byArtist having multipleValues set to list,
it generates these triples expressed in Turtle:
@prefix md: <http://www.w3.org/ns/md#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix schema: <http://schema.org/> .
<> md:item ([ a schema:MusicPlaylist;
schema:name "Classic Rock Playlist";
schema:byArtist ("Lynard Skynard" "AC/DC");
schema:numTracks "2";
schema:tracks (
[ a schema:MusicRecording;
schema:byArtist ("Lynard Skynard");;
schema:name "Sweet Home Alabama";
schema:url <sweet-home-alabama>]
[ a schema:MusicRecording;
schema:byArtist ("AC/DC");;
schema:name "Shook you all Night Long";
schema:url <shook-you-all-night-long>]
)]); .
The following is an example registry in JSON format.
{
"http://schema.org/": {
"propertyURI": "vocabulary",
"multipleValues": "unordered",
"properties": {
"blogPosts": {"multipleValues": "list"},
"breadcrumb": {"multipleValues": "list"},
"byArtist": {"multipleValues": "list"},
"creator": {"multipleValues": "list"},
"episodes": {"multipleValues": "list"},
"events": {"multipleValues": "list"},
"founders": {"multipleValues": "list"},
"itemListElement": {"multipleValues": "list"},
"musicGroupMember": {"multipleValues": "list"},
"performerIn": {"multipleValues": "list"},
"performers": {"multipleValues": "list"},
"producer": {"multipleValues": "list"},
"recipeInstructions": {"multipleValues": "list"},
"seasons": {"multipleValues": "list"},
"subEvents": {"multipleValues": "list"},
"tracks": {"multipleValues": "list"}
}
},
"http://microformats.org/profile/hcard": {
"propertyURI": "vocabulary",
"multipleValues": "unordered"
},
"http://microformats.org/profile/hcalendar#": {
"propertyURI": "vocabulary",
"multipleValues": "unordered",
"properties": {
"categories": {"multipleValues": "list"}
}
},
"http://n.whatwg.org/work": {
"propertyURI": "contextual",
"multipleValues": "list"
}
}