Contracts (ODCS)

[!NOTE] Data Contracts are one of several artifact types that ChooChoo can validate. The CLI validates contract files against the ODCS schema — contract management commands (create, list, diff) are planned.

A Contract defines the shape, quality rules, and compliance requirements for a dataset. ChooChoo validates contract definitions against the Open Data Contract Standard (ODCS) v3.1.0. For all supported standards, see the Standards Reference.

The Contract Schema

Contracts are defined in contracts/*.contract.yaml. See the File Structure specification for naming conventions and the Schema Definitions for all required fields.

Components

1. Schema (Models): The physical structure of the data (fields, types).
2. Semantics: Business meaning, PII tags, and classification.
3. Quality (SLAs): Verifiable rules like freshness, completeness, and uniqueness. See Validation Rules for the quality rule grammar.

Compliance Tags

ChooChoo extends ODCS with specific support for compliance tagging. These tags trigger governance workflows and affect risk scoring. For the full taxonomy of supported tags, see Compliance Tags.

Fields tagged with pii are subject to special security considerations, including masking for agents without PII access and mandatory audit logging.

Example

dataContractSpecification: "3.1.0"
id: customer-360
info:
  version: "1.0.0"
  owner: [email protected]
  status: active

models:
  - name: Customer
    type: table
    fields:
      - name: id
        type: string
        unique: true
        description: Primary key
      - name: email
        type: string
        pii: true
        complianceTags: ["pii", "gdpr-article-6"]
        classification: confidential
      - name: country
        type: string
        description: ISO country code

quality:
  completeness:
    threshold: 0.99
  freshness:
    maxStaleness: "1h"

Validation

When choochoo validate runs, it checks:

1. Schema Validity: Does the YAML match the ODCS spec?
2. Breaking Changes: Are fields removed or types changed? This affects the artifact lifecycle.
3. Policy Violations: Are PII fields unencrypted or mislabeled? See Security Considerations.

Validation failures produce specific error codes and exit codes that can be interpreted in CI/CD pipelines.

Contracts and Products

Contracts are referenced from Products via outputPorts. This relationship is tracked in the Lineage Graph, enabling ChooChoo to calculate the Impact Radius of any contract change — how many downstream products and consumers are affected.

When a contract change involves sensitive fields, ChooChoo's risk scoring algorithm may trigger an approval workflow requiring human sign-off before the change can proceed.

Related