How Yandex indexes sites
A site on search results page

Introduction to Schema.org


This document is a copy of the original manual at http://schema.org/docs/gs.html with some small additions.

Most webmasters are familiar with HTML tags. Usually HTML tags tell the browser how to display the information included in the tag. For example, <h1>Avatar</h1> tells the browser to display the text string “Avatar” in a heading 1 format. However, the HTML tag doesn't give any information about what that string means: “Avatar” could refer to the hugely successful 3D movie, or it could refer to a type of profile picture. That makes it more difficult for search engines to intelligently display relevant content to a user.

Schema.org provides a collection of shared vocabularies webmasters can use to mark their pages in ways that can be understood by the major search engines: Yandex, Google, Microsoft, and Yahoo.

You use the schema.org vocabulary along with microdata. Although the long-term goal is to broaden the list of supported semantic markup formats, microdata is the first to be used. This guide will help get you up to speed with microdata and schema.org so that you can start adding markups to your web pages.

How to mark your content using microdata

Why use microdata?

Your web pages have an underlying meaning that people understand when they read them, though search engines have a limited understanding of what is being discussed. By adding additional tags to the HTML of your web pages, you are saying: “Hey, search engine, this information describes this specific movie (or place, person, video)”. That way you can help search engines and other applications better understand your content and display it in a useful, relevant way. Microdata is a set of tags introduced with HTML5 that allows you to do this.

itemscope and itemtype

Let's start with a concrete example. Imagine you have a page about the movie “Avatar” — a page with a link to a movie trailer, information about the director, and so on. Your HTML code might look something like this:

<div> <h1>Avatar</h1> <span>Director: James Cameron (born August 16, 1954)</span> <span>Sci-Fi</span> <a href="../movies/avatar-theatrical-trailer.html">Trailer</a> </div>

To begin, identify the section of the page that is about the movie “Avatar”. To do this, add the itemscope element to the HTML tag that encloses that information:

<div itemscope> <h1>Avatar</h1> <span>Director: James Cameron (born August 16, 1954) </span> <span>Sci-Fi</span> <a href="../movies/avatar-theatrical-trailer.html">Trailer</a> </div>

By adding itemscope, you are specifying that the HTML contained in the <div>...</div> block is about a particular item.

So far we have only specified that there is an item being discussed, though we haven't specified what kind of item it is. You can specify the type of item using the itemtype attribute immediately after the itemscope.

<div itemscope itemtype="http://schema.org/Movie"> <h1>Avatar</h1> <span>Director: James Cameron (born August 16, 1954)</span> <span>Sci-Fi</span> <a href="../movies/avatar-theatrical-trailer.html">Trailer</a> </div>

This specifies that the item contained in the <div> is in fact a movie (as described in the schema.org type hierarchy). Item types are provided as URLs, in this case http://schema.org/Movie.


What additional information can we give search engines about the movie “Avatar”? Movies have interesting properties such as actors, director, and ratings. To label properties of an item, use the itemprop attribute. For example, to identify the director of a movie, add itemprop="director" to the element enclosing the director's name. (There's a full list of all the properties you can associate with a movie at http://schema.org/Movie.)

<div itemscope itemtype="http://schema.org/Movie"> <h1 itemprop="name">Avatar</h1> <span>Director: <span itemprop="director">James Cameron</span> (born August 16, 1954)</span> <span itemprop="genre">Sci-Fi</span> <a href="../movies/avatar-theatrical-trailer.html"  itemprop="trailer">Trailer</a> </div>

Note that we have added additional <span>...</span> tags to attach the itemprop attributes to the appropriate text on the page. The <span> tags don't change the way pages are rendered by a web browser, so they are a convenient HTML element to use with itemprop.

Search engines can now understand not just that http://www.avatarmovie.com is a URL, but also that it's the URL for the trailer for the science fiction movie “Avatar”, which was directed by James Cameron.

Embedded items

