Skip to content
Tutorials Center
My learning

Topics

Lesson 54 of 122 ยท The Head, Metadata and SEO

Structured Data

Describe your pages to machines with schema.org structured data. Write JSON-LD and microdata, learn about rich results, and validate your markup.

Your HTML tells a browser that a piece of text is a heading or a paragraph. It does not say that the heading is the name of a recipe, that "40 min" is its cooking time, or that "4.7" is an average rating from 312 reviews. A person understands that at a glance; a program has to guess.

Structured data removes the guessing. You add a machine-readable description of the things on your page, using a shared vocabulary, and search engines and other tools can read it reliably. In return, search engines may show your page as a rich result: a listing with star ratings, cooking times, event dates or prices.

In this lesson you will learn the schema.org vocabulary, write structured data in the two formats that matter today (JSON-LD and microdata), and see how to check your work.

The vocabulary: schema.org

Structured data needs words everyone agrees on. The common dictionary is schema.org, a vocabulary started in 2011 by several major search engines and maintained in the open since then.

It defines types and properties:

  • A type is a kind of thing: Recipe, Event, Product, Article, Person, Organization, LocalBusiness, BreadcrumbList and hundreds more.
  • Each type has properties: a Recipe has a name, recipeIngredient, cookTime and so on.
  • Property values can be text, numbers, dates, URLs, or other typed things. An Event has a location, and that location is itself a Place with its own address.

Types are written in PascalCase (LocalBusiness) and properties in camelCase (startDate). Both are case-sensitive.

JSON-LD: data in a script element

JSON-LD (JSON for Linking Data) puts the description in a <script> element with the type application/ld+json. The browser does not run it, because it is not JavaScript; it simply keeps the text for anyone who wants to read it.

HTML
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Event",
  "name": "Riverside Jazz Night",
  "startDate": "2026-11-14T19:30:00-05:00",
  "location": {
    "@type": "Place",
    "name": "The Boathouse",
    "address": "12 Quay Street, Portland, ME"
  }
}
</script>
  • @context says which vocabulary the names come from.
  • @type names the schema.org type.
  • Every other key is a property. A nested object with its own @type describes a related thing.

JSON-LD is the format most sites use, and the one Google recommends, because it is kept separate from your visible markup: you can add or change it without touching the layout. It can go in the head or the body.

The script below reads a JSON-LD block from its own page and turns it into a mock rich result. Change the rating, add an ingredient, or break the JSON by deleting a comma and see what happens.

From JSON-LD to a rich result

When the JSON is broken, the whole block is useless: a search engine cannot pick out the valid parts. JSON is strict. Keys and strings need double quotes, there are no trailing commas, and there are no comments.

Durations, dates and other formats

Many schema.org values follow standard formats:

  • Dates and times use ISO 8601: 2026-11-14 or 2026-11-14T19:30:00-05:00. Include the time zone offset for events.
  • Durations also use ISO 8601: PT30M is 30 minutes, PT1H15M is an hour and a quarter.
  • Enumerated values are schema.org URLs, such as "availability": "https://schema.org/InStock".
  • Prices are plain numbers with a separate currency code: "price": "24.00", "priceCurrency": "USD".

Several things on one page

A page often describes more than one thing: an article, its author, the site's organization and a breadcrumb trail. You can add several JSON-LD blocks, or put the items in one block under an @graph array. Use @id to give an item an identifier other items can refer to:

HTML
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://weeknightpot.example/#org",
      "name": "Weeknight Pot",
      "url": "https://weeknightpot.example/"
    },
    {
      "@type": "BreadcrumbList",
      "itemListElement": [
        { "@type": "ListItem", "position": 1, "name": "Soups", "item": "https://weeknightpot.example/soups" },
        { "@type": "ListItem", "position": 2, "name": "Lemon Herb Lentil Soup" }
      ]
    }
  ]
}
</script>

The BreadcrumbList mirrors a visible breadcrumb trail like the ones you built in Building Navigation Menus.

