A data contract is an explicit, versioned agreement between the team that produces a dataset and the teams that consume it. It writes down what the dataset contains — column names, types, allowed values — and what the producer promises about it: how fresh it will be, what “order_total” actually means, and what counts as a breaking change.
The problem it solves
Most data breakage isn’t dramatic. An engineer renames a column in the application database, or changes a status enum, or starts writing timestamps in a new timezone. The change ships, the ETL job keeps running, and three days later someone notices the revenue chart has been flat since Tuesday. The producer never knew anyone depended on that column; the consumer never knew the column could change.
The underlying issue is that the dependency was implicit. Application teams version their APIs and treat breaking changes as events that need coordination — but the analytics tables reading from their databases get no such courtesy. A data contract extends the API mindset to data: the interface between producer and consumer becomes something written down, agreed to, and checkable.
What goes in one
A useful contract typically covers three layers:
- Schema. Columns, types, nullability, and keys — the part machines can check automatically.
- Semantics. What each field means, in plain language: whether
revenueincludes refunds, whethercountryis the billing or shipping address. This is metadata that no type checker can infer. - Guarantees. Freshness (updated within an hour), completeness (no dropped days), and a change policy — how much notice consumers get before a breaking change, and how versions are handled.
The format matters less than the enforcement. A contract that lives in a wiki is documentation; a contract checked in CI — where a pull request that breaks the promised schema fails before it merges — actually changes behavior. Teams commonly enforce contracts at pipeline boundaries, validating data as it lands in the data warehouse and alerting when a guarantee is missed.
Trade-offs
Contracts add friction on purpose, and the friction has to be worth it. Writing and maintaining them for every table is overkill; the leverage is in the handful of datasets that many teams depend on. They also shift work upstream — producers take on obligations they didn’t have before, which is an organizational negotiation, not just a technical one. That’s why data contracts show up so often in data mesh conversations: once domain teams own their data as a product, the contract is the product’s interface.
Why BI teams care
A BI tool sits at the end of the chain, which means it’s where breakage becomes visible. Metabase queries your database or warehouse directly, so when an upstream schema shifts under a dashboard, the dashboard is often the first place anyone notices. Contracts move that discovery earlier: the failed check fires when the change is proposed, not when an executive asks why the numbers stopped moving.
Related terms
Further reading
Put it to work
- Data freshness — Metric
- ETL dashboard — Dashboard
- Integrations — Integrations
