Data Validation

The Stylebook validates generated brand data against JSON Schemas to protect the contract between generate and build.

Pipeline Position

brand/ → generate → output/ → **validate** → build → packages/

Validation runs after generate produces JSON and before build consumes it. If validation fails, build does not proceed.

Running Validation

# Validate everything
stylebook validate

# Validate a single domain
stylebook validate --domain color

# Detailed output
stylebook validate --verbose

Via Taskfile: task validate. The task build command runs validation automatically.

Schema Structure

Schemas live in stylebook/domains/validator/schemas/.

Shared Schemas

Domain Schemas

Each domain has a schema validating its data key deeply:

Root Schema

brand.json validates the complete output/brand.json — root metadata keys (brand, identity, audience, etc.) plus all domain keys referencing their individual schemas.

Adding a New Domain

When adding a new domain to brand/:

1. Create stylebook/domains/validator/schemas/<domain>.json
2. Follow the pattern: allOf: [{$ref: _envelope.json}] plus data properties
3. Inspect actual output: uv run python -c "import json; print(json.dumps(json.load(open('output/data/<domain>.json'))['data'], indent=2))"
4. Run stylebook validate to verify

Progressive Tightening

Schemas start matching current output and can be tightened over time:

1. Phase 1 (current): Schemas match existing data structure
2. Phase 2: Standardize doc objects — require description everywhere
3. Phase 3: Tighten metadata — require status, overview
4. Phase 4: Enforce naming conventions