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.
| Field | Type | Why it earns its place |
|---|---|---|
id | UUID | Stable and permanent. Cache it: a later fetch through /v1/product costs 1 credit instead of a 2-credit search. |
gtin | string | The strongest cross-retailer key. If you are joining to a merchant feed, this is the join column. |
model_number | string | MPN. Reliable within a brand and essential where GTINs are inconsistent. Note: type=mpn on lookup maps onto this field. |
retailer_sku | string | Retailer-specific, so only meaningful alongside the retailer. Pair with a retailer filter when looking up. |
product_identifiers | object | Article numbers and alternate part numbers — the long tail that rescues matches in categories with messy identity. |
brand, title | string | Human-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.
categorydrives 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_casescaptures 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_originandrelease_yearcarry 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 visibledetected_text, and dominant colours. It is derived from the hero image and safe to show to users or pass to an agent. It isnullwhen 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": {
"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.
7. Retailer link and market
links.retailer— the captured retailer product page. This is where a shopper goes to inspect availability, delivery terms and the current offer. It may benullwhen 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/searchresults; cosine similarity between 0 and 1.visual_similarity_scoreis its image-search counterpart. They measure different things and must not be blended into one ranking number.
"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.
| Field | When it can be absent | Recommended behaviour |
|---|---|---|
links.retailer / links.buy | No verified retailer product URL for the row | Suppress the call to action; keep the product visible |
visual | Row not yet visually enriched | Fall back to image_url and text; do not describe the image yourself |
gtin | Category or retailer does not publish one | Fall back to model_number, then retailer_sku with a retailer filter |
Keys within spec | Source page did not state the attribute | Exclude from that comparison axis. Never infer a value |
review_score / review_count | No review coverage | Rank on other criteria; state that review data is unavailable |
colour, release_year | Frequently null by nature | Optional by default; never make them required in your own model |
Empty arrays (materials, compatible_with) | Not applicable to the category | Treat 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
{
"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?
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?
Can I map this to schema.org Product markup?
Why are relevance_score and visual_similarity_score separate?
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.