Escape </script> in generated JSON. If a value contains the text </script>, the HTML parser ends the script element right there, and the rest of your JSON (or an attacker's HTML) spills into the page. When you output JSON-LD from server code, use a JSON encoder that escapes < (as <) or / (as \/).

Microdata: attributes on your visible HTML

Microdata takes a different approach. Instead of a separate block, you annotate the HTML that is already on the page with three main attributes:

  • itemscope starts a new item.
  • itemtype gives the item's type as a full URL, such as https://schema.org/Event.
  • itemprop marks an element as a property of the nearest item that contains it.

The value of a property depends on the element: most elements use their text, but <a> and <link> use href, <img> uses src, <time> uses datetime, <data> uses value, and <meta> uses content. With an itemprop attribute, <meta> and <link> are allowed in the body, so they can carry values that are not visible text.

The example marks up an event card with microdata, then runs a small extractor that rebuilds the data, just as a search engine would, and prints it as JSON.

Microdata extractor

Notice how location and offers are themselves items: an element with both itemprop and itemscope becomes a nested object. Try changing the price, or adding <span itemprop="performer">The Tidewater Trio</span> inside the article.

JSON-LD or microdata?

Both describe the same vocabulary, and search engines understand both. JSON-LD is usually easier: it lives in one place, does not tangle with your markup, and is simple to generate from a database. Microdata has one real advantage: because it annotates the visible content, the data cannot quietly drift away from what people see. A third format, RDFa, works in a similar way to microdata; you have already met its property attribute in Social Sharing Previews.

Pick one format per item and stay consistent.

Rich results

Search engines use structured data in two ways: to understand a page better, and to decide whether it is eligible for a rich result. Common examples include recipes with ratings and cooking times, events with dates and venues, products with prices and availability, breadcrumbs in place of a raw URL, and article details such as the publication date.

Keep your expectations honest:

  • Eligible is not guaranteed. Valid markup makes a page eligible for a rich result; the search engine still decides whether to show it for a given search.
  • It is not a ranking boost by itself. Structured data helps search engines understand content, and rich results can attract more clicks, but the markup alone does not move a page up.
  • Features change. Search engines add and retire rich result types over time. Google, for example, sharply limited FAQ and how-to rich results in 2023. Check the search engine's current documentation before investing in a particular type.
  • Mark up only what is visible. Structured data must describe content that is actually on the page. Invented reviews, hidden text or misleading prices violate search engine guidelines and can lead to manual actions against your site.

Required and recommended properties. Each search engine documents which properties it needs for each rich result type, for example a Product needs a name plus an offer, review or rating. schema.org itself defines far more properties than any search engine uses.

Testing your structured data

Two free tools cover most needs:

  • The Schema Markup Validator (validator.schema.org) checks your markup against the schema.org vocabulary, for any format.
  • Google's Rich Results Test shows which Google rich results a page is eligible for and lists missing required properties.

Both accept a URL or a pasted code snippet. After launch, Google Search Console reports structured data errors across your whole site. For the other things search engines read, revisit Meta Tags and Page Titles and Descriptions.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which script type marks a block of JSON-LD structured data?

    JSON-LD uses <script type="application/ld+json">. The browser does not execute it; tools read its text.
  2. 2. In microdata, which value does <time itemprop="startDate" datetime="2026-11-14">Nov 14</time> provide?

    For <time>, microdata uses the datetime attribute when it is present. The visible text is for people.
  3. 3. Your page has valid Recipe markup. What can you expect?

    Valid structured data only makes a page eligible. The search engine decides when to display a rich result, and the markup itself is not a ranking boost.
  4. 4. Which of these is acceptable in structured data?

    Structured data must describe content that is visible on the page. Hidden or misleading data breaks search engine guidelines.
  5. 5. Why do JSON-LD blocks fail completely when you leave a trailing comma?

    A single syntax error makes the entire JSON document invalid, so none of its data can be used.

Summary

  • Structured data describes the things on a page in a machine-readable way, using the schema.org vocabulary of types and properties.
  • JSON-LD puts the data in <script type="application/ld+json">; it is the most common and widely recommended format.
  • Microdata annotates visible HTML with itemscope, itemtype and itemprop; each element type supplies its value in a defined way.
  • Use ISO 8601 for dates and durations, and escape </script> when generating JSON-LD.
  • Valid markup makes a page eligible for rich results, never guarantees them, and must match visible content.
  • Check your work with the Schema Markup Validator and the Rich Results Test.

Next lesson: Loading Resources Efficiently.