{"slug": "json-ld-structured-data-tell-agents-what-a-page-is", "title": "JSON-LD Structured Data: Tell Agents What a Page Is", "summary": "JSON-LD structured data embedded in web pages provides unambiguous typed facts that AI agents can extract deterministically, improving semantic signal density and reducing inference errors. The article explains how to implement JSON-LD using Schema.org vocabulary, validate it, and avoid common mistakes like client-side injection or mismatched data.", "body_md": "*Part of the Agent Readiness course. Measure any page with the Core Agent Vitals analyzer.*\n\n## What it is\n\nJSON-LD is a small block of JSON, embedded in a `<script type=\"application/ld+json\">`\n\ntag, that describes a page using the shared vocabulary at [Schema.org](https://schema.org): `Organization`\n\n, `Product`\n\n, `Article`\n\n, `LocalBusiness`\n\n, `FAQPage`\n\n, and hundreds more. It states, in typed fields, what the page *is* — name, price, author, rating, hours, address — separate from how it's rendered.\n\n## Why agents need it\n\nA human reads a product page and understands \"$49, 4.5 stars, in stock\" from layout and context. An agent working from your HTML has to *infer* all of that from prose and markup — and inference is lossy. Is \"49\" a price, a SKU, a quantity? Structured data removes the guessing:\n\n```\n{ \"@type\": \"Product\", \"name\": \"Acme Widget\", \"offers\": { \"price\": \"49.00\", \"priceCurrency\": \"USD\" } }\n```\n\nNow the fact is unambiguous and typed. Agents extract JSON-LD deterministically, so it's the single highest-fidelity signal you can add. It directly improves the analyzer's **Semantic Signal Density (SSD)** — pages with valid, populated JSON-LD score meaningfully higher because a larger share of what an agent recovers is real, typed meaning.\n\n## How to implement\n\nAdd the right type to each page's purpose. Homepage → `Organization`\n\n(or `LocalBusiness`\n\n). Product pages → `Product`\n\n+ `Offer`\n\n. Articles/posts → `Article`\n\n. Support pages → `FAQPage`\n\n.\n\n```\n<script type=\"application/ld+json\">\n{\n  \"@context\": \"https://schema.org\",\n  \"@type\": \"Organization\",\n  \"name\": \"Acme\",\n  \"url\": \"https://acme.com\",\n  \"logo\": \"https://acme.com/logo.png\",\n  \"sameAs\": [\"https://linkedin.com/company/acme\"]\n}\n</script>\n```\n\nRender it server-side so it's in the raw HTML (an agent that doesn't run your JavaScript still sees it), and keep it in sync with the visible content.\n\n## Validate\n\nPaste your URL into Google's [Rich Results Test](https://search.google.com/test/rich-results) or [Schema.org validator](https://validator.schema.org/), or:\n\n```\ncurl -s https://your-site.com | grep -A5 'application/ld+json'\n```\n\nThe [Core Agent Vitals analyzer](https://agentvitals.dev/analyze) parses your JSON-LD, checks it's valid, and reports the `@type`\n\ns it found — an empty or malformed block is flagged.\n\n## Common mistakes\n\n**Structured data that disagrees with the page.** JSON-LD saying`\"price\": \"49\"`\n\nwhile the page shows`$59`\n\nis worse than none — it teaches agents to distrust you (and search engines penalize it).**Injecting it only with client JavaScript.** A raw-HTML fetch (how many agents read) misses it. Server-render the block.**Missing required fields.**`@type`\n\nwith no populated properties is noise. Fill the fields that define the entity (name, and the type-specific ones like price/author/address).**One giant graph on every page.** Scope the type to the page —`Product`\n\non product pages, not the homepage.**Forgetting it entirely on the pages that most need it.** Product, pricing, and article pages are where typed facts pay off most.\n\n*Next: API Docs for Agent Tool Use — from readable to callable.*", "url": "https://wpnews.pro/news/json-ld-structured-data-tell-agents-what-a-page-is", "canonical_source": "https://blog.r-lopes.com/posts/agent-readiness-json-ld", "published_at": "2026-07-02 14:00:00+00:00", "updated_at": "2026-07-03 21:15:18.282727+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "large-language-models"], "entities": ["Schema.org", "Google", "Core Agent Vitals", "JSON-LD", "Acme Widget"], "alternates": {"html": "https://wpnews.pro/news/json-ld-structured-data-tell-agents-what-a-page-is", "markdown": "https://wpnews.pro/news/json-ld-structured-data-tell-agents-what-a-page-is.md", "text": "https://wpnews.pro/news/json-ld-structured-data-tell-agents-what-a-page-is.txt", "jsonld": "https://wpnews.pro/news/json-ld-structured-data-tell-agents-what-a-page-is.jsonld"}}