Product data an agent can use without guessing.

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.

Source: Google Merchant Center: Product data specification; Google Search: Product variant structured data

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.

{
  "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"
    }
  }
}

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.

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.