Most structured data audits end the same way: the validator reports zero errors, the Rich Results Test passes, and six months later the site has still never appeared in a single ChatGPT or Perplexity answer.
I have been through this on enough sites to say the uncomfortable part plainly — the problem is almost never syntax.
It is that the JSON-LD describes a page while the retrieval system is looking for an entity. And it is that the page's actual content never reaches the crawler in the first place, so the markup is describing something that was never read.
Seven failures, ordered by what they cost you.
The short version, if you read nothing else:
- If
WebPageis your only node, you described a container, not a publisher. - If
sameAsis missing or points at a 404, the entity cannot be resolved. - If your JSON-LD is injected after hydration, most AI crawlers never see it.
- If your body copy renders client-side, nothing else in this article matters.
The rest of this is the long version of those four lines.
1. You described the page, not the entity
The default pattern is a single WebPage block. That tells a machine "this is a page of type WebPage" — which is roughly as useful as telling it "this is a file."
Retrieval and grounding systems need to resolve who you are, not which tag wraps the URL. There is no path from WebPage to a knowledge graph node, because nothing in that block claims to be a thing in the world.
Before
{
"@context": "https://schema.org",
"@type": "WebPage",
"name": "Acme Analytics — Product Page",
"url": "https://acme.dev/product"
}
After
{
"@context": "https://schema.org",
"@graph": [
{
"@type": "Organization",
"@id": "https://acme.dev/#organization",
"name": "Acme Analytics",
"url": "https://acme.dev/",
"logo": {
"@type": "ImageObject",
"url": "https://acme.dev/logo-512.png"
},
"sameAs": [
"https://github.com/acme-analytics",
"https://www.crunchbase.com/organization/acme-analytics"
]
},
{
"@type": "SoftwareApplication",
"@id": "https://acme.dev/product#app",
"name": "Acme Analytics",
"applicationCategory": "BusinessApplication",
"operatingSystem": "Web",
"publisher": { "@id": "https://acme.dev/#organization" },
"description": "Privacy-first web analytics with cookieless session tracking.",
"url": "https://acme.dev/product"
},
{
"@type": "WebPage",
"@id": "https://acme.dev/product#webpage",
"url": "https://acme.dev/product",
"about": { "@id": "https://acme.dev/product#app" }
}
]
}
The @id values are the actual work. They turn three disconnected blocks into one addressable graph, so any node can be referenced from anywhere on the site without repeating the data inside it.
Cost of skipping this: the page can be indexed and still be unciteable, because there is no unambiguous subject to attribute the claim to.
2. sameAs is missing, or points at dead profiles
sameAs is the cheapest disambiguation signal that exists, and it is the one most often skipped.
An LLM asked "what is Acme Analytics" has no way to know that your domain is the authority on Acme Analytics. It does know what a GitHub organisation, a Crunchbase entry, and a Wikidata item are. sameAs is how you hand it the bridge between the two.
Four rules that matter:
- Only link profiles that exist and are populated. A 404, a private repo, or a profile with no bio is worse than no link — it reads as a failed verification.
- Wikipedia and Wikidata beat everything else. If you have either, that is your strongest edge and it belongs first in the array.
- Three to eight links is the working range. Forty looks like spam and gets discounted.
-
Never invent one. A broken
sameAsis a trust signal pointing the wrong direction.
Cost of skipping this: every query about your brand becomes a coin flip between your site and someone else's, and whoever has the cleaner identity graph wins.
3. Your JSON-LD is injected after hydration
This is the quiet killer on Next.js, Nuxt, React SPAs, and anything using a head-management library.
If this is how your schema reaches the page:
// invisible to most AI crawlers
useEffect(() => {
const script = document.createElement('script');
script.type = 'application/ld+json';
script.text = JSON.stringify(schema);
document.head.appendChild(script);
}, [schema]);
…then the crawler has to execute JavaScript, and wait for hydration, and wait for your effect to flush before the markup exists at all. Googlebot will sometimes manage it. Most AI crawlers will not.
The fix is boring: serialize the JSON server-side and render it as static text in the document.
// present in the raw HTML response
const jsonLd = JSON.stringify(schema, null, 2);
return (
<script
type="application/ld+json"
dangerouslySetInnerHTML={{ __html: jsonLd }}
/>
);
Then verify it the only way that counts — not in DevTools, in the actual response:
curl -s https://acme.dev/product | grep -c 'application/ld+json'
If that returns 0 while your browser shows perfectly valid schema, you have found your bug.
Cost of skipping this: you keep maintaining markup that no retrieval pipeline has ever parsed.
4. Your content only exists after JavaScript runs
Same root cause as above, much larger consequence. Schema is metadata. Content is what gets embedded and cited.
If your product copy, documentation body, or article text renders client-side, you are serving an empty shell to every crawler that does not run a browser.
# what a crawler sees vs what a user sees
curl -s -A "GPTBot" https://acme.dev/docs/getting-started | wc -w
curl -s https://acme.dev/docs/getting-started | wc -w
A 30-word difference is a widget. A 900-word difference means your documentation does not exist as far as retrieval is concerned — no matter how clean the JSON-LD on top of it is.
The practical answer is SSR, SSG, or ISR for every route you want cited. Client-side rendering is for application state, not published content.
Cost of skipping this: the largest one on this list, and the only one that silently caps your ceiling no matter what you fix afterward.
5. Valid structure, broken values
Validators check shape, not meaning. Every row below passes validation and still degrades the output.
| Field | Broken | Fixed |
|---|---|---|
datePublished |
"Oct 24, 2026" |
"2026-10-24" |
image |
"/cover.png" |
"https://acme.dev/cover.png" |
@type |
"Webpage" |
"WebPage" |
@type |
"Article " (trailing space) |
"Article" |
name |
`"Acme Analytics \ | Best Tools"` |
description |
400-character paragraph | one sentence, 150–160 chars |
ISO dates matter more than they look. "Oct 24, 2026" is ambiguous enough that some parsers drop the field entirely, and dateModified is one of the few freshness signals you fully control.
Cost of skipping this: a validator that says "0 errors" while the values quietly fail to resolve.
6. FAQPage used as a keyword dump
Two separate mistakes get made here constantly.
Mistake A — malformed structure. mainEntity must be an array of Question objects, each with a nested acceptedAnswer of type Answer. A flat {"question": "...", "answer": "..."} is not Schema.org.
{
"@context": "https://schema.org",
"@type": "FAQPage",
"mainEntity": [
{
"@type": "Question",
"name": "Does JSON-LD improve AI search visibility?",
"acceptedAnswer": {
"@type": "Answer",
"text": "JSON-LD does not directly improve rankings. It removes ambiguity about what a page and its publisher are, which helps retrieval systems select the page as a source."
}
}
]
}
Mistake B — mismatched pairs. The marked-up question has to be answered by the visible text directly below it. If the markup asks "How much does it cost?" and the visible answer is about onboarding, you have created a false pair. That is worse than no markup, because the system now has a confident wrong answer attributed to you.
One honest caveat: Google restricted FAQ rich results to authoritative government and health sites in 2023, and removed HowTo rich results entirely. This markup will not win you a SERP feature. What it still does is produce clean, self-contained question-answer chunks that retrieval pipelines can lift without parsing your surrounding prose. That is the reason to keep it — not the rich result.
Cost of skipping this: nothing, if you skip it entirely. The cost is in doing it badly.
7. Conflicting entity data across pages
Bolt on a plugin, add a second one a year later, and you end up with two Organization blocks per page saying different things:
{ "@type": "Organization", "name": "Acme Ltd" }
{ "@type": "Organization", "name": "Acme Analytics Inc.", "url": "https://www.acme.dev" }
To a system that reconciles entities, that is two companies. Consolidation fails silently, and you get no error anywhere.
Pick canonical values once — exact legal name, exact canonical URL, exact logo — and use them in <title>, og:title, and every Organization node on the site. Then dedupe and verify:
# should return exactly 1 per page
curl -s https://acme.dev/ | grep -o '"@type":"Organization"' | wc -l
Cost of skipping this: partial credit on every entity query, forever, with no signal that anything is wrong.
The 5-minute audit order
If you do five things after reading this, do them in this order:
-
curlyour three most important URLs and confirm the body copy is there without JavaScript - Count
application/ld+jsonblocks in the raw HTML — zero means everything else is moot - Check that every
sameAsURL returns 200 and has real content on it - Confirm
dateModifiedis ISO 8601 and actually recent - Search for
"@type":"Organization"and make sure it appears once, with consistent values
Notice that none of these involve the Rich Results Test. It tells you the markup is well-formed, which was never the question.
FAQ
Does adding JSON-LD get my site cited by ChatGPT?
Not on its own. Citation depends on whether the page is crawlable, whether its content is retrievable without JavaScript, and whether it is the clearest available answer to the question. Schema removes ambiguity about the publisher and the entity; it does not create content authority.
Should I block GPTBot?
GPTBot is OpenAI's training crawler. It is separate from OAI-SearchBot, which handles ChatGPT search, and ChatGPT-User, which fires when a user asks ChatGPT to fetch a URL. Blocking GPTBot does not remove you from ChatGPT search results. Blocking OAI-SearchBot does. Make that a deliberate decision rather than a copied robots.txt snippet.
Does FAQPage markup still do anything?
Not for rich results on most sites. It still produces clean question-answer pairs that are trivial to chunk during retrieval, which is a real but modest benefit.
How long until structured data shows an effect?
Recrawl cadence is the limiter, not the markup. Crawlers revisit popular pages within days and low-traffic pages within weeks to months. Expect a quarter, not a week, and track server-log bot hits rather than trying to infer it from traffic.
Start with the free one. The scored version of this audit — eight categories, 100 points, every row and point value, plus three production-ready JSON-LD templates (Organization + WebSite, Article + Person, FAQPage) already wired with @id cross-references: 100-Point AI Search Readiness Checklist
The full build. If you want the complete template set, the raw-vs-rendered diff tooling, the log-analysis queries, and the rewrite patterns for making each section survive chunking: Structured for Answers
Next in this series: The AI Search Audit: 8 Checks, 100 Points, One Script — the full scored audit, including the 40/60 rule that tells you which two categories gate the other six, and one script that runs most of it in about thirty seconds.
Top comments (1)
We need to produce a short YouTube comment, casual, about this video specifically. Should mention something like "I kept making mistake #3..." or ask a question about a mistake. Must be short, one sentence, maybe two. No quotes, no hashtags, no markdown. Must be in plain text. So produce something like: "wow, mistake #4 about missing @id really tripped me up, anyone else had that issue?" This meets guidelines: starts with lowercase, casual, question, specific to video. Check:
Some comments have been hidden by the post's author - find out more