File Structure
Repository layout and naming conventions
A conforming ChooChoo repository MUST have the following structure. For a gentler introduction, see the Getting Started: Project Structure guide.
Directory Layout
Directory Descriptions
| Directory | Contents | Related Documentation |
|---|---|---|
.choochoorc | Project configuration file (JSON) | Configuration |
.choochoo/ | Metadata including approval policies | Approval Workflows |
products/ | Data Product definitions following ODPS | Products (ODPS) |
contracts/ | Data Contract definitions following ODCS | Contracts (ODCS) |
workflows/ | Workflow definitions following Arazzo | Workflows (Arazzo) |
apis/ | OpenAPI and AsyncAPI specifications | Standards Reference |
agents/ | Agent registration and boundaries | Agents |
system-cards/ | System Card identity documents | System Cards |
File Naming Conventions
File names MUST:
- Use lowercase letters, numbers, and hyphens only.
- Not contain spaces or special characters.
- Be unique within their directory.
| Artifact Type | Pattern | Example |
|---|---|---|
| Product | <name>.yaml | customer-360.yaml |
| Contract | <name>.contract.yaml | customer-360.contract.yaml |
| Workflow | <name>.workflow.yaml | onboarding.workflow.yaml |
| OpenAPI | <name>.openapi.yaml | payments.openapi.yaml |
| AsyncAPI | <name>.asyncapi.yaml | events.asyncapi.yaml |
| System Card | <name>.yaml | code-assistant.yaml |
Violations of these naming conventions are detected during the first step of the validation pipeline and produce error E003 (Invalid file extension).
Configuration File
The .choochoorc file in the project root is a JSON file that controls all Engine behavior. See the Configuration guide for the full schema and options, including:
- Validation strictness and schema version pinning
- Governance rules and compliance tag policies
- Agent enablement and registry path
Initialization
Running choochoo init creates this directory structure automatically. Use the --with-agents flag to include the agents/ and system-cards/ directories. See the Quickstart for a step-by-step walkthrough.
Related
Project Structure
A practical overview of the directory layout with explanations for each directory.
Schema Definitions
The JSON Schemas that each artifact type must conform to.
Validation Rules
The validation pipeline that checks file naming, syntax, schemas, and quality rules.
Configuration
Full documentation for the .choochoorc configuration file schema and options.