Catalog and product modeling

Catalog and product modeling

How to structure the sellable surface of a commerce system. This skill frames the modeling decisions; it does not prescribe a schema. The right schema depends on the business model, product type, and the variation dimensions enumerated below.

Read the domain-vocabulary skill first. Terms used here without redefinition are defined there: product, variant, SKU, bundle, attribute, option, category, taxonomy, collection, channel, store.

Vocabulary additions

The general terms come from domain-vocabulary. The following are specific to catalog modeling.

Master product (parent product) — In platforms that distinguish parent and variant, the top-level product record holding shared fields (name, description, marketing media). The variants under it carry the differentiating fields (price, SKU, inventory, variant-specific media).

Option type vs option value — Option type is the dimension (Size, Color); option value is the specific choice (Medium, Red). A variant is identified by a tuple of option values, one per option type defined on its parent.

Product type (product class) — A reusable schema describing which attributes and options apply to a product. commercetools and Sylius both expose this; Shopify hints at it via product templates. (commercetools, Sylius)

Faceted attribute — An attribute exposed to the storefront for filtering (brand, material, size). Indexed for query, often denormalized into a search index.

Slug (URL handle) — The URL-safe string identifying a product or category in storefront URLs (/products/red-cotton-shirt). Slugs are part of the SEO surface and must be stable; historical slugs typically need redirects.

Media asset — An image, video, or 3D model attached to a product, variant, or both. Carries metadata: alt text, position, type, and a reference (URL or CDN path).

Catalog scope — The set of products visible in a given channel, store, or region. The same product can be in-catalog for one channel and out-of-catalog for another without being deleted.

Canonical model

Most ecommerce systems converge on this structure:

Product (1) ──< has many >── Variant (N)
   │                            │
   ├── name, description        ├── SKU
   ├── product_type             ├── price (or price list ref)
   ├── slug                     ├── option values { size: M, color: red }
   ├── categories (M)           ├── inventory (per location)
   ├── collections (M)          └── variant-specific media
   ├── product-level media
   └── attributes { brand, material, ... }

Key invariants:

1. One variant per stockable unit. Even a product with no apparent configurability has one variant under it; that variant is what carries inventory and price.
2. Variants are identified by their option-value tuple. Two variants of the same product cannot share the same set of option values.
3. Attributes are descriptive; options generate variants. A field is one or the other, not both. Re-classifying mid-life requires a data migration.
4. Categories form a tree; collections form arbitrary sets. A product has one canonical place in the taxonomy but many collection memberships.
5. Slugs are part of the public API surface. Treat them as immutable from the SEO and integration perspective; if they must change, plan redirects.

Variation dimensions

The canonical model adapts along these axes. Be explicit about where the system sits before choosing a schema.

• Business model — B2C (single price list, simple catalog), B2B (price list per account, restricted catalog visibility), marketplace (vendor-owned products, per-vendor catalog), subscription (the product is a plan), hybrid.
• Product type — Physical (stockable, shippable variants), digital (no inventory, entitlement-based), service (booking-based, no shipment), bundles, configurable-to-order (CTO with generated variants), made-to-order.
• Configurability complexity — Fixed options (predefined size/color matrix) vs free configurators (build-your-own with rules) vs personalized (engraving, embroidery; per-line uniqueness, not pre-modeled variants).
• Catalog scope — Single-channel vs multi-channel vs multi-store. Multi-store decisions: shared product master with per-store overrides, or fully independent catalogs.
• Localization — Single-locale vs multi-locale. Multi-locale: translated name, description, slug, attributes; localized media.
• Search and discovery — Browse-driven (taxonomy-heavy) vs search-driven (attribute-heavy, faceted). Affects whether to over-invest in deep categories or in rich attribute schemas.

Decision frameworks

Variant vs separate product

Use a single product with multiple variants when:

• The buyer perceives them as the same thing in different forms (size, color, material).
• They share the same marketing copy and most media.
• They share a price list structure (one variant cheaper, one more expensive of the same item).

Use separate products when:

• The marketing description, hero media, or category placement differs meaningfully.
• The items are bought for different reasons (a leather wallet and a fabric wallet of the same brand — likely separate products).
• The buyer is unlikely to switch between them in a single shopping decision.

When in doubt: ask whether the storefront URL should be the same. If yes, one product; if no, two.

Attribute vs option

A field is an option if and only if:

• Each value produces a separately stockable, separately priced unit, and
• The buyer selects the value on the product page before adding to cart.

Otherwise it is an attribute (descriptive metadata). Common mistakes:

• Treating "material" as an option when there is only ever one material per product — should be an attribute.
• Treating "brand" as an option — should always be an attribute (or its own entity).
• Treating "color" as an attribute when the customer can choose between several — should be an option.

The cost of getting this wrong: variant explosion (combinatorial blowup when an attribute is wrongly modeled as an option) or stocked-product collapse (cannot sell each color/size separately when an option is wrongly modeled as an attribute).

Taxonomy shape

Three patterns appear most often:

Pattern	Description	When to choose
Deep tree	4+ levels (Apparel > Men > Tops > Shirts > Dress shirts)	Catalog with thousands of products and clear hierarchical browsing intent.
Shallow tree + facets	2–3 levels, rich faceted attributes	Catalog where buyers filter (electronics, fashion with many attributes).
Flat + collections	One level of categories, curated collections do the rest	Boutique catalogs, brand storefronts, content-driven commerce.

Pick deliberately. Mixing them in one store means buyers encounter inconsistent navigation; the engineering complexity also compounds.

Categories vs collections vs tags

Mechanism	Cardinality	Buyer-facing?	Purpose
Category	One canonical per product (taxonomy is a tree)	Yes — navigation	Find by what the product is
Collection	Many per product (arbitrary set)	Yes — merchandising	Curate by editorial logic (sale, seasonal, themed)
Tag	Many per product	Often internal	Filtering, internal taxonomy, AI features

If the system needs only one of these, prefer categories. The pull to add collections appears when merchandising needs decouple from taxonomy ("Summer Sale" cuts across the tree).

Slug strategy

Three positions:

1. Auto-generated, never editable. Lowest operational cost; SEO-fragile if the auto rule changes.
2. Auto-generated, editable, history kept. Balanced: editors can refine, redirects auto-create on change. Most platforms default here.
3. Manually authored, history kept. Best SEO control; highest operational burden.

Choose 2 unless there is a specific reason to constrain editors.

Multi-store catalog sharing

Three positions:

1. Independent catalogs per store. Maximum flexibility, maximum duplication.
2. Shared master with per-store visibility. Single source of truth, store-specific catalog scope.
3. Shared master with per-store overrides. Single source of truth, store-specific name/description/price/media as needed.

Choice 2 is the default for multi-region stores selling the same products at different prices. Choice 3 is needed when localized descriptions and media diverge meaningfully. Choice 1 is correct when stores represent independent brands sharing only infrastructure.

Bundle modeling

Three patterns:

• Virtual bundle (assembled at order): the bundle is a product whose available inventory is min(component_available). No bundle-level on-hand; fulfillment picks components.
• Physical bundle (pre-assembled): the bundle is its own stockable variant with independent on-hand. Components are not tracked as separate stockable units once assembled.
• Configurable bundle (build-your-own): the bundle is a configurator that emits a cart of independent line items; the bundle itself has no SKU.

The choice cascades into inventory, fulfillment, returns, and reporting. Decide before modeling the data, not after.

Catalog at scale

The decisions above hold at any catalog size; the physical realization changes once the catalog crosses ~100k variants or experiences peak-traffic spikes. Three concerns surface:

Browse vs search authority. At low scale, the OLTP product database answers both browse (category listings) and search (queries, filters). At high scale, search is offloaded to a dedicated index (Elasticsearch, OpenSearch, Algolia, Meilisearch) and the OLTP database becomes the system of record but not the read source. The index is rebuilt asynchronously from product changes — eventual consistency the storefront must tolerate (newly created products are not searchable for seconds to minutes). AWS retail reference architectures and Alibaba's Taobao platform both follow this split. (AWS retail architecture, Alibaba Cloud retail)

