JSON-LD for AI: why entity clarity beats keyword density for being understood

JSON-LD does not make an AI cite you — controlled tests, including an Ahrefs study across four separate experiments in 2025, found no significant citation lift from adding schema. What it does do is decide whether the model gets your facts right once it has already chosen you: which company you are, which product, which price. That is a confirmation job, not a discovery job, and confusing the two is why most schema advice overpromises.

The difference stopped being academic for us while building the product audit inside Contexta, where we kept meeting stores whose schema was immaculate and whose AI-generated descriptions were still wrong. Working from a site's own Search Console data makes the pattern hard to miss: the pages losing on AI surfaces were rarely losing for lack of markup. What follows is what the evidence actually supports, the layer model that reconciles the contradictory studies, and the one rule that makes JSON-LD pay off at all.

Does JSON-LD schema actually get you cited by AI?

On the current evidence, no — schema markup shows no measurable effect on whether an AI engine cites a page. Two independent 2025–2026 analyses tested it directly and found nothing, while the widely-quoted statistics in favour of schema are correlations that don't survive scrutiny.

That SE Ranking figure is the one you'll see quoted as proof, and it's the weakest item in the table. Pages carrying structured data are overwhelmingly pages from sites that also have clean HTML, server-rendered content, real authority and an editorial process — the markup rides along with a dozen other things that do drive citation. Note too what the one platform confirmation actually claims: Microsoft said schema aids understanding, not ranking. Read carefully, the boosters and the skeptics are describing different variables.

What does schema actually do for an LLM, then?

It confirms and disambiguates facts the model has already extracted from your visible text — acting as a machine-readable second opinion rather than a route into the answer. An LLM building a response has to resolve which entity your page describes and which specific values attach to it, and unstructured prose is genuinely ambiguous about both.

Eligibility

Can the crawler fetch the page at all? Robots, Cloudflare, server response. Nothing else matters until this passes.

Delivery

Does the visible, JavaScript-free text contain the fact? This is what retrieval embeds and what the model quotes.

Confirmation

Does structured data agree with the text? Resolves ambiguity, pins identity, corrects near-misses.

The layer model explains the contradictory studies cleanly. Ahrefs and Search Atlas measured citation rate — a retrieval outcome, which lives on layers one and two, so schema was never going to move it. Microsoft described comprehension — a layer-three outcome. Both results are correct; they were measuring different things. The practical consequence is that schema is a quality multiplier on traffic you already earn, not a lever for earning it.

Why doesn't keyword density matter to an AI reading your page?

Because retrieval matches meaning through embeddings rather than counting term occurrences, so repeating a phrase adds no signal while genuinely ambiguous entities cost you real accuracy. A page saying "premium leather bags" nine times is not more retrievable than one saying it once; a page that never establishes which brand, model or price it refers to is measurably harder for a model to represent correctly.

That trade is the whole argument for entity clarity over density. Density optimises for a matching algorithm that no longer runs; entity clarity optimises for a model that must decide whether your "Atlas 3" is the backpack, the software, or the mountaineering company. The clearer the entity, the smaller the chance your page gets merged with a namesake — a shift that runs through everything about how writing for AI differs from writing for search rankings.

Can an AI even see your JSON-LD?

Often not — JSON-LD lives inside a <script type="application/ld+json"> block, and many text-extraction pipelines strip script tags before the content ever reaches the model. Whether your markup is read depends entirely on whether a given system fetches raw HTML or a cleaned text rendering, and you don't get to choose which.

This is the mechanism most schema guides skip, and it's the practical reason the null results are unsurprising. Four failure modes we hit repeatedly on real WooCommerce stores:

• Client-side injection. A plugin writes the JSON-LD after page load, so a raw-HTML fetch sees an empty document. The browser renders it perfectly and every validator passes — the same class of blindness that makes JavaScript-dependent content invisible to AI crawlers.
• Duplicate conflicting blocks. Theme and SEO plugin each emit a Product, with different prices. A parser taking the first block gets whichever loaded first.
• Silent drift after a sale. The displayed price updates, the schema offers block keeps the old figure. Nothing errors; the store just publishes two prices.
• Validator-clean, meaning-empty. A Product with no brand, no gtin, no sku validates fine and identifies nothing.

None of these throw warnings in Google's Rich Results Test, because that tool checks syntax against a spec — not whether the values are true, current, or reachable by a text extractor.

Which schema fields actually resolve your entity?

The identity fields, not the descriptive ones: sameAs, @id, brand, gtin and sku do the disambiguation work, while description and keywords contribute almost nothing a model can't already read from your page. Identity fields answer "which thing is this," and that is the only question prose is genuinely bad at answering.

sameAs is the highest-leverage of them because it points at entities that already exist in external knowledge bases — a Wikidata entry, a Crunchbase profile, an official brand page — letting a model anchor you to a known node instead of guessing. For products, a real gtin does the same job in the commerce graph, which is why barcodes matter more to AI agents than they ever did to shoppers. A business with no catalog anchors the same way through its listings instead, which is most of what AI visibility for a local service business comes down to.

This is the gap Contexta's Commerce Readiness audit checks for: it walks every WooCommerce product and flags the ones missing the identity data agents need — image, price, GTIN, brand, weight — with a link straight to the product that's missing each field. It won't argue that filling those fields earns citations; it makes sure that when an agent does read your catalog, there's an unambiguous product on the other end.

What's the one rule that makes schema pay off?

Never let a fact exist only in your structured data — every value in the JSON-LD must also appear in the visible, JavaScript-free text of the page. If the extractor strips your script block, a fact that lives nowhere else simply doesn't exist, and if the two copies disagree, you've taught the model that your site is unreliable about its own details.

The rule that survives every pipeline

Write the fact in the visible text first, then mirror it in JSON-LD.

Schema confirms what the page already says. It is a second copy of the truth, never the only copy.

When prose, schema and feed disagree, the model doesn't pick a winner — it lowers confidence in all three.

The failure mode that follows is worth stating plainly: consistency matters more than completeness. A minimal Product block whose price matches the page and the merchant feed beats an exhaustive one that contradicts them, because contradiction is an active signal while absence is merely neutral. That's the same arithmetic behind why AI writes the wrong price into product descriptions — three copies of a number are three chances to disagree.

Honest limit on all of this, as of mid-2026: schema's real payoff is insurance, and insurance is hard to see working. You will not watch citations climb after a markup pass. What you should see instead is fewer wrong prices, fewer merged identities and fewer AI answers describing a product you stopped selling — improvements that only show up if you were measuring accuracy rather than volume.