HTML reference

itemscope

The Microdata itemscope attribute marks an element as the boundary of one structured-data item, such as a person, product, or article.

What you will learn

  • How itemscope groups related information
  • How it relates to itemtype and itemprop
  • How to keep structured data accurate

See how three attributes describe a person

Microdata adds labels to HTML so software can identify what the information means. These three attributes have different jobs.

The item, its type, and its properties
AttributeJobIn this example
itemscopeStarts one itemOne person’s profile
itemtypeIdentifies the kind of itemhttps://schema.org/Person
itempropNames a property of the itemname = the person’s name
<div itemscope itemtype="https://schema.org/Person">
  <p itemprop="name">Aki</p>
</div>

The page displays “Aki”. These attributes do not change the text’s size or color. A program that reads Microdata can identify Aki as the name of a person.

Try keeping two people’s names separate

How to group the information

Aki

Kai

HTML for the grouping above

<div itemscope itemtype="https://schema.org/Person">
  <p itemprop="name">Aki</p>
</div>

<div itemscope itemtype="https://schema.org/Person">
  <p itemprop="name">Kai</p>
</div>

The name values read from these items

  • Person 1: name = Aki
  • Person 2: name = Kai

With separate items, Aki and Kai belong to different people.

This example shows which person owns each name. It is not a validator for every kind of Microdata.

Where a property value comes from

How standard HTML Microdata obtains a value
MarkupValue
<span itemprop="name">Aki</span>Aki
<meta itemprop="priceCurrency" content="JPY">JPY
<data itemprop="price" value="19800">19,800</data>19800
<img itemprop="image" src="photo.jpg" alt="…">The image URL resolved from src
<time itemprop="birthDate" datetime="2000-11-27">…</time>2000-11-27

For example, a span normally supplies its text. To provide a differently formatted value, use the mechanism defined for that element, such as value on data.

Connect a nested item with a property name

A product and its offer are different items. Use Product for the product, and an Offer connected by offers for the price and currency.

See the itemprop article for a complete price example.

Check what you have written

  1. Paste the code into Schema Markup Validator and check the Person items and name values.
  2. Use Rich Results Test to check features Google supports. Check the eligible item types and their required properties.

If a minimal Person example is not eligible for a rich result, that does not by itself make the Microdata invalid. Rich results are search listings with features such as rating stars. Correct structured data does not guarantee a ranking increase or a rich result.

JSON-LD writes structured data separately from the visible HTML. If you are adding structured data, consider this format as well. Google recommends JSON-LD when your site can use it.

Check your understanding: write two separate person items and explain which attribute keeps their names separate.

Sources: HTML Microdata values, Schema.org price, and Google’s structured data guide.

Basic example

<article itemscope itemtype="https://schema.org/Book">
  <h2 itemprop="name">The Web Guide</h2>
  <p itemprop="author">A. Reader</p>
</article>

itemscope starts the item. itemtype says which vocabulary type it uses, and itemprop labels the properties inside it. The visible content should still be natural and truthful for readers.

Nested items

An item can contain another item, such as a product containing an offer. Keep nesting aligned with the vocabulary's model; adding attributes does not automatically make search results richer.

Validation and alternatives

Validate structured data and check the documentation of the consumer that will read it. JSON-LD can be easier to maintain when annotations would make the visible HTML difficult to read.

Related pages