HTML Microdata and Machine-Readable Semantics

Advanced

HTML Microdata lets an HTML document carry machine-readable name-value pairs alongside its human-readable content. The HTML Standard defines the microdata model, its attributes, how property values are obtained, and how an item is described; this lesson keeps those rules together so individual element lessons do not become duplicate semantic owners.

The microdata model

A microdata item is a group of name-value pairs. The group is an item; each name is a property; each property has one or more values. A value can be a string or another item. Properties with the same name retain their relative order, while different property names are not ordered by the microdata model.

<div itemscope>
  <!-- choose -->
</div>?

itemscope creates an item

Every HTML element may have the itemscope attribute. When it is specified, the element creates a new microdata item. The item can be a top-level item or can itself be the value of a property on another item.

<div itemscope>
  <!-- choose -->
</div>?

itemprop names properties

itemprop adds one or more property names to an item. The property element is found by the microdata item property algorithm, which follows the item subtree and can also use itemref. If an item is typed, the vocabulary associated with its type determines which property names are defined for that type.

<div itemscope>
  <!-- choose -->
</div>?

Nested items

A property value can itself be an item. Put itemscope on the element that also carries itemprop to make that nested item the property value. This is how microdata represents structured relationships rather than only flat strings.

<div itemscope>
  <!-- choose -->
</div>?

itemtype gives an item its types

An item can have itemtype when it also has itemscope. Its value is an unordered set of unique space-separated absolute URLs, and the types must be defined by applicable specifications and use the same vocabulary. An item type is an identifier; user agents do not infer its meaning by dereferencing an unknown type.

<div itemscope>
  <!-- choose -->
</div>?

Do not invent vocabulary semantics

The HTML Standard defines the mechanics of microdata. It does not make an arbitrary URL into a vocabulary with application-specific meanings. When a typed item uses a vocabulary, the specification defining that vocabulary determines its permitted types and property names. For teaching examples, use clearly illustrative URLs and do not imply that they are real production vocabularies.

<div itemscope>
  <!-- choose -->
</div>?

itemid supplies a global identifier

itemid can give an item a global identifier when the item has both itemscope and itemtype and the vocabulary supports global identifiers. Its value is a URL parsed relative to the element’s node document. itemid is not a general-purpose replacement for HTML id.

<div itemscope>
  <!-- choose -->
</div>?

itemref reaches properties outside the subtree

Normally, an item’s properties are found among the element’s descendants. itemref adds a list of element IDs to crawl in addition to that descendant subtree. It is a syntactic aid for non-tree-shaped annotations; it is not itself part of the underlying item data model.

<div itemscope>
  <!-- choose -->
</div>?

Property values depend on the element

The microdata value of a property is not always its rendered text. The HTML Standard defines value extraction by element type: nested items contribute item values; meta contributes its content value; audio, embed, iframe, img, source, track, and object contribute URLs from their relevant attributes; data and meter use their machine-readable values; and time can use datetime. Other elements contribute their text content.

<div itemscope>
  <!-- choose -->
</div>?

URL-valued properties

When a property value is a URL, the HTML Standard defines URL-bearing elements that contribute their relevant URL attributes. This keeps machine-readable values distinct from arbitrary rendered text.

<div itemscope>
  <!-- choose -->
</div>?

Multiple properties with the same name

An item may have multiple properties with the same name and different values. The relative order of those repeated values is preserved. This lets an item represent a list of values without inventing a second property name for every occurrence.

<div itemscope>
  <!-- choose -->
</div>?

Top-level items and property items

An item is top-level when its element does not have itemprop. A nested item used as a property value has itemprop on the element that creates it. Keeping this distinction clear helps you read an annotated document as a graph of items and property values.

<div itemscope>
  <!-- choose -->
</div>?

What microdata does not do

Microdata does not replace semantic HTML. A heading remains a heading, a time element remains a time element, and an image still needs appropriate alternative text. Microdata adds machine-readable item/property annotations alongside the document semantics. It also does not define a universal search-engine or application vocabulary.

<div itemscope>
  <!-- choose -->
</div>?

Conformance matters

The HTML Standard defines constraints on combinations such as itemtype requiring itemscope, itemid requiring the required item conditions, and itemref requiring itemscope. It also defines conditions under which microdata is erroneous, including problematic itemref relationships. Conforming authoring is different from what a user agent can mechanically parse from malformed markup.

<div itemscope>
  <!-- choose -->
</div>?

A complete small annotation

Here is the complete pattern: create an item, optionally type it, give properties to descendants, use nested items for structured values, and use itemref only when the properties cannot conveniently remain in the item subtree.

<div itemscope>
  <!-- choose -->
</div>?

Authoring rules to remember

Use microdata when its annotation model and vocabulary are actually useful for your document. Keep human-readable HTML meaningful without the annotations. Treat itemtype URLs as vocabulary identifiers rather than URLs to fetch blindly. Use itemid only when the vocabulary supports global identifiers, and use itemref as a structural escape hatch rather than as a default pattern. Finally, verify vocabulary-specific constraints from the specification that defines that vocabulary.