Copyright © 2013W3C® (MIT,ERCIM,Keio,Beihang), All Rights Reserved. W3Cliability,trademark anddocument use rules apply.
This specification defines the HTML microdata mechanism. This mechanism allows machine-readable data to be embedded in HTML documents in an easy-to-write manner, with an unambiguous parsing model. It is compatible with numerous other data formats including RDF and JSON.
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 theW3C technical reports index at http://www.w3.org/TR/.
This document was edited in place on 23 June 2014 to fix a wrong "Previous Version" link.
If you wish to make comments regarding this document in a manner that is tracked by the W3C, please submit them via usingour public bug database. If you cannot do this then you can also e-mail feedback topublic-html-comments@w3.org (subscribe,archives), and arrangements will be made to transpose the comments to our public bug database. All feedback is welcome.
The bulk of the text of this specification is also available in the WHATWGHTML Living Standard, under a license that permits reuse of the specification text.
Publication as a Working Group Note 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.
The latest stable version of the editor's draft of this specification is always available onthe W3C HTML git repository.
The W3CHTML Working Group is the W3C working group responsible for this specification's progress. This specification is the 29 October 2013 Working Group Note.
This specification is an extension to the HTML5 language. All normative content in the HTML5 specification, unless specifically overridden by this specification, is intended to be the basis for this specification.
This document was produced by a group operating under the5 February 2004 W3C Patent Policy. W3C maintains apublic 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 containsEssential Claim(s) must disclose the information in accordance withsection 6 of the W3C Patent Policy.
This specification depends on the Web IDL and HTML5 specifications.[WEBIDL][HTML5]
This specification relies heavily on the HTML5 specification to define underlying terms.
HTML5 defines the concept of DOMcollections and theHTMLCollection interface, as well as the concept of IDL attributesreflecting content attributes. It also definestree order and the concept of a node'shome subtree.
HTML5 defines the termsURL,valid URL,absolute URL, andresolve a URL.
HTML5 defines the termsalphanumeric ASCII characters,space characterssplit a string on spaces,converted to ASCII uppercase, andprefix match.
HTML5 defines the meaning of the termHTML elements, as well as all the elements referenced in this specification. It also defines theHTMLElement andHTMLDocument interfaces. It defines the specific concept ofthetitle element in the context of anHTMLDocument. In the context of content models it defines the termsflow content andphrasing content. It also defines what an element'sID orlanguage is in HTML.
HTML5 defines the set ofglobal attributes, as well as terms used in describing attributes and their processing, such as the concept of aboolean attribute, of anunordered set of unique space-separated tokens, of avalid non-negative integer, of adate, atime, aglobal date and time, avalid date string, and avalid global date and time string.
HTML5 defines whatthe document's current address is.
Finally, HTML5 also defines the concepts ofdrag-and-drop initialization steps and of thelist of dragged nodes, which come up in the context of drag-and-drop interfaces.
All diagrams, examples, and notes in this specification are non-normative, as are all sections explicitly marked non-normative. Everything else in this specification is normative.
The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in RFC2119. The key word "OPTIONALLY" in the normative parts of this document is to be interpreted with the same normative meaning as "MAY" and "OPTIONAL". For readability, these words do not appear in all uppercase letters in this specification.[RFC2119]
Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.
For example, were the spec to say:
To eat an orange, the user must:1. Peel the orange.2. Separate each slice of the orange.3. Eat the orange slices.
...it would be equivalent to the following:
To eat an orange:1. The user must peel the orange.2. The user must separate each slice of the orange.3. The user must eat the orange slices.
Here the key word is "must".
The former (imperative) style is generally preferred in this specification for stylistic reasons.
Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)
This 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 calleditems, and each name-value pair is a property. Items and properties are represented by regular elements.
To create an item, theitemscope attribute is used.
To add a property to an item, theitemprop attribute is used on one of theitem'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 microdata attributes has no effect on microdata.
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 href="/?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 aURL, it is expressed using thea element and itshref attribute, theimg element and itssrc 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="google-logo.png" alt="Google"></div>
When a string value is in some machine-readable format unsuitable for human consumption, it is expressed using thevalue attribute of thedata 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, themeter element and itsvalue attribute can be used instead.
Here a rating is given using ameter element.
<div itemscope itemtype="http://schema.org/Product"> <span itemprop="name">Panasonic White 60L Refrigerator</span> <img src="panasonic-fridge-60l-white.jpg" alt=""> <div itemprop="aggregateRating" itemscope itemtype="http://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, thetime element and itsdatetime 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 theitemscope attribute on the element that declares the property.
Items that are not part of others are calledtop-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 theitemscope attribute can be associated with theitem using theitemref attribute. This attribute takes a list of IDs of elements to crawl in addition to crawling the children of the element with theitemscope attribute.
This example is the same as the previous one, but all the properties are separated from theiritems:
<div itemscope itemref="a b"></div><p>Name: <span itemprop="name">Amanda</span></p><div itemprop="band" itemscope itemref="c"></div><div> <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".
Anitem 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="castle.jpeg"> <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="castle.jpeg"> <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 eachitem a type, such as "http://example.com/person", or "http://example.org/cat", or "http://band.example.net/". Types are identified asURLs.
The type for anitem is given as the value of anitemtype attribute on the same element as theitemscope attribute.
Here, the item's type is "http://example.org/animals#cat":
<section itemscope itemtype="http://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="hedral.jpeg" alt="" title="Hedral, age 18 months"></section>
In this example the "http://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 "http://census.example/person" might refer to the economic class of an individual, while a property named "class" given for an item with the type "http://example.com/school/teacher" might refer to the classroom a teacher has been assigned. Several types can share a vocabulary. For example, the types "http://example.org/people/teacher" and "http://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 "http://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, anitem gives information about a topic that has a global identifier. For example, books can be identified by their ISBN number.
Vocabularies (as identified by theitemtype attribute) can be designed such thatitems get associated with their global identifier in an unambiguous way by expressing the global identifiers asURLs given in anitemid attribute.
The exact meaning of theURLs given initemid attributes depends on the vocabulary used.
Here, an item is talking about a particular book:
<dl itemscope itemtype="http://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 "http://vocab.example.net/book" vocabulary in this example would define that theitemid attribute takes aurn: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 usingURLs, 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 atexample.com, athttp://example.com/~jon/... andhttp://example.com/~adam/... respectively, then they could select identifiers of the form "http://example.com/~jon/name" and "http://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 "http://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="http://example.org/animals#cat"> <h1 itemprop="name http://example.com/fn">Hedral</h1> <p itemprop="desc">Hedral is a male american domestic shorthair, with a fluffy <span itemprop="http://example.com/color">black</span> fur with <span itemprop="http://example.com/color">white</span> paws and belly.</p> <img itemprop="img" src="hedral.jpeg" alt="" title="Hedral, age 18 months"></section>
This example has one item with the type "http://example.org/animals#cat" and the following properties:
| Property | Value |
| name | Hedral |
| http://example.com/fn | Hedral |
| desc | Hedral is a male american domestic shorthair, with a fluffy black fur with white paws and belly. |
| http://example.com/color | black |
| http://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.
Thedocument.getItems(typeNames) method provides access to thetop-level microdata items. It returns aNodeList containing the items with the specified types, or all types if no argument is specified.
Eachitem is represented in the DOM by the element on which the relevantitemscope attribute is found. These elements have theirelement.itemScope IDL attribute set to true.
The type(s) ofitems can be obtained using theelement.itemType IDL attribute on the element with theitemscope attribute.
This sample shows how thegetItems() 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("http://example.com/feline");Once an element representing anitem has been obtained, its properties can be extracted using theproperties IDL attribute. This attribute returns anHTMLPropertiesCollection, 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 anitemValue IDL attribute that returns its value.
This sample gets the first item of type "http://example.net/user" and then pops up an alert using the "name" property from that item.
var user = document.getItems('http://example.net/user')[0];alert('Hello ' + user.properties['name'][0].itemValue + '!');TheHTMLPropertiesCollection object, when indexed by name in this way, actually returns aPropertyNodeList object with all the matching properties. ThePropertyNodeList object can be used to obtain all the values at once usingitsgetValues method, which returns an array of all the values.
In an earlier example, a "http://example.org/animals#cat" item had two "http://example.com/color" values. This script looks up the first such item and then lists all its values.
var cat = document.getItems('http://example.org/animals#cat')[0];var colors = cat.properties['http://example.com/color'].getValues();var result;if (colors.length == 0) { result = 'Color unknown.';} else if (colors.length == 1) { result = 'Color: ' + colors[0];} else { result = 'Colors:'; for (var i = 0; i < colors.length; i += 1) result += ' ' + colors[i];}It's also possible to get a list of all theproperty names using the object'snames 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="http://example.org/animals#cat"> <h1 itemprop="name http://example.com/fn">Hedral</h1> <p itemprop="desc">Hedral is a male american domestic shorthair, with a fluffy <span itemprop="http://example.com/color">black</span> fur with <span itemprop="http://example.com/color">white</span> paws and belly.</p> <img itemprop="img" src="hedral.jpeg" alt="" title="Hedral, age 18 months"></section>
...it would result in the following output:
(The duplicate occurrence of "http://example.com/color" is not included in the list.)
The microdata model consists of groups of name-value pairs known asitems.
Each group is known as anitem. Eachitem can haveitem types, aglobal identifier (if the vocabulary specified by theitem typessupport global identifiers for items), and a list of name-value pairs. Each name in the name-value pair is known as aproperty, and eachproperty has one or morevalues. Eachvalue is either a string or itself a group of name-value pairs (anitem). The names are unordered relative to each other, but if a particular name has multiple values, they do have a relative order.
EveryHTML element may have anitemscope attribute specified. Theitemscope attribute is aboolean attribute.
An element with theitemscope attribute specified creates a newitem, a group of name-value pairs.
Elements with anitemscope attribute may have anitemtype attribute specified, to give theitem types of theitem.
Theitemtype attribute, if specified, must have a value that is anunordered set of unique space-separated tokens that arecase-sensitive, each of which is avalid URL that is anabsolute URL, and all of which are defined to use the same vocabulary. The attribute's value must have at least one token.
Theitem types of anitem are the tokens obtained bysplitting the element'sitemtype attribute's value on spaces. If theitemtype attribute is missing or parsing it in this way finds no tokens, theitem is said to have noitem types.
Theitem types must all be types defined inapplicable specifications and must all be defined to use the same vocabulary.
Except if otherwise specified by that specification, theURLs given as theitem types should not be automatically dereferenced.
A specification could define that itsitem 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 givenURL.
Item types are opaque identifiers, and user agents must not dereference unknownitem types, or otherwise deconstruct them, in order to determine how to processitems that use them.
Theitemtype attribute must not be specified on elements that do not have anitemscope attribute specified.
Anitem is said to be atyped item when either it has anitem type, or it is thevalue of aproperty of atyped item. Therelevant types for atyped item is theitem'sitem types, if it has any, or else is therelevant types of theitem for which it is aproperty'svalue.
Elements with anitemscope attribute and anitemtype attribute that references a vocabulary that is defined tosupport global identifiers for items may also have anitemid attribute specified, to give a global identifier for theitem, so that it can be related to otheritems on pages elsewhere on the Web.
Theitemid attribute, if specified, must have a value that is avalid URL potentially surrounded by spaces.
Theglobal identifier of anitem is the value of its element'sitemid attribute, if it has one,resolved relative to the element on which the attribute is specified. If theitemid attribute is missing or if resolving it fails, it is said to have noglobal identifier.
Theitemid attribute must not be specified on elements that do not have both anitemscope attribute and anitemtype attribute specified, and must not be specified on elements with anitemscope attribute whoseitemtype attribute specifies a vocabulary that does notsupport global identifiers for items, as defined by that vocabulary's specification.
The exact meaning of aglobal identifier is determined by the vocabulary's specification. It is up to such specifications to define whether multiple items with the same global identifier (whether on the same page or on different pages) are allowed to exist, and what the processing rules for that vocabulary are with respect to handling the case of multiple items with the same ID.
Elements with anitemscope attribute may have anitemref attribute specified, to give a list of additional elements to crawl to find the name-value pairs of theitem.
Theitemref attribute, if specified, must have a value that is anunordered set of unique space-separated tokens that arecase-sensitive, consisting ofIDs of elements in the samehome subtree.
Theitemref attribute must not be specified on elements that do not have anitemscope attribute specified.
Theitemref attribute is not part of the microdata data model. It is merely a syntactic construct to aid authors in adding annotations to pages where the data to be annotated does not follow a convenient tree structure. For example, it allows authors to mark up data in a table so that each column defines a separateitem, while keeping the properties in the cells.
This example shows a simple vocabulary used to describe the products of a model railway manufacturer. The vocabulary has just five property names:
This vocabulary has four defineditem types:
Eachitem that uses this vocabulary can be given one or more of these types, depending on what the product is.
Thus, a locomotive might be marked up as:
<dl itemscope itemtype="http://md.example.com/loco http://md.example.com/lighting"> <dt>Name: <dd itemprop="name">Tank Locomotive (DB 80) <dt>Product code: <dd itemprop="product-code">33041 <dt>Scale: <dd itemprop="scale">HO <dt>Digital: <dd itemprop="digital">Delta</dl>
A turnout lantern retrofit kit might be marked up as:
<dl itemscope itemtype="http://md.example.com/track http://md.example.com/lighting"> <dt>Name: <dd itemprop="name">Turnout Lantern Kit <dt>Product code: <dd itemprop="product-code">74470 <dt>Purpose: <dd>For retrofitting 2 <span itemprop="track-type">C</span> Track turnouts. <meta itemprop="scale" content="HO"></dl>
A passenger car with no lighting might be marked up as:
<dl itemscope itemtype="http://md.example.com/passengers"> <dt>Name: <dd itemprop="name">Express Train Passenger Car (DB Am 203) <dt>Product code: <dd itemprop="product-code">8710 <dt>Scale: <dd itemprop="scale">Z</dl>
Great care is necessary when creating new vocabularies. Often, a hierarchical approach to types can be taken that results in a vocabulary where each item only ever has a single type, which is generally much simpler to manage.
itemprop attributeEveryHTML element may have anitemprop attribute specified, if doing soadds one or more properties to one or moreitems (as defined below).
Theitemprop attribute, if specified, must have a value that is anunordered set of unique space-separated tokens that arecase-sensitive, representing the names of the name-value pairs that it adds. The attribute's value must have at least one token.
Each token must be either:
Specifications that introducedefined property names must ensure all such property names contain no "." (U+002E) characters, no ":" (U+003A) characters, and nospace characters.
When an element with anitemprop attributeadds a property to multipleitems, the requirement above regarding the tokens applies for eachitem individually.
Theproperty names of an element are the tokens that the element'sitemprop attribute is found to contain when its value issplit on spaces, with the order preserved but with duplicates removed (leaving only the first occurrence of each name).
Within anitem, the properties are unordered with respect to each other, except for properties with the same name, which are ordered in the order they are given by the algorithm that definesthe properties of an item.
In the following example, the "a" property has the values "1" and "2",in that order, but whether the "a" property comes before the "b" property or not is not important:
<div itemscope> <p itemprop="a">1</p> <p itemprop="a">2</p> <p itemprop="b">test</p></div>
Thus, the following is equivalent:
<div itemscope> <p itemprop="b">test</p> <p itemprop="a">1</p> <p itemprop="a">2</p></div>
As is the following:
<div itemscope> <p itemprop="a">1</p> <p itemprop="b">test</p> <p itemprop="a">2</p></div>
And the following:
<div> <p itemprop="a">1</p></div><div itemscope itemref="x"> <p itemprop="b">test</p> <p itemprop="a">2</p></div>
Theproperty value of a name-value pair added by an element with anitemprop attribute is as given for the first matching case in the following list:
itemscope attributeThe value is theitem created by the element.
meta elementThe value is the value of the element'scontent attribute, if any, or the empty string if there is no such attribute.
audio,embed,iframe,img,source,track, orvideo elementThe value is theabsolute URL that results fromresolving the value of the element'ssrc attribute relative to the element at the time the attribute is set, or the empty string if there is no such attribute or ifresolving it results in an error.
a,area, orlink elementThe value is theabsolute URL that results fromresolving the value of the element'shref attribute relative to the element at the time the attribute is set, or the empty string if there is no such attribute or ifresolving it results in an error.
object elementThe value is theabsolute URL that results fromresolving the value of the element'sdata attribute relative to the element at the time the attribute is set, or the empty string if there is no such attribute or ifresolving it results in an error.
data elementThe value is the value of the element'svalue attribute, if it has one, or the empty string otherwise.
meter elementThe value is the value of the element'svalue attribute, if it has one, or the empty string otherwise.
time elementThe value is the element'sdatetime value.
The value is the element'stextContent.
TheURL property elements are thea,area,audio,embed,iframe,img,link,object,source,track, andvideo elements.
If a property'svalue, as defined by the property's definition, is anabsolute URL, the property must be specified using aURL property element.
These requirements do not apply just because a property value happens to match the syntax for a URL. They only apply if the property is explicitly defined as taking such a value.
For example, a book about the first moon landing could be called "mission:moon". A "title" property from a vocabulary that defines a title as being a string would not expect the title to be given in ana element, even though it looks like aURL. On the other hand, if there was a (rather narrowly scoped!) vocabulary for "books whose titles look like URLs" which had a "title" property defined to take a URL, then the propertywould expect the title to be given in ana element (or one of the otherURL property elements), because of the requirement above.
To findthe properties of an item defined by the elementroot, the user agent must run the following steps. These steps are also used to flagmicrodata errors.
Letresults,memory, andpending be empty lists of elements.
Add the elementroot tomemory.
Add the child elements ofroot, if any, topending.
Ifroot has anitemref attribute,split the value of thatitemref attribute on spaces. For each resulting tokenID, if there is an element in thehome subtree ofroot with theIDID, then add the first such element topending.
Loop: Ifpending is empty, jump to the step labeledend of loop.
Remove an element frompending and letcurrent be that element.
Ifcurrent is already inmemory, there is amicrodata error; return to the step labeledloop.
Addcurrent tomemory.
Ifcurrent does not have anitemscope attribute, then: add all the child elements ofcurrent topending.
Ifcurrent has anitemprop attribute specified and has one or moreproperty names, then addcurrent toresults.
Return to the step labeledloop.
End of loop: Sortresults intree order.
Returnresults.
A document must not contain anyitems for which the algorithm to findthe properties of an item finds anymicrodata errors.
Anitem is atop-level microdata item if its element does not have anitemprop attribute.
Allitemref attributes in aDocument must be such that there are no cycles in the graph formed from representing eachitem in theDocument as a node in the graph and eachproperty of an item whosevalue is another item as an edge in the graph connecting those two items.
A document must not contain any elements that have anitemprop attribute that would not be found to be a property of any of theitems in that document were theirproperties all to be determined.
In this example, a single license statement is applied to two works, usingitemref from the items representing the works:
<!DOCTYPE HTML><html> <head> <title>Photo gallery</title> </head> <body> <h1>My photos</h1> <figure itemscope itemtype="http://n.whatwg.org/work" itemref="licenses"> <img itemprop="work" src="images/house.jpeg" alt="A white house, boarded up, sits in a forest."> <figcaption itemprop="title">The house I found.</figcaption> </figure> <figure itemscope itemtype="http://n.whatwg.org/work" itemref="licenses"> <img itemprop="work" src="images/mailbox.jpeg" alt="Outside the house is a mailbox. It has a leaflet inside."> <figcaption itemprop="title">The mailbox.</figcaption> </figure> <footer> <p>All images licensed under the <a itemprop="license" href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</p> </footer> </body></html>
The above results in two items with the type "http://n.whatwg.org/work", one with:
images/house.jpeghttp://www.opensource.org/licenses/mit-license.php...and one with:
images/mailbox.jpeghttp://www.opensource.org/licenses/mit-license.phpCurrently, theitemscope,itemprop, and other microdata attributes are only defined forHTML elements. This means that attributes with the literal names "itemscope", "itemprop", etc, do not cause microdata processing to occur on elements in other namespaces, such as SVG.
Thus, in the following example there is only one item, not two.
<p itemscope></p> <!-- this is an item (with no properties and no type) --><svg itemscope></svg> <!-- this is not, it's just ansvg element with an invalid unknown attribute -->getItems( [types ] )Returns aNodeList of the elements in theDocument that createitems, that are not part of otheritems, and that are of the types given in the argument, if any are listed.
Thetypes argument is interpreted as a space-separated list of types.
propertiesIf the element has anitemscope attribute, returns anHTMLPropertiesCollection object with all the element's properties. Otherwise, an emptyHTMLPropertiesCollection object.
itemValue [ =value ]Returns the element'svalue.
Can be set, to change the element'svalue. Setting thevalue when the element has noitemprop attribute or when the element's value is anitem throws anInvalidAccessError exception.
Thedocument.getItems(typeNames) method takes a string that contains anunordered set of unique space-separated tokens that arecase-sensitive, representing types. When called, the method must return aliveNodeList object containing all the elements in the document, intree order, that are eachtop-level microdata items whosetypes include all the types specified in the method's argument, having obtained the types bysplitting the string on spaces. If there are no tokens specified in the argument, then the method must return aNodeList containing all thetop-level microdata items in the document. When the method is invoked on aDocument object again with the same argument, the user agent may return the same object as the object returned by the earlier call. In other cases, a newNodeList object must be returned.
TheitemScope IDL attribute onHTML elements mustreflect theitemscope content attribute. TheitemType IDL attribute onHTML elements mustreflect theitemtype content attribute. TheitemId IDL attribute onHTML elements mustreflect theitemid content attribute. TheitemProp IDL attribute onHTML elements mustreflect theitemprop content attribute. TheitemRef IDL attribute onHTML elements mustreflect theitemref content attribute.
Theproperties IDL attribute onHTML elements must return anHTMLPropertiesCollection rooted at the element'sroot element (which element this is might change during the collection's lifetime, as the element moves between different subtrees), whose filter matches only elements that arethe properties of the item created by the element on which the attribute was invoked, while that element is anitem, and matches nothing the rest of the time.
TheitemValue IDL attribute's behavior depends on the element, as follows:
itemprop attributeThe attribute must return null on getting and must throw anInvalidAccessError exception on setting.
itemscope attributeThe attribute must return the element itself on getting and must throw anInvalidAccessError exception on setting.
meta elementThe attribute must act as it would if it wasreflecting the element'scontent content attribute.
audio,embed,iframe,img,source,track, orvideo elementThe attribute must act as it would if it wasreflecting the element'ssrc content attribute.
a,area, orlink elementThe attribute must act as it would if it wasreflecting the element'shref content attribute.
object elementThe attribute must act as it would if it wasreflecting the element'sdata content attribute.
data elementThe attribute must act as it would if it wasreflecting the element'svalue content attribute.
meter elementThe attribute must act as it would if it wasreflecting the element'svalue content attribute.
time elementOn getting, if the element has adatetime content attribute, the IDL attribute must return that content attribute's value; otherwise, it must return the element'stextContent. On setting, the IDL attribute must act as it would if it wasreflecting the element'sdatetime content attribute.
The attribute must act the same as the element'stextContent attribute.
When theitemValue IDL attribute isreflecting a content attribute or acting like the element'stextContent attribute, the user agent must, on setting, convert the new value to the IDLDOMString value before using it according to the mappings described above.
In this example, a script checks to see if a particular elementelement is declaring a particular property, and if it is, it increments a counter:
if (element.itemProp.contains('color')) count += 1;This script iterates over each of the values of an element'sitemref attribute, calling a function for each referenced element:
for (var index = 0; index < element.itemRef.length; index += 1) process(document.getElementById(element.itemRef[index]));
TheHTMLPropertiesCollection interface is used forcollections of elements that addname-value pairs to a particularitem in themicrodata model.
interfaceHTMLPropertiesCollection :HTMLCollection { // inheritslength anditem() getterPropertyNodeList?namedItem(DOMString name); // shadows inherited namedItem() readonly attribute DOMString[]names;};typedef sequence<any>PropertyValueArray;interfacePropertyNodeList :NodeList {PropertyValueArraygetValues();};lengthReturns the number of elements in the collection.
item(index)Returns the element with indexindex from the collection. The items are sorted intree order.
namedItem(name)Returns aPropertyNodeList object containing any elements that add a property namedname.
Returns aPropertyNodeList object containing any elements that add a property namedname. Thename index has to be one of the values listed in thenames list.
namesReturns an array with theproperty names of the elements in the collection.
getValues()Returns an array of the various values that the relevant elements have.
The object'ssupported property indices are as defined forHTMLCollection objects.
Thesupported property names consist of theproperty names of all the elementsrepresented by the collection, intree order, ignoring later duplicates.
Thenames attribute must return aliveread only array object giving theproperty names of all the elementsrepresented by the collection, listed intree order, but with duplicates removed, leaving only the first occurrence of each name. The same object must be returned each time.
ThenamedItem(name) method must return aPropertyNodeList object representing alive view of theHTMLPropertiesCollection object, further filtered so that the only nodes in thePropertyNodeList object are those that have aproperty name equal toname. The nodes in thePropertyNodeList object must be sorted intree order, and the same object must be returned each time a particularname is queried.
Members of thePropertyNodeList interface inherited from theNodeList interface must behave as they would on aNodeList object.
ThegetValues method thePropertyNodeList object must return a newly constructed array whose values are the values obtained from theitemValue IDL attribute of each of the elements represented by the object, intree order.
Given a list of nodesnodes in aDocument, a user agent must run the following algorithm toextract the microdata from those nodes into a JSON form:
Letresult be an empty object.
Letitems be an empty array.
For eachnode innodes, check if the element is atop-level microdata item, and if it is thenget the object for that element and add it toitems.
Add an entry toresult called "items" whose value is the arrayitems.
Return the result of serializingresult to JSON in the shortest possible way (meaning no whitespace between tokens, no unnecessary zero digits in numbers, and only using Unicode escapes in strings for characters that do not have a dedicated escape sequence), and with a lowercase "e" used, when appropriate, in the representation of any numbers.[JSON]
This algorithm returns an object with a single property that is an array, instead of just returning an array, so that it is possible to extend the algorithm in the future if necessary.
When the user agent is toget the object for an itemitem, optionally with a list of elementsmemory, it must run the following substeps:
Letresult be an empty object.
If nomemory was passed to the algorithm, letmemory be an empty list.
Additem tomemory.
If theitem has anyitem types, add an entry toresult called "type" whose value is an array listing theitem types ofitem, in the order they were specified on theitemtype attribute.
If theitem has aglobal identifier, add an entry toresult called "id" whose value is theglobal identifier ofitem.
Letproperties be an empty object.
For each elementelement that has one or moreproperty names and is one ofthe properties of the itemitem, in the order those elements are given by the algorithm that returnsthe properties of an item, run the following substeps:
Letvalue be theproperty value ofelement.
Ifvalue is anitem, then: Ifvalue is inmemory, then letvalue be the string "ERROR". Otherwise,get the object forvalue, passing a copy ofmemory, and then replacevalue with the object returned from those steps.
For each namename inelement'sproperty names, run the following substeps:
If there is no entry namedname inproperties, then add an entry namedname toproperties whose value is an empty array.
Appendvalue to the entry namedname inproperties.
Add an entry toresult called "properties" whose value is the objectproperties.
Returnresult.
For example, take this markup:
<!DOCTYPE HTML><title>My Blog</title><article itemscope itemtype="http://schema.org/BlogPosting"> <header> <h1 itemprop="headline">Progress report</h1> <p><time itemprop="datePublished" datetime="2013-08-29">today</time></p> <link itemprop="url" href="?comments=0"> </header> <p>All in all, he's doing well with his swim lessons. The biggest thing was he had trouble putting his head in, but we got it down.</p> <section> <h1>Comments</h1> <article itemprop="comment" itemscope itemtype="http://schema.org/UserComments"> <link itemprop="url" href="#c1"> <footer> <p>Posted by: <span itemprop="creator" itemscope itemtype="http://schema.org/Person"> <span itemprop="name">Greg</span> </span></p> <p><time itemprop="commentTime" datetime="2013-08-29">15 minutes ago</time></p> </footer> <p>Ha!</p> </article> <article itemprop="comment" itemscope itemtype="http://schema.org/UserComments"> <link itemprop="url" href="#c2"> <footer> <p>Posted by: <span itemprop="creator" itemscope itemtype="http://schema.org/Person"> <span itemprop="name">Charlotte</span> </span></p> <p><time itemprop="commentTime" datetime="2013-08-29">5 minutes ago</time></p> </footer> <p>When you say "we got it down"...</p> </article> </section></article>
It would be turned into the following JSON by the algorithm above (supposing that the page's URL washttp://blog.example.com/progress-report):
{ "items": [ { "type": [ "http://schema.org/BlogPosting" ], "properties": { "headline": [ "Progress report" ], "datePublished": [ "2013-08-29" ], "url": [ "http://blog.example.com/progress-report?comments=0" ], "comment": [ { "type": [ "http://schema.org/UserComments" ], "properties": { "url": [ "http://blog.example.com/progress-report#c1" ], "creator": [ { "type": [ "http://schema.org/Person" ], "properties": { "name": [ "Greg" ] } } ], "commentTime": [ "2013-08-29" ] } }, { "type": [ "http://schema.org/UserComments" ], "properties": { "url": [ "http://blog.example.com/progress-report#c2" ], "creator": [ { "type": [ "http://schema.org/Person" ], "properties": { "name": [ "Charlotte" ] } } ], "commentTime": [ "2013-08-29" ] } } ] } } ]}If theitemprop attribute is present onlink ormeta, they areflow content andphrasing content. Thelink andmeta elements may be used wherephrasing content is expected if theitemprop attribute is present.
If alink element has anitemprop attribute, therel attribute may be omitted.
If ameta element has anitemprop attribute, thename,http-equiv, andcharset attributes must be omitted, and thecontent attribute must be present.
If theitemprop is specified on ana orarea element, then thehref attribute must also be specified.
If theitemprop is specified on aniframe element, then thedata attribute must also be specified.
If theitemprop is specified on anembed element, then thedata attribute must also be specified.
If theitemprop is specified on anobject element, then thedata attribute must also be specified.
If theitemprop is specified on amedia element, then thesrc attribute must also be specified.
Thedrag-and-drop initialization steps are:
The user agent must take thelist of dragged nodes andextract the microdata from those nodes into a JSON form, and then must add the resulting string to thedataTransfer member, associated with theapplication/microdata+json format.
application/microdata+jsonThis registration is for community review and will be submitted to the IESG for review, approval, and registration with IANA.
application/json[JSON]application/json[JSON]application/json[JSON]application/json[JSON]application/microdata+json type asserts that the resource is a JSON text that consists of an object with a single entry called "items" consisting of an array of entries, each of which consists of an object with an entry called "id" whose value is a string, an entry called "type" whose value is another string, and an entry called "properties" whose value is an object whose entries each have a value consisting of an array of either objects or strings, the objects being of the same form as the objects in the aforementioned "items" entry. Thus, the relevant specifications are the JSON specification and this specification.[JSON]Applications that transfer data intended for use with HTML's microdata feature, especially in the context of drag-and-drop, are the primary application class for this type.
application/json[JSON]application/json[JSON]application/json[JSON]Fragment identifiers used withapplication/microdata+json resources have the same semantics as when used withapplication/json (namely, at the time of writing, no semantics at all).[JSON]
All references are normative unless marked "Non-normative".
XMLHttpRequest, A. van Kesteren. WHATWG.