JSON-LD, short for JavaScript Object Notation for Linked Data, is a W3C standard format for expressing linked data in JSON, and in SEO it is the preferred way to add structured data to a web page. It places a machine-readable description of the page’s entities, such as an article, a product, an organization or a breadcrumb trail, inside a dedicated script element that is separate from the visible HTML.
Search engines read JSON-LD to understand what a page is about and how its entities relate, to qualify pages for rich results, and to feed knowledge graphs. Google, Bing and other engines accept several structured data formats, but JSON-LD is the format Google recommends, mainly because it is easier to generate, validate and maintain.
How JSON-LD encodes structured data
A JSON-LD block is a JSON object placed in a script element with the type application/ld+json. Browsers do not display it; parsers read it as data. The object uses a small set of reserved keywords, each starting with an at sign, that connect plain JSON to a shared vocabulary, which in SEO is almost always Schema.org.
The @context keyword declares the vocabulary, @type names the entity class, and ordinary properties such as headline, author or offers describe the entity. The @id keyword assigns a stable identifier so that separate blocks, or separate pages, can refer to the same entity without repeating it.
| Keyword | Purpose | Typical value |
|---|---|---|
| @context | Declares the vocabulary in use | The Schema.org namespace |
| @type | Names the entity class | Article, Product, Organization |
| @id | Gives the entity a unique identifier | Page URL plus a fragment such as #organization |
| @graph | Holds several related entities in one block | Array of entity objects |
| Nested object | Describes a related entity inline | Author as a Person object |
Because the data is a graph rather than a flat list, a well-built page can describe a WebPage that is part of a WebSite, published by an Organization, with an Article whose author is a Person, all linked through @id references.
JSON-LD compared with Microdata and RDFa
JSON-LD is one of three syntaxes that can carry Schema.org vocabulary; the others are Microdata and RDFa. All three express the same meaning, but they differ in where the markup lives and how tightly it is bound to the visible HTML.
| Syntax | Where markup lives | Main advantage | Main drawback |
|---|---|---|---|
| JSON-LD | Separate script block | Decoupled from layout, easy to generate | Can drift from visible content |
| Microdata | Attributes on HTML elements | Tied directly to visible text | Fragile when templates change |
| RDFa | Attributes on HTML elements | Rich linked data features | Verbose and harder to maintain |
The decoupling that makes JSON-LD convenient is also its main risk: since the data is not attached to visible elements, it is easy to publish values that do not match the page, such as a price or rating that users cannot see. Search engine guidelines treat such mismatches as misleading markup.
JSON-LD within the structured data toolkit
JSON-LD is the container, while Schema.org supplies the vocabulary and rich results are one possible outcome. Keeping these layers apart avoids a common confusion in structured data work, where a valid JSON-LD block is mistaken for a guarantee of enhanced search appearance.
| Term | Role | Relation to JSON-LD |
|---|---|---|
| Schema.org | Shared vocabulary of types and properties | Supplies the terms used inside JSON-LD |
| Rich results | Enhanced search result displays | May be granted when eligible JSON-LD is present |
| Article schema | Type for news and blog content | Commonly expressed as a JSON-LD block |
| BreadcrumbList | Type for page hierarchy trails | Encoded as an ordered list in JSON-LD |
Eligibility depends on each feature’s required and recommended properties, on content policies and on the engine’s own judgment. Valid markup makes a page eligible, not entitled, to an enhanced display.
Implementing JSON-LD correctly
Robust implementations generate JSON-LD from the same data source that renders the visible page, typically the content management system or product database. This keeps titles, prices, dates and availability synchronized automatically instead of relying on manual copies.
- Place the script in the head or body; both locations are read by search engines.
- Prefer server-rendered JSON-LD; markup injected by client scripts is processed later and ignored by some parsers.
- Use absolute URLs and ISO 8601 dates with time zones, for example 2026-11-09T09:30:00+01:00.
- Link entities with consistent @id values across the whole site.
- Validate with the Rich Results Test and the Schema Markup Validator before release.
The table below lists frequent implementation errors, how they show up and how to correct them.
| Error | Symptom | Fix |
|---|---|---|
| Invalid JSON syntax | Whole block ignored | Validate output, escape quotes correctly |
| Missing required property | Feature marked as not eligible | Add the property from page data |
| Values absent from visible page | Manual action risk for spammy markup | Mark up only content users can see |
| Duplicate blocks from plugins | Conflicting entities and types | Keep one generator per entity |
| Wrong type for the content | Markup ignored or flagged | Choose the most specific fitting type |
Limits and misconceptions about JSON-LD
JSON-LD is not a direct ranking factor in the sense of a boost for having markup. Its value lies in clearer entity understanding, eligibility for rich results and better extraction by search and AI systems, which can improve visibility and click-through indirectly.
Rich result support also changes over time: search engines have retired or restricted several features, such as FAQ and HowTo displays, for most sites. Markup for a retired feature is harmless but no longer produces the enhanced display, so implementation priorities should follow current documentation rather than older checklists.
In plain words
JSON-LD is a hidden label attached to a web page. It describes the page in a format computers read easily. A visitor sees a recipe with a photo and instructions. The label tells the search engine, in neat fields, that this is a recipe, how long it takes and who wrote it.
The label sits apart from the visible page, so it is easy to add and update. One rule matters most. The label must describe what is really on the page, or search engines stop trusting it.
A real-world example
A regional news publisher wants its stories to show richer search listings and appear correctly in news features. Its existing templates contain no structured data, and article dates are shown only as plain text such as yesterday or 3 hours ago.
The developers add a server-rendered JSON-LD graph to every article template: a NewsArticle with headline, image, datePublished and dateModified in ISO 8601 format, an author Person linked to an author page, the publisher Organization with a logo, and a BreadcrumbList for the section path. All values come from the content management system. After validation and a recrawl, the articles show correct publication dates and breadcrumb paths in results, and the error report for structured data stays at zero across about 40,000 articles.