Data contracts between teams: a simple tool that prevents a class of breakages

There is a class of data problem that arises regularly in companies with multiple teams, different systems, and attempts to connect those systems. It plays out roughly like this: the analytics team builds a report based on data from the CRM. The CRM development team changes the export structure - adds a field, renames a column, changes a date format. The report breaks. The analytics team learns about it not from the developers, but from the business, which received incorrect numbers.

This is not a technical problem. It is an organisational problem. And data contracts are one way to solve it.

What a data contract is

A data contract is a formal agreement between the team that produces data (the producer) and the team that consumes it (the consumer). The agreement describes: which fields exist in the data, what type they are, what they are called, what they mean, how often they are updated, and which values are permissible.

This is not a complex technical document. In its simplest form it is a table or file that says: "field customer_id - integer, not null, unique identifier for the customer from the customers table."

The key principle: if the producer wants to change the data in a way that violates the contract, they are required to first agree the change with all consumers. Without that agreement, the change does not happen.

Why this solves what tools cannot

Companies usually fight breakages with technical measures: monitoring, automated tests, alerts. These are useful but do not address the cause.

The cause is the absence of an explicit agreement that data should be stable for consumers. The developer who renamed the column was not thinking about whether anyone depended on it. They were just cleaning up the code.

A data contract changes this at the process level, not the tooling level. It makes the dependency visible and requires explicit agreement on changes.

How this works in practice

A simple scheme to start with:

First step - inventory. Understand which data from which teams other teams consume. This is often undocumented and exists only in people's heads.

Second step - description. For each significant dependency, write a contract. You do not need to describe everything - start with the data whose breakage will cause real pain.

Third step - change process. Agree: any change that violates a contract requires notifying consumers X days in advance and getting their agreement. This does not need to be heavy bureaucracy - a simple notification in a shared channel is enough.

Fourth step - versioning. When changes are unavoidable, do them with versioning: the old structure stays available for a period, the new one is added alongside it. This gives consumers time to update their side.

When this matters most

Data contracts are especially valuable in a few situations:

• The product development team and analytics team work independently.
• Multiple systems consume data from a single source.
• Data comes from partners or external vendors - where the contract also becomes a legally relevant document.
• The company is in active development and data structures change frequently.

Questions to start

1. Which three analytics or integration breakages in the past six months were caused by an unexpected data change?
2. Does everyone who consumes specific data know that they depend on it - and do the producers of that data know it?
3. Is there anywhere that describes what the key fields in your systems mean?
4. How does communication about data changes between teams happen today?
5. What would need to change in your processes for breakages from unexpected data changes to become rare?

Data contracts are not a platform and not a large project. They are an agreement between people, written down somewhere accessible. You can start with one critical dependency and one text file.