JSON-LD
JSON-LD is the recommended format for adding structured data to a page. Learn how it compares to Microdata and RDFa, and why engines prefer it.
TL;DR
JSON-LD is a format for writing structured data, holding your markup in a single script block rather than scattering attributes through your HTML. It stands for JavaScript Object Notation for Linked Data. Google recommends it over the alternatives, and AI crawlers parse it reliably, which has made it the default choice for almost every new implementation.
Why JSON-LD is the preferred format
The format decision looks trivial and turns out to matter, because it determines who can maintain the markup and how often it breaks.
- Separation: Markup sits in its own script tag, so changing page layout does not disturb it and vice versa.
- Maintainability: One block of readable data beats attributes spread across dozens of HTML elements.
- Injectability: Tag managers and templates can output it without touching the page structure.
- Engine support: Google names it as the recommended format, and every major AI crawler reads it.
How to implement JSON-LD
Create the script block
A script tag with type set to application/ld+json, placed in the head or body. Position does not affect parsing.
Declare context and type
Every block opens by pointing at schema.org as the vocabulary and naming the primary type of the page.
Fill the required properties
Each type expects certain fields. Supply those first, then optional ones that add genuine detail.
Nest rather than duplicate
An author inside an Article, an offer inside a Product. Nesting expresses relationships that separate blocks cannot.
Generate it from real data
Populate the block from the same source that renders the page, so the two cannot drift apart when content changes.
Validate the output, not the template
Test the rendered page, since template variables sometimes produce empty or malformed values that only appear at runtime.
JSON-LD vs. Microdata and RDFa
JSON-LD: A separate script block. Easy to read, easy to inject, and unaffected by layout changes. The current recommendation.
Microdata: Attributes added directly to HTML elements. Ties markup to markup, so a template refactor can silently break it.
RDFa: Similar attribute-based approach with roots in the semantic web. Still parsed, rarely chosen for new work.
All three are understood by engines. The practical case for JSON-LD is maintenance rather than capability: markup that lives apart from presentation survives redesigns.
Format choice is the easy part. Whether engines fetch the page, parse the block and then actually cite you is the question that matters. Findrix checks structured data alongside crawler access and rendering, then tracks citations across seven AI engines weekly. Every gap comes with the fix already written: technical, content and off-site. The audit is free, takes about a minute, and requires no signup.
What to watch when using JSON-LD
- Rendering dependency: If JSON-LD is injected by client-side JavaScript, crawlers that do not execute scripts will never see it.
- Content mismatch: The block must describe what is visibly on the page, or it becomes a guidelines violation.
- Duplicate blocks: Multiple conflicting blocks on one page force engines to choose, usually badly.
- Stale values: Hardcoded prices and dates in markup age faster than anyone expects.
- Empty properties: Template variables that resolve to nothing produce invalid markup that validators catch and humans do not.
Why the format matters less than the facts
JSON-LD is a container. Engines care about what is inside it, and the most common failure in structured data has nothing to do with syntax: the markup is valid, well-formed, correctly nested, and describes claims too vague to be worth quoting.
There is also a rendering trap specific to this format. Because JSON-LD sits in a script tag, teams frequently inject it client-side through a tag manager, which works perfectly for Googlebot and fails completely for AI crawlers that do not run JavaScript.
Check that your markup appears in the raw HTML response rather than only in the rendered DOM. That single test catches more real problems than any validator.
Frequently asked questions
Is JSON-LD better than Microdata?
For maintenance, clearly. Engines parse both, so capability is not the differentiator. JSON-LD keeps markup separate from presentation, which means redesigns and template changes are far less likely to break it.
Where should JSON-LD go on the page?
Either the head or the body works, and engines do not treat one as better. What matters is that it appears in the server response rather than being added later by client-side JavaScript.
Can one page have multiple JSON-LD blocks?
Yes, and it is normal to have Organization, BreadcrumbList and a page-specific type together. The problem is contradictory blocks describing the same thing differently, which forces engines to pick between them.