What Is JSON-LD Format? Examples and How Google Reads It

What JSON-LD means

JSON-LD stands for JavaScript Object Notation for Linked Data. It is a W3C standard, first published in 2014 and updated as JSON-LD 1.1 in 2020, for writing linked data using normal JSON syntax. The community site at json-ld.org hosts the specification links and a playground for testing.

On a website, JSON-LD is almost always used to carry structured data written with the Schema.org vocabulary. Schema.org is a shared dictionary of types such as LocalBusiness, Product, Article and FAQPage, and properties such as name, address and price. JSON-LD is the container; Schema.org supplies the words that go inside it.

The block sits in a script tag with a special media type:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Bakery",
  "name": "Example Bakery",
  "telephone": "+44 1632 960961",
  "url": "https://example.com/"
}
</script>

Because the type is application/ld+json and not text/javascript, the browser does not run it and visitors never see it. Search engines, AI crawlers and other tools read it as data. That separation is why Google recommends JSON-LD over the older Microdata and RDFa formats: you can add, change or remove it without touching the visible HTML.

JSON vs JSON-LD: the actual difference

Every JSON-LD document is valid JSON. The difference is that JSON-LD gives certain keys a fixed meaning, so a program that has never seen your data before can still work out what it describes. Plain JSON has no such agreement: a key called name could mean anything, and only the developer who wrote it knows.

So the honest answer to json vs json-ld is that you are not choosing between two formats. JSON-LD is JSON with an agreed set of rules on top. Anything that can parse JSON can parse JSON-LD; it simply will not understand the linked data part unless it knows the rules.

This also means a JSON syntax error breaks JSON-LD completely. A trailing comma, a smart quote pasted from a word processor or a missing bracket stops the parser before it reads a single property. The JSON syntax guide lists the common mistakes and how to spot them.

The special keys: @context, @type, @id and @graph

JSON-LD reserves keys that start with @. You only need four of them for nearly all website structured data.

@context

Tells the reader which vocabulary the other keys come from. For search, it is "https://schema.org". With that context, name means the Schema.org property name and nothing else. Google accepts http or https and with or without a trailing slash, but use https://schema.org consistently.

@type

Says what kind of thing the object is. It must match a Schema.org type exactly, including capitals: LocalBusiness works, localbusiness does not. You can give more than one type as an array, for example ["WebPage", "TechArticle"].

@id

A unique identifier for the thing, written as a URL. It does not have to be a page that loads; it is a name. The convention is your page URL plus a fragment, such as https://example.com/#business. Once an object has an @id, other objects can point to it instead of repeating it. The guide to schema @id values covers naming patterns and common clashes.

@graph

Holds several top-level objects in one block, sharing a single @context. This is how WordPress SEO plugins output a website, a web page, a breadcrumb trail and a business in one script tag.

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Bakery",
      "@id": "https://example.com/#business",
      "name": "Example Bakery",
      "url": "https://example.com/"
    },
    {
      "@type": "WebPage",
      "@id": "https://example.com/opening-times/#webpage",
      "url": "https://example.com/opening-times/",
      "name": "Opening times",
      "publisher": { "@id": "https://example.com/#business" }
    }
  ]
}

The publisher property contains only an @id. A reader joins the two objects together, so the page is published by the bakery described above. That joining is the linked part of linked data.

JSON-LD examples, annotated

A local business

{
  "@context": "https://schema.org",
  "@type": "Bakery",
  "@id": "https://example.com/#business",
  "name": "Example Bakery",
  "telephone": "+44 1632 960961",
  "url": "https://example.com/",
  "address": {
    "@type": "PostalAddress",
    "streetAddress": "1 Example Street",
    "addressLocality": "Exampletown",
    "postalCode": "EX1 1AA",
    "addressCountry": "GB"
  },
  "openingHoursSpecification": [{
    "@type": "OpeningHoursSpecification",
    "dayOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
    "opens": "08:00",
    "closes": "17:00"
  }]
}

Notice that address is a nested object with its own @type. Nesting is how JSON-LD says that a property's value is itself a thing with properties. Country codes use two-letter ISO codes, and times use 24-hour format.

An article

{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "How we bake sourdough",
  "datePublished": "2026-03-02T09:00:00+00:00",
  "dateModified": "2026-09-14T11:30:00+01:00",
  "author": { "@type": "Person", "name": "Sam Example" },
  "image": "https://example.com/images/sourdough.jpg"
}

