This specification defines new HTML attributes to embed machine-readable data in HTML documents in a style similar to RDFa. It is compatible with JSON, and can be written in a style which is convertible to RDF, although two-way conversion is not lossless.

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 https://www.w3.org/TR/.

This document is a milestone Working Draft, published as an update to the 4 May 2017 W3C First Public Working Draft.

This specification is an extension to HTML. All normative content in the HTML specification not specifically overridden by this specification is intended to be normative for this specification. [HTML52]

Review is sought, particularly for the changes made in how property names are determined and questions of internationalisation. A list of substantive changes is included to help guide reviewers, as well as full details of changes made. Ideally review comments will be provided before 15 July 2017, and a Candidate Recommendation incorporating revisions published by the end of July.

If you wish to make comments regarding this document please submit them as github issues. All feedback is welcome, but please note the contribution guidelines require agreement to the terms of the W3C Patent Policy for substantive contributions.

This document was published by the Web Platform Working Group as a Working Draft. This document is intended to become a W3C Recommendation.

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

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

This document is governed by the 1 March 2017 W3C Process Document.

1. Dependencies

This specification depends on the HTML specification and its extensions for definitions of individual HTML elements and attributes. [HTML52][html-extensions]

Information expressed as microdata can be converted to JSON, as described in Section 6.1. Microdata can be converted to RDF, for example via conversion to JSON-LD or RDFa, if additional constraints are applied to the microdata content. A process to convert microdata directly to RDF is described in Microdata to RDF. [ JSON] [rdfa-core] [microdata-rdf]

2. Terminology

For the purposes of this specification, the terms "URL" and "URI" are equivalent. The URL specification, and RFC 3986 which uses the term URI, define a URL, valid URL, and absolute URL. [RFC3986][URL]

A valid absolute URL is an absolute URL which is valid.

RFC 3986 defines the term resolve a URL [RFC3986].

DOM 4.1 defines textContent for attributes, and for elements or nodes, as well as the term tree order. [DOM41]

This specification relies on the HTML specification to define the following terms: [HTML52]

3. Conformance

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

The key words "must", "must not", "should", "should not", and "may" in the normative parts of this document are to be interpreted as described in RFC2119. [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.)

4. Introduction

4.1 Overview

This section is non-normative.

Sometimes, it is desirable to annotate content with specific machine-readable labels. For example, search engines can better identify page content using schema.org annotations, and content management systems can find and use information from documents, if it is marked up in a known way.

Microdata provides a simple mechanism to label content in a document, so it can be processed as a set of items described by name-value pairs.

Each name-value pair identifies a property of the item, and a value of that property.

Figure 1 A common way to represent items, properties and values graphically

An Item Item A Property Property A Value Value

The value of a property may be an item.

4.2 The basic syntax

This section is non-normative.

Items and properties are generally represented by regular elements.

The itemscope attribute creates an item.

The itemprop attribute on a descendent element of an item's identifies a property of that item. Typically, the text content of that element is the value of that property.

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 itemscope>
 <p>My name is 
  <span itemprop="name">Daniel</span>.</p>
Figure 2 The example represented graphically: two items, each with a value for the property name
Item name Elizabeth Item name Daniel

Markup other than 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 itemscope>
   <p>My name is
    <span itemprop="name"><a href="/?user=daniel">Daniel</a></span>.</p>

Note that this means any information recorded in markup for purposes such as internationalisation or accessibility will be lost in the conversion to data.

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>

If the text that would normally be the value of a property, such as the element content, is unsuitable for recording the property value, it can be expressed using the content attribute of the element.

Here, the visible content may be added by a script. A microdata processor can extract the content from the content attribute without running scripts. The value of the product-id property for this item is 9678AOU879

<li itemscope>
 <span itemprop="product-id" content="9678AOU879"

When a string value is in some machine-readable format unsuitable to present as the content of an element, it can be expressed using the value attribute of the data element, as long as there is no content attribute.

Here, there is an item with a property whose value is a product identifier. The identifier is not human-friendly, so instead it is encoded for microdata using the value attribute of the data element, and the product's name is used as the text content of the element that is rendered on the page.

