agentsready
Content Accessibility Medium

Schema.org JSON-LD for AI: markup agents actually read

What Schema.org JSON-LD is, why it matters for AI and rich results, a minimal example, right vs wrong, mistakes, and how to verify.

Updated:

What it is

Schema.org is a vocabulary of types (Organization, Product, Article, FAQPage…) you use to describe a page’s content in a machine-readable way. The recommended format is JSON-LD inside a <script type="application/ld+json"> tag in the <head> or <body>.

Why it matters for AI agents

A human sees “price $19.90”; a machine sees plain text. JSON-LD states it explicitly: this is a Product, price 19.90, currency USD. AI engines and search engines use this markup for rich results (stars, prices, FAQs) and as grounding in AI Overviews / ChatGPT and Perplexity answers — structured facts are safer to cite.

Minimal working example

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "Example Inc.",
  "url": "https://example.com",
  "logo": "https://example.com/logo.png",
  "sameAs": [
    "https://www.linkedin.com/company/example",
    "https://github.com/example"
  ]
}
</script>

Right vs wrong

RightWrong
JSON-LD in <script type="application/ld+json">Legacy microdata/RDFa in attributes
Has @context and a valid @typeMissing @context — the markup is ignored
Markup matches the visible contentMarkup for prices/reviews not on the page (spam → penalties)
Valid JSONA trailing comma / bad quote — the parser drops the whole block

Common mistakes

  • Invalid JSON (trailing comma, single quotes) — one character breaks the whole block.
  • No @context: "https://schema.org" — without it the type isn’t recognised.
  • Markup ≠ content — review/price markup for things not on the page. Google penalises this.
  • Too generic a @type (Thing) instead of a specific one (Product, Article).
  • Duplicates of one type with conflicting data.

How to verify

A scan checks for JSON-LD and its basic validity. Going deeper:

curl -s https://example.com/ | grep -o 'application/ld+json'

Sources