In beta, with limited placesOpen to everyone in Q1 2027

Help Log in

↑↓ to move · Enter to open · Esc to close

Structured data

What is JSON-LD (JSON for Linking Data)?

JSON-LD is a W3C standard format for writing linked data in JSON. On a website, JSON-LD is the block of code that describes the page with a vocabulary such as Schema.org, inside a script tag separate from the visible text, so that a search engine reads which product, price or brand is there without depending on how the page is laid out.

Written by
Patricia Antuña
Reviewed by
Daniel Rico
Reviewed by
Santiago Melluso
Published 7 min read
Takeaway:

Key takeaways

  • JSON-LD is a format, not a vocabulary: it is the syntax in which Schema.org's words are written.
  • It goes in its own script block, separate from the visible HTML, which is why it can be maintained without touching the layout.
  • Google supports three formats and recommends this one, as the easiest to maintain at scale.
  • Being separate does not mean it can say something else: it has to describe the same thing the reader sees.
  • The current version is 1.1, from 2020; 1.2 is under way and what is written in 1.1 will stay valid.

If you open the source code of a product page and search for application/ld+json, what you find is JSON-LD: a block of text that describes the page for machines, separate from what the customer sees. JSON-LD is the format, the way of writing; the words it carries (product, price, brand) belong to Schema.org, and together they make up the page's structured data. It matters to you because it is the format Google recommends, including for pages that aim for rich results, and because, being separate, it is easy for it to say one thing while the page says another.

How it works

JSON-LD is a W3C specification. Its current version, JSON-LD 1.1, defines it as a JSON-based format to serialize Linked Data, designed to fit into systems that already use JSON, and it has been a W3C Recommendation since July 16, 2020. It is a superset of version 1.0, from January 2014: everything that one allowed is still there.⁠[1]W3C. JSON-LD 1.1: A JSON-based Serialization for Linked Data The community site presents it under its long name: JSON for Linking Data.⁠[2]json-ld.org. JSON-LD: JSON for Linking Data

A JSON-LD document is plain JSON with a few keywords that start with an at sign. The four you will see in a store:⁠[1]W3C. JSON-LD 1.1: A JSON-based Serialization for Linked Data

  • @context: the rules for interpreting the document. In practice, "@context": "https://schema.org" says that the words that follow are Schema.org's.
  • @type: the type of what is being described, for example Product.
  • @id: a unique identifier for the node, usually a web address (an IRI). It is what lets another block refer to that same product without repeating it; it has its own entry, the @id identifier.
  • @graph: used to express a graph, several nodes in a single block. The entry on @graph explains it.

On a web page, the block goes inside a <script type="application/ld+json"> element.⁠[1]W3C. JSON-LD 1.1: A JSON-based Serialization for Linked Data Google accepts that element in both the <head> and the <body>, and of the three formats it supports (JSON-LD, microdata and RDFa) it recommends JSON-LD whenever your site allows it, because it is the easiest to implement and maintain at scale and the least prone to errors.⁠[3]Google Search Central. Introduction to structured data markup in Google Search

The block can arrive written into the HTML the server sends or be added later with JavaScript. Google can process structured data that is in the DOM when it renders the page, but it warns that dynamically generated markup can make Shopping crawls less frequent and less reliable, a problem for what changes fast, like price and availability.⁠[4]Google Search Central. Generate structured data with JavaScript If your theme or an app injects the block with JavaScript, the entry on JavaScript rendering explains what that implies.

The format is still alive. The W3C's JSON-LD working group has a mandate from January 6, 2026 to January 31, 2028 to publish JSON-LD 1.2, with the recommendation expected for the fourth quarter of 2027, and it commits that any document valid in JSON-LD 1.1 will remain valid in 1.2.⁠[5]W3C. JSON-LD Working Group Charter What you publish today in 1.1 will not need rewriting because of the version change.

In a store

A product page's block, reduced to the essentials. Fictitious example: the store, the product, the address and the price are made up, and the block only says what that imaginary page shows on screen.

<script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "Product",
    "@id": "https://www.example.com/calella-linen-shirt#product",
    "name": "Calella linen shirt, blue",
    "image": "https://www.example.com/img/calella-blue.jpg",
    "sku": "CAL-BL-M",
    "brand": { "@type": "Brand", "name": "Calella" },
    "offers": {
      "@type": "Offer",
      "price": "39.90",
      "priceCurrency": "USD",
      "availability": "https://schema.org/InStock",
      "url": "https://www.example.com/calella-linen-shirt"
    }
  }
