itemprop attributeThis section is non-normative.
Sometimes, it is desirable to annotate content with specific machine-readable labels, e.g. to allow generic scripts to provide services that are customised to the page, or to enable content from a variety of cooperating authors to be processed by a single script in a consistent manner.
For this purpose, authors can use the microdata features described in this section. Microdata allows nested groups of name-value pairs to be added to documents, in parallel with the existing content.
This section is non-normative.
At a high level, microdata consists of a group of name-value pairs. The groups are called items, and each name-value pair is a property. Items and properties are represented by regular elements.
To create an item, the itemscope attribute is used.
To add a property to an item, the itemprop attribute is used
on one of the item's descendants.
Here there are two items, each of which has the property "name":
<div itemscope> <p>My name is <span itemprop="name">Elizabeth</span>.</p> </div> <div itemscope> <p>My name is <span itemprop="name">Daniel</span>.</p> </div>
Markup without the microdata-related attributes does not have any effect on the microdata model.
These two examples are exactly equivalent, at a microdata level, as the previous two examples respectively:
<div itemscope> <p>My <em>name</em> is <span itemprop="name">E<strong>liz</strong>abeth</span>.</p> </div> <section> <div itemscope> <aside> <p>My name is <span itemprop="name"><a class="/?user=daniel">Daniel</a></span>.</p> </aside> </div> </section>
Properties generally have values that are strings.
Here the item has three properties:
<div itemscope> <p>My name is <span itemprop="name">Neil</span>.</p> <p>My band is called <span itemprop="band">Four Parts Water</span>.</p> <p>I am <span itemprop="nationality">British</span>.</p> </div>
When a string value is a URL, it is expressed using the a element and
its href attribute, the img element and its
src attribute, or other elements that link to or embed external
resources.
In this example, the item has one property, "image", whose value is a URL:
<div itemscope> <img itemprop="image" src="/img/spacer.gif"> </div>
When a string value is in some machine-readable format unsuitable for human consumption, it is
expressed using the value attribute of the data
element, with the human-readable version given in the element's contents.
Here, there is an item with a property whose value is a product ID. The ID is not human-friendly, so the product's name is used the human-visible text instead of the ID.
<h1 itemscope> <data itemprop="product-id" value="9678AOU879">The Instigator 2000</data> </h1>
For numeric data, the meter element and its value attribute can be used instead.
Here a rating is given using a meter element.
<div itemscope itemtype="schema.org/Product">
<span itemprop="name">Panasonic White 60L Refrigerator</span>
<img src="/img/spacer.gif">
<div itemprop="aggregateRating"
itemscope itemtype="schema.org/AggregateRating">
<meter itemprop="ratingValue" min=0 value=3.5 max=5>Rated 3.5/5</meter>
(based on <span itemprop="reviewCount">11</span> customer reviews)
</div>
</div>
Similarly, for date- and time-related data, the time element and its datetime attribute can be used instead.
In this example, the item has one property, "birthday", whose value is a date:
<div itemscope> I was born on <time itemprop="birthday" datetime="2009-05-10">May 10th 2009</time>. </div>
Properties can also themselves be groups of name-value pairs, by putting the itemscope attribute on the element that declares the property.
Items that are not part of others are called top-level microdata items.
In this example, the outer item represents a person, and the inner one represents a band:
<div itemscope> <p>Name: <span itemprop="name">Amanda</span></p> <p>Band: <span itemprop="band" itemscope> <span itemprop="name">Jazz Band</span> (<span itemprop="size">12</span> players)</span></p> </div>
The outer item here has two properties, "name" and "band". The "name" is "Amanda", and the "band" is an item in its own right, with two properties, "name" and "size". The "name" of the band is "Jazz Band", and the "size" is "12".
The outer item in this example is a top-level microdata item.
Properties that are not descendants of the element with the itemscope attribute can be associated with the item using the itemref attribute.
This attribute takes a list of IDs of elements to crawl in addition to crawling the children of
the element with the itemscope attribute.
This example is the same as the previous one, but all the properties are separated from their items:
<div itemscope id="amanda" itemref="a b"></div> <p id="a">Name: <span itemprop="name">Amanda</span></p> <div id="b" itemprop="band" itemscope itemref="c"></div> <div id="c"> <p>Band: <span itemprop="name">Jazz Band</span></p> <p>Size: <span itemprop="size">12</span> players</p> </div>
This gives the same result as the previous example. The first item has two properties, "name", set to "Amanda", and "band", set to another item. That second item has two further properties, "name", set to "Jazz Band", and "size", set to "12".
An item can have multiple properties with the same name and different values.
This example describes an ice cream, with two flavors:
<div itemscope> <p>Flavors in my favorite ice cream:</p> <ul> <li itemprop="flavor">Lemon sorbet</li> <li itemprop="flavor">Apricot sorbet</li> </ul> </div>
This thus results in an item with two properties, both "flavor", having the values "Lemon sorbet" and "Apricot sorbet".
An element introducing a property can also introduce multiple properties at once, to avoid duplication when some of the properties have the same value.
Here we see an item with two properties, "favorite-color" and "favorite-fruit", both set to the value "orange":
<div itemscope> <span itemprop="favorite-color favorite-fruit">orange</span> </div>
It's important to note that there is no relationship between the microdata and the content of the document where the microdata is marked up.
There is no semantic difference, for instance, between the following two examples:
<figure> <img src="/img/spacer.gif"> <figcaption><span itemscope><span itemprop="name">The Castle</span></span> (1986)</figcaption> </figure>
<span itemscope><meta itemprop="name" content="The Castle"></span> <figure> <img src="/img/spacer.gif"> <figcaption>The Castle (1986)</figcaption> </figure>
Both have a figure with a caption, and both, completely unrelated to the figure, have an item with a name-value pair with the name "name" and the value "The Castle". The only difference is that if the user drags the caption out of the document, in the former case, the item will be included in the drag-and-drop data. In neither case is the image in any way associated with the item.
This section is non-normative.
The examples in the previous section show how information could be marked up on a page that doesn't expect its microdata to be re-used. Microdata is most useful, though, when it is used in contexts where other authors and readers are able to cooperate to make new uses of the markup.
For this purpose, it is necessary to give each item a type, such as "example.com/person", or "example.org/cat", or "band.example.net/". Types are identified as URLs.
The type for an item is given as the value of an itemtype attribute on the same element as the itemscope attribute.
Here, the item's type is "example.org/animals#cat":
<section itemscope itemtype="example.org/animals#cat"> <h1 itemprop="name">Hedral</h1> <p itemprop="desc">Hedral is a male american domestic shorthair, with a fluffy black fur with white paws and belly.</p> <img itemprop="img" src="/img/spacer.gif"> </section>
In this example the "example.org/animals#cat" item has three properties, a "name" ("Hedral"), a "desc" ("Hedral is..."), and an "img" ("hedral.jpeg").
The type gives the context for the properties, thus selecting a vocabulary: a property named
"class" given for an item with the type "census.example/person" might refer to the economic
class of an individual, while a property named "class" given for an item with the type
"example.com/school/teacher" might refer to the classroom a teacher has been assigned.
Several types can share a vocabulary. For example, the types "example.org/people/teacher" and "example.org/people/engineer" could be defined to use the same vocabulary
(though maybe some properties would not be especially useful in both cases, e.g. maybe the "example.org/people/engineer" type might not typically be used with the
"classroom" property). Multiple types defined to use the same vocabulary can
be given for a single item by listing the URLs as a space-separated list in the attribute' value.
An item cannot be given two types if they do not use the same vocabulary, however.
This section is non-normative.
Sometimes, an item gives information about a topic that has a global identifier. For example, books can be identified by their ISBN number.
Vocabularies (as identified by the itemtype attribute) can
be designed such that items get associated with their global
identifier in an unambiguous way by expressing the global identifiers as URLs given in an itemid attribute.
The exact meaning of the URLs given in itemid attributes depends on the vocabulary used.
Here, an item is talking about a particular book:
<dl itemscope
itemtype="vocab.example.net/book"
itemid="urn:isbn:0-330-34032-8">
<dt>Title
<dd itemprop="title">The Reality Dysfunction
<dt>Author
<dd itemprop="author">Peter F. Hamilton
<dt>Publication date
<dd><time itemprop="pubdate" datetime="1996-01-26">26 January 1996</time>
</dl>
The "vocab.example.net/book" vocabulary in this example would
define that the itemid attribute takes a urn: URL pointing to the ISBN of the book.
This section is non-normative.
Using microdata means using a vocabulary. For some purposes, an ad-hoc vocabulary is adequate. For others, a vocabulary will need to be designed. Where possible, authors are encouraged to re-use existing vocabularies, as this makes content re-use easier.
When designing new vocabularies, identifiers can be created either using URLs, or, for properties, as plain words (with no dots or colons). For URLs, conflicts with other vocabularies can be avoided by only using identifiers that correspond to pages that the author has control over.
For instance, if Jon and Adam both write content at example.com, at example.com/~jon/... and example.com/~adam/... respectively, then
they could select identifiers of the form
"example.com/~jon/name" and "example.com/~adam/name"
respectively.
Properties whose names are just plain words can only be used within the context of the types for which they are intended; properties named using URLs can be reused in items of any type. If an item has no type, and is not part of another item, then if its properties have names that are just plain words, they are not intended to be globally unique, and are instead only intended for limited use. Generally speaking, authors are encouraged to use either properties with globally unique names (URLs) or ensure that their items are typed.
Here, an item is an "example.org/animals#cat", and most of the properties have names that are words defined in the context of that type. There are also a few additional properties whose names come from other vocabularies.
<section itemscope itemtype="example.org/animals#cat"> <h1 itemprop="name example.com/fn">Hedral</h1> <p itemprop="desc">Hedral is a male american domestic shorthair, with a fluffy <span itemprop="example.com/color">black</span> fur with <span itemprop="example.com/color">white</span> paws and belly.</p> <img itemprop="img" src="/img/spacer.gif"> </section>
This example has one item with the type "example.org/animals#cat" and the following properties:
| Property | Value |
| name | Hedral |
| example.com/fn | Hedral |
| desc | Hedral is a male american domestic shorthair, with a fluffy black fur with white paws and belly. |
| example.com/color | black |
| example.com/color | white |
| img | .../hedral.jpeg |
This section is non-normative.
The microdata becomes even more useful when scripts can use it to expose information to the user, for example offering it in a form that can be used by other applications.
The document.getItems(typeNames)
method provides access to the top-level microdata items. It returns a
NodeList containing the items with the specified types, or all types if no argument
is specified.
Each item is represented in the DOM by the element on which
the relevant itemscope attribute is found. These elements have
their element.itemScope IDL attribute set to true.
The type(s) of items can be obtained using the element.itemType IDL attribute on the element with the itemscope attribute.
This sample shows how the getItems() method can be
used to obtain a list of all the top-level microdata items of a particular type given in the
document:
var cats = document.getItems("example.com/feline");
Once an element representing an item has been obtained, its
properties can be extracted using the properties IDL
attribute. This attribute returns an HTMLPropertiesCollection, which can be
enumerated to go through each element that adds one or more properties to the item. It can also be
indexed by name, which will return an object with a list of the elements that add properties with
that name.
Each element that adds a property also has an itemValue IDL
attribute that returns its value.
This sample gets the first item of type "example.net/user" and then pops up an alert using the "name" property from that item.
var user = document.getItems('example.net/user')[0];
alert('Hello ' + user.properties['name'][0].itemValue + '!');
The HTMLPropertiesCollection object, when indexed by name in this way, actually
returns a PropertyNodeList object with all the matching properties. The
PropertyNodeList object can be used to obtain all the values at once using
its getValues method, which returns
an array of all the values.
In an earlier example, a "example.org/animals#cat" item had two "example.com/color" values. This script looks up the first such item and then lists all its values.
var cat = document.getItems('example.org/animals#cat')[0];
var colors = cat.properties['example.com/color'].getValues();
var result;
if (colors.length == 0) {
result = 'Colour unknown.';
} else if (colors.length == 1) {
result = 'Colour: ' + colors[0];
} else {
result = 'Colours:';
for (var i = 0; i < colors.length; i += 1)
result += ' ' + colors[i];
}
It's also possible to get a list of all the property names using the object's
names IDL attribute.
This example creates a big list with a nested list for each item on the page, each with all of the property names used in that item.
var outer = document.createElement('ul');
var items = document.getItems();
for (var item = 0; item < items.length; item += 1) {
var itemLi = document.createElement('li');
var inner = document.createElement('ul');
for (var name = 0; name < items[item].properties.names.length; name += 1) {
var propLi = document.createElement('li');
propLi.appendChild(document.createTextNode(items[item].properties.names[name]));
inner.appendChild(propLi);
}
itemLi.appendChild(inner);
outer.appendChild(itemLi);
}
document.body.appendChild(outer);
If faced with the following from an earlier example:
<section itemscope itemtype="example.org/animals#cat"> <h1 itemprop="name example.com/fn">Hedral</h1> <p itemprop="desc">Hedral is a male american domestic shorthair, with a fluffy <span itemprop="example.com/color">black</span> fur with <span itemprop="example.com/color">white</span> paws and belly.</p> <img itemprop="img" src="/img/spacer.gif"> </section>
...it would result in the following output:
(The duplicate occurrence of "example.com/color" is not included in the list.)
The microdata model consists of groups of name-value pairs known as items.
Each group is known as an item. Each item can have item types, a global identifier (if the vocabulary specified by the item types support global identifiers for items), and a list of name-value pairs. Each name in the name-value pair is known as a property, and each property has one or more values. Each value is either a string or itself a group of name-value pairs (an item). The names are unordered relative to each other, but if a particular name has multiple values, they do have a relative order.
Every HTML element may have an itemscope attribute specified. The itemscope attribute is a boolean attribute.
An element with the itemscope attribute specified creates a
new item, a group of name-value pairs.
Elements with an itemscope attribute may have an itemtype attribute specified, to give the item
types of the item.
The itemtype attribute, if specified, must have a value that
is an unordered set of unique space-separated tokens that are
case-sensitive, each of which is a valid URL that is an absolute
URL, and all of which are defined to use the same vocabulary. The attribute's value must
have at least one token.
The item types of an item are the tokens obtained
by splitting the element's itemtype attribute's value on spaces. If the itemtype attribute is missing or parsing it in this way finds no
tokens, the item is said to have no item types.
The item types must all be types defined in applicable specifications and must all be defined to use the same vocabulary.
Except if otherwise specified by that specification, the URLs given as the item types should not be automatically dereferenced.
A specification could define that its item type can be derefenced to provide the user with help information, for example. In fact, vocabulary authors are encouraged to provide useful information at the given URL.
Item types are opaque identifiers, and user agents must not dereference unknown item types, or otherwise deconstruct the