<h1 itemscope>
 <data itemprop="product-id" value="9678AOU879">The Instigator 2000</data>

This will not work if there is a content attribute as well. In the following example, the value of the product-id property is taken from the content attribute, so it will be This one rocks!:

<h1 itemscope>
 <data itemprop="product-id" value="9678AOU879" 
   content="This one rocks!">The Instigator 2000</data>

When an itemprop is used on an element that can have a src or href attribute, such as links and media elements, that does not have a content attribute, the value of the name-value pair is an absolute URL based on the src or href attribute (or the empty string if they are missing or there is an error).

In this example, the item has one property, logo, whose value is a URL based on the location of the page, and ending with our-logo.png:

<div itemscope itemtype="https://schema.org/LocalBusiness">
 <img itemprop="logo" src="our-logo.png" alt="Our Company">

Note that accessibility information, such as the alt attribute in the previous example, is ignored. To provide that as a value, repeat it in a content attribute. In the following example, the value of the name property is The Company:

<div itemscope itemtype="https://schema.org/LocalBusiness">
 <img itemprop="name" src="our-logo.png"
     content="The Company" alt="Our Company">

For numeric data, the meter element and its value attribute can be used instead, as long as there is no content attribute.

Here a rating of 3.5 is given using a meter element.

<div itemscope itemtype="https://schema.org/Product">
 <span itemprop="name">Panasonic White 60L Refrigerator</span>
 <img src="panasonic-fridge-60l-white.jpg" alt="">
  <div itemprop="aggregateRating"
       itemscope itemtype="https://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)

Similarly, for date- and time-related data, the time element and its datetime attribute can be used to specify a specifically formatted date or time, as long as there is no content attribute.

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

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>

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>

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>
  <li itemprop="flavor">Lemon sorbet</li>
  <li itemprop="flavor">Apricot sorbet</li>

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>

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.

The following two examples are exactly the same microdata, because they produce exactly the same information when processed:

 <img src="castle.jpeg">
 <figcaption><span itemscope><span
  itemprop="name">The Castle</span></span> (1986)</figcaption>
<span itemscope><meta itemprop="name"
 content="The Castle"></span>
 <img src="castle.jpeg">
 <figcaption>The Castle (1986)</figcaption>

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". In neither case is the image in any way associated with the item.

4.3 Typed items

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 "http://example.com/person", or "http://example.org/cat", or "http://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. The value is a URL, which determines the vocabulary identifier for properties

Assuming a page at http://example.net/some/dataexample contains the following code:

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

The item's type is "http://example.org/animals#cat"

In this example the "http://example.org/animals#cat" item has three properties:

Hedral is a male american domestic shorthair, with a fluffy black fur with white paws and belly.

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. A vocabulary may define several types. For example, the types " http://example.org/people/teacher" and "http://example.org/people/engineer" could be defined in the same vocabulary. Some properties might not be especially useful in both cases: the "classroom" property might not be meaningful with the "http://example.org/people/engineer" type. Multiple types from the same vocabulary can be given for a single item by listing the URLs, separated by spaces, in the attribute's value. An item cannot be given two types if they do not use the same vocabulary, however.

4.4 Global identifiers for items

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, or concepts can be identified by a URL as in [rdf-primer].

The itemtype attribute associates an item with a global identifier in the form of a URLs.

Here, an item is talking about a particular book:

<dl itemscope
 <dd itemprop="title">The Reality Dysfunction
 <dd itemprop="author">Peter F. Hamilton
 <dt>Publication date
 <dd><time itemprop="pubdate" datetime="1996-01-26">26 January 1996</time>

4.5 Selecting names when defining vocabularies

This section is non-normative.

Using microdata means using a vocabulary. For some purposes an ad-hoc vocabulary is adequate, but authors are encouraged to re-use existing vocabularies to make 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 http://example.com/~jon/... and http://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 in the page http://example.net/some/dataexample is an "http://example.org/animals/cat", and most of the properties have names defined in the context of that type. There are also a few additional properties whose names come from other vocabularies.

