Structured data

A machine reads the page too

A search engine can read your headings and paragraphs, but it has to guess what they mean. Structured data removes the guess: it states the facts in a form a machine understands — this is a recipe, this is its author, this takes 40 minutes, this image is the finished loaf.

The vocabulary is called schema.org, and it is a shared dictionary of types. A search engine that finds a Recipe can show it as a recipe card; one that finds only text shows a link.

The facts, in one block

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Recipe",
  "name": "Rye loaf with caraway",
  "description": "Dense, sour and worth the third attempt.",
  "author": { "@type": "Person", "name": "Nadia" },
  "totalTime": "PT40M"
}
</script>

More than one syntax

JSON-LD is one of three ways to put schema.org facts in a page. Microdata puts the type and the properties on the visible elements themselves: itemscope marks the thing, itemtype names its type, and itemprop labels each fact. RDFa uses attributes too, with a different spelling.

The vocabulary is the same in all three; only the syntax changes. JSON-LD keeps the facts in one block and is easier to validate. Microdata keeps each fact attached to the element that shows it, so the markup and the claim are less likely to drift apart. Pick one and be consistent on a page.

Where it lives, and what it costs

The block is a <script> with type="application/ld+json", and JSON inside it — the same shape as a Python dictionary or a JavaScript object. It sits in the head or the body, it is not drawn on the page, and one page can carry several blocks: the recipe, the person who wrote it, the breadcrumb trail.

Because it is never shown, it costs nothing to a reader: no layout, no download to speak of, no effect on the page’s appearance. It is read by the machines that already visit.

A block, line by line

Read the block from the top. @context names the dictionary, so every word after it is understood in schema.org terms rather than as an invented key. @type says what kind of thing the block describes. The rest are properties of that type, and their names are the ones the vocabulary defines: name, description, author, totalTime. A duration is written in the ISO 8601 form the vocabulary expects — PT40M is forty minutes, PT1H30M is ninety — and a nested author is an object with its own @type. Every key is a string in double quotes, every value is a string, number, boolean, array or object, and the whole block is one JSON value. A missing comma or a trailing one makes the block invalid, and an invalid block is ignored in silence.

Identifiers and nesting

@type says what the thing is, and @id gives it a stable address others can refer to. A recipe can name its author as a nested Person, or point at a person declared elsewhere on the site; the nested form is simpler when the author appears once.

Only claim properties the page supports. A Recipe with an aggregateRating but no visible rating is a claim a reader cannot check, and search engines treat that as spam. Start with the name, the description and the author, then add what the page actually shows.

The rules that keep it honest

Two rules matter more than any others. Declare only what the page actually contains — structured data that promises a price, a rating or a step that a reader cannot find is a penalty waiting to happen, not a trick. And check your work: the search engines publish a Rich Results Test that reads the block the way they do and names what is missing.

Structured data does not raise a page by itself. It makes the page eligible to be shown better, which is worth having once the page is worth showing.

Try these next

• Write the same recipe twice, once as JSON-LD and once as microdata, and compare which is easier to keep true.
• Give a Person an @id and refer to it from two pages.
• Remove a fact from the visible page and check whether the structured data still makes an honest claim.