Validation Rules

The choochoo validate command validates files using AJV (JSON Schema Draft-2019-09 and Draft-2020-12). It runs locally and in CI/CD pipelines.

[!NOTE] The CLI currently performs schema validation (steps 1-3 below). Cross-reference resolution, quality rule evaluation, and policy checks are planned.

Validation Order

1. File extension check: Does the file match the naming convention? Violations produce error E003.
2. Syntax validation: Is it valid YAML/JSON? Parse errors produce error E001.
3. Schema validation: Does it match the ODPS/ODCS/Arazzo schema? Missing fields produce error E002.
4. Cross-reference resolution: Do referenced contracts exist? Missing references produce error E004. Circular dependencies produce error E005.
5. Quality rule evaluation: Do the SLA metrics meet thresholds defined in contracts? Failures produce error E006.
6. Lifecycle validation: Are state transitions valid? Invalid transitions produce error E009.
7. Agent boundary checks: Are agent actions within permitted scope? Violations produce error E007.
8. Policy evaluation: Are approval workflows triggered? If so, the CLI returns exit code 10 (APPROVAL_REQUIRED).

Each step runs in sequence — if an earlier step fails, subsequent steps may be skipped. Use the --format json flag with choochoo validate for machine-readable output in CI.

Quality Rule Grammar

Quality rules in contracts follow this grammar:

rule        = metric operator threshold
metric      = "completeness" | "freshness" | "uniqueness" | "accuracy"
operator    = ">" | ">=" | "<" | "<=" | "==" | "!="
threshold   = number | duration

Examples:

• completeness >= 0.95
• freshness < 1h

Quality rule failures produce error E006 and contribute to the Historical Quality (H) factor in the Risk Scoring algorithm.

Contract Resolution

When a Product references a Contract (e.g., contract: customer-360), resolution follows:

1. If version is specified (@1.0.0), use that exact version.
2. If no version is specified, use the highest semantic version with status active (see Artifact Lifecycle).
3. If no active version exists, validation fails with error E004.

These references create edges in the Lineage Graph, which ChooChoo uses for impact analysis and risk scoring.

Agent Boundary Validation

When agent governance is enabled in the configuration, the validation engine also checks:

• Scope limits: Is the agent modifying files outside its permitted paths?
• PII access: Is the agent reading fields tagged with compliance tags like pii without the appropriate capability? See Security Considerations.
• Environment restrictions: Is the agent operating in a restricted environment?

Boundary violations produce error E007 and are logged in the Audit Trail. The agent's System Card is referenced to verify capabilities.

Strict Mode

When --strict is passed to choochoo validate (or set in the configuration via validation.strict: true), warnings are promoted to errors. This is recommended for CI/CD pipelines to catch issues early.

In strict mode, the CLI returns exit code 1 (VALIDATION_ERROR) for any warning or error.

Schema Version Pinning

The .choochoorc configuration allows you to pin specific versions of the standards:

{
  "validation": {
    "schemas": {
      "odps": "1.0.0",
      "odcs": "3.1.0"
    }
  }
}

This ensures that your artifacts are validated against consistent schema versions. For the full compatibility matrix, see Version Compatibility. For the standards themselves, see the Standards Reference.

Related