</script>

It reads top to bottom. @context sets the vocabulary. @type says it is a product, the Product type. @id gives it a stable name that other blocks on the page can point to. The properties that follow are the vocabulary's, and offers opens a second, nested node, of type Offer, with the price, the currency and the availability. Notice the price, with a decimal point, no symbol and the currency in its own property: the Offer entry explains why it is written that way.

A real page usually carries more than one node: the organization, the website, the breadcrumbs and the product. A page published with Clione, for example, carries a single @graph with Organization, WebSite, BreadcrumbList and Product, plus FAQPage when it has questions, and its Product node has a stable @id that coexists with the theme's instead of duplicating it.

Warning:

What people often get wrong

Thinking that, because the block is not visible, it can say anything. Google asks for the opposite, with a JSON-LD example: if the markup describes an artist, the body of the page has to describe that same artist. What the reader does not see is not marked up.⁠[6]Google Search Central. General structured data guidelines

How to check it

  1. Open the page's source code (not the browser inspector) and search for application/ld+json. Count how many blocks there are and which @type each declares: that is what your server serves.
  2. Run the same URL through the Rich Results Test. It supports JSON-LD, microdata and RDFa, tells you which types it finds with their errors and suggestions, and also accepts a pasted code snippet.⁠[7]Search Console Help. Rich Results Test
  3. Compare the two readings. If the test finds a block that the source code did not have, JavaScript is adding it, and for price and availability that has the cost Google describes.⁠[4]Google Search Central. Generate structured data with JavaScript
  4. If there are two product nodes, compare their data. If they do not say the same thing, at least one does not represent the page.⁠[6]Google Search Central. General structured data guidelines

Microdata is the other common way of writing the same vocabulary. It is part of the HTML standard and adds groups of name-value pairs in parallel to content that already exists, with attributes such as itemscope, itemtype and itemprop on the visible tags.⁠[8]WHATWG. HTML Standard: Microdata JSON-LD does the opposite: it describes the page in a separate block. Google supports both and recommends JSON-LD.⁠[3]Google Search Central. Introduction to structured data markup in Google Search The practical difference is where the data lives: in microdata it is stuck to the text the customer reads, and in JSON-LD it can be changed without touching the layout, at the risk that it stops matching it.

To go further, the structured data reading path orders the rest of the terms, and the guide to auditing a product page's structured data applies these steps to a whole page.

Synonyms

English
JSON-LD, JSON for Linking Data
Español
JSON-LD, marcado JSON-LD

Sources

  1. [1] W3C. JSON-LD 1.1: A JSON-based Serialization for Linked Data. Accessed . ↑ ↑ ↑
  2. [2] json-ld.org. JSON-LD: JSON for Linking Data. Accessed . ↑
  3. [3] Google Search Central. Introduction to structured data markup in Google Search. Accessed . ↑ ↑
  4. [4] Google Search Central. Generate structured data with JavaScript. Accessed . ↑ ↑
  5. [5] W3C. JSON-LD Working Group Charter. Accessed . ↑
  6. [6] Google Search Central. General structured data guidelines. Accessed . ↑ ↑
  7. [7] Search Console Help. Rich Results Test. Accessed . ↑
  8. [8] WHATWG. HTML Standard: Microdata. Accessed . ↑

Change history

  • First English version.

This definition is published under CC BY 4.0. Reuse this definition freely, crediting Clione with a link to this page.

Related terms

Glossary

Schema.org

What Schema.org is, who maintains it, how its types and properties are organized, and why it is not the same as the format or as what Google requires.
Glossary

Structured data

What structured data is, which pieces make it up, what a store gets from it according to Google, and how to check it matches the product page.
Glossary

Product

What the Schema.org Product type is, which properties it carries, what Google requires for product snippets and merchant listings, and how to check it.
Glossary

Offer

What the Schema.org Offer type is, how to write price, currency and availability, what Google requires, and how Offer differs from AggregateOffer.
Glossary

@graph

What @graph is in JSON-LD, what the W3C specification says, how it links a product page's product, store and site, and how to review your store's.
Glossary

@id

What the @id identifier in JSON-LD is, how it ties your schema nodes together, why it should not change and how to avoid two products where there is one.

Make your catalog easy for bots to read

Clione fills every product page with what bots read best: the JSON-LD graph with its structured data, the meta description and the FAQs. You review and press Push; then we check your live store so it all stays published.

See how Clione works →