The Field Guide · Term
Semantic Contract
A metric definition with a version, an owner, and consumers that are told when it changes.
A semantic contract is a versioned, owned definition of a business metric — its formula, grain, filters, and tests — held in one governed source that every consumer reads, so a dashboard tile and an AI agent cannot silently disagree about what the number means.
The definition is the interface
Every metric your business runs on is an agreement: what counts, what doesn't, at what grain, since when. In most companies that agreement lives in four places at once — a BI tool's calculated field, a finance model, an analyst's memory, a board deck footnote — and each copy drifts on its own schedule. A semantic contract collapses those copies into one artifact: the definition as code, with an owner accountable for it, a version history behind it, and tests that prove the number still reconciles.
The word contract is doing real work. Like an API contract, it binds two sides: the team that maintains the definition, and every consumer — human or machine — that reads it. Change the contract, and the change is versioned, tested, and announced. Consumers upgrade deliberately, or hold at the version they trust. That discipline is routine in software engineering. Applying it to business definitions is what makes an analytics layer safe to put AI on top of.
The payoff compounds when agents arrive. A human analyst who inherits an ambiguous definition asks a colleague. An AI agent doesn't — it picks an interpretation and answers confidently. A semantic contract removes the ambiguity at the source: the agent retrieves the certified definition and its current value, cites the version it used, and refuses questions the contract doesn't cover.
How it fails in the wild
The classic case is the metric with three defensible definitions. Net revenue retention computed one way in the BI tool, another in the finance model, a third in the board deck — each formula reasonable, each owned by nobody, disagreeing by a few points. Humans argue it out in the meeting. An AI assistant just picks one, per query, and nobody notices for a month.
The quieter case is the definition that changes without a version. Someone widens “active customers” to include trials — a defensible call, made in one tool, told to no one. Every downstream chart moves a little. The AI trained to explain metric movement explains this one fluently: growth initiatives, seasonality. The real cause — the definition changed — isn't in its context, because the change was never an event anyone recorded.
How to detect the gap
- 01
Pick your five most-quoted metrics. Count the places each is defined — every BI calculated field, finance model, and doc copy counts. More than one is a live risk.
- 02
Ask who owns each definition. If the answer is a team, it's nobody. Contracts name a person.
- 03
Ask what happens downstream when a definition changes. If the honest answer is “people find out when a chart moves,” there is no contract — there's a copy.
- 04
Diff test: can you produce the definition of a metric as it stood last quarter? If history isn't retrievable, versions don't exist.
Questions, answered plainly
Is a semantic contract the same thing as a semantic layer?
A semantic layer is the technology surface — the place tools read definitions from. A semantic contract is the governance discipline applied to each definition inside it: an owner, a version, tests, and consumers that are notified on change. You can buy a semantic layer. You have to operate contracts.
What does a semantic contract physically look like?
Usually definitions-as-code in your repo — dbt-compatible YAML declaring the metric's formula, grain, dimensions, owner, and tests — reviewed through the same pull-request discipline as any other code, and readable by both your BI tools and your AI retrieval layer.
Who should own a contract — data or the business?
The business owns the meaning; data engineering owns the implementation. In practice: a named business owner signs off on what the metric means, and the definition-as-code encodes that decision where every consumer reads it. The failure mode is assigning both halves to whoever built the dashboard.
How many metrics need contracts?
Fewer than you think. The 15–40 metrics that actually drive decisions cover most of the risk. Contracting everything is how governance programs stall; contracting the metrics your executives quote is how they ship.
Watch it run
Adjacent terms
Trust Gate
The checkpoint between definitions and every consumer that reads them.
Definitions-as-Code
Business definitions in version control, reviewed like the production assets they are.
Metric Trust
The property your executives already measure informally — made explicit, scored, and managed.
Governed AI Analytics
What it takes to let AI touch the numbers a business runs on.