# Structured data that helps explain your business

> How to use Schema.org, JSON-LD, stable identifiers, and visible facts without inventing a special AI ranking formula.

Canonical: https://byagents.dev/humans/structured-data
Published: 2026-09-13
Reviewed: 2026-09-13
Publisher: ByAgents
Type: Guide
Level: Technical
Outcome: Choose an accurate structured description and reconcile it with visible product facts.

Structured data gives software explicit labels for facts that would otherwise need to be inferred from a page. Schema.org provides a shared vocabulary; JSON-LD is one way to express it. The goal is an accurate description of the offering, not a hidden sales pitch.

## Model the real thing
A business, a product, an offer, and a service are related but distinct. Use the type that represents the entity described on the page. Give important entities stable identifiers so multiple pages can refer to the same thing. A product’s price and availability belong to an offer; a company’s identity belongs to its organization record.

Schema.org’s Product vocabulary includes relationships such as brand, offers, and identifiers. The properties you choose should fit the actual information available. [Schema.org Product](https://schema.org/Product).

## Start with a small, consistent record
For a fictional extraction API, a useful visible fact sheet might say: it accepts PDF invoices, returns line items in JSON, charges per page, and requires an API key. The structured description should agree with that page. Do not add a free offer, rating, certification, or unsupported capability merely because the schema permits the field.

```json
{
  "@context": "https://schema.org",
  "@type": "SoftwareApplication",
  "@id": "https://example.com/invoice-api#software",
  "name": "Example Invoice API",
  "url": "https://example.com/invoice-api",
  "applicationCategory": "DeveloperApplication",
  "description": "Extracts line items from PDF invoices into JSON."
}
```

This is a vocabulary example using a reserved example domain. It is not a complete recipe for a Google rich result and does not describe a ByAgents customer.

## Keep markup and pages in agreement
Google uses structured data to understand page content and support eligible search appearances. Its documentation recommends JSON-LD and requires the markup to represent the visible content. Valid markup does not guarantee a rich result. [Google’s structured data introduction](https://developers.google.com/search/docs/appearance/structured-data/intro-structured-data).

A common failure is maintaining the website, product feed, and structured record separately. A changed price then leaves three different answers. Prefer a shared source for recurring facts, with a clear owner and update process. If a value changes frequently, link to the live source and indicate when a snapshot was checked.

## Useful validation questions
- Does the type describe the actual entity on the page?
- Do names, URLs, identifiers, currencies, and units match across representations?
- Are claims backed by visible content and appropriate sources?
- Have placeholder prices, invented ratings, and stale availability been removed?
- Does the chosen search feature have additional eligibility requirements?

A syntax validator can catch malformed data. It cannot establish that a claim is true, a price is current, or an agent will choose the product. Review meaning as well as format.

## The next step is still separate
Structured data can explain an offering. An action still needs a real destination, available inventory or capacity, and appropriate permission. For APIs, that usually means a complete contract and usable onboarding. For services, it might mean a scoped inquiry or booking flow. Make the facts and the action agree.

## Resolve contradictions at the source

Build a small consistency matrix: entity identifier, visible name, price unit, current offer source, relevant limits, and next-action URL. Compare the same fields across the product page, markup, feed, and documentation. If one disagrees, identify which system owns the fact before updating the copies.

Stable identity is particularly useful for variants. A blue 750 ml bottle and a green 500 ml bottle may share a family but are different purchasable items. A feed must not send both to a generic page that loses the selected variant. For a service, avoid presenting an inquiry as a confirmed booking. The [feed validation recipe](https://byagents.dev/agents/feed-validation-recipe) checks these relationships without treating valid syntax as proof of truth.

## Sources

- [Schema.org Product](https://schema.org/Product)
- [Google: Structured data](https://developers.google.com/search/docs/appearance/structured-data/intro-structured-data)

## Related reading

- [Give agents something worth citing](https://byagents.dev/humans/citations-and-evidence)
- [Agent discovery for brands and ecommerce](https://byagents.dev/humans/brands-and-commerce)
- [Agent discovery for services, freelancers, and local businesses](https://byagents.dev/humans/service-businesses)
- [Recipe: validate a product feed across the full handoff](https://byagents.dev/agents/feed-validation-recipe)
- [Product feeds for AI shopping](https://byagents.dev/humans/product-feeds-for-ai-shopping)