A practical product data schema for AI shopping assistants

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.

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.

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:

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 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.

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.

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

Frequently asked questions