Getting Started - schema.org

http://schema.org/docs/gs.html Archived on 2026-04-24 23:55 UTC

Getting started with schema.org using Microdata
Most webmasters are familiar with HTML tags on their pages. Usually, HTML tags tell the browser how to display the information included in the tag. For example,

Avatar

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 text string means—"Avatar" could refer to the hugely successful 3D movie, or it could refer to a type of profile picture—and this can make 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 up their pages in ways that can be understood by the major search engines: Google, Microsoft, Yandex and Yahoo!
You use the
schema.org
vocabulary along with the
Microdata
RDFa
, or
JSON-LD
formats to add information to your Web content.
This guide will help get you up to speed with Microdata and schema.org so that you can start adding markup to your web pages.
Although this guide focuses on
Microdata
most examples on the
schema.org
site show examples in RDFa and JSON-LD too.
The basic ideas (types, properties etc.) introduced here are relevant beyond Microdata - take a look at the
examples to see how the details compare.
How to mark up your content using microdata
Why use microdata?
itemscope and itemtype
itemprop
Embedded items
Using the schema.org vocabulary
schema.org types and properties
Expected types, text, and URLs
Testing your markup
Advanced topic: Machine-understandable versions of information
Dates, times, and durations
Enumerations and canonical references
Missing/implicit information
Extending schema.org
1. How to mark up your content using microdata
1a. Why use microdata?
Your web pages have an underlying meaning that people understand when they read the web pages. But search engines have a limited understanding of what is being discussed on those pages. By adding additional tags to the HTML of your web pages—tags that say, "Hey search engine, this information describes this specific movie, or place, or person, or video"—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.
1b. 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:

Avatar

Director: James Cameron (born August 16, 1954)
Science fiction
Trailer

To begin, identify the section of the page that is "about" the movie Avatar. To do this, add the
itemscope
attribute to the HTML tag that encloses information about the item, like this:
itemscope

Avatar

Director: James Cameron (born August 16, 1954)
Science fiction
Trailer

By adding
itemscope
, you are specifying that the HTML contained in the

...

block is about a particular item.
But it's not all that helpful to specify that there is an item being discussed without specifying what kind of an item it is. You can specify the type of item using the
itemtype
attribute immediately after the
itemscope

itemtype="https://schema.org/Movie"

Avatar

Director: James Cameron (born August 16, 1954)
Science fiction
Trailer

This specifies that the item contained in the div is in fact a Movie, as defined in the schema.org type hierarchy. Item types are provided as URLs, in this case
1c. itemprop
What additional information can we give search engines about the movie Avatar? Movies have interesting properties such as actors, director, 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 https://schema.org/Movie.)

itemprop="name"
>Avatar
Director: itemprop="director"
>James Cameron (born August 16, 1954)
itemprop="genre"
>Science fiction
itemprop="trailer"
>Trailer

Note that we have added additional
...
tags to attach the
itemprop
attributes to the appropriate text on the page.

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.
1d. 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 and the Person has 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

Avatar

itemprop="director" itemscope itemtype="https://schema.org/Person"
Director: James Cameron (born itemprop="birthDate"
>August 16, 1954)

Science fiction
Trailer

2. Using the schema.org vocabulary
2a. schema.org types and properties
Not all web pages are about movies and people—in addition to the Movie and Person types described in section 1, schema.org describes a variety of other item types, each of which has its own set of properties that can be used to describe the item.
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 parent. (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:
Creative works:
CreativeWork
Book
Movie
MusicRecording
Recipe
TVSeries
...
Embedded non-text objects:
AudioObject
ImageObject
VideoObject
Event
Organization
Person
Place
LocalBusiness
Restaurant
...
Product
Offer
AggregateOffer
Review
AggregateRating
You can also see a
full list of all item types
, listed on a single page.
2b. Expected types, text, and URLs
Here are a few notes to keep in mind when adding schema.org markup to your web pages.
2c. Testing your markup
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 write, you should also test your schema.org markup to make sure it is implemented correctly. Google provides a rich snippets testing tool, which you can use to test your markup and identify any errors.
3. Advanced topic: Machine-understandable versions of information
Many pages can be described using only the
itemscope
itemtype
, and
itemprop
attributes (described in section 1) along with the types and properties defined on schema.org (described in section 2).
However, sometimes an item property is difficult for a machine to understand 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
Enumerations and canonical references: use the
link
tag with
href
Missing/implicit information: use the
meta
tag with
content
3a. Dates, times, and durations: use the time tag with datetime
Dates and times can be difficult for machines to understand. Consider the date "04/01/11". Does it mean January 11, 2004? January 4, 2011? Or April 1, 2011? To make dates unambiguous, use the
time
tag along with the
datetime
attribute. The value of the
datetime
attribute is the date specified using
YYYY-MM-DD
format. The HTML code below specifies the date unambiguously as April 1, 2011.

04/01/11

You can also specify a time within a day, using the
hh:mm
or
hh:mm:ss
format. Times are prefixed with the letter
and can be provided along with a date, like this:

May 8, 7:30pm

Let's see this in context. Here's 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.
itemscope itemtype="https://schema.org/Event"
itemprop="name"
>Spinal Tap
itemprop="description"
>One of the loudest bands ever
reunites for an unforgettable two-day show.
Event date:

May 8, 7:30pm

Durations can be specified in an analogous way using the
time
tag with the
datetime
attribute. Durations are prefixed with the letter
(stands for "period"). Here's how you can specify a recipe cook time of 1 ½ hours:
itemprop="cookTime"
datetime="PT1H30M"
>1 1/2 hrs

is used to designate the number of hours, and
is used to designate the number of minutes.
The date, time, and duration standards are specified by the
ISO 8601 date/time standard
3b. Enumerations and canonical references: use link with href
Enumerations
Some properties can take only a limited set of possible values. Programmers often call these "enumerations." For example, an online store with an item for sale could use the
Offer
item type to specify the details of the 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 up with the Offer type and relevant properties:

Blend-O-Matic
$19.95
Available today!

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

Blend-O-Matic
$19.95

Available today!

Schema.org provides enumerations for a handful of properties—typically wherever there are a limited number of typical values for a property, there is a corresponding enumeration specified in schema.org. In this case, the possible values for
availability
are specified in
ItemAvailability
Canonical references
Typically, links are specified using the

element. For example, the following HTML links to the Wikipedia page for the book Catcher in the Rye.

The Catcher in the Rye—
by J.D. Salinger
Here is the book's itemprop="url"
href="http://en.wikipedia.org/wiki/The_Catcher_in_the_Rye">Wikipedia page.

As you can see,
itemprop="url"
can be used to specify a link to a page on another site (in this case Wikipedia) discussing the same item. Links to 3rd party sites can help search engines to better understand the item you are describing on your web page.
However, you might not want to add a visible link on your page. In this case, you can use a
link
element instead, as follows:

The Catcher in the Rye—

by J.D. Salinger

3c. Missing/implicit information: use the meta tag with content
Sometimes, a web page has information that would be valuable to mark up, but the information can't be marked up 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 to specify the information. Consider this example—the image shows users a 4 out of 5 star rating:

Blend-O-Matic
$19.95

Based on 25 user ratings

Here is the example again with the rating information marked up.

Blend-O-Matic
$19.95
itemprop="reviews" itemscope itemtype="https://schema.org/AggregateRating"

Based on itemprop="ratingCount"
>25 user ratings

This technique should be used sparingly. Only use
meta
with content for information that cannot otherwise be marked up.
3d. Extending schema.org
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

Same domain → Similar titles →