Structured data for AI agents: a practical JSON-LD guide

1. Separate page facts from tool contracts

Three related technologies answer different questions. HTML carries the content and controls a visitor encounters. Schema.org supplies a vocabulary for describing entities; JSON-LD is one way to serialize those descriptions. A tool input schema describes the arguments an operation accepts. Sharing the word “schema” does not make these interchangeable.

Google recommends JSON-LD for structured data in Search, while also supporting other formats. That recommendation concerns its search processing; it does not establish which representation every AI agent reads. See Google’s structured-data introduction.

For Google AI Overviews and AI Mode, the documentation explicitly says there is no special Schema.org markup requirement. Normal search eligibility and useful content still matter, and inclusion is not guaranteed. See Google’s AI features guidance. Treat “add AI schema to get cited” as an unsupported promise unless the claimant supplies evidence for the particular system and outcome.

WebMCP addresses interaction. Chrome describes it as a proposed standard for exposing structured tools through JavaScript and annotated forms. Adding a JSON-LD block does not register such a tool. Check the current WebMCP documentation before implementation, then use our WebMCP tool-testing guide for execution checks.

2. Choose the entity and facts to describe

Begin with the question a buyer needs answered, not a plugin’s list of available schema types. Write a small fact sheet containing the subject, its public URL, the answer, and the person or system responsible for keeping it current. This is your comparison reference throughout the audit.

For a software pricing page, that sheet might name the application, plan, price, currency, billing period, included seats, tax treatment, and purchase or demo destination. For a service page, it might instead identify the provider, service scope, area served, and quote conditions. If a value is unknown, fix the content or omit the unsupported claim.

• Organization describes the business or publisher. Keep its identity consistent across pages.
• SoftwareApplication describes an application. Its offer is a related object, not a replacement for the application’s identity.
• Service fits a service offered by a provider. Choose it because it matches the subject, not because a template promises visibility.
• Article describes editorial content, with properties for its headline, author, and dates. This page uses the more specific BlogPosting type.

Describe the main subject of the URL. An article discussing an imaginary product should not publish that imaginary offer as live product metadata. Likewise, a page comparing three plans should not silently label the cheapest plan’s price as the cost of every configuration.

Use stable absolute identifiers such as https://www.example.com/planner/#app to connect references to the same entity. Keep the page URL and entity identifier conceptually separate: a fragment identifier can name the application, while the canonical URL names the document. Do not regenerate entity identifiers randomly on every build.

3. Build HTML and JSON-LD from the same facts

Here is a fictional application and annual offer. The names, prices, and URLs are illustrative; they are not Adapt My Page’s plans. The visible page could contain:

<section aria-labelledby="team-plan">
  <h2 id="team-plan">Maple Planner — Team annual plan</h2>
  <p>USD 120 per workspace for one year, billed annually.
     Includes 3 seats. Applicable taxes are additional.</p>
  <p>Renews annually unless cancelled before renewal.</p>
  <a href="/planner/team/">View Team plan details</a>
</section>

A matching JSON-LD block can describe the application and this specific offer. Place the block in the HTML document using your framework’s safe JSON serialization mechanism:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "SoftwareApplication",
  "@id": "https://www.example.com/planner/#app",
  "name": "Maple Planner",
  "url": "https://www.example.com/planner/",
  "applicationCategory": "BusinessApplication",
  "operatingSystem": "Web browser",
  "offers": {
    "@type": "Offer",
    "@id": "https://www.example.com/planner/team/#annual-offer",
    "name": "Team annual plan",
    "url": "https://www.example.com/planner/team/",
    "price": "120.00",
    "priceCurrency": "USD",
    "description": "USD 120 per workspace for one year, billed annually. Includes 3 seats. Applicable taxes are additional. Renews annually unless cancelled before renewal."
  }
}
</script>

The Offer vocabulary supplies properties such as price, currency, URL, and description. Here, 120.00 is the annual amount stated on the page. It is not the monthly equivalent. The description carries the billing unit and conditions; the number alone cannot tell a consumer whether a charge is annual, monthly, or per seat.

More complex pricing may use UnitPriceSpecification to express price components and billing details. Verify those properties against both the vocabulary and your intended consumer. Do not assume that a richer graph will be interpreted completely. Keep the terms in visible text even when you model them in additional properties.

This example deliberately omits ratings and reviews. Google’s software-app rich result currently requires a rating or review as well as the specified name and offer information. Therefore, this illustrative entity description is not a complete Google software-app rich-result implementation. Use Google’s software-app requirements to evaluate that separate goal. Never manufacture a review to make a validator turn green.

