Data Contracts: How to Stop Upstream Changes From Breaking Your Pipelines

Data & Analytics Engineering

Blog

On Monday morning, the revenue dashboard shows sales down 40%. The leadership team asks what happened, and the data team spends the morning tracing it. The cause was a sensible change: on Friday, an application team renamed a column during a routine release. The pipeline kept running, the numbers quietly changed, and nobody downstream knew.

Nobody made a mistake in that story. What was missing was an agreement. Data contracts are explicit, versioned agreements between the teams that produce data and the teams that use it. They describe what the data looks like, how good it must be, how fresh it should be and who owns it, and they are checked automatically before a change reaches production.

‍

What Is a Data Contract?

A data contract works like an API contract for data. The producing team commits to a defined structure and quality level, and consuming teams can build dashboards, reports and models on it with confidence. Most data contracts are written in YAML, which is both human-readable and machine-readable, so they can live in the same repository as the code that produces the data.

The idea has moved from early adopters into the mainstream. IBM and Monte Carlo's updated guide both cover the concept in depth, and open standards now define a common structure. The Open Data Contract Standard gives teams a shared format, and on 12 October 2026 the Open Data Product Specification published its v4.2 release candidate, focused on making data contracts reusable and explicit.

‍

What Goes into a Data Contract

A useful contract covers six things, and each one answers a question consumers would otherwise have to guess:

  1. Schema. Which columns exist, their data types and which fields are required.
  2. Quality rules. The data quality expectations that must hold, such as no missing order IDs or no negative amounts. IBM's data quality overview describes the main dimensions.
  3. Freshness. How often the data arrives and how late it is allowed to be.
  4. Ownership. Which team produces the data and who to contact when something changes.
  5. Meaning. A plain-language description of each field, so "revenue" means the same thing to everyone.
  6. Change policy. How versions are numbered and how much notice consumers get before a breaking change.

‍

A Simple Data Contract Example

Here is a simplified data contract example for an orders dataset. Real contracts following the Open Data Contract Standard include more detail, but the core ideas fit on one screen:

contract: orders
version: 2.1.0
owner: commerce-platform-team
contact: data-orders@company.com
description: One row per confirmed customer order.

schema:
  order_id: { type: string, required: true, unique: true }
  customer_id: { type: string, required: true }
  order_total: { type: decimal, required: true, minimum: 0 }
  currency: { type: string, allowed: [USD, EUR, SEK, AED] }
  created_at: { type: timestamp, required: true }

quality:
  max_null_rate_customer_id: 0%
  duplicate_order_ids: 0

freshness:
  updated: hourly
  max_delay: 2 hours

change_policy:
  breaking_changes: new major version, 30 days notice
  additive_changes: allowed in minor versions

Anyone reading this knows what the dataset contains, what "good" looks like and who to call. Machines can read it too, which is what makes automatic enforcement possible.

‍

How Data Contracts Handle Schema Evolution

Data structures always change as products grow, so contracts are designed to manage change rather than prevent it. Schema evolution is the practice of changing a dataset's structure over time without breaking the systems that depend on it. Databricks and Confluent's schema registry both document how this works in practice.

Contracts make the distinction between two types of change explicit:

  1. Additive changes, such as a new optional column, are safe and can ship in a minor version.
  2. Breaking changes, such as renaming or removing a column or changing its type, require a new major version, advance notice and a migration window for consumers.

With this in place, the Friday column rename from the opening becomes a planned version upgrade instead of a Monday surprise.

‍

Enforcing Contracts with dbt Model Contracts

A contract only protects consumers if it is checked automatically. For teams using dbt, dbt model contracts provide built-in enforcement. When a model's contract is enforced, dbt checks that the columns and data types match the definition every time the model is built, and stops the build if they do not. Combined with dbt tests for quality rules, this turns a written agreement into a working safeguard.

The strongest setups run these checks in continuous integration, so a breaking change is caught when a pull request is opened, long before it reaches production.

Why Data Contracts Matter for Data Products and AI

Many organisations now treat important datasets as a data product: a reusable, well-documented asset with a clear owner and defined consumers. IBM's explanation of data products is a good starting point. A data contract is what makes a data product dependable, because it states exactly what consumers can rely on.

This matters even more as AI models and agents become regular data consumers. A dashboard user may notice that a number looks wrong, while an automated system usually will not. Contracts give AI systems the same stable, well-described inputs that human analysts have always needed.

‍

A Practical Rollout Plan for Data Contracts

  1. Start with one critical dataset, ideally one that feeds leadership reporting or a customer-facing product.
  2. Name a producer and a consumer owner, and agree the contract together.
  3. Write the contract in YAML and store it alongside the code that produces the data.
  4. Enforce it automatically with dbt model contracts, tests and checks in continuous integration.
  5. Monitor in production for quality and freshness, and review the contract each quarter.

‍

What This Means for Data Leaders

Data contracts change the relationship between the teams that build applications and the teams that rely on their data. Changes still happen, but they happen in the open, with notice and a plan. The result is fewer surprise incidents, faster delivery and numbers that leadership can trust without asking twice.

At Datum Labs, our Data Engineering and Analytics Engineering teams help companies introduce data contracts without slowing delivery. We identify the datasets that matter most, write contracts with producer and consumer teams, enforce them through dbt model contracts and CI checks, and set up the monitoring that keeps them reliable as data grows.

Every data team will face upstream changes. With data contracts in place, those changes become routine updates rather than Monday morning incidents.

Featured Insights

November 19, 2026
Datum Labs
Data contracts turn upstream changes into planned upgrades. Learn what goes into a contract, how schema evolution works, and how to enforce it with dbt.

Data Contracts: How to Stop Upstream Changes From Breaking Your Pipelines