# AI-ready catalog contract (agentic commerce input)

Companion to **The AI-ready product catalog**.

This is the **output contract** search, recommendations, GEO, and shopping agents consume. It is **not** the PIM extract → validate → merchandiser-publish workflow. That workflow lives in [`catalog-validation-rules.md`](catalog-validation-rules.md) and [post 9](https://www.factualminds.com/blog/ai-product-catalog-management-ecommerce-2026/).

Pipeline this contract assumes already happened:

```text
Raw → Clean → Normalize → Enrich → Validate → Structure
    → AI-ready catalog
    → Search / recommendations / agents / GEO
```

Skip a stage and the agent fills the gap with language.

## Record shape (illustrative JSON)

Context: not a published schema. Align names to your PIM. `asOf` older than your SLA must become `unknown`.

```json
{
  "sku": "SHOE-TR-W-10",
  "gtin": "00012345678912",
  "parentId": "SHOE-TR",
  "categoryId": "trail-running-shoes",
  "title": "Trail runner, wide, size 10",
  "description": "Waterproof trail shoe. Wide last. Not a hiking boot.",
  "attributes": {
    "color": "slate",
    "size": "10",
    "width": "wide",
    "material": "synthetic-mesh",
    "waterproof": true,
    "use": "trail"
  },
  "relationships": {
    "variants": ["SHOE-TR-W-09", "SHOE-TR-W-10", "SHOE-TR-N-10"],
    "compatibleWith": []
  },
  "offer": {
    "price": { "amount": 140.0, "currency": "USD", "taxIncluded": false },
    "availability": { "status": "in_stock", "quantity": 22, "asOf": "2026-08-27T09:00:00Z" },
    "shipping": { "promise": "2-day", "region": "US-contiguous" }
  },
  "evidence": {
    "ratingValue": 4.4,
    "reviewCount": 128
  },
  "policy": {
    "returnsDays": 30,
    "restricted": false
  }
}
```

## Defects that break agentic commerce (not just SEO)

| Defect | What an agent does | Who pays |
| ------ | ------------------ | -------- |
| Missing required attributes | Matches marketing adjectives; fails comparison | Returns, "not as described" |
| Duplicates / GTIN clash | Retrieves the wrong URL or merges two offers | Inventory and ads |
| Bad category | Retrieves the SKU for the wrong intent | Wasted click, angry shopper |
| Poor / contradictory description | Quotes prose that fights the spec | Trust at checkout |
| Weak variant relationships | Compares a size-9 to a size-10 parent | Fit failures |
| Stale inventory | Asserts in-stock from a cache | [Baymard](https://baymard.com/lists/cart-abandonment-rate) 70.22% already includes broken confidence — agents amplify it |
| Price only in HTML | Quotes a number checkout will not honor | Chargebacks / abandoned carts |

## Consumer map

| Consumer | Needs from this contract | Must not invent |
| -------- | ------------------------ | --------------- |
| On-site search / facets | Attributes + category IDs | New taxonomy nodes |
| Recommendations | In-stock + policy + parent/child | Discounts |
| Your shopping copilot | Same as [readiness checklist](shopping-agent-readiness-checklist.md) | Coupons, payment |
| External shopping agent / AI search | Machine-readable offer + identity | Your merchandising rank |
| GEO packaging | JSON-LD / feed that matches this record | A second "SEO" product |

## When NOT to call the catalog AI-ready

- Completeness % is high but variants have no parent IDs
- Enrichment ran (pretty copy) before validation passed
- Inventory is not on the same SKU the storefront sells
- You plan to let agents scrape PDPs instead of serving this record

## Score

Pick **one** category. Count SKUs that would fail the JSON above (missing field, stale `asOf`, duplicate GTIN, no parent). That count is **yours**. Do not invent a FactualMinds completeness KPI.