Sometimes the value of an item property can itself be another item with its own set of properties. For example, we can specify that the director of the movie is an item of type Person with the properties name and birthDate. To specify that the value of a property is another item, you begin a new itemscope immediately after the corresponding itemprop.

 <div itemscope itemtype="http://schema.org/Movie"> <h1 itemprop="name">Avatar</h1> <div itemprop="director" itemscope itemtype="http://schema.org/Person"> Director: <span itemprop="name">James Cameron</span> (born <span itemprop="birthDate">August 16, 1954</span>) </div> <span itemprop="genre">Sci-Fi</span> <a href="../movies/avatar-theatrical-trailer.html" itemprop="trailer">Trailer</a> </div>

Using the Schema.org vocabulary

Schema.org types and properties

In addition to the Movie and Person types laid out in section How to mark your content using microdata, schema.org describes a variety of other item types, each of which has its own set of properties.

The broadest item type is Thing, which has four properties: name, description, url, and image. More specific types share properties with broader types. For example, a Place is a more specific type of Thing, and a LocalBusiness is a more specific type of Place. More specific items inherit the properties of their parents. (Actually, a LocalBusiness is a more specific type of Place and a more specific type of Organization, so it inherits properties from both parent types.)

Here's a set of commonly used item types:

You can also see a full list of all item types on a single page.

Expected types, text and URLs

Here are a few recommendations to keep in mind when adding schema.org markups to your web pages:

  • More is better, except for hidden text. The more content you mark, the better. However, as a general rule, you should mark only the content that is visible to people who visit the web page and not content in hidden <div> tags or other hidden page elements.

  • Expected types or text. When browsing the schema.org types, you will notice that many properties have so-called "expected types". This means that the value of the property can itself be an embedded item (see section Embedded items). But this is not a requirement - it's fine to include just regular text or a URL.

    In addition, a child type can be used instead of an expected type. For example, if the expected type is Place, it's also okay to embed a LocalBusiness.

  • Using the url property. Some web pages are about a specific item. For example, you may have a web page about a single person, which you could mark using the Person item type. Others have a collection of items. For example, your company website could have a page listing employees, with a link to a profile page for each person. For pages like this with a collection of items, you should mark each item separately (in this case a series of Persons) and add the url property to the link to the corresponding page for each item, like this:

    <div itemscope itemtype="http://schema.org/Person"> <a href="alice.html" itemprop="url">Alice Jones</a> </div> <div itemscope itemtype="http://schema.org/Person"> <a href="bob.html" itemprop="url">Bob Smith</a> </div>

Testing your markups

Much like a web browser is important for testing changes to your web page layout and a code compiler is important for testing code you wrote, you should also test your schema.org markups. There are several tools online you can use to test your markups and identify any errors: from Yandex, Rich Snippets Testing Tool from Google, Structured Data Linter.

Advanced topic: machine-understandable versions of information

Many pages can be described using only the itemscope, itemtype, and itemprop attributes (described in section How to mark your content using microdata) along with the types and properties defined on schema.org (described in section Using the Schema.org vocabulary).

However, sometimes it is difficult for the robot to understand an item property without additional disambiguation. This section describes how you can provide machine-understandable versions of information when marking up your pages.

Dates, times, and durations: use the <time> tag with datetime attribute

Dates and times can be difficult for robots to understand. Consider the date “04/01/11” - is it January 11, 2004, January 4, 2011, or April 1, 2011? To make a date unambiguous, use the <time> tag along with the datetime attribute. The value of the datetime attribute is the date specified using the YYYY-MM-DD format. The HTML code below specifies the date unambiguously as April 1, 2011:

<time datetime="2011-04-01">04/01/11</time>

You can also specify a time within a day using the hh:mm or hh:mm:ss format along with the T prefix. Times can be specified along with dates:

<time datetime="2011-05-08T19:30">May 8, 19:30</time>

Let's see this in context: Here is some HTML describing a concert taking place on May 8, 2011. The Event markup includes the name of the event, a description, and the date of the event.

 <div itemscope itemtype="http://schema.org/Event"> <div itemprop="name">Spinal Tap</div> <span itemprop="description">One of the biggest musical acts of all time is reuniting for an unforgettable two-day show.</span> The concert is scheduled for <time itemprop="startDate" datetime="2011-05-08T19:30">May 8 at 19:30</time> </div> 

