A schema validator for Organizational Schema Theory specifications -- reverse-design TDD for business operations.
Organizational Schema Theory is a methodology where businesses are designed backward from customer experience goals using testable, version-controlled YAML specifications. Each operational layer validates the layer above it, forming a multi-level TDD cascade:
L0: Customer Experience Contract → acceptance tests
L1: Signal Requirements → integration tests
L2: Process Contracts → unit tests
L3: Procedures → implementation
L4: Input Specifications → dependencies
L5: Sourcing Requirements → infrastructure
This framework provides the validation tooling: JSON schemas and a CLI validator that checks your specifications for structural correctness, cross-reference integrity, signal coverage, and experience traceability.
Requires Python 3.12+.
# Clone the framework
git clone https://github.com/spectralbranding/orgschema-framework.git
cd orgschema-framework
# Install with uv (recommended)
uv sync
# Or install with pip
pip install -e .Validate the Spectra Coffee demo specifications:
# Clone the demo repository
git clone https://github.com/spectralbranding/orgschema-demo.git
# Run the validator against it
orgschema-validate ./orgschema-demoExpected output (all levels passing):
=== Orgschema TDD Cascade Validator ===
Validating: ./orgschema-demo
Level 1: Schema Validation
[PASS] organization.yaml
[PASS] products/espresso.yaml
[PASS] products/oat_latte.yaml
...
Level 2: Cross-Reference Integrity
[PASS] All satisfies_signal references resolve
[PASS] All satisfies_experience references resolve
Level 4: Signal Coverage
[PASS] All 18 signal requirements have satisfying specifications
Level 5: Experience Traceability
[PASS] All products trace to experience goals
[PASS] All processes trace to experience goals
Results: 0 errors, 0 warnings
The validator implements 4 of the 6 TDD cascade validation levels:
| Level | Name | What It Checks |
|---|---|---|
| 1 | Schema Validation | YAML files conform to JSON Schema (structure, types, required fields) |
| 2 | Cross-Reference Integrity | satisfies_signal and satisfies_experience annotations reference valid targets |
| 4 | Signal Coverage | Every signal requirement in perception/signal_requirements.yaml has at least one satisfying specification |
| 5 | Experience Traceability | Every product and process traces upward to an L0 customer experience goal |
Levels 3 (contract satisfaction) and 6 (waste detection) are planned for future releases.
Four JSON Schema files define the structure of orgschema specifications:
| Schema | Validates | Required Fields |
|---|---|---|
organization.json |
organization.yaml |
name, type, version |
product.json |
products/*.yaml |
version, id, name, category, available |
process.json |
processes/*.yaml |
version |
compliance.json |
compliance/*.yaml |
version |
All schemas use JSON Schema Draft 2020-12 and allow additional properties for extensibility.
Product IDs must be lowercase with underscores: ^[a-z][a-z0-9_]*$
Version strings follow semver: ^\d+\.\d+\.\d+$
Signal references link to L1: satisfies_signal: ["L1_taste_quality", "L1_craft_preparation"]
Experience references link to L0: satisfies_experience: ["L0_product_excellence"]
orgschema-framework/
├── orgschema_framework/
│ ├── __init__.py
│ ├── validate.py # CLI validator (4 validation levels)
│ └── schemas/
│ ├── compliance.json
│ ├── organization.json
│ ├── process.json
│ └── product.json
├── CITATION.cff
└── pyproject.toml
Add the validator to your GitHub Actions workflow:
- name: Validate orgschema specifications
run: |
pip install -e path/to/orgschema-framework
orgschema-validate .The validator returns exit code 1 on errors, making it suitable for CI/CD pipelines. Warnings are non-fatal.
See orgschema-demo/.github/workflows/ci.yml for a working example.
Start with organization.yaml:
name: "My Coffee Shop"
type: "food_and_beverage"
version: "0.1.0"
mission: "Serve excellent coffee with transparency"Then specify a product:
version: "0.1.0"
id: "espresso"
name: "Espresso"
category: "hot_beverage"
available: true
preparation:
method: "espresso_extraction"
equipment: ["espresso_machine", "grinder"]
ingredients:
coffee_beans:
origin: "Ethiopia"
weight_g: 18
pricing:
price: 3.50
currency: "EUR"
satisfies_signal:
- "L1_taste_quality"
- "L1_craft_preparation"
satisfies_experience:
- "L0_product_excellence"Run orgschema-validate . to check your work. The validator will tell you what is missing or misconfigured.
- orgschema-demo -- Spectra Coffee: a complete demonstration of the orgschema methodology (25 YAML files, 6 products, full TDD cascade)
- sbt-framework -- Spectral Brand Theory: the perception measurement framework that provides orgschema's L0-L1 test specification language
If you use this framework in academic work:
@software{zharnikov2026orgschema,
author = {Zharnikov, Dmitri},
title = {Organizational Schema Theory Framework},
year = {2026},
url = {https://github.com/spectralbranding/orgschema-framework},
version = {0.1.0}
}See CITATION.cff for the full citation metadata.
MIT
Clone the repository and enter the directory:
git clone https://github.com/spectralbranding/orgschema-framework.git
cd orgschema-frameworkPython dependencies are managed via uv (Python ≥ 3.12):
uv sync --extra devThe project anchor is pyproject.toml at the repository root.
.
├── orgschema_framework/ # Python package (CLI validator + JSON schemas)
│ ├── __init__.py
│ ├── validate.py
│ └── schemas/
│ ├── compliance.json
│ ├── organization.json
│ ├── process.json
│ └── product.json
├── output/ # Generated artifacts
│ ├── figures/
│ ├── tables/
│ └── logs/ # reproduce.sh master_run.log lands here
├── CITATION.cff # Machine-readable citation
├── LICENSE # MIT (code)
├── LICENSE-data # CC BY 4.0 (data + figures + schemas)
├── pyproject.toml # Python project anchor + dependencies
├── reproduce.sh # Single-command reproduction
├── README.md # This file
└── .gitignore # Excludes secrets, env, build artifacts
Reproduce dependency install + test suite + CLI smoke check:
./reproduce.shThe script runs uv sync --extra dev, executes the pytest suite (if any tests are collected), verifies the orgschema-validate CLI installs, and logs run details to output/logs/master_run.log.
To validate a target specifications directory directly, see the "Quick Start" section above.
Runtime dependencies (pinned in pyproject.toml):
pyyaml >= 6.0jsonschema >= 4.20.0
Development dependencies (install via uv sync --extra dev):
pytest >= 7.0black >= 24.0,flake8 >= 7.0,mypy >= 1.8types-PyYAML
Install with uv sync (runtime) or uv sync --extra dev (with dev tools).
| Block | Entry point | Inputs | Outputs |
|---|---|---|---|
| Validation CLI | orgschema-validate <path> |
YAML specs at <path> |
stdout PASS/FAIL summary; exit code 0/1 |
| Schema files | orgschema_framework/schemas/*.json |
— | Reused by validate.py |
| Test suite | pytest |
tests/ (if present) |
output/logs/master_run.log |
| Full reproduction | ./reproduce.sh |
repo root | output/logs/master_run.log |
If you build on this framework, please cite:
Dmitry Zharnikov (2026). "Organizational Schema Theory Framework." https://github.com/spectralbranding/orgschema-framework
Machine-readable citation: see CITATION.cff. GitHub's "Cite this repository" button, Zotero, Mendeley, and Pandoc all read this format natively.
- Code — © Dmitry Zharnikov, 2026. MIT Licence.
- Data, schemas, figures, tables — © Dmitry Zharnikov, 2026. CC BY 4.0.
Both licences permit reuse with attribution. The MIT Licence permits modification and redistribution of code; CC BY 4.0 permits any reuse of data, schemas, and rendered artifacts with attribution to the author.
Last updated: 2026-05-29