saleor 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-modelinginstead
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
- Required fields -- each entity type has required fields (e.g., channels need
name,slug,currencyCode) - Unique identifiers -- slugs/names must be unique within their entity type
- Valid references -- cross-entity references must match (e.g., a product's
productTypemust match a defined product type name) - Currency codes -- valid ISO 4217 (USD, EUR, GBP, etc.)
- 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
- Use meaningful slugs --
womens-summer-dressesnotcat-123 - Consistent naming -- match display names to slugs when possible
- Comment complex sections -- use YAML comments for documentation
- 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 rulesconfigurator-cli- CLI commands for deploying configurationsproduct-modeling- Product type design and attribute selection