Websites and Tech

JSON-LD

Also called JSON for Linked Data, structured data script

The script format Google prefers for structured data, placed in a page's code separately from the visible content.

Quick facts: JSON-LD

Category
Websites and Tech
Also called
JSON for Linked Data, structured data script
Level
Advanced
Affects
Rich result eligibility, how clearly machines read a page, click-through rate
Where to see it
Rich Results Test, Schema Markup Validator, Google Search Console, browser view source
In this article4
  1. How JSON-LD works
  2. Why JSON-LD matters
  3. Common mistakes with JSON-LD
  4. How to act on it

How JSON-LD works

Search engines read your page as text and infer what it is about. Structured data removes the inference by stating it outright: this is a local business, this is its address, this is an article, this is its author. JSON-LD is the way that statement is written — a self-contained block of script placed in the page’s code, marked as linked data, and completely separate from the words a visitor sees.

Inside the block, each thing you describe is an object with a type and a set of properties, and objects can refer to each other. A vocabulary, almost always schema.org, supplies the type names so that everyone means the same thing by “opening hours” or “author”. Because the block is independent of the layout, redesigning a page does not disturb it — which is the practical reason Google states a preference for JSON-LD over the older approaches that wrap attributes around visible HTML.

Why JSON-LD matters

It is how you become eligible for the richer results that appear beyond a plain blue link: review stars where genuine reviews exist, event dates, product availability, frequently asked questions, breadcrumbs, business details in a knowledge panel. Eligibility is not a guarantee — search engines decide when to show these — but without the markup the question never arises.

It has become more useful, not less, as answer engines and assistants have grown. A clearly described entity is easier for any machine to read confidently, whether it is building a search result or summarising a page, which is why structured data keeps appearing in conversations about AI-generated answers.

Common mistakes with JSON-LD

The serious one is describing something the page does not show. Marking up review ratings you did not collect, prices that are not listed, or an FAQ that no visitor can read is against Google’s guidelines and risks a manual penalty against the site. The markup is meant to describe the page, not to improve on it.

Then there are the quiet technical failures. A block copied from a generator and left with its example values still in place. Two competing descriptions of the same entity, one from a plugin and one from the theme, each contradicting the other. Markup injected by JavaScript that the crawler never executes, so a validation tool run in your browser passes while the search engine sees nothing. And a single missing bracket or a straight quote replaced by a curly one, which invalidates the entire block rather than one line of it.

How to act on it

Start with the types that genuinely describe your pages — the organisation, the local business, articles, services, products, breadcrumbs — and resist adding more for its own sake. Generate the values from the same source as the visible content wherever you can, so the two cannot drift apart when a price or an address changes.

Validate every template once with Google’s Rich Results Test and the Schema Markup Validator, then check the rendered page source rather than your draft, because plugins and tag managers both add markup of their own. Watch the enhancement reports in Search Console after launch, since that is where errors surface at scale. If several plugins are competing, turn all but one off; a single accurate description beats three arguing ones. Where the markup itself is the project, treat it as ongoing schema markup work that is reviewed whenever templates change.

Do and do not

Do

  • Describe only what the page actually shows
  • Generate values from the same source as visible content
  • Validate the rendered page, not your draft

Do not

  • Leave a generator's example values in place
  • Let a plugin and a theme both describe one entity
  • Mark up ratings or prices visitors cannot see

Questions people ask about this

Does JSON-LD improve my rankings?

Not directly. It is not a ranking factor in the way content and links are. What it does is make a page eligible for richer search features and easier for machines to interpret confidently, and those features can raise how often people click a result that already ranks. Treat it as clarity and eligibility rather than as a lever on position.

Where should the JSON-LD script go on the page?

Either in the head or in the body works; search engines accept both. What matters far more is that the block appears in the page as it is finally rendered, that it is valid, and that only one description of each entity exists. If a plugin, a theme and a tag manager all add markup, conflicting statements are the likely result.

Can I mark up reviews I have received privately?

Only if those reviews are shown on the page itself and were genuinely left by customers. Review markup is meant to describe visible content, and using it for ratings a visitor cannot see breaches Google's guidelines. Sites doing it risk losing rich results and, in serious cases, a manual action. Publish the reviews first, then describe them.

Related terms

Found this useful?

Share it, or ask an AI to summarise it

Back to the glossary

Knowing the term is the easy part

Applying it to your own site and budget is the work. Book a call and I will tell you what actually applies to you.