Once a data product is in production, other teams build on its interface. Changing that interface is the moment a product either keeps its consumers’ trust or loses it, and the difference is usually process rather than technology.
Three things in a data product carry their own version, because they change for different reasons and at different speeds.
| What carries a version | What the version describes | What a change signals |
|---|---|---|
| The data product | The product as a whole | Its overall release, tracked in semantic versioning |
| Each port | One interface | The shape or behavior of that specific interface changed |
| Each data contract | One agreement | The terms or schema were renegotiated |
Versioning each separately means a fix to one output port does not force a version bump on a product’s other interfaces, and a contract can be revised without moving the product through its own lifecycle.
Reading a version number
Versions use semantic versioning — MAJOR.MINOR.PATCH, such as 2.1.0. Each position carries a specific promise to consumers.
| Position | Increment when | What consumers should expect |
|---|---|---|
| MAJOR | You make a breaking change | Their integration may stop working; they must act |
| MINOR | You add something backward-compatible | Nothing breaks; new capability is available |
| PATCH | You fix something without changing the interface | No action needed |
The value of this convention is that a consumer can tell from the number alone whether they need to read the release notes.
What counts as a breaking change
A change is breaking if it can stop a consumer’s existing usage from working. The test is not how hard the change was to make — it is whether someone downstream has to change something.
Breaking:
- Removing or renaming a field consumers can read.
- Narrowing a type, or tightening a constraint that previously accepted their data.
- Changing what a field means while keeping its name — the most damaging kind, because nothing fails loudly.
- Changing a port’s access format, protocol, or authentication method.
- Removing an output port, or dropping assets from one.
- Making quality or freshness guarantees weaker than the SLA states.
Not breaking:
- Adding a new optional field.
- Adding a new output port.
- Improving freshness, availability, or quality beyond what you promised.
- Fixing a value that was always wrong, where the intended meaning does not change.
- Editing descriptions, tags, or documentation.
The borderline case worth naming is a field whose definition drifts — a revenue column that quietly starts excluding refunds. Consumers keep reading it successfully and get wrong answers. Treat a definition change as breaking even when the schema is untouched.
Ship a breaking change
Before changing an output port, open the product’s Consumed by view to see which products depend on it. A change that looks local is only local if nothing downstream reads that port.
- Identify who is affected. Check the consumers of the port you are changing, and the lineage beyond them.
- Decide whether to version or to add. If consumers can migrate quickly, raise the port’s MAJOR version. If they cannot, add a new output port alongside the existing one and run both.
- Announce it before you ship it. Tell the affected owners what changes, when, and what they need to do. The product’s version notes are the durable record.
- Update the contract. Revise the data contract covering the port so its schema and terms match the new reality, and have the Steward approve it.
- Give consumers a migration window. Keep the old interface working long enough for them to move, based on what they told you in step 1.
- Retire the old interface. Remove the superseded port or version once the consumers you identified have migrated.
Running two interfaces at once costs more than a clean cut, which is why step 2 is a judgment call rather than a rule. The cost of a clean cut lands on other teams; the cost of running both lands on you.
Retiring a whole product
Retiring an entire product follows the same logic at a larger scale, and the lifecycle has states for it. Moving a product to sunset announces the end of life while the product keeps honoring its SLAs, which gives consumers a documented window to migrate. Retired then means the data is no longer served.
Because the record is kept after retirement, downstream lineage still resolves and anyone still pointing at the product can see what happened to it. For what each state means, see The data product lifecycle.
How consumers learn about changes
Consumers do not watch your product for changes; they find out when something breaks or when you tell them. Three mechanisms carry the message:
- Version numbers signal whether action is needed.
- Version notes on the product record describe what changed, and stay readable later.
- Contract status shows whether the agreement they rely on is active or deprecated.
An announcement that only exists in a chat message is gone by the time the next person needs it. Put the durable version in the product record.