Skip to content
The Data EngineeringThe Data EngineeringBeta
About
Main content

Contracts, required fields and semantic types

What can a data contract say that a schema cannot, and when does it actually work?

Compatibility modes govern structure, and a machine can check them against two documents. A data tries to govern meaning. That requires checking against data and against people. So a contract is a different kind of object, not a stronger version of the same one.

What a contract adds that a schema cannot express:

  • currency_code instead of string. price_in_cents as int64 instead of plain int64. The unit is what structural checking cannot see.
  • An owner. A violated contract needs someone to escalate to.
  • A registered consumer list. This is quietly the most valuable item. It turns this mechanism's central unverifiable assumption (we do not know our ) into an enumerable one. It also makes the last step of (prove nobody reads the old field) decidable.
  • Freshness and volume expectations ("the table is updated every hour; it has at least 1 million rows a day"). These are checked by data-quality and observability tooling.
  • A change protocol with a notice period. This is a compatibility mode expressed in weeks instead of in types: "breaking changes need 30 days' notice".
contract: shipment_events
owner: team-tracking@parcelo.example
fields:
  price:        { type: int64, semantic: money_cents, currency_field: currency }
  currency:     { type: string, semantic: iso_4217 }
consumers: [warehouse-app, finance-dashboard, partner-csv, nightly-loader]
freshness: "< 15 minutes"
change_policy: { breaking: "30 days notice", additive: "any time" }

The honest assessment

The technical content of data contracts is a thin wrapper over a and an expectations framework (a set of data checks). The load-bearing part is organizational. A contract establishes that a 's table is a product with named consumers, and that breaking it has a cost to the producer. Contracts fail where the producer's incentives exclude consumer breakage. No amount of YAML repairs an incentive gap.

Contracts encode what schemas cannot (unit, owner, , notice period), and they work exactly to the degree that breakage costs the producer.