Version Compatibility

ChooChoo is built on top of open standards. This table defines the compatible versions for ChooChoo v1.0.x. For detailed documentation on each standard, see the Standards Reference.

You can pin specific schema versions in your .choochoorc configuration under the validation.schemas setting. The validation engine uses these pinned versions when checking artifacts against their schema definitions.

Backward Compatibility

• ChooChoo maintains backward compatibility within major versions.
• Breaking changes will result in a major version increment (e.g., 2.0.0).
• Deprecated features will be supported for at least one major version cycle.

When upgrading between minor versions (e.g., 1.0.0 → 1.1.0), your existing artifacts should continue to validate without changes. The validation rules are additive — new rules may produce warnings but will not break existing passing artifacts unless you run in --strict mode.

Schema Version Pinning

In your .choochoorc configuration file, you can pin the schema versions used for validation:

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

If no versions are pinned, ChooChoo uses the latest compatible versions from the table above. Version mismatches between your configuration and your artifact files will produce error E001 (Invalid schema) during validation.

Lifecycle State Compatibility

All artifact types (Products, Contracts, Workflows) share the same lifecycle state machine. State transitions are enforced regardless of the schema version — an artifact cannot skip states (e.g., draft → active) even if the underlying standard version changes.

Migration Path

When ChooChoo introduces support for a new major version of an underlying standard (e.g., ODCS 4.0.0), the migration path will be:

1. The new version is added as an option in .choochoorc.
2. Both old and new versions are supported simultaneously for at least one ChooChoo major version.
3. A migration command (choochoo migrate) will be provided to update artifacts to the new schema.
4. The old version is deprecated with warnings, then removed in the next major version.

Check the Roadmap for upcoming version support and migration timelines.

Related