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

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: 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 or Schema.org validator, or:

curl -s https://your-site.com | grep -A5 'application/ld+json'

The Core Agent Vitals analyzer parses your JSON-LD, checks it's valid, and reports the @types 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.