Saleor Domain Modeling

Overview

This skill helps you design your product catalog structure in Saleor -- choosing the right product types, attributes, variants, categories, and collections. The key decisions are what makes a product vs. a variant, and which attribute type to use for each field.

When to Use

• "How do I model my products?"
• "What attributes should I use?"
• "Product vs variant attributes?"
• "When to use DROPDOWN vs MULTISELECT?"
• "How to structure my product types?"
• "Categories vs Collections?"
• "When to use Models (Pages) vs Attributes?"
• When NOT looking for YAML syntax -- use configurator-schema instead
• When NOT looking for CLI commands -- use configurator-cli instead

The Core Flow

This is the most important relationship to understand:

1. ATTRIBUTES (define fields)
   └── Reusable typed fields: Size (DROPDOWN), Color (SWATCH), Brand (DROPDOWN)

2. PRODUCT TYPES (define structure)
   └── Assign attributes:
       ├── productAttributes: Brand, Material (same for all variants)
       └── variantAttributes: Size, Color (create SKU combinations)

3. PRODUCTS (create items)
   └── Instance of a ProductType:
       ├── Set values: Brand="Nike", Material="Cotton"
       └── Define variants with SKU combinations

4. VARIANTS (purchasable SKUs)
   └── Each combination = 1 variant:
       ├── SKU: "TSHIRT-BLK-M" -> Size="M", Color="Black", Price=$29.99
       └── SKU: "TSHIRT-WHT-L" -> Size="L", Color="White", Price=$29.99

Key insight: Attributes are building blocks. ProductTypes assemble them into templates. Products are instances. Variants are what customers buy.

Decision Framework: Product vs Variant Attributes

This is the most critical modeling decision.

Use Product-Level When:

Use Variant-Level When:

Quick Decision Matrix

Attribute Type Selection

Saleor supports 12 attribute input types. Use this decision tree:

Is it a CHOICE from predefined options?
├── YES: Can user select MULTIPLE?
│   ├── YES -> MULTISELECT
│   └── NO: Is it a COLOR/PATTERN?
│       ├── YES -> SWATCH
│       └── NO: Is it YES/NO?
│           ├── YES -> BOOLEAN
│           └── NO -> DROPDOWN
└── NO: Is it a NUMBER with units?
    ├── YES -> NUMERIC
    └── NO: Is it a DATE?
        ├── YES -> DATE (or DATE_TIME if time needed)
        └── NO: Is it long formatted text?
            ├── YES -> RICH_TEXT
            └── NO: Is it a file/document?
                ├── YES -> FILE
                └── NO: Link to another entity?
                    ├── YES -> REFERENCE
                    └── NO -> PLAIN_TEXT

For the complete attribute type reference, see references/attribute-types-deep-dive.md.

Variant Matrix Planning

Before creating variants, calculate the SKU explosion:

SKU Count = Value1 x Value2 x Value3 x ...

Example: T-Shirt
- Sizes: XS, S, M, L, XL, XXL (6)
- Colors: Black, White, Navy, Gray, Red (5)
- SKUs: 6 x 5 = 30 variants per product

Tips for high counts: Split by product line, reduce dimensions, move non-purchasable attributes to product level.

Industry Patterns

Quick reference for common store types:

For complete YAML examples of each pattern, see references/industry-patterns.md.

Categories vs Collections

Both organize products, but they serve different purposes:

Use Categories for main site navigation, browse/filter structure, SEO URLs. Use Collections for curated groups, promotions, campaigns, temporary groupings.

Keep category trees to 3 levels deep. If you need a 4th level, consider using Collections instead.

Models and Structures

Models (Pages/PageTypes) let you create custom entities beyond products -- like Brands, Ingredients, or Scent Profiles. Use them when data is shared across many products, has its own attributes, and needs its own page.

Structures (Menus) assemble Categories, Collections, Models, and URLs into navigation hierarchies.

For complete guidance and examples, see references/models-and-structures.md.

Workflow: Designing a New Product Type

1. List all product characteristics -- write down every field/attribute
2. Categorize each -- apply the decision framework (product vs variant)
3. Select types -- use the attribute type decision tree
4. Calculate SKU count -- ensure the variant matrix is manageable
5. Write the YAML -- create the ProductType configuration
6. Validate -- deploy with --plan to check structure

Common Mistakes

Additional Resources

Reference Files

• references/attribute-types-deep-dive.md -- complete attribute type reference
• references/industry-patterns.md -- detailed YAML for 5+ industries
• references/models-and-structures.md -- Models and Structures guide

Related Skills

• configurator-schema - Complete YAML schema reference
• saleor-domain - Entity relationships and Saleor concepts
• configurator-recipes - Complete store templates