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)
productTypes:   # Product type definitions (name-based)
attributes:     # Attribute definitions (name-based)
categories:     # Category hierarchy (slug-based)
collections:    # Product collections (slug-based)
products:       # Product definitions (slug-based)
taxClasses:     # Tax classifications (name-based)
shippingZones:  # Shipping zone definitions (name-based)
warehouses:     # Warehouse definitions (slug-based)
menus:          # Navigation menus (slug-based)
pageTypes:      # Page type definitions (name-based)
pages:          # Content pages (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:

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"
    children:
      - 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

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