What Is JSON-LD? – Definition and How It Works
Learn what JSON-LD is, how the context maps terms to vocabularies, why search engines read it, and why it is valuable for data extraction.
JSON-LD is JSON with a linking context: ordinary JSON whose keys are mapped to shared vocabulary terms, so the same field name means the same thing across sites and systems.
1. The Idea
Plain JSON is unambiguous to machines syntactically and ambiguous semantically. One site's name and another's title may mean the same thing, and nothing in either document says so.
JSON-LD adds a @context that maps keys onto a shared vocabulary, giving them agreed meaning.
{
"@context": "https://schema.org",
"@type": "Product",
"name": "Widget",
"offers": { "@type": "Offer", "price": "49.90", "priceCurrency": "USD" }
}
2. The Key Constructs
| Keyword | Purpose |
|---|---|
@context |
Maps terms to vocabulary definitions |
@type |
Declares what kind of thing this is |
@id |
A stable identifier for the entity |
@graph |
Several entities in one document |
3. Why It Appears on Web Pages
Search engines read structured data to understand pages, and JSON-LD is the format they recommend. Sites embed it in a script tag to describe products, articles, organisations, events, reviews, and breadcrumbs.
<script type="application/ld+json"> { ... } </script>
Because it drives search features, publishers keep it accurate — which is exactly why it is useful to anyone else reading the page.
4. Why It Is Valuable for Extraction
A page's JSON-LD block often carries the same fields a scraper would otherwise extract from rendered markup: name, price, availability, rating, review count, publication date.
Reading it is more reliable than parsing layout, because it is a data contract maintained for search engines rather than incidental markup that changes with every redesign.
5. How to Extract It
Find every application/ld+json script, parse each as JSON, and handle three shapes: a single object, an array of objects, or a @graph containing several.
Then filter by @type for the entity you want. Pages frequently carry several blocks — organisation, breadcrumb, and product all at once.
6. Caveats
- It can be wrong. Structured data sometimes disagrees with the visible page.
- It can be partial, describing only some of what is displayed.
- Types vary in how completely they are filled.
- Invalid JSON happens, especially with unescaped characters in descriptions.
- It may be injected by scripts, so a plain fetch might not contain it.
Validate what you extract rather than trusting it, and compare against the rendered value when accuracy matters.
7. Publishing It
Describe what is genuinely on the page, keep it synchronised with the visible content, use the vocabulary's documented types, and validate with a structured-data testing tool.
Structured data that contradicts the page is a policy violation, not an optimisation.
8. Summary
JSON-LD is JSON with a context that maps keys to a shared vocabulary, embedded in pages to describe entities for search engines.
For extraction it is often the cleanest available source on a page — a maintained data contract rather than incidental markup — provided it is validated rather than trusted, and provided the fetch actually contains it.