Trust your data blindly? Here's how data contracts make it real

There is a saying: trust arrives on foot and leaves on horseback. Throughout my career in data, I have found this saying to be very applicable when it comes to the adoption of data products within an organization. Trust in your data produtcs takes a very long time to build, and if the organisation sees one mistake in it, it sends you back to the start. You lose their trust almost immediately.

The data issues we face that breakdown trust

Imagine the following: you spend a lot of time getting the dashboards right, getting the definitions aligned, getting the business to actually look at the numbers instead of arguing about them. And then, one Monday morning, an executive opens a report before their first coffee and the revenue number is wrong.\ By 9:15 you have three emails.\ By the end of the day someone has rebuilt the calculation in Excel.\ By the end of the week, that Excel file is the version everyone trusts.\ You can fix the report in an afternoon. The Excel file will live for many years.

This is one of the reasons self-service BI keeps stalling, even after a decade of better tools, better warehouses, and better practices. The transformations underneath the semantic model are a black box to the consumer. When the data stops behaving the way they expect, even once, people reach for the thing they understand. They take back control and they do not always come back. When I look back at the incidents I have seen, across clients, across stacks, they almost always fall into one of these four shapes:

Breaking the schema. A producer renames a column, drops a field, or changes a type. They had no idea anyone downstream depended on it. As a result the dashboard breaks and the data team spends three days untangling lineage that should have been obvious from the start.

Semantic drift. The same column means something different than it used to. A revenue field that used to be in EUR is now in local currency, because someone added multi-region support and the conversion logic moved upstream. Nothing technically broke. The numbers in the dashboard just quietly stopped meaning what they used to mean. Consumers find out weeks later, when the quarterly review numbers do not match what finance is reporting.

The definitional mismatch. Two people walk into a meeting holding different revenue numbers. Both numbers are correct. They are answering subtly different questions, gross versus net, booked versus recognized, including or excluding a particular segment. Nobody named the difference, because the metric appeared under the same label in both reports. The meeting derails. A decision is delayed. Trust takes another small hit.

The compliance leak. A new field ships into production. It contains personal data. Nobody classified it as such, because classification lives in a wiki nobody updated. The field flows into an export that goes to a third party. Now the GDPR seventy-two-hour notification clock is running, and the conversation is no longer about data quality. It is about regulatory fines and a press release.

Nobody makes these mistakes on purpose. Everyone is busy, everyone is doing their job, but unfortunately almost nobody has the full picture of all dependencies when they are making the changes. Beneath all these issues lies one overarching problem.

There is no explicit, machine-readable, jointly-owned agreement between the producer of the data and the consumers about what the data actually means. No contract. Just a series of implicit assumptions, written in a neglected document, enforced by nothing.

Data contracts

What is a data contract

In its core, there are a couple of strong descriptions about data contracts that slightly differ in perspective but have the same outcome. The one I favour is described below.

There's a lot packed into that definition. The verbs in particular.

Established. The contract is not an implicit assumption that emerges from documentation that nobody reads. It is a deliberate act of writing the agreement down, in a place that producers and consumers both look.

Updated. The contract evolves over time, with versioning. A change to the data is also a change to the contract, and that change can be reviewed, communicated, and rolled back like any other piece of code.

Enforced. This is the verb that matters most. The contract is automatically checked, not voluntarily honored. It plugs into the same toolchain that already runs unit tests, deployment checks, and CI/CD pipelines. If a producer tries to ship a change that violates the contract, the build fails. The change does not reach production.

In general you could see a data contract as an interface. It is a publisher's commitment to maintain the documented behavior of a data asset, and a consumer's commitment to program against only what is documented. It carries expectations: schema, valid values, freshness, ownership, classification. And it is explicit, meaning the data is generated on purpose, for the consumer, rather than scraped as a side effect of an upstream system. Most data in most organizations today is generated implicitly. The marketing dashboard is built on top of an event stream that exists because the application happens to log those events. Nobody designed that stream as a product. It just leaked out of the system.

The cultural shift the data contract asks for is small to describe and hard to do: Stop generating data implicitly. Start generating it on purpose, for the people who will use it. We will talk more about the culture change later.

What is NOT a data contract

This is where initially a lot of the confusion lives, because organizations have been trying to solve this problem with other tools for a long time, and some of those tools look superficially like contracts.

For example: - A data contract is not tribal knowledge. Tribal knowledge is what people should use when nothing is officially or in production, and it leaves the company every time someone changes job. - A data contract is not a wiki. A wiki page describing a table is documentation. It is not machine-readable, it is not versioned with the code that produces the data, and it does not break the build when reality drifts away from it. - A data contract is not an SLA. An SLA is a service-level commitment, often quite formally written. But it is rarely enforced by tooling, and it sits in a Confluence page that nobody references between annual renewals. An SLA is something that should be written down in a data contract. - A data contract is not a data catalog. This one is the most important to get right, because catalogs are genuinely useful and overlap with contracts in places. A catalog is a discovery tool: a place for consumers to look up what data exists and what it means. Modern catalogs auto-ingest schema and lineage from production, so the descriptive part stays current. But the prescriptive part, what the producer has committed to, what the consumer can rely on, what breaks the build when violated. This is usually missing entirely.

If you only remember one thing from this blog, it should be this: a data contract is different because it breaks the CI when violated. Wikis, SLAs, and catalogs do not. That is the single property that produces a step change in data quality, because it integrates the agreement with the same enforcement mechanism developers already trust for code quality.

