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

> Source: <https://blog.r-lopes.com/posts/agent-readiness-json-ld>
> Published: 2026-07-02 14:00:00+00:00

*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.*