Under a data contract, how does a producer safely drop a field consumers still read?

## Removal is the hard direction Adding to a dataset is cheap; taking away is where contracts earn their existence. A removal is invisible to the producer — their tests pass, their service is healthier without the field — and catastrophic to whoever was reading it. The contract's job is to convert that invisible act into a scheduled, announced, measurable one. ## Step one: deprecate in the spec, do not delete The first change is additive metadata, not a removal. In the contract, the field gains a deprecation block: **since** which version, **remove_after** which date, **replacement** (a field, or none), and **why**. This is a compatible change, so it passes the producer's CI gate without a major version bump and without consumer sign-off — deliberately, because you want deprecation to be frictionless while deletion stays expensive. If a replacement exists, it ships in the same version and is populated from that moment. The overlap period is the whole mechanism: while both fields carry correct data, each consuming team migrates on its own schedule, and no coordination meeting is required. ## Step two: announce on the channel the contract names A change nobody saw is not a change that was announced. The contract's change policy should name where announcements land — a catalog entry that surfaces the deprecation to anyone browsing the dataset, plus a push into whatever channel consuming teams actually read. Publishing a new contract version on merge is what makes this automatic rather than dependent on somebody remembering. ## Step three: measure who is still reading This is the step that separates a real process from theatre. The calendar does not tell you it is safe to remove a field; **usage telemetry** does. Two sources are typically available: - **Query history / access logs** from the warehouse, parsed for references to the column. Most engines record executed SQL, and column-level parsing turns that into a reader list with team attribution. - **Column-level lineage** from your transformation tooling or catalog, which finds models and downstream tables that select the field even if no human queried it recently. Both have blind spots. Query logs miss a monthly or quarterly job that has not run inside the retention window — a real cause of "we checked, nobody used it" incidents. Lineage misses consumers outside your lineage graph entirely: an application reading the table directly, an exported extract, a notebook. So combine both, extend the observation window past your longest known job cadence, and treat *silence* as weaker evidence than an explicit confirmation from an owner. ## Step four: converge, then remove As the date approaches, the remaining readers should be a short list of named teams, and you talk to them. Two outcomes are legitimate: they migrate, or the window extends. What is not legitimate is removing on schedule while a known reader is still reading, because the whole social contract collapses the first time a deprecation window is enforced over a live dependency. When usage is zero, the removal ships as a **major version**. The producer's CI gate — which blocks field removals — is satisfied by the major bump plus whatever sign-off the change policy requires, and increasingly by an automated assertion that the deprecation existed for the required window and that usage telemetry is clean. ## Renames are removals A rename is an add plus a remove, and it must be run as one: introduce the new name, populate both, deprecate the old, wait, then drop. Teams that treat a rename as a single atomic edit are the origin of most contract incidents, precisely because it feels harmless in the producer's diff. ## Choosing the window length The window is a property of the contract, not of the individual change, and it should be long enough to cover your slowest consumer's release cadence plus their queue — a quarter is a common choice for shared datasets and a fortnight for datasets read only inside one team. Publish it in the contract so that when the moment comes, nobody is negotiating a timeline under pressure. ## The failure modes The recurring failures are: deleting first and discovering consumers through the incident channel; announcing but never measuring, so the removal is a coin flip; measuring only recent query history and missing the quarterly job; leaving the field deprecated forever because nobody owns closing it out, which trains everyone to ignore deprecation notices; and dual-writing two fields with subtly different semantics during the window, so consumers who migrate early get different numbers than those who have not.