🤝 Data Contracts: How to Stop Upstream Schema Changes From Silently Breaking Your Metrics
What a data contract actually is, who enforces it, and why most teams that claim contracts only have documentation. Build vs buy, hype removed.
🚀 THE EXECUTIVE SUMMARY
The Definition: A data contract is an explicit, versioned agreement between a data producer and its consumers that pins down a dataset's schema, semantics, and quality guarantees — and, critically, what happens when those guarantees are violated. It is enforced by tooling, not goodwill.
The Core Insight: Most teams that say they "have data contracts" have documentation. A YAML file sitting in a catalog stops nothing. If a violating change is not blocked in CI or at build time, you do not have a contract — you have a wish. The distinction between declared and enforced is the entire subject, and it is the first question to ask any vendor selling you contract tooling.
What a Data Contract Actually Does
Every broken dashboard has the same autopsy. An upstream engineer renames a column, or a field that has always been an integer starts arriving as a string, or an event property quietly disappears in an app release. Nothing alerts, because nothing was watching the shape of the data — only the plumbing. The failure surfaces days later, downstream, in a revenue number that stopped moving. If you run AI on top of that warehouse, it surfaces even later, because an AI analyst reads your schema as truth and will confidently aggregate the broken column.
A data contract makes the implicit assumptions between producer and consumer explicit and machine-checkable. A real contract covers:
- Schema: column names, data types, nullability — the guarantees that break most often.
- Semantics: what the field means, its owner, and who consumes it.
- Quality and service levels: freshness, volume expectations, allowed values.
- Change policy: how breaking changes are versioned and who signs off before they ship.
Enforcement can live in three places, and mature setups use more than one. A CI gate checks proposed schema changes against the contract before code merges. Build-time enforcement — the model dbt uses — runs a preflight check that the model's output matches the declared columns and types, and refuses to build the table if it does not. Runtime validation checks rows as they flow, catching what static checks cannot.
There is now a vendor-neutral way to write all of this down: the Open Data Contract Standard (ODCS), governed by Bitol, a Linux Foundation AI & Data project, with an MIT-licensed Data Contract CLI that tests contracts against live sources and exports to the major tool formats.
The Compliance Angle: Contracts as GDPR Machinery
Regulators have been describing data contracts for years without using the term. GDPR Article 5 requires personal data to be "adequate, relevant and limited to what is necessary" (data minimisation), "collected for specified, explicit and legitimate purposes" (purpose limitation), and "accurate and, where necessary, kept up to date."
Read those as engineering requirements and a contract is the natural enforcement layer. A schema that only admits declared fields is data minimisation you can actually prove — undeclared collection fails the build instead of accumulating silently. A contract that names each field's purpose and consumers is purpose limitation with an audit trail. Accuracy obligations become quality checks that run on every load rather than an annual attestation. The same logic serves CCPA data-inventory obligations: the contract is the inventory, kept current because the pipeline breaks when it drifts.
Be clear about the limit: a contract is not a compliance program. It cannot judge whether a purpose is legitimate or a retention period defensible. What it does is turn policy decisions, once made, into constraints that engineering cannot accidentally violate — which is where most privacy incidents actually start.
Build vs Buy: Four Ways In, and a Consolidation Warning
| Approach | What enforces it | Cost | The catch |
|---|---|---|---|
| In-house checks (JSON Schema, pydantic in CI) | Your CI pipeline | Engineering time only | You maintain it forever; coverage erodes as the team changes |
| dbt model contracts | Preflight check + DDL at build time; violating models do not build | Included in dbt | Guards the transformation boundary only — says nothing about raw sources landing upstream |
| ODCS + Data Contract CLI | CI gate against live sources | Open source (MIT) | You assemble the workflow; the standard does not enforce itself |
| Commercial platforms (Gable, Soda, and others) | Managed CI and runtime validation | Subscription | Format lock-in, and licensing is shifting under your feet |
That last row deserves the skeptical read. The contract-tooling market consolidated hard this year: dbt Labs completed its merger into Fivetran in June, which now also stewards the open-source Great Expectations project, and Soda moved Soda Core from Apache to the more restrictive Elastic License with its latest major version. None of this makes the tools worse today. It does mean the license you adopt is not guaranteed to be the license you renew — which quietly strengthens the case for keeping the contract definitions in a neutral format like ODCS, whatever engine you enforce them with.
The Expert Perspective
The sharpest recent writing on this gap comes from engineer Robert Allen, whose tool-by-tool audit found that most popular contract tooling stores contracts without executing them:
"The contract sits in a catalog as documentation. The catalog has no opinion about the data flowing past it."
His test is the one worth stealing: when a producer publishes a row that violates the contract, what stops it? For most teams the honest answer is nothing — "consumers find out at 2 AM when a dashboard breaks." Publishing a contract declares an intention to enforce. It is not the enforcement.
Conclusion & Next Steps
Do not launch a data-contracts program. Write one contract. Pick the single table your most-watched dashboard reads, declare its columns, types, and nullability, and wire the check into CI or your dbt build so a violation fails loudly before it ships. You will learn more from the first contract that blocks a real breaking change than from a quarter of governance meetings. Expand along the pain: contract the sources that break most, version breaking changes deliberately, and keep definitions in a portable format so consolidation among vendors stays their problem instead of yours.
FAQ
What is a data contract in simple terms? A machine-checkable agreement between whoever produces a dataset and whoever consumes it, covering the schema, meaning, and quality of the data — with tooling that blocks changes violating the agreement.
Are data contracts the same as dbt tests? No. Tests inspect data after a model builds; a dbt model contract is checked before the build, and a model that violates it does not build at all. Tests detect, contracts prevent.
Do small teams need data contracts? A five-person startup where one engineer owns the whole pipeline can usually skip them. The need appears the moment producers and consumers are different people — that is when implicit assumptions start breaking silently.
What is ODCS? The Open Data Contract Standard: a vendor-neutral YAML format for writing contracts, governed by the Bitol project under the Linux Foundation, with open-source tooling to test contracts against live data sources.
Are data contracts legally binding? No — the name is a metaphor. They are engineering controls. But they generate exactly the kind of documented, enforced data-handling evidence that privacy regulations reward.
References & Sources Cited
- dbt Docs — Model contracts
- Bitol — Open Data Contract Standard (Linux Foundation AI & Data)
- Data Contract CLI — Comparison with other tools
- Robert Allen — Most Data Contract Tools Don't Enforce Contracts
- Fivetran — Fivetran and dbt Labs complete merger
- GDPR Article 5 — Principles relating to processing of personal data
See you soon,
Team Perspection Data
Perspection Data is researched and fact-checked by our Editorial Team.
