Data Contract Versioning: What Counts as a Breaking Change
A data contract has a version field. What should you put in it, and when should it change? The useful answer is about consumers: a change is breaking if something that worked before stops working. This guide sorts common changes into breaking and safe, suggests a simple version rule, and shows how to check a change before you ship it.
Open the Data Contract Generator
The rule of thumb
A change is **breaking** when a consumer who followed the old contract can now fail or get wrong results. A change is **safe** when everyone following the old contract keeps working. The version number is how you tell people which kind of change this is.
A simple version rule
The contract uses a version like `1.0.0`. A common convention:
- **Major** (1.0.0 to 2.0.0): a breaking change.
- **Minor** (1.0.0 to 1.1.0): a safe addition, such as a new optional column.
- **Patch** (1.0.0 to 1.0.1): a fix that changes no promise, such as a better description.
The tool writes the version into the contract, but it does not enforce a rule: the number is a label you keep honest.
Breaking changes
- **Removing a column.** Anything that reads it fails.
- **Renaming a column.** For the consumer this is a removal plus an addition.
- **Changing a type.** An integer that becomes text, or a date written in a new format. In the sample run, a date arriving as `04/02/2026` failed the rule `order_date must be a date`.
- **Making a nullable column required in the other direction**, or letting a required column be empty. A consumer that assumed a value is always there will break on the first empty one.
- **Narrowing the allowed values or range** the consumer relies on, or **widening** it when the consumer has a fixed list. A new status such as `shipped` failed `status must be one of: paid, pending, refunded`.
- **Changing what a value means.** Amounts that move from euros to cents pass every type check and still break every report. No tool finds this one; tell people.
- **Changing the grain.** If one row per order becomes one row per order line, totals change. Document it as a major change.
Usually safe changes
- Adding a new column that nobody is required to read. (A consumer that fails on unexpected columns will still notice: by default the tool's check fails on extra columns, which you can switch off.)
- Adding documentation.
- Making a rule more lenient in a way no consumer relied on.
Check a change before you ship it
- **Against the old contract.** Validate a sample of the new data against the old contract in the Data Contract tool. The failures are the breaking changes, listed with example rows.
- **Against the old data.** Compare an old file with a new one by key with Data Comparison to see which rows and columns changed.
- **Against your SQL.** If the change is to a table your own SQL or dbt models read, load the project in the SQL Lineage Analyzer, edit the model, and read the impact card: it lists the downstream tables and columns that would break. See edit SQL and see what breaks. It sees only the SQL you load, not dashboards or other repositories.
How to roll out a breaking change
- Announce it before it happens, with the old and new contract side by side.
- Keep the old version available for an agreed period when you can.
- Bump the major version, update the contract in the repository and tell the named owners of the things that read it.
Limits
Versioning is a human agreement. A tool can show you which rules a new file breaks, but it cannot know which consumers exist or what they assume. Keep a list of who reads each dataset.
Open the Data Contract Generator
Related tool pages
- ODCS Data Contract Generator: Generate an Open Data Contract Standard (ODCS) v3 YAML file from a CSV, Excel, JSON or Parquet file. Edit the rules, then download. Free, in your browser.
- Validate a CSV Against a Schema: Check a CSV or Excel file against a data contract: required values, types, unique columns, allowed values, ranges, patterns and missing or extra columns. Free, in your browser.
Also try
How to use the Data Contract Generator: step by step
- List what changed.
- Mark each as breaking or safe.
- Validate new data against the old contract.
- Check downstream SQL, then announce and bump the version.
When to use the Data Contract Generator
- Deciding when to bump a contract version
- Finding breaking changes before they ship
- Planning a rollout
Example
Input: orders.csv: order_id, status, unit_price
Output: kind: DataContract schema: - name: orders properties: - name: order_id logicalType: integer required: true unique: true
Frequently asked questions
What is a breaking change in a data contract?
A change after which someone who followed the old contract can fail or get wrong results: removing or renaming a column, changing a type, or changing what a value means.
How should I version a data contract?
A simple rule is major for breaking changes, minor for safe additions and patch for fixes that change no promise. The version is a label you keep honest.
Is adding a column a breaking change?
Usually not, but a consumer that fails on unexpected columns will notice. The tool's check fails on extra columns by default, and you can switch that off.
Can a tool find all breaking changes?
No. It can show which rules new data breaks and which downstream SQL is affected. It cannot know what a changed value means to a person.
Tip: Ask one question about every change: could someone who followed the old contract now fail? If yes, it is a major change.