Schema Definitions

ChooChoo enforces strict schemas for all artifacts. All schemas are validated using JSON Schema Draft-07 via a compliant validator. For the full validation pipeline, see Validation Rules. For supported standard versions, see Version Compatibility.

Product Schema (ODPS)

ChooChoo implements the Open Data Product Standard v1.0.0.

Required fields:

• dataProductSpecification: 1.0.0
• info: Object containing id, name, version, owner, status.
• inputPorts: List of dependencies.
• outputPorts: List of data exposed by the product.

Products go through a defined lifecycle with strict state transitions enforced by the validation engine. The status field must be a valid lifecycle state (draft, proposed, active, deprecated, retired). Invalid transitions produce error E009.

Output ports reference Contracts via the contract field, creating edges in the Lineage Graph. Missing references produce error E004.

For a detailed guide on working with Products, see Products (ODPS).

Contract Schema (ODCS)

ChooChoo implements the Open Data Contract Standard v3.1.0.

Required fields:

• dataContractSpecification: 3.1.0
• id: Unique contract ID.
• models: Data schema definitions.
• quality: SLA and quality rules.

ChooChoo extends ODCS with compliance tags (complianceTags array on fields) that trigger governance workflows and affect risk scoring. Fields tagged with pii: true are subject to special security considerations, including masking for agents without PII access.

The quality section follows a specific grammar for defining rules — see Validation Rules for the quality rule grammar.

For a detailed guide on working with Contracts, see Contracts (ODCS).

Workflow Schema (Arazzo)

ChooChoo implements the Arazzo v1.0 specification.

Required fields:

• arazzo: 1.0.0
• workflows: List of workflows and steps.
• steps.requiresApproval: (Extension) Boolean flag for approval gates.

ChooChoo extends Arazzo with governance-specific fields:

• requiresApproval: When true, the step pauses execution and triggers the configured approval workflow.
• approvalPolicy: References a named policy in .choochoo/approval-policies.yaml — see Configuration.
• successCriteria: Validation logic for step outputs, using the same quality rule grammar as contracts.

Workflow steps can reference Contracts via contractRef, which creates edges in the Lineage Graph.

For a detailed guide on working with Workflows, see Workflows (Arazzo).

System Card Schema

Required fields:

• systemCardSpecification: 1.0.0
• info: Metadata about the AI system.
• intendedUse: List of allowed uses.
• limitations: Known failure modes.
• compliance: Frameworks and data residency.

The compliance.frameworks field determines which compliance reporting frameworks the agent falls under. The limitations field documents known failure modes, which informs the Historical Quality (H) factor in risk scoring.

System Cards should be referenced from the Agent Registry (agents/AGENTS.md). Unreferenced System Cards produce warnings during validation.

For a detailed guide on working with System Cards, see System Cards.

File Naming

All artifacts must follow the file naming conventions and be placed in the correct directory within your project structure. Files with incorrect extensions produce error E003.

Validation

When you run choochoo validate, all artifacts are checked against these schemas. The validation pipeline runs in a specific order — see Validation Rules for the full sequence.

Related