Skip to content

A practical product data schema for AI shopping assistants

Field by field: the identity, specification, media, review and price fields a product response needs for retrieval, comparison and explanation.

Abstract structured product data schema connecting product identity, specifications, price and provenance for an AI shopping assistant
Structured product data connecting evidence, specifications and provenance. Credit: Generated for Simlir

The short answer

A shopping assistant needs more than a title and a URL. Its product record should preserve identity, comparable specifications, visual context, review context, price provenance and a retailer destination — each with an explicit market. The test for any field is simple: can the application do something with it that it could not do by asking a model to guess? Identity enables joining and re-fetching. Specifications enable comparison. Provenance enables explanation. Anything that fails that test is decoration.

The worked example throughout is the simlir product object, because it is a published contract you can check rather than an idealised schema. Every field named below appears in the response format documentation.

1. Identity and variant fields

Identity does three jobs: it lets you deduplicate, join to other systems, and re-fetch the same product later without repeating a search.

FieldTypeWhy it earns its place
idUUIDStable and permanent. Cache it: a later fetch through /v1/product costs 1 credit instead of a 2-credit search.
gtinstringThe strongest cross-retailer key. If you are joining to a merchant feed, this is the join column.
model_numberstringMPN. Reliable within a brand and essential where GTINs are inconsistent. Note: type=mpn on lookup maps onto this field.
retailer_skustringRetailer-specific, so only meaningful alongside the retailer. Pair with a retailer filter when looking up.
product_identifiersobjectArticle numbers and alternate part numbers — the long tail that rescues matches in categories with messy identity.
brand, titlestringHuman-facing identity. Necessary, but never sufficient for matching.

The variant trap. Colour, size, capacity and pack quantity change the price and often the GTIN. If your schema treats a variant as an attribute of one product rather than as an identifiable thing, you will eventually show a price that belongs to a different variant. Decide early whether your product entity is the model or the purchasable unit, and be consistent about it.

2. Category and normalised attributes

Category is not just a label for a breadcrumb. It is what tells your comparison logic which specifications matter.

  • category drives your comparison rules: for a protein powder, the deciding attributes are protein per serving and price per serving; for a dishwasher, they are noise level, width and place settings. One generic comparison template across all categories produces bland, unhelpful output.
  • use_cases captures who the product is for. It is useful for matching soft, context-heavy requests — “for a beginner”, “for travel” — that never appear in a specification table.
  • certifications, materials, country_of_origin and release_year carry constraints that shoppers raise explicitly and that are painful to reconstruct from prose.

3. Comparable specifications

A spec object is the single most important structural decision in the schema, because it is what makes two products commensurable.

Not comparable

"features": "24g protein, mixes smoothly, over 20 flavours" One string. To rank on protein content you must parse prose at query time, for every candidate, every time.

Comparable

"spec": { "protein_per_serving": "24g", "servings": "29", "calories_per_serving": 120 } Named keys. Sortable, filterable, and directly quotable in an explanation.

Two practical notes. First, values may arrive as strings with units embedded ("24g") or as numbers (120). Normalise once, at ingestion into your own store, rather than in every comparison. Second, structured measurement objects like dimensions and weight carry an explicit unit alongside the value — preserve it. A weight of 0.899 with the unit dropped is a bug waiting for a unit-conversion incident.

4. Images, descriptions and visual context

  • image_url — the durable hero image, always a retailer-hosted HTTPS URL. Expiring thumbnails and non-image assets are rejected before this value is set, which is what makes it safe to store rather than proxy.
  • images — the HTTPS-only gallery array, intended for gallery rendering.
  • product_description — the short factual summary. This is the one to show in a card or quote in an explanation.
  • description — the long form. Useful as context for a model, usually too long for an interface.
  • key_selling_points — a short array. Ideal for the three bullet points under a product card, and far safer than asking a model to summarise the long description on every render.
  • visual — a summary of what the hero image shows, plus labels, any clearly visible detected_text, and dominant colours. It is derived from the hero image and safe to show to users or pass to an agent. It is null when a row has not been visually enriched, so handle that.

5. Review score and its context

Never store a review score without its count. review_score: 5.0 from three reviewers is weaker evidence than review_score: 4.6 from nine hundred, and a ranking function that cannot see review_count cannot know that.

Two rules that prevent most review-related embarrassment: apply a minimum count threshold before letting review score influence ranking at all, and always display the count next to the score. “4.8 from 20 reviews” is honest. “4.8 stars” invites a shopper to assume a sample size that does not exist.

6. Price snapshot, currency and checked time

Price should never be a bare number in your schema. In the simlir contract it is an object:

price
"price": {
  "amount": 29.99,
  "currency": "GBP",
  "retailer": "Holland & Barrett",
  "as_of": "2026-04-07"
}

All four parts are load-bearing. amount without currency is ambiguous the moment you add a second market. retailer tells a shopper where the number came from. as_of is what makes the value honest — it is the date the price was observed when the product was last rediscovered, not a guarantee about today.

Carry the object through your entire stack. The moment it is flattened to a float, your interface loses the ability to say where and when, and starts making claims it cannot support. There is a longer treatment in why product prices need a source and checked time.

  • links.retailer — the captured retailer product page. This is where a shopper goes to inspect availability, delivery terms and the current offer. It may be null when the row has no verified retailer product URL.
  • links.buy — a compatibility alias retained for older clients. When a verified retailer page exists it mirrors the same URL. Treat the two as the same destination rather than as two different journeys, and expect both to be null together.
  • market — echoes the shopper country you requested. Compare it against what you sent. A mismatch is an integration bug, not a data quirk.
  • relevance_score — present only on /v1/search results; cosine similarity between 0 and 1. visual_similarity_score is its image-search counterpart. They measure different things and must not be blended into one ranking number.
