# Product data an agent can use without guessing.

> A practical product-data contract for variants, dimensions, availability, provenance, and unknown values, with a downloadable JSON example.

By George Kelly · Published 2026-09-05 · Updated 2026-09-05

Canonical: https://www.iamgeorgekelly.com/field-guide/product-data-for-agents

## Short answer

Give an agent an identifiable variant, explicit units, a current offer record, and a source for each material fact. Keep unknown values unknown. A polished description cannot compensate for a mismatched SKU, stale availability, or an ambiguous dimension.

## Start with the sellable variant

A product family is not the same thing as an orderable item. A finish, size, handing, or included-component change can alter what the customer receives. An agent should be able to distinguish the group from the exact variant and preserve that identity when passing between a feed, product page, specification, and proposed recommendation.

Google Merchant Center documents stable item identifiers and variant attributes. Google Search separately documents ProductGroup relationships for structured product variants. These are useful interoperability references; the internal contract below is an original example, not a replacement for either specification.

Sources: [Google Merchant Center: Product data specification](https://support.google.com/merchants/answer/7052112?hl=en); [Google Search: Product variant structured data](https://developers.google.com/search/docs/appearance/structured-data/product-variants)

## A minimal internal contract

The following fictional cabinet record demonstrates the structure. Null offer values are deliberate: the example has no verified live price or availability. Do not paste it into a merchant feed. Adapt field names and required attributes to the destination and the actual product category.

The record separates durable product facts from rapidly changing offer facts. It also says what the dimension means. A width without a unit or measurement definition is a string that looks useful while leaving the important decision unresolved.

```json
{
  "schemaVersion": "1.0",
  "exampleOnly": true,
  "productGroupId": "DEMO-CABINET-24",
  "variantId": "DEMO-CABINET-24-OAK",
  "title": "Demonstration cabinet, 24-inch width, oak finish",
  "dimensions": {
    "width": {
      "value": 24,
      "unit": "in"
    },
    "meaning": "product exterior width, not installation opening"
  },
  "includedComponents": [
    "cabinet"
  ],
  "excludedComponents": [
    "faucet"
  ],
  "offer": {
    "price": null,
    "currency": "USD",
    "availability": "unknown",
    "observedAt": null
  },
  "provenance": {
    "specification": {
      "source": "Replace with approved specification URL",
      "checkedAt": null,
      "owner": "Product data owner"
    },
    "offer": {
      "source": "Replace with authorized live offer source",
      "checkedAt": null,
      "owner": "Commerce operations"
    }
  }
}
```

[Download the example product-data contract](https://www.iamgeorgekelly.com/downloads/product-data-contract.json)

## Set rules at the field level

A single updated-at timestamp can hide mixed freshness. A specification may remain valid for months while availability changes during the day. Give each fact family its own source and observation time, then choose a freshness requirement according to the action being taken.

A descriptive comparison can tolerate a different freshness window from a promise to fulfill an order. The window is a business rule to define with the source owner. It should not be invented by the model.

| Fact family | Required clarity | Failure response |
| --- | --- | --- |
| Identity | Stable variant identifier and family relationship | Stop matching if identifiers disagree. |
| Dimensions | Numeric value, unit, and measurement meaning | Flag missing units or incompatible measurements. |
| Compatibility | Explicit approved relationship or constraint | Say unverified instead of inferring fit from a similar title. |
| Included components | What ships together and what is separate | Prevent copy from implying an accessory is included. |
| Offer | Price, currency, availability, observation time | Refresh or report unavailable when the record is stale. |
| Provenance | Source location and accountable owner | Route a conflict to the owner; retain both source values. |

## Handle a conflict as an exception, not a writing task

Imagine a synthetic listing whose title says 24 inches while the approved specification says 23.5 inches of exterior width. First inspect whether the two values describe different concepts: nominal size versus measured exterior size. If so, retain both with labels. If both claim to be exterior width, the task is unresolved.

The output should name the variant, reproduce the conflicting values, cite the two source locations, and state which downstream copy is paused. Replacing one value with the more plausible number creates the appearance of resolution without evidence.

This exception record is useful content for both a reviewer and an agent. It narrows the next action and makes it possible to test whether the issue was actually resolved.

## Test the contract before expanding the catalog

Choose a representative set of variants that includes similar names, missing dimensions, unavailable items, and component differences. Test whether the system keeps those distinctions through retrieval and rendering. A large catalog import is not proof that a specific variant can be recommended correctly.

The acceptance artifact should show the source record, the normalized record, and the rendered result for the same identifier. Re-run the affected cases when a mapping changes. Preserve the difference between an empty value, a verified absence, and a value that was never checked.

- Keep an explicit unknown state; do not replace it with a favorable default.
- Validate allowed units and currency codes at the integration boundary.
- Check every displayed price and availability against the same variant.
- Attach sources to decision-critical claims, not only to the page as a whole.
- Version the contract so a renamed field does not silently change its meaning.

## Sources and scope

- [Google Merchant Center: Product data specification](https://support.google.com/merchants/answer/7052112?hl=en) — Supports stable identifiers, explicit variant attributes, and consistency between submitted data and the destination. Checked 2026-09-05.

- [Google Search: Product variant structured data](https://developers.google.com/search/docs/appearance/structured-data/product-variants) — Supports explicit ProductGroup and Product relationships. The downloadable internal contract is illustrative, not Google feed syntax. Checked 2026-09-05.

## Related reading

- [Product data ownership: resolve a price conflict](https://www.iamgeorgekelly.com/field-guide/product-data-ownership/index.md)

- [Does the product page match the variant you submitted?](https://www.iamgeorgekelly.com/field-guide/product-variant-acceptance-test/index.md)

- [From request to release: a supervised commerce workflow.](https://www.iamgeorgekelly.com/field-guide/supervised-commerce-workflows/index.md)

- [Agentic commerce starts with an operating model.](https://www.iamgeorgekelly.com/field-guide/agentic-commerce/index.md)

## Editorial note

AI-assisted research and drafting. Provider-specific claims link to primary sources. Frameworks are editorial proposals; worked examples are illustrative and are not employer performance results.

Related career work: https://www.iamgeorgekelly.com/projects/vintage-bath-home