What does a data contract specify beyond the column names and types?

## The problem a data contract solves Every analytics pipeline depends on tables and event streams produced by teams that did not write the pipeline. A backend engineer renames a column on Tuesday because it reads better in their service; on Wednesday a dashboard is silently wrong and nobody connects the two. The dependency was real, but it was invisible: nothing in the producing team's repository said that seven downstream models select `coupon_code`. A data contract makes that dependency explicit, versioned and reviewable. It is a specification of the dataset as an interface — the same idea as an API contract for a service, applied to a table or an event topic. ## Part one: schema The obvious part. Field names, types, nullability, allowed values for enumerated fields. Two things matter here that raw DDL usually omits: - **The key** — which field or combination uniquely identifies a row, and whether the producer guarantees it is stable across retries. - **The grain** — what one row *is*: one row per order, per order line, per shipment. Grain is the single most consequential fact about a dataset and the one most often left unwritten. ## Part two: semantics Types do not carry meaning. `integer` does not tell you that `gross_amount_cents` is cents rather than dollars, includes tax, and excludes shipping. `timestamp` does not tell you whether `placed_at` is the moment the customer clicked (event time) or the moment the row landed (ingest time), nor whether it is UTC. Nothing in the type system says whether a cancelled order is deleted, updated in place, or emitted as a second row that supersedes the first. These are exactly the details that produce quietly wrong numbers rather than loud failures, so a contract states them in prose next to each field. If your organisation has a metric definition — "active user", "net revenue" — the contract is where the producer commits to the definition the field implements. ## Part three: service levels A correctly-typed but empty table is still an outage. Contracts therefore carry operational commitments: a **freshness** target (maximum lag between when something happened and when it is queryable), an **expected volume** range so a partial or empty load is detectable, and often an availability or completeness expectation. These are the clauses that turn a contract from documentation into something you can alert on. ## Part four: change policy The contract says how it may change. That means a version scheme, an explicit list of what counts as a compatible change (adding an optional field) versus a breaking one (removing a field, narrowing a type, changing units or grain), a **deprecation window** during which a field is marked dead but still emitted, the channel on which change is announced, and who has to approve a breaking change. Without this section a contract is just a snapshot of today's schema. ## Ownership and where it lives A contract with no named owner is a wish. Ownership sits with the producing team, because they are the only ones who can prevent a breaking change rather than detect it after the fact. Practically, the spec file lives in the **producer's** repository next to the code that emits the data, is reviewed in their pull requests, and is published to a catalog or registry when it merges. That placement is what makes the contract enforceable in the producer's own CI instead of being a document the data team maintains alone. ## What a data contract is not It is not a serialization compatibility setting — a registry's compatibility mode is a mechanical check on encoded payloads and is a neighbouring concern, not the whole agreement. It is not a set of pipeline tests that run after the data has landed; those detect a violation, they do not prevent one, and by then the bad rows exist. And it is not a document written by the consuming team and shown to producers hopefully — a contract only functions when the producer has agreed to it and is gated by it. ## How contracts fail in practice The common failure modes are all social. A contract written for every table on day one, most of which nobody reads, dies of maintenance. A contract with sixty fields and no owner is unreviewable. And a contract nothing enforces is a comment. The version that works starts with one high-value dataset, is small enough that a producer will actually read the diff, and is checked automatically.