About microdata

The HTML5 microdata specification is a way to label content to describe a specific type of information—for example, reviews, person information, or events. Each information type describes a specific type of item, such as a person, and event, or a review. For example, an event has the properties venue, starting time, name, and category.

Microdata uses simple attributes in HTML tags (often <span> or <div>) to assign brief and descriptive names to items and properties. Here's an example of a short HTML block showing basic contact information for Bob Smith.

<div> 
  My name is Bob Smith but people call me Smithy. Here is my home page:
  <a href="http://www.example.com">www.example.com</a>
  I live in Albuquerque, NM and work as an engineer at ACME Corp.
</div>

Here is the same HTML marked up with microdata.

<div itemscope itemtype="http://data-vocabulary.org/Person"> 
  My name is <span itemprop="name">Bob Smith</span> 
  but people call me <span itemprop="nickname">Smithy</span>. 
  Here is my home page:
  <a href="http://www.example.com" itemprop="url">www.example.com</a>
  I live in Albuquerque, NM and work as an <span itemprop="title">engineer</span>
  at <span itemprop="affiliation">ACME Corp</span>.
</div>

Here's how this sample works.

  • In the first line, itemscope indicates that the content in the <div> is an item. itemtype="http://data-vocabulary.org/Person indicates that the item is a Person.
  • Each property of the Person item is identified with the itemprop attribute. For example, itemprop="name" describes the person's name.

Nested entities

The example above shows contact information about Bob Smith, but it doesn't include his address. The example below shows the same HTML, but in this case, it includes the address property.

<div itemscope itemtype="http://data-vocabulary.org/Person">
   My name is <span itemprop="name">Bob Smith</span>, 
   but people call me <span itemprop="nickname">Smithy</span>.
   Here is my homepage: 
   <a href="http://www.example.com" itemprop="url">www.example.com</a>.
   I live in 
   <span itemprop="address" itemscope
      itemtype="http://data-vocabulary.org/Address">
      <span itemprop="locality">Albuquerque</span>, 
      <span itemprop="region">NM</span> 
   </span>
   and work as an <span itemprop="title">engineer</span>
   at <span itemprop="affiliation">ACME Corp</span>.
</div>

Here's how this sample works:

  • The address property is itself an item, containing its own set of properties. This is indicated by putting the itemscope attribute on the item that declares the address property, and using the itemtype attribute to specify the type of item being described, like this: <span itemprop="address" itemscope itemtype="http://data-vocabulary.org/Address">.

For more examples, see Nested items.

Referred items

You can define an item in one location and then refer to it from one or more other locations. The example below describes an address, and then lists two people (Bob and Jane Smith) who live at the address.

<div id="smith-address" itemprop="address" itemscope itemtype="http://data-vocabulary.org/Address">
   <span itemprop="locality">Albuquerque</span>, 
   <span itemprop="region">NM</span> 
</div>

<div itemscope itemtype="http://data-vocabulary.org/Person" itemref="smith-address">
   My name is <span itemprop="name">Bob Smith</span>, 
   but people call me <span itemprop="nickname">Smithy</span>.
   Here is my homepage: 
   <a href="http://www.example.com" itemprop="url">www.example.com</a>.
   I work as an <span itemprop="title">engineer</span>
   at <span itemprop="affiliation">ACME Corp</span>.
</div>

<div itemscope itemtype="http://data-vocabulary.org/Person" itemref="smith-address">
   My name is <span itemprop="name">Jane Smith</span>.
</div>

Here's how this sample works:

  • The HTML that defines the address item includes an id attribute, like this: <div id="smith-address" itemprop="address" itemscope itemtype="http://data-vocabulary.org/Address">.
  • The person items for Bob and Jane Smith refer to the address by including an itemref attribute and specifying the id the address, like this: <div itemscope itemtype="http://data-vocabulary.org/Person" itemref="smith-address">.

Date and time information

To specify dates and times unambiguously, use the time element with the datetime attribute. Here, the startDate property indicates the start date of an event. The value in the datetime attribute is specified using the ISO date format. Using this format lets you provide search engines with detailed date, time and—optionally—time zone in ISO format ("2009-10-15T19:00-08:00"), while still displaying the date on your page in a user-friendly way ("15 October 2009, 7PM").

<time itemprop="startDate" datetime="2009-10-15T19:00-08:00">15 October 2009, 7PM</time>

Non-visible content

In general, Google won't display content that is not visible to the user. In other words, don't show content to users in one way, and use hidden text to mark up information separately for search engines and web applications. You should mark up the text that actually appears to your users when they visit your web pages.

There are a few exceptions to this guideline. In some situations it can be valuable to provide search engines with more detailed information, even if you don't want that information to be seen by visitors to your page. For example, if a restaurant has a rating of 8.5, users (but not search engines) will assume that the rating is based on a scale of 1–10. In this case, you can indicate this using the meta element, like this:

<div itemprop="rating" itemscope itemtype="http://data-vocabulary.org/Rating">
   Rating: <span itemprop="value">8.5</span>
   <meta itemprop="best" content="10" />
</div>

Here's how this sample works:

  • The meta tag is used to specify additional information that is not visible on the page—in this case, the fact that the "best possible" rating is 10. The value of the property is specified using the content attribute.

Similarly, providing the duration of an event in ISO duration format can help ensure that it appears correctly in search results, like this:

Duration: 
<span>1 hour 30 minutes<meta itemprop="duration" content="PT1H30M" />
</span>

Here's how this sample works:

  • Use the meta tag to specify the value of the property (in this case a duration). This allows you to use the value of the content attribute ("PT1H30M") to specify the duration in ISO 8601 duration format, while still displaying the duration in user-friendly text ("1 hour 30 minutes") on the page itself.
  • Google looks at the parent element of the meta element to identify what information that is being represented in an alternate way inside the meta tag. So in this case, it is important to make sure that the immediate parent node of the meta tag wraps around the text "1 hour 30 minutes".

For specific vocabulary and examples, see:

To check your markup, use the structured data testing tool.