<section itemscope itemtype="http://myvocab.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">

This example has one item with the type "http://myvocab.example.org/animals/cat" and the following properties:

Hedral is a male american domestic shorthair, with a fluffy black fur with white paws and belly.

5. Encoding microdata

5.1 The microdata model

The microdata model consists of groups of name-value pairs known as items.

Each group is known as an item. Each item can have zero or more item types, global identifier(s), and associated 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.

5.2 Items: itemscope, itemtype, and itemid.

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 that describe properties, and their values, of the thing represented by that element.

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 absolute URL, and all of which are in 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 determine the vocabulary identifier. This is a URL that is prepended to property names, which identifies them as part of their vocabulary. The value of the vocabulary identifier for an item is determined as follows:

User agents must not automatically dereference unknown URLs given as item types and property names. These URLs are a priori opaque identifiers.


A specification could define that its item types can be derefenced to provide the user with help information. Vocabulary authors are encouraged to provide useful information at the given URL, either in prose or a formal language such as RDF. User agents are

The itemtype attribute must not be specified on elements that do not have an itemscope attribute specified.

An item is said to be a typed item when either it has an item type, or it is the value of a property of a typed item. The relevant types for a typed item is the item's item types, if it has any, or else is the relevant types of the item for which it is a property's value.

Elements with both itemscope and itemtype attributes may also have an itemid attribute specified, to give a global identifier for the item, so that it can be related to other items elsewhere on the Web, or with concepts beyond the Web such as ISBN numbers for published books.

The itemid attribute, if specified, must have a value that is a valid URL potentially surrounded by space characters.

The global identifier of an item is the value of its element's itemid attribute, if it has one, resolved relative to the element on which the attribute is specified. If the itemid attribute is missing or if resolving it fails, it is said to have no global identifier.

The itemid attribute must not be specified on elements that do not have both an itemscope attribute and an itemtype attribute specified.

This example shows a simple vocabulary used to describe the products of a model railway manufacturer. The vocabulary has just five property names:

A number that identifies the product in the manufacturer's catalog.
A brief description of the product.
One of "HO", "1", or "Z" (potentially with leading or trailing whitespace), indicating the scale of the product.
If present, one of "Digital", "Delta", or "Systems" (potentially with leading or trailing whitespace) indicating that the product has a digital decoder of the given type.
For track-specific products, one of "K", "M", "C" (potentially with leading or trailing whitespace) indicating the type of track for which the product is intended.

This vocabulary has four defined item types:

Rolling stock with an engine
Passenger rolling stock
Track pieces
Equipment with lighting

Each item 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
 <dd itemprop="name">Tank Locomotive (DB 80)
 <dt>Product code:
 <dd itemprop="product-code">33041
 <dd itemprop="scale">HO
 <dd itemprop="digital">Delta

A turnout lantern retrofit kit might be marked up as:

<dl itemscope itemtype="http://md.example.com/track
 <dd itemprop="name">Turnout Lantern Kit
 <dt>Product code:
 <dd itemprop="product-code">74470
 <dd>For retrofitting 2 <span itemprop="track-type">C</span> Track
 turnouts. <meta itemprop="scale" content="HO">

A passenger car with no lighting might be marked up as:

<dl itemscope itemtype="http://md.example.com/passengers">
 <dd itemprop="name">Express Train Passenger Car (DB Am 203)
 <dt>Product code:
 <dd itemprop="product-code">8710
 <dd itemprop="scale">Z

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.

5.3 Properties: the itemprop and itemref attributes

The itemprop attribute, when added to any HTML element that is part of an item, identifies a property of that item. The attribute must be an unordered set of unique space-separated tokens, representing the case-sensitive names of the properties that it adds. The attribute must contain at least one token.

Each token must be either a valid absolute URL or a a string that contains no "." (U+002E) characters and no ":" (U+003A) characters.

Vocabulary specifications must not define property names for Microdata that contain "." (U+002E) characters, ":" (U+003A) characters, nor space characters (defined in [HTML52] as U+0020, U+0009, U+000A, U+000C, and U+000D).

The property names of an element are determined as follows:

Within an item, 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 defines the 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>

Thus, the following is equivalent:

<div itemscope>
 <p itemprop="b">test</p>
 <p itemprop="a">1</p>
 <p itemprop="a">2</p>

As is the following:

<div itemscope>
 <p itemprop="a">1</p>
 <p itemprop="b">test</p>
 <p itemprop="a">2</p>

Elements with an itemscope attribute may have an itemref attribute specified, to give a list of additional elements to crawl to find the name-value pairs of the item.

The itemref attribute, if specified, must have a value that is an unordered set of unique space-separated tokens that are case-sensitive, consisting of IDs of elements in the same document.

The itemref attribute must not be specified on elements that do not have an itemscope attribute specified.

The preceding example:

<div itemscope>
 <p itemprop="a">1</p>
 <p itemprop="a">2</p>
 <p itemprop="b">test</p>

Could also be written as follows:

<div id="x">
 <p itemprop="a">1</p>
<div itemscope itemref="x">
 <p itemprop="b">test</p>
 <p itemprop="a">2</p>

When an element with an itemprop attribute adds a property to multiple items, the requirement above regarding the tokens applies for each item individually.

For the following code:

<div itemscope itemtype="http://example.com/a"> <ref itemred="x"> </div>
<div itemscope itemtype="http://example.com/b"> <ref itemref="x"> </div>
<meta id="x" itemprop="z" content="">

The author should be certain that z is a valid property name for both the http://example.com/a and http://example.com/b vocabularies.

5.4 Values: the content attribute.

The algorithm to determine the value for a name-value pair is given by applying the first matching case in the following list:

If the element also has an itemscope attribute

The value is the item created by the element.

If the element has a content attribute

The value is the textContent of the element's content attribute.


HTML only allows the content attribute on the meta element. This specification changes the content model to allow it on any element, as a global attribute.

If the element is an audio, embed, iframe, img, source, track, or video element

If the element has a src attribute, let proposed value be the result of resolving that attribute's textContent. If proposed value is a valid absolute URL: The value is proposed value.
otherwise The value is the empty string.

If the element is an a, area, or link element

If the element has an href attribute, let proposed value be the result of resolving that attribute's textContent. If proposed value is a valid absolute URL: The value is proposed value.
otherwise The value is the empty string.

If the element is an object element

If the element has a data attribute, let proposed value be the result of resolving that attribute's textContent. If proposed value is a valid absolute URL: The value is proposed value.
otherwise The value is the empty string.

If the element is a data or meter element

If the element has a value attribute, the value is that attribute's textContent.

If the element is a time element

If the element has a datetime attribute, the value is that attribute's textContent.


The value is the element's textContent.

The URL property elements are the a, area, audio, embed, iframe, img, link, object, source, track, and video elements.

If a property's value, as defined by the property's definition, is an absolute URL, the property must be specified using a URL 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 an a element, even though it looks like a URL. On the other hand, if there was a (rather narrowly scoped!) vocabulary for "books whose titles look like URLs" which had a "title" property whose content was defined as a URL, then the property would expect the title to be given in an a element (or one of the other URL property elements), because of the requirement above.

5.5 Associating names with items

To find the properties of an item defined by the element root, the user agent must run the following steps. These steps are also used to flag microdata errors.

  1. Let results, memory, and pending be empty lists of elements.

  2. Add the element root to memory.

  3. Add the child elements of root, if any, to pending.

  4. If root has an itemref attribute, split the value of that itemref attribute on spaces. For each resulting token ID, if there is an element in the document whose ID is ID, then add the first such element to pending.

  5. Loop: If pending is empty, jump to the step labeled end of loop.

  6. Remove an element from pending and let current be that element.

  7. If current is already in memory, there is a microdata error; return to the step labeled loop.

  8. Add current to memory.

  9. If current does not have an itemscope attribute, then: add all the child elements of current to pending.

  10. If current has an itemprop attribute specified and has one or more property names, then add current to results.

  11. Return to the step labeled loop.

  12. End of loop: Sort results in tree order.

  13. Return results.

