What is JSON-LD?

CEO & Digital Strategist

8 min reviewed on 2026-08-08

Technical SEO

Definition

JSON-LD (JSON for Linking Data) is the structured data format specified by the W3C that embeds semantic information in a page through a dedicated <script type="application/ld+json"> block, kept separate from the visible HTML.

A punched paper tape spilling from an old reader, with nothing printed on it — beside the title JSON-LD — Holes in a tape: the machine reads what you cannot

On this page 6

What does JSON-LD mean?
JSON-LD versus Microdata and RDFa
How it works
Why it matters
Best practices
Common mistakes

In brief

How a JSON-LD block is built, why Google recommends it over Microdata and RDFa, and what actually separates the Rich Results Test from the Schema.org Validator.

What does JSON-LD mean?

JSON-LD stands for JSON for Linking Data, a format for serializing linked data defined by the W3C and updated to version 1.1 in July 2020. It describes a page's content using Schema.org vocabulary written in plain JSON syntax, something most web developers already know how to read and write.

Unlike other methods, JSON-LD lives inside a single <script type="application/ld+json"> block placed in the <head> or <body> of the document, without mixing into the tags that build the visible layout. It is one form of structured data that helps search engines understand what a page is about beyond the text a visitor actually reads.

Google recommends JSON-LD as its preferred format because, according to its own Search Central documentation, "it is the easiest solution for website owners to implement and maintain at scale." That recommendation explains why most SEO plugins and content management systems generate it by default, even for simple cases like a rich snippet showing star ratings.

JSON-LD versus Microdata and RDFa

Format	Where the code lives	Maintainability
JSON-LD	Standalone <script> block, usually in the <head>	High: edited without touching visible HTML
Microdata	itemscope, itemtype and itemprop attributes inside the HTML tags themselves	Medium: a layout change can break the markup
RDFa	vocab, typeof and property attributes, also woven into the HTML	Medium to low: more verbose, less widely used syntax

The core technical difference is where the code sits. In a technical SEO workflow built around JSON-LD, markup can be generated, edited or removed entirely without touching a single tag of the visible HTML. With Microdata and RDFa, each attribute is woven into the same tag that renders the content, so any template redesign forces a review of the semantic markup too.

How it works

A JSON-LD block is built from a small set of reserved keys. @context states the vocabulary in use, almost always https://schema.org, and removes any ambiguity about what a property means. @type declares the kind of entity being described (Article, Product, FAQPage, Organization...), and the type-specific properties follow from there: name, description, datePublished, price, or whichever the vocabulary defines. These properties can hold nested values too, such as an author described as a full Person object inside the same block, with no need for a separate script.

A single page can include several independent <script type="application/ld+json"> blocks, for example one for the article and another for the breadcrumb. Multiple entities can also be combined inside one block using the @graph key, a tidier option when entities are related to each other, such as an article that belongs to an organization and also carries a list of frequently asked questions. That approach also saves the browser a bit of work, since it only has to parse one block instead of several.

To let Google recognize that two blocks on different pages refer to the same entity, such as a company's logo and contact details, @id is used: a unique identifier, usually a URL with an anchor like https://mydomain.com/#organization, repeated on every page where that entity appears. This avoids duplicating information and keeps a site's structured data coherent as a whole.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "What is JSON-LD?",
  "url": "https://zds.es/en/what-is-json-ld/",
  "datePublished": "2026-08-08",
  "author": {
    "@type": "Organization",
    "@id": "https://zds.es/#organization",
    "name": "ZDS",
    "url": "https://zds.es"
  }
}
</script>

Why it matters

JSON-LD is the prerequisite for Google to display a rich snippet in search results: star ratings, prices, expandable questions, or a visual breadcrumb trail right in the SERP. Without correct markup, that extra information simply doesn't appear, even if the content is clearly visible to users on the page itself.

Because it lives apart from the HTML, the markup fits well into technical SEO workflows: it can be generated dynamically from a template or CMS without risking the page's layout, and a development team can change it without coordinating with whoever maintains the visible HTML.

Increasingly, the same markup also helps generative AI systems understand a page's content when citing it in conversational answers. That use case adds to the traditional one of rich results and turns JSON-LD into as routine a technical task as monitoring Core Web Vitals or a site's load speed. Neglecting that upkeep costs a site its rich results and makes the page harder for any automated system to interpret correctly.

Best practices

Validate every block first with the Schema.org Validator, then with the Rich Results Test: the first checks the full vocabulary, the second only what triggers rich results in Google.
Use a consistent @id across organization, logo and sameAs so Google links the same entity across different pages of the site.
Place the block in the <head> or right before the closing <body> tag, never duplicated inside components that load more than once on the same page.
Limit the markup to what genuinely exists on the visible page: don't describe a price, a rating or an FAQ that users can't actually see.
Recheck the markup after every migration or template redesign, since a platform change can drop the <script> block without any visible effect on the layout, a typical technical SEO failure that can go unnoticed for months.
Document which Schema.org type each template uses so two developers don't end up describing the same data with different properties.

Common mistakes

Declaring a @type that doesn't match the page's actual content, for example Product on an informational page with no price or availability.
Leaving the JSON-LD block with data from an older version of the page after a content update, so it no longer matches what users see.
Using a @context other than https://schema.org without a real reason, which makes the markup harder for search engines to interpret.
Mistaking a passing Rich Results Test for full validation: the test can pass while vocabulary errors remain that only the Schema.org Validator catches.
Repeating the same JSON-LD block across several template components and ending up with duplicated or contradictory data on a single page.

Manuel Riveiro Rodriguez CEO & Digital Strategist

A technical audit covers this and everything else in one pass.

Request an audit

Frequently asked

Does JSON-LD affect a page's ranking?

Not directly. Google has repeatedly stated that JSON-LD markup is not a ranking factor on its own. What it does is enable rich results and help search engines understand content more precisely, which can improve click-through rate without moving the ranking position itself.

Can a page have several JSON-LD blocks?

Yes. It's common to combine, for example, one block for the article, one for the breadcrumb, and one for the organization. Multiple entities can also be grouped inside a single block using the @graph key, which is tidier when the entities are related to each other.

What's the difference between the Rich Results Test and the Schema.org Validator?

Google's Rich Results Test only checks the markup types that can trigger a rich result in its own search engine. The Schema.org Validator, by contrast, checks markup against the entire official vocabulary, including types Google doesn't use for rich results.

Does JSON-LD replace traditional meta tags?

No. JSON-LD complements tags like title or meta description, it doesn't replace them. Search engines still use those tags for the title and snippet shown in results; JSON-LD markup adds an extra layer of semantic context on top of the same content.

Do I need coding skills to add JSON-LD to my site?

It depends on the system. Many content management systems and SEO plugins generate the JSON-LD block automatically from fields you already fill in. Custom cases do require editing JSON code inside the script tag, though the syntax is simpler than Microdata or RDFa.