response meta
"meta": {
  "count": 5,
  "market": "gb",
  "response_time_ms": 340,
  "credits_used": 2
}

8. A missing value policy

Every schema decision above eventually meets a row where the field is absent. The difference between a trustworthy assistant and an unreliable one is usually not data coverage — it is whether the missing-value policy was designed or improvised.

FieldWhen it can be absentRecommended behaviour
links.retailer / links.buyNo verified retailer product URL for the rowSuppress the call to action; keep the product visible
visualRow not yet visually enrichedFall back to image_url and text; do not describe the image yourself
gtinCategory or retailer does not publish oneFall back to model_number, then retailer_sku with a retailer filter
Keys within specSource page did not state the attributeExclude from that comparison axis. Never infer a value
review_score / review_countNo review coverageRank on other criteria; state that review data is unavailable
colour, release_yearFrequently null by natureOptional by default; never make them required in your own model
Empty arrays (materials, compatible_with)Not applicable to the categoryTreat as unknown, not as “none”

The one rule underneath all of these: do not let a model fill a gap. A missing specification that gets invented becomes a confident, wrong claim attached to a real product with a real retailer link, and it is very hard to detect after the fact.

9. The full record

product object
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "brand": "Optimum Nutrition",
  "category": "protein powder",
  "gtin": "5060245603478",
  "title": "Optimum Nutrition Gold Standard Whey Protein Powder",
  "description": "The Optimum Nutrition Gold Standard 100% Whey delivers 24g of protein...",
  "product_description": "Premium whey protein powder with 24g protein per serving...",
  "key_selling_points": ["24g protein per serving", "5.5g BCAAs", "Informed Sport certified"],
  "use_cases": ["post-workout recovery", "muscle building", "competitive athletes"],
  "spec": {
    "protein_per_serving": "24g",
    "servings": "29",
    "calories_per_serving": 120,
    "bcaa_per_serving": "5.5g",
    "flavour": "Double Rich Chocolate"
  },
  "cosmetic_features": { "packaging_style": "resealable tub" },
  "image_url": "https://images.optimumnutrition.co.uk/whey-front.jpg",
  "images": [
    "https://images.optimumnutrition.co.uk/whey-front.jpg",
    "https://images.optimumnutrition.co.uk/whey-nutrition-label.jpg"
  ],
  "visual": {
    "summary": "Black whey protein tub with red and gold accents...",
    "labels": ["protein powder", "supplement tub", "black packaging"],
    "detected_text": ["Gold Standard", "24g Protein"],
    "dominant_colours": ["black", "red", "gold"]
  },
  "certifications": ["informed_sport", "gluten_free"],
  "materials": [],
  "dimensions": { "value": { "h": 24, "diameter": 16 }, "unit": "cm" },
  "weight": { "value": 0.899, "unit": "kg" },
  "colour": { "primary": null, "family": null },
  "release_year": null,
  "country_of_origin": "US",
  "compatible_with": [],
  "included_in_box": ["scoop"],
  "model_number": "GS100W-2270G-DRC",
  "retailer_sku": "ON-2270G-GB",
  "product_identifiers": {
    "article_number": "GSWHEY-2LB-CHOC",
    "alternate_part_numbers": ["1031660-P"]
  },
  "review_score": 4.8,
  "review_count": 20,
  "price": {
    "amount": 29.99,
    "currency": "GBP",
    "retailer": "Holland & Barrett",
    "as_of": "2026-04-07"
  },
  "links": {
    "buy": "https://www.hollandandbarrett.com/shop/product/...",
    "retailer": "https://www.hollandandbarrett.com/shop/product/..."
  },
  "market": "gb",
  "relevance_score": 0.923
}

Frequently asked questions

Should I store the full record or re-fetch it?
Store what you need for your own ranking and display, and always store the id. Re-fetching through /v1/product costs 1 credit against 2 for a fresh search, so caching UUIDs is the cheapest refresh path. Store price with its as_of date so you can decide when a cached value has aged past what your interface should show.
How do I compare products across different categories?
Generally you should not. Specification keys are category-dependent by design — protein per serving and noise level are not on the same axis. Compare within a category using rules defined for that category, and when a shopper's request spans categories, group the results rather than forcing a single ranked list.
Can I map this to schema.org Product markup?
Partially, and only where it matches what your page actually shows. The obvious correspondences are brand, gtin, sku, mpn, image, description, aggregateRating and offers. But Google's guidance is explicit that structured data must reflect visible page content, so do not mark up a third-party price snapshot as if it were your own offer. Mark up what you sell; use the API record for retrieval and comparison inside your application.
Why are relevance_score and visual_similarity_score separate?
Because they measure different things. relevance_score is a cosine similarity between the query and the product's text representation, on a 0–1 scale, returned only by /v1/search. visual_similarity_score is a visual-match measure returned only by image search. Averaging them, or sorting a mixed list on whichever is present, produces a ranking that means nothing.

Sources

Jay

Co-founder, simlir

Jay is the co-founder of simlir