JSON-LD

1. What JSON-LD is

The W3C defines JSON-LD as “a lightweight syntax to serialize Linked Data in JSON” (W3C, 2020). It became a W3C Recommendation with version 1.0 in 2014 and version 1.1 in July 2020. The name stands for JSON for Linked Data. The format lets a JSON document describe a graph of typed entities with stable identifiers so that consumers of RDF or Linked Data can process it.

For Schema.org markup, JSON-LD is one of three serialization formats, along with Microdata and RDFa. All three carry the same vocabulary. Schema.org defines terms such as Organization, Person, Article, sameAs, and mainEntity independently of the format a page uses. Its getting-started guide states: “You use the schema.org vocabulary along with the Microdata, RDFa, or JSON-LD formats to add information to your Web content” (Schema.org Getting Started). Schema.org for AI explains what individual types and properties signal to AI engines, including why sameAs matters more than FAQPage for citation work.

2. The three Schema.org serialization formats

All three formats can describe the same graph. They differ in how they add markup to a page.

The following examples describe the same minimal Organization in each format:

<!-- Microdata -->
<div itemscope itemtype="https://schema.org/Organization">
  <span itemprop="name">Example Co</span>
  <link itemprop="url" href="https://example.com">
  <link itemprop="sameAs" href="https://en.wikipedia.org/wiki/Example_Co">
  <link itemprop="sameAs" href="https://www.wikidata.org/wiki/Q000000">
</div>

<!-- RDFa -->
<div vocab="https://schema.org/" typeof="Organization">
  <span property="name">Example Co</span>
  <link property="url" href="https://example.com">
  <link property="sameAs" href="https://en.wikipedia.org/wiki/Example_Co">
  <link property="sameAs" href="https://www.wikidata.org/wiki/Q000000">
</div>

<!-- JSON-LD -->
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "Example Co",
  "url": "https://example.com",
  "sameAs": [
    "https://en.wikipedia.org/wiki/Example_Co",
    "https://www.wikidata.org/wiki/Q000000"
  ]
}
</script>

Microdata and RDFa attach each property to an element in the visible HTML. JSON-LD keeps the declaration in a separate, self-contained block. That separation is the practical reason behind Google’s recommendation.

3. Why JSON-LD is the recommended format

Google states its preference in Intro to How Structured Data Markup Works:

“In general, Google recommends using JSON-LD for structured data if your site’s setup allows it, as it’s the easiest solution for website owners to implement and maintain at scale.”

The same page makes clear that this is a practical recommendation, not a technical one: “all 3 formats are equally fine for Google, as long as they are valid and implemented properly per the feature’s documentation.” Google does not prefer JSON-LD because it parses the format better. It prefers JSON-LD because the format is easier for site owners to maintain.

Four practical advantages explain that preference:

1. It stays separate from visible HTML. Changes to the markup do not affect page elements or risk breaking the visible layout. For example, redesigning a price display cannot accidentally invalidate Product markup because the display and the declaration are separate.
2. Several parts of the publishing system can add it. A CMS, build step, or server middleware can output the <script> block as a string. Microdata and RDFa require the template engine to interleave attributes with the elements it renders.
3. It uses standard JSON parsing. Any consumer with a JSON parser can read the graph without traversing the DOM or resolving HTML attributes. This is especially useful for downstream tools, though less important to Google itself.
4. A syntax error does not break the page. A JSON-LD syntax error invalidates the markup but leaves the page intact. Malformed Microdata or RDFa attributes can occur alongside HTML rendering bugs.

The other formats remain reasonable in a few cases. A site with extensive Microdata can keep it when the cost of migration would outweigh the benefit, since Google treats all three formats equally. RDFa remains common in government and academic linked-data publishing, where prefix declarations make support for multiple vocabularies useful. JSON-LD is the practical choice for a new implementation.

4. Four JSON-LD keywords that matter most

JSON-LD includes more features than most pages need, including @graph, @vocab, @reverse, @container, framing, and contexts that override other contexts. For AI citation work, four keywords are especially important.

This minimal Organization block uses all four keywords:

{
  "@context": "https://schema.org",
  "@type": "Organization",
  "@id": "https://example.com/#org",
  "name": "Example Co",
  "url": "https://example.com",
  "sameAs": [
    "https://en.wikipedia.org/wiki/Example_Co",
    "https://www.wikidata.org/wiki/Q000000",
    "https://www.linkedin.com/company/example-co"
  ]
}

The sameAs property connects the entity in the markup to matching entities in the knowledge graph. AI engines can use that connection even when they do not parse the page’s JSON-LD directly, as §6 explains. Entity Recognition and Knowledge Graph Presence describe how this matching process works. A page with several entities, such as an Organization, a Person author, and an Article, may use one <script> block per entity or combine them in one @graph block. The Schema Implementation playbook provides templates and validation steps for each type.

5. Placement, delivery, and crawler access

Three choices affect the block’s placement, organization, and crawler visibility.

