The Field Guide · Term
Definitions-as-Code
Business definitions in version control, reviewed like the production assets they are.
Definitions-as-code is the practice of storing business metric definitions as versioned, testable artifacts in a code repository — reviewed through pull requests, deployed through CI, and read by every consumer — instead of scattering them across BI tools, documents, and memory.
The binder that never worked, replaced
Every organization has tried the glossary. A document, a wiki, a data dictionary — written in a burst of good intentions, drifting from reality within a quarter, trusted by no one within two. The failure isn't effort; it's architecture. A document describes definitions. It doesn't enforce them, version them, or tell anyone when they change.
Definitions-as-code moves the definition into the same machinery that already governs your transformation logic: a repo. A metric's formula, grain, dimensions, owner, and tests live as structured, dbt-compatible artifacts. Changing one is a pull request — reviewed by the owner, tested by CI, merged with history. The glossary stops being a description of the system and becomes part of it.
The quiet advantage is that machines read repos fluently. The same artifact that renders documentation for humans grounds retrieval for an AI copilot — one source, two consumers. Teams that did this for pipeline code a decade ago already know the ending: the question stops being “is the doc current?” because the doc is the deployed thing.
How the alternative fails
The dictionary drift: the wiki says one thing, the BI tool computes another, and everyone senior enough to know the difference routes around the wiki — which guarantees it never improves. New hires and AI systems, lacking the route-around knowledge, trust the wrong layer.
The unreviewed change: a calculated field edited directly in the BI tool on a Thursday afternoon. No diff, no reviewer, no announcement — just a chart that moves and a retrospective that eventually finds the edit. In code, that change would have been a one-line PR someone approved. In the tool, it was invisible.
How to detect the gap
- 01
Ask where your definition of revenue lives. If the answer names a tool or a document rather than a repo path, it isn't code.
- 02
Ask to see the review that approved the last definition change. No review trail means changes are edits, not decisions.
- 03
Check whether definition history is retrievable — the definition as it stood last quarter, on demand.
- 04
Ask whether your AI retrieval reads the same artifact your BI renders. Two sources is drift with a countdown attached.
Questions, answered plainly
Is this just dbt metrics or a semantic layer product?
Those are excellent substrates for it. The practice is the discipline — definitions in version control with owners, reviews, and tests — and it survives tool changes. Adopt the substrate your stack supports; keep the discipline regardless of vendor.
Do business owners really review YAML?
They review the rendered change — “trial accounts now count as active” — the same way executives review contracts without reading the source. The PR is the mechanism; the review surface is human-readable. What matters is that approval and history exist, not that the CFO writes YAML.
How does this relate to a semantic contract?
Definitions-as-code is the storage and change discipline; a semantic contract is what each definition becomes once it has an owner, a version, and consumers bound to it. Code is the how; the contract is the what.
Watch it run
Adjacent terms
Semantic Contract
A metric definition with a version, an owner, and consumers that are told when it changes.
Trust Gate
The checkpoint between definitions and every consumer that reads them.
Human-API Analysts
When your best analysts spend their week serving lookups a governed layer should serve.
Governed AI Analytics
What it takes to let AI touch the numbers a business runs on.