How to Help AI Understand Your Content with JSON-LD
· 11 min read · Updated
Українською: JSON-LD: як пояснити AI, про що ваша сторінка — читати українською
When an extension reports that there's no valid JSON-LD with core entities (Article, FAQPage, Product) on a page, that's not a cosmetic defect. It's a signal. Large language models and systems like Google AI Overviews see your page as a bag of unconnected tokens, not as a structured object with a clearly tagged author, publish date, headline, price, or answer to a specific question.
Without markup, the model guesses. With markup, it knows.
Why do LLMs depend on structured data?
Large language models generate text based on probabilities, but when a query touches facts — a specific author, a date, a price, an answer — they fall back on what Google calls grounding (anchoring an answer in a source). JSON-LD becomes that source of truth in a machine-readable format.
A few concrete mechanisms worth understanding:
- AI Overviews and generative search lift paragraphs and facts off pages. Structured markup substantially raises the chance that your content is selected as the citation source rather than a competitor's content the model had to parse from "naked" HTML.
- Schema.org remains the shared vocabulary. Search engines, LLM parsers, voice assistants, and AI-platform crawlers all understand it — from ChatGPT to Perplexity.
- Precision without NLP extraction. Without markup, the model extracts entities through NLP analysis. It works, but unpredictably. Through JSON-LD you hand the model unambiguous fields: this is
headline, this isauthor, this isdatePublished. No room for interpretation.
An important nuance about FAQPage. Google narrowed FAQ rich results to authoritative government and health sites in August 2023, then retired the feature outright: as of 7 May 2026 the FAQPage documentation states that the rich result "is no longer shown in Google Search results." Google has not asked anyone to remove the markup, and this site still emits it.
You will find a widely quoted figure claiming pages with
FAQPageare 3.2× more likely to land in AI Overviews. I went looking for its source and could not find one. The number circulates with a different owner every time — an SEO vendor's own index, a "Princeton/Moz study," a freshness study that used the same multiplier for something else entirely — while neighboring posts quote 2.3×, 28%, and 61.7% for the same idea. None of them link to data you can check. So I am not repeating it. The honest version is thatFAQPagegives a retriever question-and-answer pairs already split into fields, which is a cheap thing to hand it, and that no one has published evidence I trust about how much it is worth.
The analogy is simple. HTML is a page layout for humans. JSON-LD is the same content rewritten in a format that leaves machines no room for guesswork.
What does correct Article + FAQPage markup look like?
Mark up a <script type="application/ld+json"> block in <head> or near the end of <body>. You can use multiple separate scripts — or unite the entities into a single @graph. The second option is cleaner: it lets you connect objects via @id.
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@graph": [
{
"@type": "Article",
"@id": "https://example.com/posts/json-ld-guide#article",
"headline": "How to help AI understand your content with JSON-LD",
"description": "A step-by-step guide on adding structured data for AI Overviews and LLMs.",
"image": [
"https://example.com/images/cover-1x1.jpg",
"https://example.com/images/cover-4x3.jpg",
"https://example.com/images/cover-16x9.jpg"
],
"datePublished": "2026-05-01T08:00:00+00:00",
"dateModified": "2026-05-01T08:00:00+00:00",
"inLanguage": "en-US",
"author": {
"@type": "Person",
"name": "Olena Koval",
"url": "https://example.com/authors/olena-koval"
},
"publisher": {
"@type": "Organization",
"name": "Example Media",
"logo": {
"@type": "ImageObject",
"url": "https://example.com/logo.png"
}
},
"mainEntityOfPage": {
"@type": "WebPage",
"@id": "https://example.com/posts/json-ld-guide"
}
},
{
"@type": "FAQPage",
"@id": "https://example.com/posts/json-ld-guide#faq",
"mainEntity": [
{
"@type": "Question",
"name": "Does JSON-LD replace Microdata markup?",
"acceptedAnswer": {
"@type": "Answer",
"text": "Yes. Google recommends JSON-LD as the primary format for structured data. Microdata remains valid, but JSON-LD is easier to maintain — it's decoupled from HTML markup and doesn't break during redesigns."
}
},
{
"@type": "Question",
"name": "Will an LLM see my markup if it renders via JavaScript?",
"acceptedAnswer": {
"@type": "Answer",
"text": "Most modern crawlers do execute JS, but the reliable path is to ship JSON-LD in the initial HTML — via SSR or static generation. That way you avoid render races and guarantee inclusion in AI-platform indexes."
}
},
{
"@type": "Question",
"name": "Will I get a FAQ rich snippet in Google search?",
"acceptedAnswer": {
"@type": "Answer",
"text": "No, unless your site is in an authoritative government or medical category. But FAQPage is still worth adding — AI Overviews, ChatGPT, Perplexity, and Gemini actively pull content from this markup."
}
}
]
}
]
}
</script>A few principles that make this block actually useful, not decorative:
@graphlets you place several entities in a single script and connect them via@id. Cleaner than two separate tags.@idis not the page URL, it's a unique identifier for the entity. The hash fragment (#article,#faq) makes it stable.mainEntityOfPagetiesArticleto a specific canonical URL — the same URL your<link rel="canonical">andog:urlmust name. Three places asserting the canonical is fine; three places disagreeing about it is how citation potential gets split across variants of one page.imageas an array with three aspect ratios (1:1, 4:3, 16:9) is a direct Google requirement for gettingArticlerich results.inLanguagehelps LLM platforms understand the content language and correctly cite it in language-specific queries.
Implementation in Next.js (App Router)
A working page example for Next.js 16 with Tailwind CSS. The key technical decision here is using JSON.stringify instead of a template literal to safely escape data.
import type { Metadata } from "next";
interface PageProps {
params: Promise<{ slug: string }>;
}
export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
const { slug } = await params;
return {
title: `Article ${slug}`,
alternates: { canonical: `https://example.com/posts/${slug}` },
};
}
export default async function PostPage({ params }: PageProps) {
const { slug } = await params;
const canonicalUrl = `https://example.com/posts/${slug}`;
const jsonLd = {
"@context": "https://schema.org",
"@graph": [
{
"@type": "Article",
"@id": `${canonicalUrl}#article`,
"headline": "How to help AI understand your content with JSON-LD",
"description":
"A step-by-step guide on adding structured data for AI Overviews and LLMs.",
"image": [
"https://example.com/images/cover-1x1.jpg",
"https://example.com/images/cover-4x3.jpg",
"https://example.com/images/cover-16x9.jpg",
],
"datePublished": "2026-05-01T08:00:00+00:00",
"dateModified": "2026-05-01T08:00:00+00:00",
"inLanguage": "en-US",
"author": {
"@type": "Person",
"name": "Olena Koval",
"url": "https://example.com/authors/olena-koval",
},
"publisher": {
"@type": "Organization",
"name": "Example Media",
"logo": {
"@type": "ImageObject",
"url": "https://example.com/logo.png",
},
},
"mainEntityOfPage": {
"@type": "WebPage",
"@id": canonicalUrl,
},
},
{
"@type": "FAQPage",
"@id": `${canonicalUrl}#faq`,
"mainEntity": [
{
"@type": "Question",
"name": "Does JSON-LD replace Microdata markup?",
"acceptedAnswer": {
"@type": "Answer",
"text": "Yes — Google recommends JSON-LD as the primary format. Microdata is still valid, but JSON-LD is easier to maintain because it's decoupled from HTML.",
},
},
{
"@type": "Question",
"name": "Will an LLM see my markup if it renders via JavaScript?",
"acceptedAnswer": {
"@type": "Answer",
"text": "The reliable path is to ship JSON-LD in the initial HTML — via SSR or static generation.",
},
},
],
},
],
};
return (
<>
<script
type="application/ld+json"
dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
/>
<article className="max-w-3xl mx-auto py-10 px-4 sm:px-6 lg:px-8">
<header className="mb-8">
<h1 className="text-3xl font-bold tracking-tight text-gray-900">
How to help AI understand your content with JSON-LD
</h1>
<div className="mt-2 text-sm text-gray-500">
<time dateTime="2026-05-01T08:00:00+00:00">May 1, 2026</time>
</div>
</header>
<div className="prose prose-blue lg:prose-lg">
<p>
Correct data structure is foundational for effective interaction
with AI algorithms. Without it, crawlers fall back on basic NLP
text analysis.
</p>
<h2>Adding the markup</h2>
<p>
Using a built-in script of type <code>application/ld+json</code>{" "}
guarantees that search systems can identify entities on your page
without ambiguity.
</p>
</div>
</article>
</>
);
}How do you verify the markup without extra tools?
You don't need a local CLI or a SaaS to confirm your markup is valid. Three official steps are enough.
Step 1. Browser DevTools — instant presence check
Open the page, run this snippet in the console:
const blocks = document.querySelectorAll('script[type="application/ld+json"]');
console.log(`JSON-LD blocks found: ${blocks.length}`);
blocks.forEach((block, i) => {
try {
const parsed = JSON.parse(block.textContent);
console.group(`Block #${i + 1}`);
console.log(parsed);
if (parsed["@graph"]) {
const types = parsed["@graph"].map((item) => item["@type"]);
console.log("Entity types in @graph:", types);
} else if (parsed["@type"]) {
console.log("Entity type:", parsed["@type"]);
}
console.groupEnd();
} catch (err) {
console.error(`Block #${i + 1} contains invalid JSON:`, err.message);
}
});The snippet instantly shows: how many blocks there are, whether each parses, what entities it contains. If the counter reads zero — the extension was right, there's no markup. If JSON.parse throws — you have broken syntax, and no validator further down the line will help until you fix it.
Step 2. Schema Markup Validator — syntax and vocabulary
Visit validator.schema.org. It's the tool from the schema.org community itself. It checks JSON-LD syntax against the vocabulary, shows every entity it found, fields, and unknown properties. A baseline check, not tied to any specific search engine.
Step 3. Rich Results Test — Google's-eye view
Go to search.google.com/test/rich-results. Google's tool renders your page as Googlebot, executes JavaScript, and shows which rich results your content is potentially eligible for. This is where you catch issues Schema Validator misses: missing required fields for a specific type (for example, missing image on Article) or post-JS-render errors.
Order, and why it matters:
- DevTools snippet — confirm the blocks even reach the rendered page.
- Schema Markup Validator — verify syntax and vocabulary conformance.
- Rich Results Test — verify what Google sees after rendering.
Green across all three and your content is ready for AI Overviews, ChatGPT, Perplexity, and classic Google search to read it precisely — not paraphrase it approximately.
Which structured-data syntax should you use?
All three are valid to a parser. Only one is pleasant to maintain.
| JSON-LD | Microdata | RDFa | |
|---|---|---|---|
| Where it lives | One <script> in <head> |
Attributes on markup | Attributes on markup |
| Survives a redesign | Yes — decoupled from the DOM | No — breaks with the template | No |
| Google's recommendation | Preferred | Supported | Supported |
| Generated server-side | Trivially | Coupled to components | Coupled to components |
| Readable in one place | Yes | Scattered | Scattered |
The maintenance column is the whole argument. Microdata drifts the first time
someone reorders the markup and a itemprop ends up outside its itemscope —
a change that looks purely visual in review and silently removes the entity.
FAQ
Why does structured data matter more for AI than for search?
A search engine can rank a page it only half-understands, because a human then clicks through and reads it. A model has to restate the page in its own answer, so ambiguity becomes a wrong quote rather than a slightly worse ranking. JSON-LD removes the guessing: who wrote it, when, what type of thing it is.
Do I need both Article and FAQPage on the same page?
Yes, when the page is an article that contains a genuine FAQ section — put both
in one @graph rather than two competing scripts. The Article describes the
document; the FAQPage describes the question-and-answer pairs inside it. They
are different claims about the same URL.
What happens if the markup and the visible page disagree?
Google treats it as misleading structured data, which is a manual-action category, not a soft ranking signal. It is also the most common way FAQPage markup gets a site in trouble, because the answers are usually typed twice — once in the body, once in the schema — and the copies drift. Generate the markup from the visible text instead of alongside it.
How do I check my JSON-LD is actually valid?
Three passes, cheapest first: DevTools to confirm the script is in the served HTML at all, the Schema Markup Validator for vocabulary errors, and the Rich Results Test for what Google specifically will act on. The AEO Checker extension does the first pass on any page you open, including pages behind a login.
Sources
- schema.org/Article and schema.org/FAQPage — the vocabulary definitions
- Google Search Central: Article structured data — required and recommended fields
- Google Search Central: structured data general guidelines — the "content must match" rule and its penalties
- Google Search Central: changes to HowTo and FAQ rich results (August 2023) and the FAQPage reference carrying the 7 May 2026 retirement notice
- Schema Markup Validator · Rich Results Test
Part of the Answer Engine Optimization cluster — the full reading order in dependency sequence, plus a glossary of every term used across these articles.
Is your site still losing AI traffic to invisible content?
Follow me on LinkedIn to keep up with new AEO-architecture standards. If you're looking for an experienced architect for a platform audit, deep schema implementation, or headless-architecture optimization — get in touch for consulting.