Choose either <head> or <body>. Google’s introductory guide describes JSON-LD as “a JavaScript notation embedded in a <script> tag in the <head> and <body> elements of an HTML page,” so both locations are valid. The General Structured Data Guidelines require only that the markup appear “on the page that it describes.” In practice, <head> is the common default because it places the markup before the body and makes it easy to find in the page source. Many CMS plugins place it in <body>, which is also acceptable.

Use multiple blocks if they make the markup easier to manage. Google’s documentation does not set a per-page limit on JSON-LD blocks. Production sites commonly place an Organization in one block, an Article in another, and a BreadcrumbList in a third. Combining several entities in one @graph block is also valid. The choice is stylistic rather than a matter of correctness.

Prefer server-rendered or build-time markup. JSON-LD added to the DOM by client-side JavaScript reaches only consumers that execute JavaScript. Google’s JavaScript SEO basics confirms that Googlebot does: “Once Google’s resources allow, a headless Chromium renders the page and executes the JavaScript.” Many AI crawler documents do not address rendering directly, and observed behavior varies by crawler:

Server-rendered or build-time JSON-LD reaches every crawler in the table. Only Googlebot reliably receives client-injected JSON-LD. To make the markup broadly visible, render it through the same layer that serves the page’s visible content. SSR for AI Crawlers explains the broader rendering tradeoff.

6. How AI engines consume JSON-LD

AI systems handle JSON-LD differently depending on whether they use a search index or fetch a page directly.

Google’s AI features and your website page states: “You don’t need to create new machine readable files, AI text files, or markup to appear in these features. There’s also no special schema.org structured data that you need to add.” JSON-LD reaches Google AI Overviews through the same search-index process used by Google Search.

Direct page retrieval produces a different result. In a controlled December 2025 test, searchVIU placed a price only inside JSON-LD on a test page and queried five AI systems. None of the live-fetch chatbots extracted it. The report concluded: “Current AI chatbots do NOT use JSON-LD Schema Markup during direct retrieval. Instead, they exclusively extract visible HTML content.” A separate February 2026 observation from Search Engine Roundtable found that ChatGPT and Perplexity could surface values from fabricated, syntactically invalid JSON-LD. This behavior indicates that they read the markup as page text rather than as a parsed structure.

This limitation does not make JSON-LD harmful on pages that chatbots fetch directly. It means that the format does not provide its expected parsing advantage in that setting. Entity information can still reach these models through prior knowledge and the knowledge graph rather than through the page’s <script> block. Search Engine Land summarizes the tradeoff: “Schema markup is infrastructure, not a magic bullet. It won’t necessarily get you cited more, but it’s one of the few things you can control that platforms such as Bing and Google AI Overviews explicitly use” (Jurenka, 2026). JSON-LD remains useful to index-integrated systems and does not disadvantage live-fetch systems. Live-fetch chatbots, however, should not be expected to parse it.

7. Validation, errors, and anti-patterns

The two main validators answer different questions. The Rich Results Test checks whether markup is eligible for a Google rich-result feature. Passing does not prove that the markup is technically correct; it means only that Google may consider it for a particular surface. The Schema Markup Validator checks vocabulary conformance against the Schema.org specification. Passing that test does not mean Google will display anything. Use both: the Schema Markup Validator for well-formed Schema.org markup, and the Rich Results Test for Google feature eligibility.

The following JSON-LD-specific failure modes are distinct from the vocabulary-level anti-patterns in Schema.org for AI:

Invalid JSON-LD, or markup that does not match the visible content, is worse than having no markup. This is how the vocabulary rule described in Schema.org for AI §7 applies during implementation. A contradiction between markup and visible content can lead to a Google structured-data manual action. It also gives live-fetch AI systems two conflicting facts because those systems read the JSON-LD as page text.

8. Where to go next

For the term and its neighbors, see the GEO glossary.

References

W3C and Schema.org:

• W3C: JSON-LD 1.1: A JSON-based Serialization for Linked Data (Recommendation, 2020-07-16)
• Schema.org: Getting Started · Schema.org vocabulary · Schema Markup Validator

Google Search Central:

• Intro to How Structured Data Markup Works: JSON-LD recommendation, placement, and format parity
• General Structured Data Guidelines: ranking impact and manual actions
• AI features and your website: no AI-specific schema required
• Understand the JavaScript SEO basics: Googlebot WRS rendering
• Rich Results Test

AI crawler documentation:

• OpenAI: Overview of OpenAI Crawlers
• Anthropic: Does Anthropic crawl data from the web?
• Perplexity AI: Perplexity Crawlers

Independent and industry sources:

• searchVIU: Schema Markup and AI in 2025: What ChatGPT, Claude, Perplexity & Gemini Really See (2025-12-02), a controlled test of live-fetch JSON-LD consumption
• Search Engine Land: How schema markup fits into AI search — without the hype (2026-03-25)
• Search Engine Roundtable: ChatGPT & Perplexity Treat Structured Data As Text On A Page [observation] (2026-02-03)