JSON-LD Structured Data: Tell Agents What a Page Is

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.

Part of the Agent Readiness course. Measure any page with the Core Agent Vitals analyzer. What it is JSON-LD is a small block of JSON, embedded in a <script type="application/ld+json" tag, that describes a page using the shared vocabulary at Schema.org https://schema.org : Organization , Product , Article , LocalBusiness , FAQPage , and hundreds more. It states, in typed fields, what the page is — name, price, author, rating, hours, address — separate from how it's rendered. Why agents need it A 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: { "@type": "Product", "name": "Acme Widget", "offers": { "price": "49.00", "priceCurrency": "USD" } } Now 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. How to implement Add the right type to each page's purpose. Homepage → Organization or LocalBusiness . Product pages → Product + Offer . Articles/posts → Article . Support pages → FAQPage . <script type="application/ld+json" { "@context": "https://schema.org", "@type": "Organization", "name": "Acme", "url": "https://acme.com", "logo": "https://acme.com/logo.png", "sameAs": "https://linkedin.com/company/acme" } </script Render 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. Validate Paste your URL into Google's Rich Results Test https://search.google.com/test/rich-results or Schema.org validator https://validator.schema.org/ , or: curl -s https://your-site.com | grep -A5 'application/ld+json' The Core Agent Vitals analyzer https://agentvitals.dev/analyze parses your JSON-LD, checks it's valid, and reports the @type s it found — an empty or malformed block is flagged. Common mistakes Structured data that disagrees with the page. JSON-LD saying "price": "49" while the page shows $59 is 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 with 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 on 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. Next: API Docs for Agent Tool Use — from readable to callable.