{ "slug": "structured-data-for-ai-agents", "title": "Structured Data for AI Agents: Which Schema.org Types Earn Their Keep", "description": "Most schema.org markup is invisible to machine readers. The types that are worth the effort for AI agents, how to emit them without drift, and what to build instead of more markup.", "kind": "sub", "order": 8, "target_query": "schema.org structured data for AI agents", "secondary_queries": [ "json-ld for llm consumption", "which schema types matter for AI", "structured data vs json api for agents" ], "tags": [ "structured-data", "schema.org", "json-ld", "ai-visibility", "seo" ], "published": "2026-07-26", "updated": "2026-07-26", "words": 1148, "premium": false, "license": "https://changegamer.ai/license.xml", "canonical": "https://changegamer.ai/articles/structured-data-for-ai-agents", "markdown": "https://changegamer.ai/articles/structured-data-for-ai-agents.md", "takeaways": [ "Structured data helps machine readers most where it states facts the prose leaves implicit: dates, prices, authorship, identity, licence.", "A short, correct graph beats a long, aspirational one. Four accurate types are worth more than twenty types with placeholder values.", "Emit JSON-LD from the same source that renders the page. Hand-written markup drifts from the visible content, and contradiction is worse than absence.", "Never mark up something that is not visible on the page. It is a policy violation for search rich results and it makes the whole graph untrustworthy to any consumer.", "If the thing you are marking up is really data — a catalogue, prices, availability — publish a JSON endpoint. Structured data is a description of a page; an API is the data itself." ], "outline": [ { "depth": 2, "text": "What structured data is actually good at", "anchor": "what-structured-data-is-actually-good-at", "url": "https://changegamer.ai/articles/structured-data-for-ai-agents#what-structured-data-is-actually-good-at" }, { "depth": 2, "text": "The types that earn their keep", "anchor": "the-types-that-earn-their-keep", "url": "https://changegamer.ai/articles/structured-data-for-ai-agents#the-types-that-earn-their-keep" }, { "depth": 2, "text": "The types that usually are not worth it", "anchor": "the-types-that-usually-are-not-worth-it", "url": "https://changegamer.ai/articles/structured-data-for-ai-agents#the-types-that-usually-are-not-worth-it" }, { "depth": 2, "text": "Emit it from one source, or it will lie", "anchor": "emit-it-from-one-source-or-it-will-lie", "url": "https://changegamer.ai/articles/structured-data-for-ai-agents#emit-it-from-one-source-or-it-will-lie" }, { "depth": 2, "text": "Practical rules", "anchor": "practical-rules", "url": "https://changegamer.ai/articles/structured-data-for-ai-agents#practical-rules" }, { "depth": 2, "text": "Where structured data stops and APIs start", "anchor": "where-structured-data-stops-and-apis-start", "url": "https://changegamer.ai/articles/structured-data-for-ai-agents#where-structured-data-stops-and-apis-start" }, { "depth": 2, "text": "Adjacent: provenance markup", "anchor": "adjacent-provenance-markup", "url": "https://changegamer.ai/articles/structured-data-for-ai-agents#adjacent-provenance-markup" }, { "depth": 2, "text": "A 45-minute pass on an existing site", "anchor": "a-45-minute-pass-on-an-existing-site", "url": "https://changegamer.ai/articles/structured-data-for-ai-agents#a-45-minute-pass-on-an-existing-site" } ], "faq": [ { "question": "Do LLMs read JSON-LD?", "answer": "When a model or its retrieval pipeline processes raw HTML, the JSON-LD block is part of what it sees, and it is the cleanest statement of facts on the page. Vendors do not publish how much weight it carries, so treat it as a cheap way to make facts unambiguous rather than as a ranking lever." }, { "question": "Which types should I add first?", "answer": "The ones that describe what your page actually is: `Article`/`TechArticle` for content, `Product`/`Offer` for anything priced, `BreadcrumbList` for hierarchy, `Organization` for identity, and `FAQPage` where you genuinely have questions and answers. Then stop and check they are correct before adding more." }, { "question": "Is FAQPage markup still worth adding?", "answer": "For rich results, treatment has varied by search engine and changed over time, so do not count on visual gains. As a machine-readable statement of question-answer pairs it is still useful, provided the questions and answers are visible on the page and are real questions rather than keyword shims." }, { "question": "Should structured data duplicate the page content?", "answer": "It should describe it, not restate it. Titles, dates, identifiers, prices, authorship and relationships belong in the graph; the body does not. Duplicating whole articles into JSON-LD bloats every fetch for no gain." } ], "body": "Structured data is the oldest machine-readable layer on the web and the one where effort is most often misspent. This page is about the subset that is worth doing for machine consumers, as part of [the agent-ready website](/articles/agent-ready-website).\n\n## What structured data is actually good at\n\nA model reading your prose can usually work out what a page is about. What it cannot reliably work out is the *metadata*: when this was last revised, who published it, what the price is, which currency, whether it is free, what it is part of, and what licence applies. Those are exactly the facts a JSON-LD block states unambiguously.\n\nSo the useful mental model is not \"markup for rich results\". It is: **a machine-readable fact sheet attached to a human-readable page.** Judge every type you consider adding by whether it states a fact the prose leaves implicit.\n\n## The types that earn their keep\n\n| Type | Use for | Facts it pins down |\n|---|---|---|\n| `Article` / `TechArticle` | Any content page | headline, description, `dateModified`, language, keywords, `isAccessibleForFree` |\n| `BreadcrumbList` | Pages inside a hierarchy | where this page sits; extra crawl paths into hubs |\n| `Organization` | Site-wide identity | who publishes this, canonical URL, sameAs identities |\n| `WebSite` + `SearchAction` | Homepage | the site as an entity; how to search it |\n| `Product` + `Offer` | Anything with a price | price, currency, availability, SKU, seller, subscription vs one-time |\n| `FAQPage` | Real question/answer sections | Q/A pairs as discrete, quotable units |\n| `HowTo` | Genuinely sequential procedures | ordered steps with names and text |\n| `Dataset` | Downloadable data | distribution URLs, formats, licence |\n| `CollectionPage` + `hasPart` | Index and hub pages | the set of things this page indexes |\n\nTwo of these are underused and disproportionately valuable to machine buyers:\n\n- **`Product`/`Offer` on pricing pages.** If you want an agent to be able to compare your offer without parsing a table, this is the cheapest way to say it. Pair it with a JSON pricing endpoint for the machine-first path.\n- **`isAccessibleForFree`** on `Article`. It is one boolean and it tells a crawler whether what it just fetched is the whole thing. Combined with a 402 gate, it makes your access model self-describing.\n\n## The types that usually are not worth it\n\n- **Deep `Person` graphs for every author** unless authorship is genuinely part of your value.\n- **`Review`/`AggregateRating` you generated yourself.** Fabricated or self-serving ratings are a policy problem and a trust problem.\n- **`Event`, `Recipe`, `JobPosting` and friends** when you do not have those things. Aspirational markup is the fastest way to make your graph unreliable.\n- **`speakable`** — narrow applicability, little published consumption.\n- **Marking up navigation.** `SiteNavigationElement` describes your menu. Nobody needs your menu described.\n\n## Emit it from one source, or it will lie\n\nThe failure mode is always the same: markup written once by hand, content edited later, and now the graph says the price is €19 while the page says €29. A machine consumer that catches a contradiction has no way to resolve it and every reason to distrust the rest.\n\nDerive the graph from the same data that renders the page:\n\n```ts\n// One source of truth → visible page AND graph\nconst jsonld = {\n \"@context\": \"https://schema.org\",\n \"@graph\": [\n {\n \"@type\": \"TechArticle\",\n headline: page.title, // same field the

renders\n description: page.description, // same field the meta tag renders\n dateModified: page.updated, // same field the byline renders\n inLanguage: \"en\",\n isAccessibleForFree: !page.premium,\n keywords: page.tags.join(\", \"),\n isPartOf: { \"@type\": \"WebSite\", name: SITE.name, url: SITE.url },\n publisher: { \"@type\": \"Organization\", name: SITE.name, url: SITE.url },\n },\n {\n \"@type\": \"BreadcrumbList\",\n itemListElement: trail.map((t, i) => ({\n \"@type\": \"ListItem\", position: i + 1, name: t.name, item: t.url,\n })),\n },\n ],\n};\n```\n\nThen add a CI assertion that the graph's `headline` equals the page's `

` and its `dateModified` equals the rendered date. Two assertions catch nearly every drift bug this layer produces.\n\n## Practical rules\n\n1. **JSON-LD, in ``.** Microdata and RDFa still work but are harder to keep consistent and harder to diff in review.\n2. **One `@graph` per page, not five script tags.** Consumers that only read the first block will otherwise miss most of what you said.\n3. **Stable `@id`s** for anything referenced twice (offers, organisations), scoped to the page URL.\n4. **Absolute URLs everywhere.** A relative `url` in a graph consumed out of context resolves to nothing.\n5. **Only mark up what is on the page.** This is both a search-engine policy requirement and the difference between a fact sheet and a claim sheet.\n6. **Validate on every build,** not once at launch. A schema error introduced by a template change is otherwise invisible for months.\n\n## Where structured data stops and APIs start\n\nThe boundary is worth stating plainly, because a lot of effort goes into forcing data through markup that would be better published directly.\n\n| You have | Publish as | Why |\n|---|---|---|\n| A page about a thing | JSON-LD on that page | It describes the page a client already fetched |\n| A list of things that changes | JSON endpoint | An index in markup means fetching HTML to get data |\n| Prices and tiers | Both | Markup for the crawler on the page, endpoint for the machine buyer |\n| A corpus | NDJSON / one-file export | Per-page markup cannot express a dataset |\n| A changelog | Atom/JSON Feed | Feeds exist for \"what changed\", and pollers already understand them |\n\nThe API side of this is [JSON API design for agents](/articles/json-api-design-for-agents), and the format decision — Markdown for prose, JSON for records, NDJSON for corpora — is worked through in [data formats and schema](/resources/data-formats).\n\n## Adjacent: provenance markup\n\nSchema.org states facts; it does not prove them. Where authenticity matters — images, documents, anything that could be fabricated — C2PA Content Credentials cryptographically bind assertions about origin and edit history to the asset itself. That is a different guarantee from a JSON-LD `author` field, and the two are complementary: see [C2PA content credentials](/resources/c2pa-content-credentials).\n\n## A 45-minute pass on an existing site\n\n1. Pick your highest-value template. Check whether it emits any graph at all.\n2. Add or fix `Article`/`TechArticle` with a real `dateModified` sourced from your content, not the build clock.\n3. Add `BreadcrumbList` matching the visible breadcrumb.\n4. Add `Organization` and `WebSite` once, site-wide.\n5. On priced pages, add `Product` + `Offer` generated from your price data.\n6. Delete every type that describes something you do not have.\n7. Add two CI assertions: graph headline matches `

`, graph date matches rendered date.\n\nThat sequence takes under an hour on most codebases and leaves you with a graph that is small, correct and — because it is generated — still correct next quarter.", "cluster": { "id": "agent-ready-web", "title": "The agent-ready web", "description": "How to make a website readable, citable, controllable and payable for AI agents and AI crawlers — the operator side of the machine-first web.", "status": "complete", "pillar": { "slug": "agent-ready-website", "title": "The Agent-Ready Website: A Complete Guide to AI Visibility, Access Control and Monetization", "description": "The full operator playbook for making a website work for AI agents and AI crawlers: be fetchable, be readable, be controllable, be payable — with a 30-day implementation plan.", "kind": "pillar", "order": 0, "html": "https://changegamer.ai/articles/agent-ready-website", "markdown": "https://changegamer.ai/articles/agent-ready-website.md", "json": "https://changegamer.ai/api/articles/agent-ready-website.json" }, "articles": [ { "slug": "llms-txt-vs-robots-txt-vs-sitemap", "title": "llms.txt vs robots.txt vs sitemap.xml: Which File Does What", "description": "The three root-level files every agent-ready site publishes, what each one is actually for, and why publishing one does not substitute for the others.", "kind": "sub", "order": 1, "html": "https://changegamer.ai/articles/llms-txt-vs-robots-txt-vs-sitemap", "markdown": "https://changegamer.ai/articles/llms-txt-vs-robots-txt-vs-sitemap.md", "json": "https://changegamer.ai/api/articles/llms-txt-vs-robots-txt-vs-sitemap.json" }, { "slug": "how-to-write-an-llms-txt-file", "title": "How to Write an llms.txt File (Format, Template, and Maintenance)", "description": "A step-by-step guide to writing a useful llms.txt: the exact format, a copy-paste template, what to put under ## Optional, how to validate it, and how to keep it from rotting.", "kind": "sub", "order": 2, "html": "https://changegamer.ai/articles/how-to-write-an-llms-txt-file", "markdown": "https://changegamer.ai/articles/how-to-write-an-llms-txt-file.md", "json": "https://changegamer.ai/api/articles/how-to-write-an-llms-txt-file.json" }, { "slug": "serving-markdown-variants-to-ai-agents", "title": "Serving Markdown Variants to AI Agents: The Cheapest Win in AI Visibility", "description": "How to publish a .md twin of every page — URL patterns, content negotiation, discovery headers, generation pitfalls — and why it cuts what an agent pays to read you.", "kind": "sub", "order": 3, "html": "https://changegamer.ai/articles/serving-markdown-variants-to-ai-agents", "markdown": "https://changegamer.ai/articles/serving-markdown-variants-to-ai-agents.md", "json": "https://changegamer.ai/api/articles/serving-markdown-variants-to-ai-agents.json" }, { "slug": "how-ai-search-engines-choose-sources", "title": "How AI Search Engines Choose Sources (And What You Can Actually Influence)", "description": "What is known, what is claimed and what is speculation about how ChatGPT, Perplexity and AI Overviews pick the pages they cite — and the short list of things a site owner can actually control.", "kind": "sub", "order": 4, "html": "https://changegamer.ai/articles/how-ai-search-engines-choose-sources", "markdown": "https://changegamer.ai/articles/how-ai-search-engines-choose-sources.md", "json": "https://changegamer.ai/api/articles/how-ai-search-engines-choose-sources.json" }, { "slug": "should-you-block-ai-crawlers", "title": "Should You Block AI Crawlers? A Decision Framework by Business Model", "description": "Blocking AI crawlers is four separate decisions, not one. A framework that maps each crawler class to what it costs and earns you, by business model, with the exact robots.txt for each answer.", "kind": "sub", "order": 5, "html": "https://changegamer.ai/articles/should-you-block-ai-crawlers", "markdown": "https://changegamer.ai/articles/should-you-block-ai-crawlers.md", "json": "https://changegamer.ai/api/articles/should-you-block-ai-crawlers.json" }, { "slug": "what-to-charge-ai-crawlers", "title": "What to Charge AI Crawlers: Pricing Models for Machine Buyers", "description": "Per-crawl, per-resource, corpus licence or subscription key — the four ways to price AI access, the arithmetic behind each, and why pricing before you have demand data is the standard mistake.", "kind": "sub", "order": 6, "html": "https://changegamer.ai/articles/what-to-charge-ai-crawlers", "markdown": "https://changegamer.ai/articles/what-to-charge-ai-crawlers.md", "json": "https://changegamer.ai/api/articles/what-to-charge-ai-crawlers.json" }, { "slug": "http-402-paywall-implementation", "title": "Implementing an HTTP 402 Paywall an Agent Can Actually Pay", "description": "A working implementation guide for machine-payable content: the 402 response body, Link headers, key issuance and validation, caching rules, and the mistakes that make a 402 gate unpayable.", "kind": "sub", "order": 7, "html": "https://changegamer.ai/articles/http-402-paywall-implementation", "markdown": "https://changegamer.ai/articles/http-402-paywall-implementation.md", "json": "https://changegamer.ai/api/articles/http-402-paywall-implementation.json" }, { "slug": "structured-data-for-ai-agents", "title": "Structured Data for AI Agents: Which Schema.org Types Earn Their Keep", "description": "Most schema.org markup is invisible to machine readers. The types that are worth the effort for AI agents, how to emit them without drift, and what to build instead of more markup.", "kind": "sub", "order": 8, "html": "https://changegamer.ai/articles/structured-data-for-ai-agents", "markdown": "https://changegamer.ai/articles/structured-data-for-ai-agents.md", "json": "https://changegamer.ai/api/articles/structured-data-for-ai-agents.json" }, { "slug": "json-api-design-for-agents", "title": "JSON API Design for AI Agents: Endpoints They Prefer Over Scraping", "description": "How to publish read-only JSON endpoints that agents choose over scraping your HTML: discovery index, stable shapes, freshness signals, bulk exports, and errors a machine can act on.", "kind": "sub", "order": 9, "html": "https://changegamer.ai/articles/json-api-design-for-agents", "markdown": "https://changegamer.ai/articles/json-api-design-for-agents.md", "json": "https://changegamer.ai/api/articles/json-api-design-for-agents.json" }, { "slug": "measuring-ai-agent-traffic", "title": "Measuring AI Agent Traffic: Server-Side Telemetry That Answers Real Questions", "description": "Why client-side analytics miss AI agents entirely, the minimum row schema to log, the five queries worth running, and how to tell a real crawler from a spoofed user agent.", "kind": "sub", "order": 10, "html": "https://changegamer.ai/articles/measuring-ai-agent-traffic", "markdown": "https://changegamer.ai/articles/measuring-ai-agent-traffic.md", "json": "https://changegamer.ai/api/articles/measuring-ai-agent-traffic.json" }, { "slug": "licensing-content-for-ai-training", "title": "Licensing Content for AI Training: RSL, Terms, and Provenance", "description": "How to publish machine-readable licence terms for AI use — what RSL is, what it does and does not do, how it differs from robots.txt and Content Signals, and where provenance standards fit.", "kind": "sub", "order": 11, "html": "https://changegamer.ai/articles/licensing-content-for-ai-training", "markdown": "https://changegamer.ai/articles/licensing-content-for-ai-training.md", "json": "https://changegamer.ai/api/articles/licensing-content-for-ai-training.json" }, { "slug": "mcp-server-as-distribution-channel", "title": "Running an MCP Server as a Distribution Channel for Your Content", "description": "Why a content site should expose an MCP server, which tools to ship, how discovery and authentication work, how to gate paid tools, and the honest limits of the channel.", "kind": "sub", "order": 12, "html": "https://changegamer.ai/articles/mcp-server-as-distribution-channel", "markdown": "https://changegamer.ai/articles/mcp-server-as-distribution-channel.md", "json": "https://changegamer.ai/api/articles/mcp-server-as-distribution-channel.json" }, { "slug": "why-ai-agents-cant-read-your-site", "title": "Why AI Agents Can't Read Your Site: Twelve Failure Modes and How to Find Them", "description": "A diagnostic catalogue of the twelve reasons AI agents and crawlers fail on real sites — from silent WAF blocks to JS-only rendering — each with the command that detects it and the fix.", "kind": "sub", "order": 13, "html": "https://changegamer.ai/articles/why-ai-agents-cant-read-your-site", "markdown": "https://changegamer.ai/articles/why-ai-agents-cant-read-your-site.md", "json": "https://changegamer.ai/api/articles/why-ai-agents-cant-read-your-site.json" } ] }, "navigation": { "pillar": { "slug": "agent-ready-website", "title": "The Agent-Ready Website: A Complete Guide to AI Visibility, Access Control and Monetization", "description": "The full operator playbook for making a website work for AI agents and AI crawlers: be fetchable, be readable, be controllable, be payable — with a 30-day implementation plan.", "kind": "pillar", "order": 0, "html": "https://changegamer.ai/articles/agent-ready-website", "markdown": "https://changegamer.ai/articles/agent-ready-website.md", "json": "https://changegamer.ai/api/articles/agent-ready-website.json" }, "previous": { "slug": "http-402-paywall-implementation", "title": "Implementing an HTTP 402 Paywall an Agent Can Actually Pay", "description": "A working implementation guide for machine-payable content: the 402 response body, Link headers, key issuance and validation, caching rules, and the mistakes that make a 402 gate unpayable.", "kind": "sub", "order": 7, "html": "https://changegamer.ai/articles/http-402-paywall-implementation", "markdown": "https://changegamer.ai/articles/http-402-paywall-implementation.md", "json": "https://changegamer.ai/api/articles/http-402-paywall-implementation.json" }, "next": { "slug": "json-api-design-for-agents", "title": "JSON API Design for AI Agents: Endpoints They Prefer Over Scraping", "description": "How to publish read-only JSON endpoints that agents choose over scraping your HTML: discovery index, stable shapes, freshness signals, bulk exports, and errors a machine can act on.", "kind": "sub", "order": 9, "html": "https://changegamer.ai/articles/json-api-design-for-agents", "markdown": "https://changegamer.ai/articles/json-api-design-for-agents.md", "json": "https://changegamer.ai/api/articles/json-api-design-for-agents.json" } }, "resources": [ { "slug": "data-formats", "html": "https://changegamer.ai/resources/data-formats", "markdown": "https://changegamer.ai/resources/data-formats.md", "json": "https://changegamer.ai/api/resources/data-formats.json" }, { "slug": "json-api", "html": "https://changegamer.ai/resources/json-api", "markdown": "https://changegamer.ai/resources/json-api.md", "json": "https://changegamer.ai/api/resources/json-api.json" }, { "slug": "llms-txt-explained", "html": "https://changegamer.ai/resources/llms-txt-explained", "markdown": "https://changegamer.ai/resources/llms-txt-explained.md", "json": "https://changegamer.ai/api/resources/llms-txt-explained.json" }, { "slug": "c2pa-content-credentials", "html": "https://changegamer.ai/resources/c2pa-content-credentials", "markdown": "https://changegamer.ai/resources/c2pa-content-credentials.md", "json": "https://changegamer.ai/api/resources/c2pa-content-credentials.json" } ] }