A document must not contain any items for which the algorithm to find the properties of an item finds any microdata error.

An item is a top-level microdata item if its element does not have an itemprop attribute.

All itemref attributes in a Document must be such that there are no cycles in the graph formed from representing each item in the Document as a node in the graph and each property of an item whose value is another item as an edge in the graph connecting those two items.

A document must not contain an itemprop attribute that would not be a property of any item in that document were the properties all to be determined.

In this example, a single license statement is applied to two works, using itemref from the items representing the works:

  <title>Photo gallery</title>
  <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 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>
   <p id="licenses">All images licensed under the <a itemprop="license"

The above results in two items with the type "http://n.whatwg.org/work", one with:

The house I found.

...and one with:

The mailbox.

6. Converting Microdata to other formats

6.1 JSON

Given a list of nodes nodes in a Document, a user agent must run the following algorithm to extract the microdata from those nodes into a JSON form:

  1. Let result be an empty object.

  2. Let items be an empty array.

  3. For each node in nodes, check if the element is a top-level microdata item, and if it is then get the object for that element and add it to items.

  4. Add an entry to result called "items" whose value is the array items.

  5. Return the result of serializing result 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 to get the object for an item item, potentially together with a list of elements memory, it must run the following substeps:

  1. Let result be an empty object.

  2. If no memory was passed to the algorithm, let memory be an empty list.

  3. Add item to memory.

  4. If the item has any item types, add an entry to result called "type" whose value is an array listing the item types of item, in the order they were specified on the itemtype attribute.

  5. If the item has a global identifier, add an entry to result called "id" whose value is the global identifier of item.

  6. Let properties be an empty object.

  7. 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 an item, run the following substeps:

    1. Let value be the property value of element.

    2. If value is an item, then: If value is in memory, then let value be the string "ERROR". Otherwise, get the object for value, passing a copy of memory, and then replace value with the object returned from those steps.

    3. For each name name in element's property names, run the following substeps:

      1. If there is no entry named name in properties, then add an entry named name to properties whose value is an empty array.

      2. Append value to the entry named name in properties.

  8. Add an entry to result called "properties" whose value is the object properties.

  9. Return result.

For example, take this markup:

<title>My Blog</title>
<article itemscope itemtype="https://schema.org/BlogPosting">
  <h1 itemprop="headline">Progress report</h1>
  <p><time itemprop="datePublished" datetime="2013-08-29">today</time></p>
  <link itemprop="url" href="?comments=0">
 <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>
  <article itemprop="comment" itemscope itemtype="https://schema.org/UserComments" id="c1">
   <link itemprop="url" href="#c1">
    <p>Posted by: <span itemprop="creator" itemscope itemtype="https://schema.org/Person">
     <span itemprop="name">Greg</span>
    <p><time itemprop="commentTime" datetime="2013-08-29">15 minutes ago</time></p>
  <article itemprop="comment" itemscope itemtype="https://schema.org/UserComments" id="c2">
   <link itemprop="url" href="#c2">
    <p>Posted by: <span itemprop="creator" itemscope itemtype="https://schema.org/Person">
     <span itemprop="name">Charlotte</span>
    <p><time itemprop="commentTime" datetime="2013-08-29">5 minutes ago</time></p>
   <p>When you say "we got it down"...</p>

