JSON-LD and structured data for AI clients

Structured data makes page facts explicit, but those facts must agree with the visible page and underlying source. Valid syntax can still carry a wrong price or availability.

JSON-LD is a block of structured data in a page that states facts in a form a machine can read without interpreting prose. It tells an agent what the page is about, who runs it, what it sells, and at what price, as data rather than as sentences an agent has to parse and might misread. A human reads a price from a layout and a currency symbol. An agent reading raw HTML has to guess which number is the price and which is a shipping estimate, unless the page also carries that fact as Microdata or RDFa, two other structured-data formats embedded directly in HTML tags, and a JSON-LD Offer with a price and a currency removes the same guess without relying on either one.

Facts as data

Structured data connects a page to the wider graph an agent builds. Declared types such as Organization, Service, FAQPage and Article let an agent place a page in context. They do not make a claim true and they oblige nobody to cite it. What they remove is parsing ambiguity, and trust and citation stay decisions of the system that reads the page.

Agreement across surfaces

The cost of getting it wrong is silent. An agent does not report that it failed to parse a price, it just acts on a worse guess. Clean JSON-LD is one of the cheapest ways to make a page legible, and it sits in the same family as the response headers and well-known manifests an agent reads first.

The opposite failure is data that parses and is wrong. A product page that publishes a price of 0 and an availability of InStock on every item is structurally valid, and an agent that trusts it will offer a customer a free product that is in stock. An Organization node whose email field holds a first name validates just as well. Wrong data is worse than missing data, because missing data makes an agent guess and wrong data makes it confident. The check is the one a buyer would make: read the JSON-LD next to the page and ask whether the two say the same thing, and where a source system feeds the page, whether the JSON-LD also agrees with that source.

Validation

Four separate questions get asked here, and each has its own answer. Syntax validity asks only whether the JSON-LD parses and the declared type is well-formed, because JSON-LD itself makes no property mandatory and schema.org leaves that to each consumer. Whether the declared type also carries the fields a named consumer requires, such as Google's rich result rules, is a separate, consumer-specific check: it can fail even when the syntax itself is perfectly valid, because that requirement comes from the consumer and not from JSON-LD or schema.org. A validator answers that from the markup alone, and a report should name which rules it checked. Semantic correctness asks whether the values in that valid structure match the page a person sees and the system that feeds it, and a validator cannot answer that, a person has to compare the two. AI source selection asks whether an assistant picks this page as the source for an answer at all, which depends on the assistant, the query and the moment, and neither syntax nor semantic correctness settles it on its own. The fictional example in the sample audit report, finding F1 illustrates the gap: a price of 0 passes every syntax check, and an invented assistant answer then calls the whole catalog free. The example is made up for illustration and is not evidence of how any assistant behaves.

Limits

Clean, correct JSON-LD makes a page legible. It does not guarantee that an assistant reads it, cites it, or answers a question the way the site would want. Legibility removes the guess an agent would otherwise make about the page's own facts. What an assistant does with a legible page is a separate, observed question, and it is checked by putting real questions to real assistants rather than by reading the markup again.

turva.dev declares JSON-LD for its organization, the person behind it, its services and its guides. For an audit of a site's structured data, contact info@turva.dev.

Frequently asked

What is JSON-LD?

Why does structured data matter for agents?

An agent that parses raw HTML without a layout model has to guess which number is a price and which is a shipping estimate, unless the page carries that fact as Microdata or RDFa instead. A JSON-LD Offer with a price and a currency removes the same guess for an agent that reads structured data first, and declared types let an agent place a page in context. Trust and citation stay decisions of the system that reads the page.

What should JSON-LD state on a page?

What the page is about, who runs it, what it sells and at what price, as data rather than sentences. An Offer with a price and a currency removes the guess an agent would otherwise make.

Can structured data be valid and still wrong?

Yes. A price of 0 with an availability of InStock on every product passes every syntax check and tells an agent the whole catalog is free, and a contact field holding the wrong kind of value validates the same way. A syntax validator reads the shape, so a person has to compare the data with the page it describes.