What is a data contract, and do we need one for a vendor integration?
A data contract is a written, testable agreement about the data crossing a boundary: field names, types, whether each is required, allowed values, delivery timing, and who to contact when it changes. You want one whenever a team or vendor outside your control feeds your reporting. It turns silent breakage into a caught error, because every incoming batch can be checked against the contract before anything downstream consumes it.
A contract is executable, documentation is not
The distinction that matters is enforcement. Documentation describes what the data should look like and nobody reads it after week one. A contract is expressed in a form your pipeline can check on every run, so a field that changes type from a number to a string produces a failed validation rather than a quietly wrong report three weeks later.
It does not need heavy tooling. For most service businesses a contract is a small structured file listing fields, types, required flags, allowed values and expected ranges, plus a validator that runs at ingest.
What belongs in it
- Field names and types. The mechanical half, and the easy half.
- Required versus optional. Including what a missing value means, which is not always the same as zero.
- Allowed values. Enumerations are where breakage hides. A new job status nobody told you about will map to nothing.
- Timing and completeness. When the data arrives, and how late a record can be and still be included.
- Change notice and a named contact. A person, not an address. This is the clause that is worth the most and gets written the least.
The meaning half is harder than the type half
Types are easy to agree on. Definitions are not. What counts as a completed job — dispatched and finished, or invoiced? Does revenue include tax? Does a lead include an existing customer calling back? Two systems can agree perfectly on schema and still produce numbers that will never reconcile because they mean different things.
Write the definitions down alongside the field list. Most reporting disputes between an operations team and a marketing team are definitional, and a contract that captures meaning ends the argument by making it explicit rather than by making anyone right.
Quarantine, do not reject
When validation fails, do not drop the whole batch and do not let it through. Route the failing rows to a quarantine table, load the rest, and report what was held back. Rejecting everything creates an outage over three bad rows; accepting everything creates a corrupted dataset.
Then make the quarantine visible. A quarantine count that grows over time is the earliest available signal of schema drift upstream, and it is much cheaper to investigate at fifty rows than at fifty thousand. This is the discipline that lets an intelligence platform report confidently on data it did not originate.
Topics: data contracts · schema · data quality · vendor management
Have a version of this question about your own business?
The useful answer usually depends on which systems you run and how they're connected. That's a conversation, not a blog post.