Dates use ISO 8601. Include a time zone offset so the date cannot be misread. More date rules are in the schema dates guide.

A product

{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Seeded rye loaf",
  "image": "https://example.com/images/rye.jpg",
  "offers": {
    "@type": "Offer",
    "price": "4.50",
    "priceCurrency": "GBP",
    "availability": "https://schema.org/InStock"
  }
}

Values such as availability are written as full Schema.org URLs. The price is a plain number without a currency symbol, and the currency goes in its own property. The product schema guide covers the properties Google needs for product results.

How Google reads JSON-LD

Google's documentation says it supports JSON-LD, Microdata and RDFa, and recommends JSON-LD. In practice, this is what happens when Googlebot fetches a page:

1. It reads every application/ld+json script in the HTML, in the head or the body. Position does not matter.
2. It parses each block as JSON. A block that fails to parse is dropped, and Search Console may report it as an unparsable structured data item.
3. It renders the page. JSON-LD added by JavaScript after load can also be read at this stage, as long as rendering succeeds, though server-rendered markup is more dependable.
4. It matches objects to the features it supports, such as product snippets, breadcrumbs or local business details, and checks each against that feature's required and recommended properties.
5. It decides whether to show a rich result. Valid markup makes a page eligible; it does not guarantee anything appears.

Google does not need one block per page. Several separate blocks, or one block with a @graph, both work. What matters is that the markup describes content visitors can actually see on the page, which is part of Google's structured data guidelines. Marking up prices, opening hours or questions that are not on the page breaks those guidelines and can lead to a manual action.

The last row confuses many people. Schema.org has hundreds of types and Google builds features for a small number of them. Other types are still read and can help Google and AI systems understand the page, but they will not show in the Rich Results Test. The guide to testing schema and rich results explains both tools in depth.

Where JSON-LD comes from on common platforms

• WordPress: SEO plugins such as Yoast and Rank Math write a @graph block automatically. Adding a second plugin or a theme that also writes schema creates duplicates. See JSON-LD on WordPress.
• Shopify: most themes print product JSON-LD from a Liquid snippet. Apps can add more. Check the theme code before installing a schema app. See JSON-LD on Shopify.
• Next.js and React: render the block on the server with a script tag and JSON.stringify. See JSON-LD in Next.js.
• Hand-coded sites: paste the block in the head of each page, or include it from a shared template so it cannot drift between pages.

To see what a live page really serves, fetch the raw HTML and pull out the blocks:

curl -s https://example.com/ | grep -o '<script type="application/ld+json">.*</script>'

If a block spans several lines, the grep shows nothing, so open the page in Chrome, press Ctrl+U for the source and search for ld+json instead. In DevTools, the Console line below lists every block the page holds after rendering:

[...document.querySelectorAll('script[type="application/ld+json"]')].map(s => JSON.parse(s.textContent))

If that line throws an error, one of the blocks is not valid JSON.

The fix, step by step

Edge cases worth knowing

• HTML inside values. A description containing </script> ends the block early. Escape the slash as <\/script> or strip HTML from text values.
• Smart quotes. Curly quotes copied from a document are not valid JSON delimiters. Use straight double quotes only; single quotes are not allowed for keys or strings.
• Comments. JSON has no comments. A // note left inside the block makes it unparsable.
• Numbers as text. "price": "4.50" and "price": 4.50 are both accepted by Google, but a value like "£4.50" is not a valid price.
• Case of keys. @Type or Name are different keys from @type and name, and are ignored.
• Unknown properties. A misspelt property such as telephon is ignored silently by most tools. The Schema Markup Validator flags it, so run both tools.
• Several blocks describing the same thing. Two separate business objects without a shared @id look like two different businesses. Give repeated things the same @id so they merge.

Keeping your JSON-LD correct

JSON-LD rarely breaks on its own. It breaks when something else changes: a theme update, a new plugin, a price change that never reached the markup, or a page template edited by someone who did not know the block was there. A few habits keep it healthy:

• Generate the block from the same data that fills the visible page, so prices, hours and names cannot drift apart.
• Keep one source of schema per page type. If a plugin writes it, do not also paste it by hand.
• Re-test a sample of templates after every theme or plugin update, not only the home page.
• Watch the enhancement reports in Search Console for new invalid items.
• Run a crawl that checks every page's blocks parse, so a single broken template is found in one pass. Our JSON checker guide shows how.