Project Structure
What choochoo init creates
Running choochoo init scaffolds a content directory with example files. By default it creates ./choochoo/docs, but you can change this with --dir.
Layout
choochoo/docs/
├── domains/ # Business domain definitions
├── teams/ # Team ownership metadata
├── agents/ # AI agent descriptions
├── data-products/ # Data Product definitions (ODPS)
├── data-contracts/ # Data Contract definitions (ODCS)
├── access-agreements/ # Data access agreements
├── schemas/ # Schema definitions
├── specifications/ # API and interface specs
├── workflows/ # Workflow definitions (Arazzo)
├── business-definitions/ # Business glossary terms
├── services/ # Service catalog entries
├── events/ # Event catalog entries
├── changelogs/ # Change history
└── agent-traces/ # Example trace recordsEach directory contains example YAML files that you can edit or replace with your own content.
What goes where
| Directory | Contains | Validated against |
|---|---|---|
data-products/ | Product definitions | ODPS schema |
data-contracts/ | Contract definitions | ODCS schema |
agents/ | Agent descriptions | — |
workflows/ | API workflows | Arazzo schema |
schemas/ | Custom schemas | — |
| Others | Documentation and metadata | — |
Validation
Run choochoo validate against the content directory to check all files:
choochoo validate ./choochoo/docsThe validator auto-detects schema types from file content. See CLI Reference for details on detection rules.
File naming
- Use lowercase letters, numbers, and hyphens only.
- No spaces or special characters.
- YAML (
.yaml,.yml) and JSON (.json) are both supported.
Related data
ChooChoo also stores runtime data in the project root:
| Path | Purpose |
|---|---|
.choochoo/traces.ndjson | Agent trace records |
See Configuration for all paths and environment variables.