Agent readiness

JSON-LD for AI agents: the schema markup that actually gets read

JSON-LD is the highest-leverage hour in the entire agent-readiness stack: typed, machine-verifiable facts about your business embedded in your pages. This is the practical version, with copy-paste templates for the types that matter, the implementation rules that keep them trusted, and the mistakes that get markup ignored.

Updated August 10, 2026 · 10 min read

JSON-LD is a block of structured data embedded in a script tag on your page, describing your business in the shared schema.org vocabulary: what you are, what you sell, at what price, when you are open, what customers say. Humans never see it; machines read it first. For AI agents and answer engines it converts your website from prose they must interpret into typed facts they can assert, and that difference shows up in results: pages with structured data are cited roughly three times more often in AI answers, and it is the artifact with the best-documented consumers in the whole readiness stack.

The consumers are not hypothetical. Google documents structured data as an input across its surfaces and leaned on the same fundamentals in its 2026 guidance for generative features, Bing parses it, the answer engines ground facts in it, and shopping pipelines cross-check it against product feeds. When an assistant states your price or your Saturday hours in an answer, structured data is the reason it can say so confidently instead of hedging.

This guide is the practical version: the format, the four types that cover most businesses (with templates to adapt), the implementation rules that keep markup trusted, validation, and the mistakes that get it ignored. For where this sits in the bigger picture, see the generative engine optimization guide for the citation side and agentic commerce for the transaction side.

Why JSON-LD and not the other formats

Schema.org data can also be written as microdata or RDFa, woven attribute by attribute into your HTML. Do not. JSON-LD is Google’s recommended format for a reason: it lives in one self-contained block, so it is easy to generate from a template, easy to validate, and impossible to break by restyling your page. Every template below is JSON-LD inside a script tag with type application/ld+json, placed anywhere in the page (head is conventional).

The four types that cover most businesses

Schema.org defines hundreds of types; agents care about a handful. Ship these four well before touching anything exotic.

1. LocalBusiness: your identity block

The foundation. Use the most specific subtype that fits (Physiotherapy, Restaurant, Plumber, LegalService); specificity is free relevance for category queries. Adapt this:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Physiotherapy",
  "name": "Riverside Physio",
  "url": "https://riversidephysio.com",
  "telephone": "+1-512-555-0142",
  "address": {
    "@type": "PostalAddress",
    "streetAddress": "412 Riverside Dr",
    "addressLocality": "Austin",
    "addressRegion": "TX",
    "postalCode": "78704",
    "addressCountry": "US"
  },
  "openingHoursSpecification": [{
    "@type": "OpeningHoursSpecification",
    "dayOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
    "opens": "08:00",
    "closes": "18:00"
  }],
  "areaServed": "Austin, TX",
  "priceRange": "$$"
}
</script>

2. Service with an Offer: what you do and what it costs

This is the block most service businesses are missing, and it is the one that lets an agent answer "how much does X cost" with your actual number instead of a shrug. One block per service, on the page describing that service:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Service",
  "name": "Initial Physiotherapy Assessment",
  "serviceType": "Sports physiotherapy",
  "provider": { "@type": "Physiotherapy", "name": "Riverside Physio" },
  "areaServed": "Austin, TX",
  "offers": {
    "@type": "Offer",
    "price": "140.00",
    "priceCurrency": "USD",
    "availability": "https://schema.org/InStock"
  }
}
</script>

3. Product with an Offer: catalog data

For anything sold as a product. This block is also what shopping pipelines cross-reference against your merchant feed, so the two must agree:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Recovery Foam Roller Pro",
  "description": "High-density foam roller, 45cm, for post-training recovery.",
  "sku": "RFR-PRO-45",
  "image": "https://example.com/img/roller.jpg",
  "brand": { "@type": "Brand", "name": "Riverside" },
  "offers": {
    "@type": "Offer",
    "price": "39.00",
    "priceCurrency": "USD",
    "availability": "https://schema.org/InStock",
    "url": "https://example.com/products/foam-roller-pro"
  },
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "4.7",
    "reviewCount": "132"
  }
}
</script>

4. FAQPage: your canonical answers

FAQPage markup turns your questions page into extractable question-answer pairs, which is exactly the shape answer engines lift. Only mark up questions and answers that are visibly on the page:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [{
    "@type": "Question",
    "name": "Do you take walk-in appointments?",
    "acceptedAnswer": {
      "@type": "Answer",
      "text": "No, all visits are by appointment. Same-day slots are often available and can be booked online."
    }
  }]
}
</script>

Implementation rules that keep your markup trusted

Structured data is a trust system, and trust is easy to lose. The rules that matter:

• Mirror the visible page. Every fact in JSON-LD must appear in the human-readable content. Markup that claims what the page does not show is treated as spam by Google and as noise by agents.
• Keep it current, automatically. A price in structured data that disagrees with your checkout is worse than no markup, because an assistant will quote it. Generate JSON-LD from the same source of truth as your pages, never hand-edit a stale copy.
• Use standard formats. ISO 8601 for dates and times, schema.org URLs for enumerations like availability, numbers as strings without currency symbols in price fields, and full absolute URLs.
• Connect your entities. Reference the same organization name, URL, and identity across every block on every page, so machines resolve all of it to one entity instead of fragments.
• One graph per page is fine. Multiple types can live in a single script tag using @graph, which is tidier than scattering blocks, and it is exactly how well-built platforms emit it.

Validate before you trust it

Never assume markup works; check it. Google’s Rich Results Test shows what Google extracts and flags eligibility issues, and the schema.org validator checks vocabulary correctness beyond Google’s subset. Paste your live URL, not your source file, so you test what crawlers actually receive after rendering. Then re-validate whenever your templates change; structured data breaks silently, and a JSON error takes the whole block out without any visible symptom on the page.

Where JSON-LD stops

Structured data makes your facts legible; it does not make your business transactable. An agent that reads a perfect Offer block still cannot check whether Tuesday at 3pm is free or complete a booking. That is the next layer up: live feeds for the shopping surfaces and callable endpoints like an MCP server for actions. But the layers stack in order, and this one comes first, because every downstream surface, from ChatGPT recommendations to shopping feeds, cross-references the typed facts you publish here.

If you maintain your own site, the templates above plus an hour of adaptation cover most of it. If you would rather not maintain markup by hand, this is one of the things platforms should simply do for you: Nexez generates the full JSON-LD graph for your business, services, offers, and FAQs from your listing data automatically, so the markup can never drift from the page, and ships it alongside the rest of the agent stack.