In production, render the heading, terms, and structured data from the same maintained record. Use a serializer that safely embeds JSON in HTML, including escaping characters that could terminate a script element. Avoid building JSON by concatenating unescaped CMS fields. Test an unusual product name as well as the ordinary example.

4. Keep page states and commercial terms consistent

A correct first version can drift after a pricing update or CMS change. Make ownership explicit: the product catalog owns amounts and plan identifiers; editorial content owns explanations; the rendering template maps those records into the page. The exact ownership model is yours, but every displayed fact needs a maintained source.

Billing toggles and currencies

Record the state you are describing. If the default page presents annual billing, its default markup must not describe an unrelated monthly offer. If the page describes several offers, name and distinguish each one. When a selector changes the displayed terms, inspect the resulting markup too; stale data should not be left to contradict the current presentation.

Test representative combinations separately: annual versus monthly, one currency versus another, and default versus selected plan. Avoid a full Cartesian product of every UI option unless the implementation warrants it. Focus on states that change a commercially meaningful fact.

Public offers and account-specific quotes

A public pricing page should describe the public offer it shows. A negotiated account price belongs in the authorized account experience. Do not leak private commercial data into public JSON-LD, and do not use a public list price as the final answer for a signed-in customer with different terms. An actual checkout or quote must validate its current inputs and price on the server.

Rendering and duplicate generators

Inspect both initial HTML and the rendered DOM. A theme, SEO plugin, and application component can each emit a different offer. Multiple JSON-LD blocks are not inherently wrong; conflicting descriptions of the same entity are the problem. Assign one owner for each entity and remove or update stale generators.

If important facts appear only after JavaScript runs, follow the AI crawler rendering audit. Publishing matching facts and markup in initial HTML is a practical way to reduce dependence on a consumer’s rendering capability. It does not establish that every crawler retrieves or uses them.

5. Validate at four separate levels

Keep four outcomes in your release report. Combining them into a single “schema passed” hides the difference between readable code and a successful user task.

Level 1: JSON syntax and Schema.org vocabulary

Parse every JSON-LD script, including blocks generated by plugins. Then use the Schema Markup Validator to inspect extracted types and properties. Its documentation describes extraction of JSON-LD, RDFa, and Microdata and identification of syntax mistakes. A syntax check cannot verify that the price is current or that a described service exists.

Level 2: Visible-content agreement

Compare each material field with your fact sheet and the rendered page. Check the actual HTTP response, not only the CMS preview. For the fictional example, verify the application name, USD 120 annual charge, workspace unit, three seats, additional taxes, and renewal condition. Follow the offer URL and confirm it describes the same plan.

Google’s structured-data policies require markup to represent the page’s content and prohibit misleading information. Valid syntax cannot rescue an offer that disagrees with what visitors see. Keep a short field-by-field comparison as release evidence.

Level 3: Consumer-specific eligibility and access

Use the Rich Results Test when Google rich-result eligibility is the objective. Read the requirements for that feature, then inspect the deployed URL. A general Schema.org type may have no corresponding Google rich-result feature, and a test pass does not guarantee display.

Also verify that the intended crawler can access the page. Robots policy, an edge challenge, or a login screen can prevent delivery of otherwise correct markup. Our crawler-controls guide explains the policy boundaries. Neither schema nor a validator is an access override.

Level 4: Agent understanding and permitted action

Give the intended agent a bounded question, such as: “What does the Team annual plan cost for one workspace, and what conditions apply?” Record the agent, version where available, URL, date, session state, and answer. Compare it with the fact sheet. If the agent omits the billing period, you have an observed answer failure to investigate; it does not prove which representation caused it.

If the task includes requesting a quote, separately check the chosen tool or form, its arguments, user confirmation where required, and the stored result. Use the form-testing workflow and WebMCP security checklist. A correct answer about a plan is not evidence of a correctly authorized purchase.

6. Diagnose common failures

Treat these as diagnostic recommendations, not reported experiments. Preserve the failing response or trace before editing. Change the layer implicated by the evidence, repeat the relevant check, and record what remains unknown.

7. Set a release acceptance checklist

• The page has a written task and a current fact sheet.
• The selected Schema.org types describe the actual page subject.
• JSON parses, and vocabulary checks have been reviewed.
• Prices, currencies, billing units, conditions, and destinations match visible content.
• Representative locale and selector states have no conflicting generators.
• No invented ratings, private quotes, or fictional example offers appear as live metadata.
• The deployed response and intended consumer’s checks are recorded separately.
• Any agent answer or action claim is supported by a specific observed test.

Repeat the content comparison when a plan, template, locale, or schema plugin changes. Keep the evidence with the release so a later wrong answer can be traced to the page state that produced it. If you have not run the intended agent, report “markup validated; agent behavior untested.” That gives the next person a precise starting point.