This does not mean catalogs and SLAs should disappear. They should not. They serve their own purposes and they serve them well. But they should derive from the contract, not replace it. The contract is the source of truth; everything else is a view on top of it.

Shift left

There is a phrase that has been quietly migrating from software engineering into data: shift left. The idea is simple. Quality concerns, testing, security and compliance should be addressed as early as possible in the development lifecycle. Because that is where they are cheapest to fix. In data, that first layer has been missing for years. We catch quality problems at the dashboard, which is the end of the pipeline, where everything has already gone wrong, where the consumer has already lost trust, and where the fix is most expensive. A data contract puts a check as far left as possible in the process. The contract lives in the producer's repository. A pull request that proposes a breaking change fails CI, in the same place the producer's unit tests run, in the same context the producer already trusts.

Three things happen at once:

But when nothing breaks anymore, can you still implement breaking changes if it is necessary? Definitely, but it does mean changes need to be negotiated and communicated. Because the contract is versioned, a producer who genuinely needs a breaking change is not forced to choose between blocking the business and breaking consumers. They publish the new version next to the current one and open an overlapping deprecation window. Both versions stay available for an agreed period, consumers migrate on their own schedule, and the old version is retired only once nobody depends on it. The breaking change still happens. It just stops being an incident.

Shift left does not replace the rest of the pipeline. You will still need integration tests, unit tests, and production monitoring. Each layer catches what the previous one missed.

The culture change

Data as a product

There is a failure mode I want to name before we move on. A team gets enthusiastic about contracts. They adopt ODCS (The open data contract standard). They set up CI checks and in no time they have a lot of contracts on data assets that nobody is actually using. The contracts are correct. The data underneath them is not. It is still the same side-effect-of-an-upstream-system that it always was, just with a YAML file on top.

A data contract is the technical mechanism. A data product is what the mechanism is supposed to govern. Both are needed. The data product is the goal.

What makes something a data product? - First, it always has a data owner. A single person, embedded in the producing team, accountable when things break. - It has identifiable, contactable users, not anonymous downstream consumers. - It has a roadmap based on the lifecycle. Changes are deliberate and announced. - It has KPIs like number of active consumers, freshness compliance, satisfaction scores, etc. Via these metrics the owner knows whether the product is healthy. - And last but not least. It always has a support model. People are building things on top of the data product. They are depending on it. What happens when the data breaks? Who responds? Within what time frame? Mature data products have on-call rotations, incident response runbooks, and consumer-facing status pages.

A data contract on a data product is governance. A data contract on a data dump is useless.

Maturity curve

When you made it to here, you are probably interested. You want to introduce data contracts or at least start a POC. The next thing you will want to know is: how does this actually land in an organization? Most organizations cannot go from "tribal knowledge and wikis" to "fully contract-enforced governance" in a quarter. The realistic journey has three phases.

Awareness:\ The goal is visibility. - Most producers genuinely do not know which consumers depend on which fields. - Most consumers genuinely do not know who owns the upstream data they depend on. The two sides discover each other's existence. Practical moves in this phase are lightweight: automated lineage, dashboards showing which producer tables are most heavily consumed, alerts when upstream changes affect downstream pipelines (without yet blocking those changes), and one or two pilot contracts on tier-one data products to learn the workflow. The cultural shift is small but real. Producers begin asking "who uses this?" before shipping a change

Collaboration:\ Contracts move from pilot to standard practice. Producers and consumers actively negotiate them. Breaking changes go through a review process that involves the affected consumers. CI enforcement is in place a producer cannot merge a contract-violating change without explicit consumer sign-off. The contract becomes the surface where the producer-consumer conversation happens, not after the fact, but in code, before deploying.

This is where most organizations stall in their growth. The reason is not technical, the tooling is well-understood by this point. The reason is cultural. Collaboration requires producers to accept that their changes can be blocked by consumers, and producers do not always like that. The organizations that get past it make the collaboration explicit, fast, and low-friction (a contract review takes minutes, not days), and they tie the practice to leadership-visible metrics that show the cost savings.

Ownership:\ Contracts are no longer a special practice. They are the default. Every tier-one data product has one. Every producing team has a named data product owner. Contract violations break CI as routinely as failed unit tests. The discussion in pull requests routinely includes does this change require a contract update? Have we notified affected consumers? Data is no longer the responsibility of the data team alone. It is a shared responsibility, with producers carrying operational ownership and consumers driving requirements. The data team's role shifts from incident-responder to platform-enabler.

A few things the maturity curve does not promise. - It is not a six-month plan. Organizations spend at least a year or more in each phase. - It is not a uniform organizational state. Different teams within the same company will be at different points on the curve, and that is normal. - And it is not unidirectional. A reorganization, a change of leadership, or a major incident can push a team back from collaboration to awareness. Maturity has to be actively maintained.

Conclusion

This was the first part of two blogs about data contracts. In this first part i purposly focust on the theory because the conceptual ground has to come first. The technical implementation only makes sense when you have agreed on the problem you are trying to solve.

In part two, I will walk you through what an actual contract looks like and how you can use them. Examples will contain:

In conclusion, I would like to end with this. Trust in data is not something you build with another dashboard, another tool, or another committee. It is something you build by making the agreements between producer and consumer explicit, machine-readable, and enforced.

I can't express the enforced part enough to make data contracts a success. Anything less is goodwill. And goodwill also leaves on horseback.