Data contract

Overview

A data contract is an explicit agreement — sometimes documented, sometimes enforced in code — between whoever produces a dataset (an application team, a source system) and whoever consumes it (analytics, ML models, other services) about what that dataset looks like and how it will behave over time. It typically covers the schema (column names, types, nullability), semantics (what a column actually means and how it's calculated), delivery expectations (how often it updates, acceptable latency), and change-management rules (how and when the producer will notify consumers of breaking changes).

Data contracts emerged as a response to a common failure mode: an upstream engineering team changes a field's type, renames a column, or silently drops a field, and every downstream pipeline that depended on it breaks without warning. A contract makes those expectations explicit and, ideally, enforced automatically rather than discovered after something breaks.

What a contract typically specifies

• Schema: field names, types, and whether fields are required or optional
• Semantics: business meaning of each field (e.g. is created_at in UTC or local time?)
• Quality guarantees: constraints like uniqueness, non-null expectations, or valid value ranges
• Service-level expectations: freshness, delivery cadence, and support for schema evolution
• Ownership: who to contact when something looks wrong

Enforcement

Contracts are most useful when they're enforced, not just documented. This can mean validating incoming data against a schema before it's accepted into a pipeline, running automated tests that fail a build if a contract is violated, or using database-level constraints. A simple example of schema enforcement at the database level:

Copy code
CREATE TABLE orders (
  order_id BIGINT PRIMARY KEY,
  customer_id BIGINT NOT NULL,
  order_amount DECIMAL(10,2) CHECK (order_amount >= 0),
  status VARCHAR NOT NULL
);

Here, NOT NULL and CHECK constraints encode part of a contract directly into the table definition, rejecting rows that violate it rather than letting bad data flow downstream silently.

Why it matters

As organizations have more teams producing and consuming data independently, informal assumptions about "what a table means" break down. Data contracts formalize those assumptions, shifting failures left — catching a broken schema change at the source before it silently corrupts downstream reports or models, rather than after.