Durations can be specified in an analogous way using the<time> tag with the datetime attribute. Durations are prefixed with the letter P (stands for "period"). Here's how you can specify a recipe cooking time of 1.5 hours:

<time itemprop="cookTime" datetime="PT1H30M">1.5 hours</time>

H is used to designate the number of hours, and M is used to designate the number of minutes.

The date, time, and duration standards are specified by the ISO 8601 date/time standard.

Enumerations and canonical references: use the link tag with the href attribute

  • Enumerations

    Some properties can take only a limited set of possible values. Programmers often call these "enumerations". For example, an online store could use the Offer item type to specify the details of a product offer. The availability property can typically have one of only a few possible values: In stock, Out of stock, Pre-order, and so on. Much like item types are specified as URLs, possible values for an enumeration on schema.org can also be specified as URLs.

    Here is an item for sale marked with the Offer type and relevant properties:

    <div itemscope itemtype="http://schema.org/Offer"> <span itemprop="name">Blend-O-Matic</span> <span itemprop="price">$19.95</span> <span itemprop="availability">Now available!</span> </div> 

    And here is the same item, but using <link> and href to unambiguously specify the availability as one of the permitted values:

    <div itemscope itemtype="http://schema.org/Offer"> <span itemprop="name">Blend-O-Matic</span> <span itemprop="price">$19.95</span> <link itemprop="availability" href="http://schema.org/InStock"/>Now available! </div>

    Schema.org provides enumerations for a handful of properties, typically whenever there are a limited number of typical values for a property. In this case, the possible values for availability are specified in ItemAvailability.

  • Canonical references

    Typically, links are specified using the <a> element. For example, the following HTML links to the Wikipedia page for the book “Catcher in the Rye”:

     <div itemscope itemtype="http://schema.org/Book"> <span itemprop="name">Catcher in the Rye</span> Author <span itemprop="author">J.D. Salinger</a> <a itemprop="url" href="http://en.wikipedia.org/wiki/The_Catcher_in_the_Rye">Wikipedia page</a> </div> 

    As you can see, itemprop="url" can be used to specify a link to a page on another website (in this case Wikipedia) discussing the same item. Links to third party websites can help search engines better understand the item you are describing on your web page.

    If you do not want to add a visible link on your page, use the <link> element instead, as follows:

     <div itemscope itemtype="http://schema.org/Book"> <span itemprop="name">Catcher in the Rye</span> <link itemprop="url" href="http://en.wikipedia.org/wiki/The_Catcher_in_the_Rye" /> Author <span itemprop="author">J.D. Salinger</span> </div> 

Missing/implicit information: use the <meta> tag with content attribute

Sometimes important information can't be marked because of the way it appears on the page. The information may be conveyed in an image (for example, an image used to represent a rating of 4 out of 5) or a Flash object (for example, the duration of a video clip), or it may be implied but not stated explicitly on the page (for example, the currency of a price).

In these cases, use the <meta> tag along with the content attribute. The next example is an image that shows users a 4 out of 5 rating:

<div itemscope itemtype="http://schema.org/Offer"> <span itemprop="name">Blend-O-Matic</span> <span itemprop="price">$19.95</span> <img src="four-stars.jpg" /> 25 ratings </div> 

Here is the example again with the rating information marked.

<div itemscope itemtype="http://schema.org/Offer"> <span itemprop="name">Blend-O-Matic</span> <span itemprop="price">$19.95</span> <div itemprop="reviews" itemscope itemtype="http://schema.org/AggregateRating"> <img src="four-stars.jpg" /><meta itemprop="ratingValue" content="4" /><meta itemprop="bestRating" content="5" /> <span itemprop="ratingCount">25</span> ratings </div> </div>

This technique should be used sparingly. Only use <meta> with content for information that cannot otherwise be marked.

Extending schema.org

Most websites and organizations will not have a reason to extend schema.org. However, schema.org offers the ability to specify additional properties or sub-types to existing types. If you are interested in doing this, read more about the schema.org extension mechanism.


Source: http://schema.org/docs/gs.html

© Google, Inc., Yahoo, Inc., Microsoft Corporation. 2011.

Text available via Creative Commons Attribution-ShareAlike License (version 3.0).

Rate this article
Thank you for your feedback!