Introduction to Schema.org
This document is a translation of the original manual at http://schema.org/docs/gs.html with 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, the
<h1>Avatar</h1> tag means that the “Avatar” string should be displayed in the format of the first level header. 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 profile picture. That makes it more difficult for search engines to intelligently display relevant content to a user.
Schema.org provides a shared vocabulary webmasters can use to mark their pages and make them understandable for the major search engines: Yandex, Google and Yahoo!.
The schema.org vocabulary is used 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 special tags to the HTML code of your pages, you say, “Hey, search engine, here is a description of a movie (place, person, video clip)”. 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 “Avatar” movie, with link to a movie trailer, information about the director, and so on.
<div> <h1>Avatar</h1> <span>Director: James Cameron (b. August 16, 1954)</span> <span>Science fiction</span> <a href="../movies/avatar-theatrical-trailer.html">Trailer</a> </div>
First, you need to specify which part of the page describes the “Avatar” movie. To do this, add the
itemscope attribute to the HTML tag that contains this information:
<div itemscope> <h1>Avatar</h1> <span>Director: James Cameron (b. August 16, 1954)</span> <span>Science fiction</span> <a href="../movies/avatar-theatrical-trailer.html">Trailer</a> </div>
itemscope we indicate that the HTML code contained in the
<div>...</div> block describes some entity.
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
<div itemscope itemtype="http://schema.org/Movie"> <h1>Avatar</h1> <span>Director: James Cameron (b. August 16, 1954)</span> <span>Science fiction</span> <a href="../movies/avatar-theatrical-trailer.html">Trailer</a> </div>
This indicates that the entity in the
<div> tag is a movie (the "Movie" type in the schema.org type hierarchy). Item types are provided as URLs, in this case
What kind of extra information about “Avatar” can you provide to the search engines? Movies have interesting properties such as actors, director, and ratings. To label the item properties, use the
itemprop attribute. For example, to specify the movie director, add the
itemprop="director" attribute to the HTML tag that contains the director's name. (The full list of movie properties you can mark is available 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> (b. August 16, 1954)</span> <span itemprop="genre">Science fiction</span> <a href="../movies/avatar-theatrical-trailer.html" itemprop="trailer">Trailer</a> </div>
Note that we added the
<span>...</span> tag to link the
itemprop attribute to the corresponding text on the page. The
<span> tag doesn't affect the page display in the browser, so it is easy to use with
Now search engines not only understand that http://www.avatarmovie.com is a URL, but also that it is the URL of the trailer of the “Avatar” science fiction movie directed by James Cameron.
Sometimes the value of an item property can itself be another item with its own set of properties. For example, you can mark the movie director as an item of the Person type with properties
birthDate. To specify an item as the value of a property, add the
itemscope attribute after
<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> (род. <span itemprop="birthDate">August 16, 1954</span>) </div> <span itemprop="genre">Science fiction</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 mentioned in the How to mark your content using microdata section, schema.org describes a variety of other item types, each of them has its own set of properties.
The broadest item type is Thing, which has four properties:
image. More specific types share properties with broader types. For example, Place is a more specific type of Thing, and 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:
See also the full list of 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 visible to the users, not the content of the 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 the Embedded items section). 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.
urlproperty. 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 site 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
urlproperty 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: Semantic markup validator from Yandex, Rich Snippets Testing Tool from Google, Structured Data Linter.
Advanced topic: machine-understandable versions of information
Many pages can be marked up using only the
itemprop attributes (described in the How to mark your content using microdata), along with the schema.org types and properties (described in the Using the Schema.org vocabulary section).
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 duration: use the
<time> tag with the
Dates and times can be difficult for robots to understand. For example, is “04/01/11” January 11, 2004, January 4, 2011, or April 1, 2011? To make a date unambiguous, use the
datetime tag with the
datetime attribute. The value of the
datetime attribute is the date in the
YYYY-MM-DD format. The HTML code below specifies the date unambiguously as April 1, 2011:
Time of day is set in the
hh:mm:ss format, with the
T prefix. Time can be specified next to the date:
<time datetime="2011-05-08T19:30">May 8, 19:30</time>
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 loudest music groups of all times will reunite for an unforgettable two-day show.</span> The concert will take place on <time itemprop="startDate" datetime="2011-05-08T19:30">May 8 at 19:30</time> </div>
You can specify duration in a similar way, using the
<time> tag with the
datetime attribute. Duration is 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 ½ 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
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
availabilityproperty can typically have one of only a few possible values:
Out of stock,
Pre-order, and so on. Possible values for an enumeration on can be specified in the URL, similar to the schema.org entity types.
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">Already on sale!</span> </div>
And here is the same offer marked up with
href, which allows to unambiguously specify one of the possible
<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"/>Available now! </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
availabilityare listed in ItemAvailability.
Links are usually created with the
<a>tag. For example, the following link to the Wikipedia page about the book “The Catcher in the Rye”:
<div itemscope itemtype="http://schema.org/Book"> <span itemprop="name">Catcher in the rye</span> Author <span itemprop="author">Jerome Salinger</span> <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 site (in this case Wikipedia) describing the same item. Links to third party sites can help search engines better understand the item you are describing on your web page.
If you don't want to add a link that is visible to users, use the
<link>tag as shown below:
<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">Jerome Salinger</span> </div>
Missing or implicit information: use the
<meta> tag with the
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, you can use the
<meta> tag with the
content attribute. In the following example the image shows 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. Use the
<meta> tag with the
content attribute only for information that can't be marked up in any other way.
Most sites 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.
© Google, Inc., Yahoo, Inc., Microsoft Corporation. 2011.
Text available via Creative Commons Attribution-ShareAlike License (version 3.0).