Structured data

schema.org is the vocabulary: the set of types and properties — `Article`, `Product`, `Organization`, `FAQPage` — and what each means.

JSON-LD, Microdata and RDFa are three syntaxes for expressing that vocabulary. JSON-LD is a script block in the head or body; the other two annotate the HTML in place.

Google's own documentation states a preference for JSON-LD, chiefly because it is a separate block that can be generated and validated without touching the markup around the content.

The vocabulary is far larger than what any search engine consumes. Most of it is understood by nothing in particular, which is not an argument against using it but is worth knowing.

Rich results: review stars, product prices and availability, event dates, recipe details, breadcrumb trails in place of URLs. Each has its own documented required and recommended properties.

Entity understanding: connecting a site to an organisation, a person or a place that a search engine already knows about.

Consumption by anything else that reads pages — aggregators, assistants, summarisers — for which a stated fact is far more reliable than an inferred one.

Eligibility is not entitlement. Correct markup makes a rich result possible; the search engine still decides whether to show one.

Structured data must describe what is actually on the page. Marking up a price the page does not show, or reviews that do not exist, is a policy violation rather than an optimisation.

Google's structured data guidelines state this explicitly, and the consequence of ignoring it is a manual action removing rich result eligibility for the site.

The common accidental version is a template that emits an aggregate rating on every page including ones with no reviews, usually with a hard-coded value.

Markup that becomes stale — an event date in the past, a price that changed — is the same problem arriving slowly.

`curl -s https://example.com/page | grep -A5 'application/ld+json'` shows the JSON-LD blocks in the served HTML.

Google's Rich Results Test reports which rich result types a page is eligible for and which required properties are missing.

The Schema Markup Validator checks the markup against the vocabulary itself, independently of any search engine's requirements.

Check the rendered page as well as the source when the markup is injected by JavaScript, and check that the values match what the page displays.