Data Contracts — The Enforceable Interface Between Producer and Consumer

The reason data breaks in production is almost never the data — it is the silent change. A producer renames a column, tightens a type, or drops a field, and downstream every consumer breaks at once with no warning. A data contract is the fix: an explicit, versioned, enforceable agreement between producer and consumer that makes the interface stable and change safe.

What a data contract actually specifies

A contract is more than a schema. It pins down everything a consumer depends on:

Element	What it guarantees
Schema	Field names, types, nullability, and structure
Semantics	What each field means — units, enums, business definition
Quality	Constraints: uniqueness, ranges, referential integrity, freshness
SLA	Availability, freshness, and support commitments
Ownership	The named team accountable, and the support channel
Change policy	How versions evolve and what counts as breaking

A contract as code

The contract lives in version control next to the product, and CI enforces it — so a change that violates it fails the build, not production:

# contracts/customer_360@2.1.0.yaml
contract: customer_360
version: 2.1.0
owner: customer-data-team
schema:
  - name: enterprise_customer_id
    type: string
    nullable: false
    semantics: "Golden, unique enterprise customer identifier (MDM)"
    constraints: [unique, not_null]
  - name: lifetime_value_usd
    type: decimal(18,2)
    nullable: false
    constraints: ["value >= 0"]
  - name: risk_band
    type: enum
    values: [low, medium, high]
sla:
  freshness: 5m           # data no older than 5 minutes
  availability: 99.9%
quality:
  - "row_count deviation < 10% day-over-day"
  - "null_rate(enterprise_customer_id) == 0"
classification: [pii]
change_policy:
  breaking: [remove_field, narrow_type, add_required_field]
  compatible: [add_optional_field, widen_type, add_enum_value]
  breaking_change_notice: 90d   # consumers get 90 days + migration path

How enforcement works

A contract only matters if it is enforced automatically:

• At build time — CI validates the producer's schema against the contract; a breaking change (dropping a field, narrowing a type) fails the pipeline before merge.
• At publish time — the product cannot be published to the marketplace unless its contract validates.
• At runtime — quality checks (freshness, null rate, row-count drift) run continuously; a breach pages the owner and can auto-flag the product's status.

This is the data equivalent of a typed API with a test suite — and it is the same discipline as the schema-drift guardrails that protect a federated estate.

Best practices

• Contract first, table second. Consumers depend on the contract, never your physical schema — so you can refactor storage freely.
• Semantic versioning with a breaking-change policy. Additive changes are compatible; removals and narrowings are breaking and require notice + a migration path.
• A real deprecation window. Announce breaking changes (e.g. 90 days), keep the old version live, and give consumers a migration path — the same lifecycle discipline agents get.
• Bind semantics to a shared vocabulary. Reference an ontology or business glossary so "customer" means the same thing across contracts.
• Make quality a guarantee, not a hope. Encode freshness and integrity as checked constraints, not documentation.

The path to implement

1. Write the contract as code and store it with the product in version control.
2. Enforce it in CI — breaking changes fail the build before they reach consumers.
3. Adopt semantic versioning with an explicit breaking-vs-compatible policy.
4. Run runtime quality checks against the contract and alert the owner on breach.
5. Gate marketplace publication on contract validation.

Incipient's Data Product Factory generates and enforces contracts as part of every governed product, and the Data Marketplace surfaces them so consumers depend on an interface, not your tables.

A data contract turns "please don't change that column" into a guarantee the pipeline enforces for you.

Talk to us about data contracts →