Skip to main content

Compare contract versions

Use datacontract changelog to describe the differences between two versions of a contract, or use datacontract breaking to classify their backward-compatibility impact.

Changelog​

Use datacontract changelog to compare the source contract (v1) with the target contract (v2) and report the changes between them:

datacontract changelog v1.odcs.yaml v2.odcs.yaml

See the generated changelog command reference for all options.

Breaking changes​

Use datacontract breaking when a contract change must be checked for backward compatibility. The command compares the source contract (v1) with the target contract (v2) and preserves the detailed changelog while adding a severity classification.

datacontract breaking v1.odcs.yaml v2.odcs.yaml

See the generated breaking command reference for all options.

Severity levels​

  • ERROR - a backward-incompatible change. The command exits with status 1.
  • WARNING - a potentially incompatible change that requires review. The command exits with status 0.
  • INFO - informational or currently unclassified metadata. The command exits with status 0.

The result is breaking only when at least one detailed entry has severity ERROR.

Initial compatibility rules​

The first ODCS implementation treats schema and property removals, requiredness tightening, type changes, and uniqueness tightening as errors. Primary-key changes and changes to validation constraints whose direction cannot be proven are warnings. Additions, relaxed constraints, descriptions, tags, business names, custom properties, and unrecognized changes are informational unless a more specific rule applies.

Every detailed changelog entry receives exactly one classification. Unknown fields use the informational fallback so that introducing a new ODCS field does not make detection fail.

API​

The same result is available from POST /breaking, using the same JSON request shape as POST /changelog:

{
  "v1": "<source contract YAML>",
  "v2": "<target contract YAML>"
}

The response includes summary, entries, and an is_breaking boolean. The endpoint returns HTTP 200 for a valid comparison even when is_breaking is true; invalid YAML or contracts return HTTP 422.