Read-through caching. Product reads outnumber writes by orders of magnitude. A read-through cache (Redis, Memcached, or a CDN edge cache) keyed by (product_id, locale, channel) reduces database load. The cache-aside pattern is canonical; invalidation must be triggered by every write that affects a cached projection. (Azure cache-aside pattern)

Faceted search index design. Each faceted attribute requires index support. Adding a new facet on an existing catalog typically triggers a full re-index; design the attribute schema with the facets you expect, plus a generic "extension attributes" map for additions that do not need facet support. Shopify Engineering's posts on sharding the catalog illustrate the cost of late schema changes. (Shopify Engineering)

These are physical patterns; they do not change the canonical model above. The vocabulary stays product/variant/attribute/option — only the storage and read path change.

Anti-patterns

• One product per variant. Loses the shared marketing surface; produces duplicated descriptions; breaks the "one URL per product" SEO model. Symptom: 12 nearly identical search results for one T-shirt in different sizes.
• No master product, only variants. Conversely, modeling everything as flat variants makes shared editorial impossible. Symptom: changing the product description requires updating N rows.
• Storing price on the master product. Variants must each carry their own price (or price-list reference). Master-level price breaks when variants legitimately differ in cost. Symptom: cannot price the L size higher than the S size.
• Treating SKU as the primary key. SKUs change for business reasons (rebrand, supplier change, merger). Use a system-generated stockable ID and treat SKU as a label. Symptom: cannot rename a SKU without rewriting integrations.
• Variant explosion via attributes-as-options. Marking every descriptive field as an option produces N×M×K variants where most are never stocked. Symptom: 800 variants per product, 780 of them with zero inventory.
• Re-using slugs after deletion. A deleted product's slug should be reserved (404 or redirect), not reassigned. Otherwise external links point to the wrong product when reused.
• Embedding category in the slug as the primary identifier. Tying the URL to category placement means recategorizing breaks links. Use category-free product slugs and let category be a route concern only.
• Storing translations as separate products. Locale-variant products produce orphan duplication and break analytics. Translations belong on the same product as locale-keyed fields.
• Treating digital and physical products with one model. Digital products lack shipping, inventory locations, and weight; physical products lack download URLs and license keys. Sharing one schema forces null-everywhere. Discriminate at the product-type level.
• Collections doing the job of categories (or vice versa). Mixing them confuses merchandisers and breaks navigation. Pick the responsibility of each up front: categories = what it is; collections = what it's for.

Sources

• Medusa product module — https://docs.medusajs.com/resources/commerce-modules/product
• Shopify product and variant model — https://shopify.dev/docs/api/admin-rest/latest/resources/product
• Shopify metafields and product types — https://shopify.dev/docs/apps/build/custom-data
• Sylius products, variants, options — https://docs.sylius.com/the-book/products/products
• commercetools product types — https://docs.commercetools.com/api/projects/productTypes
• commercetools product projections — https://docs.commercetools.com/api/projects/productProjections
• Google — Product structured data — https://developers.google.com/search/docs/appearance/structured-data/product
• Schema.org Product — https://schema.org/Product
• AWS Prescriptive Guidance — DynamoDB data modeling (product catalog) — https://docs.aws.amazon.com/prescriptive-guidance/latest/dynamodb-data-modeling/welcome.html
• AWS retail architecture — https://aws.amazon.com/retail/architecture/
• Azure cache-aside pattern — https://learn.microsoft.com/en-us/azure/architecture/patterns/cache-aside
• Alibaba Cloud retail solutions (Taobao catalog patterns) — https://www.alibabacloud.com/solutions/retail
• Shopify Engineering (catalog sharding) — https://shopify.engineering/
• Zalando Engineering — catalog modeling at European scale — https://engineering.zalando.com/
• Wayfair Tech — recommendation and big-ticket catalog — https://www.aboutwayfair.com/careers/tech-blog
• Amazon Science — product graph and personalization — https://www.amazon.science/
• Mercado Libre Engineering — multi-country catalog patterns — https://medium.com/mercadolibre-tech
• MACH Alliance — composable catalog principles — https://machalliance.org/resources