saleor/configurator-schema

Configurator Schema

Overview

Your store configuration lives in a single config.yml file. Each section defines a type of entity (channels, products, categories, etc.) using a declarative YAML format that Configurator syncs with your Saleor instance.

When to Use

• "What does config.yml look like?"
• "What fields are required for a product/channel/category?"
• "Why is my config failing validation?"
• "What's the difference between slug-based and name-based entities?"
• "How do I reference one entity from another?"
• When NOT designing product types or choosing attributes -- use product-modeling instead

File Structure

# config.yml - Top-level structure
shop:               # Store-wide settings (singleton)
channels:           # Sales channels (slug-based)
productAttributes:  # Standalone product attributes
contentAttributes:  # Standalone content attributes
productTypes:       # Product type definitions (name-based)
modelTypes:         # Model type definitions (name-based) — preferred over pageTypes
pageTypes:          # Page type definitions (name-based) — alias for modelTypes
categories:         # Category hierarchy (slug-based)
collections:        # Product collections (slug-based)
products:           # Product definitions (slug-based)
models:             # Content models/pages (slug-based)
taxClasses:         # Tax classifications (name-based)
shippingZones:      # Shipping zone definitions (name-based)
warehouses:         # Warehouse definitions (slug-based)
menus:              # Navigation menus (slug-based)

Entity Identification

Configurator matches your local config to remote entities using an identifier field. This is either slug or name depending on entity type:

| Identifier | Entity Types | |------------|-------------| | slug | channels, categories, collections, products, warehouses, menus, models | | name | productTypes, modelTypes/pageTypes, taxClasses, shippingZones |

Important: Changing a slug or name creates a NEW entity instead of updating the existing one.

Common Entity Examples

Channel

channels:
  - name: "US Store"
    slug: "us-store"
    currencyCode: USD
    defaultCountry: US
    isActive: true

Product Type

productTypes:
  - name: "T-Shirt"
    isShippingRequired: true
    productAttributes:
      - name: "Brand"
        type: DROPDOWN
    variantAttributes:
      - name: "Size"
        type: DROPDOWN
        values: [{ name: "S" }, { name: "M" }, { name: "L" }]
      - name: "Color"
        type: SWATCH

Product

products:
  - name: "Classic T-Shirt"
    slug: "classic-t-shirt"
    productType: "T-Shirt"
    category: "clothing/t-shirts"
    variants:
      - sku: "TSHIRT-S-RED"
        attributes:
          Size: "S"
          Color: "Red"
        channelListings:
          - channel: "us-store"
            price: 29.99

Category (hierarchical)

categories:
  - name: "Electronics"
    slug: "electronics"
    subcategories:
      - name: "Phones"
        slug: "phones"

Attribute Types

Saleor supports these attribute input types: DROPDOWN, MULTISELECT, SWATCH, BOOLEAN, PLAIN_TEXT, RICH_TEXT, NUMERIC, DATE, DATE_TIME, FILE, REFERENCE.

For detailed guidance on choosing the right type, see the product-modeling skill.

Validation Rules

1. Required fields -- each entity type has required fields (e.g., channels need name, slug, currencyCode)
2. Unique identifiers -- slugs/names must be unique within their entity type
3. Valid references -- cross-entity references must match (e.g., a product's productType must match a defined product type name)
4. Currency codes -- valid ISO 4217 (USD, EUR, GBP, etc.)
5. Country codes -- valid ISO 3166-1 alpha-2 (US, DE, GB, etc.)

Entity Dependencies

Entities depend on each other and must exist in the right order:

Level 0 (independent):  shop, channels, productTypes, pageTypes, taxClasses, shippingZones
Level 1 (needs L0):     categories, warehouses, attributes
Level 2 (needs L1):     collections, pages
Level 3 (needs L2):     products, menus

Configurator handles deployment order automatically, but understanding dependencies helps when troubleshooting validation errors.

Common Mistakes

| Mistake | Fix | |---------|-----| | Changing a slug or name to "rename" an entity | This creates a new entity. To rename, delete the old one and create new. | | Duplicate slugs within an entity type | Each slug must be unique. Check for copy-paste errors. | | Product references a nonexistent productType | The productType field must exactly match a name in your productTypes section. | | Missing required fields | Check the error message -- it tells you which field is missing. | | Products defined before their productType | Not a YAML order issue (Configurator handles order), but the referenced type must exist in the file. |

Best Practices

1. Use meaningful slugs -- womens-summer-dresses not cat-123
2. Consistent naming -- match display names to slugs when possible
3. Comment complex sections -- use YAML comments for documentation
4. Version control -- track config.yml in git

See Also

• For complete schema documentation, see references/schema.md
• For example configurations, see references/examples.md

Related Skills

• saleor-domain - Entity relationships and identifier rules
• configurator-cli - CLI commands for deploying configurations
• product-modeling - Product type design and attribute selection