Data Contracts in Plain Language

Imagine a team that maintains a customer table used by twenty reports, two machine learning models and a partner feed. One day the team renames a column. Nothing in their own pipeline breaks. Everything downstream does. A data contract exists to prevent that kind of surprise.

What a data contract is

A data contract is a written, machine-readable promise from the team that produces a data set to the teams that use it. It says what the data looks like, what quality to expect and how it will change. Because it is machine-readable, tools can check that the promise is being kept.

It is not a legal agreement, and it is not documentation that nobody reads. It is closer to an API specification for data.

What goes in one

The open format most teams now use, the Open Data Contract Standard maintained under the Linux Foundation’s LF AI & Data Foundation, organizes a contract into sections. The ones that matter most are:

• Schema: the fields, their types and which ones are required.
• Data quality: rules such as “no missing customer IDs” or “no duplicate orders”.
• Service levels: how fresh the data is and how often it is updated.
• Roles and support: who owns the data and where to ask questions.

How it is enforced

A contract that nobody checks is just documentation. Enforcement happens in the tools teams already use:

• Build tools such as dbt can refuse to build a model whose output does not match its declared columns and types.
• Streaming platforms can check each new version of a message schema against compatibility rules before it is accepted.
• Quality tools can run the contract’s checks against the real data on a schedule and report the results to the catalog.

How it handles change

Data has to change. The point of a contract is to make change predictable. A few simple rules cover most cases: add new fields with defaults, mark a field as deprecated before removing it, and publish a new version for any change that could break a consumer, with a stated period for consumers to move. Lineage tools help by showing who reads a field before anyone changes it.

Who does what

A contract has three parties, even when they sit in the same company. The producing team owns the contract: it writes it, keeps it in version control next to the code that produces the data and decides when a new version is needed. Consuming teams review proposed changes, especially breaking ones, and tell the producer which fields they rely on. The platform team makes the checks automatic, so that nobody has to remember to run them, and publishes the results where everyone can see whether each contract is being met. When a dispute arises, for example over how much notice a breaking change needs, the answer should come from an agreed rule rather than from whoever shouts loudest.

Where contracts fit

Contracts matter most at boundaries: between domains in a data mesh, between a platform team and the analysts it serves, or between your organization and a partner. Inside one small team, a conversation may be enough. Across twenty consumers, it is not.

The evidence base is still young. Peer-reviewed research specifically on data contracts mostly synthesizes practitioner experience, so it is worth measuring incidents and change lead times before and after you introduce them.

How Bassirah can help

We help teams decide where contracts are worth the effort, write their first ones in an open format and connect them to build tools, quality checks and the catalog. Our white paper on data products and data contracts covers the standards and research in depth.