It would be turned into the following JSON by the algorithm above (supposing that the page's URL was http://blog.example.com/progress-report):

  "items": [
      "type": [ "https://schema.org/BlogPosting" ],
      "properties": {
        "headline": [ "Progress report" ],
        "datePublished": [ "2013-08-29" ],
        "url": [ "http://blog.example.com/progress-report?comments=0" ],
        "comment": [
            "type": [ "https://schema.org/UserComments" ],
            "properties": {
              "url": [ "http://blog.example.com/progress-report#c1" ],
              "creator": [
                  "type": [ "https://schema.org/Person" ],
                  "properties": {
                    "name": [ "Greg" ]
              "commentTime": [ "2013-08-29" ]
            "type": [ "https://schema.org/UserComments" ],
            "properties": {
              "url": [ "http://blog.example.com/progress-report#c2" ],
              "creator": [
                  "type": [ "https://schema.org/Person" ],
                  "properties": {
                    "name": [ "Charlotte" ]
              "commentTime": [ "2013-08-29" ]

7. Changes to HTML

7.1 New attributes

This specification adds the following global attributes and associated validity constraints to HTML:

This is a boolean attribute. When present on an element, it identifies that element as the container for an item
This is a list of absolute URLs that identify an item within a particular vocabulary.
The itemtype attribute must not be specified on elements that do not have an itemscope attribute.

This attribute performs a function similar to the combination of vocab and typeof attributes in [rdfa-core].

When present on an element, it identifies that the element provides the property value of the item in which it appears, and the attribute's value defines the property name.

This attribute is equivalent to the property attribute in [rdfa-core].

This is an absolute URL that provides a global identifier for an item.
The itemid attribute must not be specified on elements that do not have both an itemscope attribute and an itemtype attribute specified.

This is approximately equivalent to declaring that an item is owl:sameAs the value of the attribute. [owl-ref]

This is a space seperated list of IDs of elements which are not descendants of the element on which it appears. It identifies each element whose ID it includes as defining a property of the item on which it is present.
The itemref attribute must not be specified on elements that do not have an itemscope attribute.

7.2 Content models

This section changes the content models defined by HTML in the following ways:

The content attribute redefined by this specification as a global attribute that may be present on that element.

This is consistent with [HTML-RDFA], which uses the attribute for the same purpose.

If the itemprop attribute is present on a link or meta element, that element is flow content and phrasing content, and may be used where phrasing content is expected.

If a link element has an itemprop attribute, the rel attribute may be omitted.

If a meta element has an itemprop attribute, the name, http-equiv, and charset attributes must be omitted, and the content attribute must be present.

If the itemprop attribute is specified on an a or area element, then the href attribute must also be specified.

If the itemprop attribute is specified on an audio, embed, iframe, img, source, track, or video element, then the src attribute must also be specified.

If the itemprop attribute is specified on an object element, then the data attribute must also be specified.

8. Accessibility and microdata

This section is not normative

Microdata can be used to provide machine-parseable information about content that is processed by tools to improve accessibility.

When editing content that contains microdata, authors should consider the possibility that this is the case. Authoring and content management tools should implement the Authoring Tool Accessibility Guidelines, and in this context note Guideline B1.1.2 - Ensure Accessibility Information is Preserved, if applicable drawing attention to the fact that changes in content may mean the encoded metadata is not accurate. [ATAG20]

Authors should be aware that a great deal of accessibility information is ignored in extracting microdata, including attributes such as alt and ARIA information. Authors should consider whether to encode accessibility information explicitly, or to use a more expressive approach such as RDFa. [rdfa-core]

9. Internationalisation and localisation

This section is not normative

Microdata conversion means that almost all internationalisation-related information is lost, except if it is specifically encoded as microdata, in which case it is important to pay attention when editing, as above for accessibility.

Machine-readable data may be presented to users, for example by search engines. Identifying content that should, or should not, be translated, would be helpful but currently microdata strips markup. It is possible to use XMLLiterals in RDFa to ensure that markup is kept. [rdfa-core]

Vocabulary design is difficult. Different languages and cultures present view ambiguity differently: two terms with different meanings in one situation may be most naturally translated by a single term that has both meanings, or a single term may have two natural translations. When developing for localisation, it is important to provide sufficient contextual information about terms in a vocabulary to enable accurate translation.

10. Privacy Considerations

This section is not normative

Microdata does not introduce new mechanisms to transmit privacy-sensitive information. However it more clearly identifies information, in a way that facilitates finding data and merging it with data from other sources.

Authors and processors should take care to ensure that their use of microdata is in line with privacy policies and any applicable regulation.

11. Security Considerations

This section is not normative

Microdata does not generally interact with browsers, being a static document format that lacks any DOM interface.

Microdata makes information machine-readable, but does not automatically include provenance information for the statements it encodes.

Processors of microdata should consider the trustworthiness of sources they use, including the possibility that data is no longer accurate, and the possibility that data gathered over an insecure connection has been altered by a "man-in-the-middle" attack.

12. IANA considerations


This registration is for community review and will be submitted to the IESG for review, approval, and registration with IANA.

Type name:
Subtype name:
Required parameters:
Same as for application/json [JSON]
Optional parameters:
Same as for application/json [JSON]
Encoding considerations:
8bit (always UTF-8)
Security considerations:
Same as for application/json [JSON]
Interoperability considerations:
Same as for application/json [JSON]
Published specification:
Labeling a resource with the 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 use this media type:

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.

Additional information:
Magic number(s):
Same as for application/json [JSON]
File extension(s):
Same as for application/json [JSON]
Macintosh file type code(s):
Same as for application/json [JSON]
For further information:
Intended usage:
Restrictions on usage:
No restrictions apply.
Change controller:

Fragment identifiers used with application/microdata+json resources have the same semantics as when used with application/json (namely, at the time of writing, no semantics at all). [JSON]

13. Changes

An exact history of changes to the text is available in the Github commit log. The following information is provided as an overview of the substantive changes made to the specification between each publication.

Changes made between the current draft and the First Public Working Draft:

Changes made between the First Public Working Draft and the 23 October 2013 W3C Note:

14. Acknowledgements

The original specification for Microdata was developed by Ian Hickson. Without him this specification would not exist. Uptake has been substantially been driven by its use for the schema.org vocabulary.

The current editors would like to thank the following people for direct contributions to this work:

Christine Runnegar, Gregg Kellogg, Ivan Herman, Jens Oliver Meiert, Léonie Watson, Manu Sporny, Marcos Caceres, Nick Doty, Philippe Le Hégaret, Ralph Swick, Robin Berjon, Tab Atkins, Tavis Tucker, Tobie Langel, Xiaoqian Wu, Yves Lafon.

A. References

A.1 Normative references

W3C DOM 4.1. Yongsheng Zhu. W3C. 9 June 2017. W3C Working Draft. URL: https://www.w3.org/TR/dom41/
HTML 5.2. Steve Faulkner; Arron Eicholz; Travis Leithead; Alex Danilo; Sangwhan Moon. W3C. 9 May 2017. W3C Working Draft. URL: https://www.w3.org/TR/html52/
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
Uniform Resource Identifier (URI): Generic Syntax. T. Berners-Lee; R. Fielding; L. Masinter. IETF. January 2005. Internet Standard. URL: https://tools.ietf.org/html/rfc3986

A.2 Informative references

Authoring Tool Accessibility Guidelines (ATAG) 2.0. Jan Richards; Jeanne F Spellman; Jutta Treviranus. W3C. 24 September 2015. W3C Recommendation. URL: https://www.w3.org/TR/ATAG20/
HTML+RDFa 1.1 - Second Edition. Manu Sporny. W3C. 17 March 2015. W3C Recommendation. URL: https://www.w3.org/TR/html-rdfa/
The application/json Media Type for JavaScript Object Notation (JSON). D. Crockford. IETF. July 2006. Informational. URL: https://tools.ietf.org/html/rfc4627
URL Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://url.spec.whatwg.org/
HTML Extension Specifications. Léonie Watson. W3C. 3 May 2017. W3C Editor's Draft. URL: https://w3c.github.io/html-extensions/
Microdata to RDF – Second Edition. Gregg Kellogg. W3C. 16 December 2014. W3C Note. URL: https://www.w3.org/TR/microdata-rdf/
OWL Web Ontology Language Reference. Mike Dean; Guus Schreiber. W3C. 10 February 2004. W3C Recommendation. URL: https://www.w3.org/TR/owl-ref/
RDF Primer. Frank Manola; Eric Miller. W3C. 10 February 2004. W3C Recommendation. URL: https://www.w3.org/TR/rdf-primer/
RDFa Core 1.1 - Third Edition. Ben Adida; Mark Birbeck; Shane McCarron; Ivan Herman et al. W3C. 17 March 2015. W3C Recommendation. URL: https://www.w3.org/TR/rdfa-core/