How should data governance teams implement a shared business glossary when metric definitions live in dbt and are consumed in downstream analytics tools?

Teams should treat the glossary as the control point for agreed business meaning, not as a documentation sidecar. Define core metrics once, connect them to lineage and ownership, and govern updates through a workflow that keeps definitions synchronized across tools. That approach reduces conflicting interpretations, supports trust in reporting, and helps analysts and business users work from the same assumptions.

Why a shared glossary needs to be the source of truth, not another layer of commentary

When metric definitions live in dbt and are consumed downstream, the glossary should function as the authoritative business meaning layer that keeps everyone aligned on what a metric actually represents. The glossary is most useful when it resolves ambiguity at the point of interpretation, while dbt remains the implementation layer that encodes the definition and lineage. That separation prevents teams from treating the same metric name as if it always means the same thing.

In practice, this means the glossary should capture the business definition, owner, scope, calculation intent, and any decision rules that affect interpretation. If a metric has multiple valid views, the glossary should make those variants explicit rather than hiding them behind one label. A useful pattern is to link the glossary entry back to the dbt model or semantic asset so consumers can trace the definition without having to guess which tool is authoritative.

For teams building the glossary at scale, it helps to anchor the meaning in a curated business term set and then map each term to one or more physical metric implementations. The Ultimate Guide to NHIs is a useful reference for the broader governance pattern of maintaining ownership, lifecycle, and visibility across shared digital assets, which is the same governance discipline needed when metric meaning spans multiple tools.

How to connect dbt definitions, lineage, and downstream analytics consumers

The cleanest implementation model is to make dbt the system of record for calculation logic and the glossary the system of record for meaning. That usually works best when metric objects in dbt are assigned stable names, documented in a consistent schema, and linked to glossary entries through metadata or catalog integration. Downstream analytics tools should then consume those same definitions rather than re-creating them locally.

Lineage matters because it tells users where a metric comes from and what it depends on, but lineage alone does not explain interpretation. A finance user, for example, may care that a metric rolls up from several source tables, while a product analyst may care that refunds are excluded or that the metric is based on booking date rather than invoice date. The glossary should hold those business rules in plain language, and the dbt layer should preserve the exact computation so the two stay synchronized.

Where tools do not support direct semantic sync, teams should establish a controlled publication workflow. That workflow should require changes to the dbt metric definition and the glossary entry to move together, with a review step that checks for naming consistency, ownership, and downstream impact. The goal is not only to publish definitions, but to prevent silent drift between a metric’s business meaning and its technical implementation.

Use one canonical business term per concept, then map it to every technical metric that implements it.
Require lineage links so consumers can see which dbt model or semantic layer object powers the metric.
Make ownership explicit so change requests have a clear approver and escalation path.

What breaks when definitions drift across tools

The main failure mode is not a broken dashboard, it is inconsistent decision-making. If the same KPI is labeled the same way in two tools but calculated differently, teams will compare numbers that are not actually comparable. That erodes trust quickly because users often blame the report, when the real issue is an unmanaged definition split between business language and implementation.

Another common failure mode is local redefinition inside downstream tools. Once a self-service analytics platform allows users to alter filters, time windows, or inclusion rules without updating the glossary, the organization may end up with several versions of the same metric. The longer that situation persists, the harder it becomes to reconcile historical reporting, audit changes, or explain why a trend moved.

Data governance teams should also watch for ownership gaps. If dbt developers can change calculations without business sign-off, or business stewards can edit wording without understanding the technical expression, the result is usually partial control rather than shared control. A glossary only works when the business meaning, lineage, and implementation changes are governed together.

Standards & Framework Alignment

This section maps relevant standards and security frameworks to the operational risks and controls described in this guidance.

CIS Controls v8 and NIST SP 800-53 Rev 5 set the technical controls, while ISO/IEC 27001:2022 defines the regulatory obligations.

Framework	Control / Reference	Relevance
CIS Controls v8	CIS-16 — Application Software Security	Metric definitions need controlled change management and authoritative documentation.
Recommendation — Treat metric definition updates as governed changes with approval, testing, and release traceability.
NIST SP 800-53 Rev 5	AU-8 — Time Stamps	Shared metric interpretation depends on synchronized, time-aware records across systems.
	CM-3 — Configuration Change Control	dbt and glossary definitions must change through a controlled workflow to prevent drift.
Recommendation — Ensure metric lineage and publication records are consistently time-stamped for traceability. Apply formal change control to metric logic, glossary text, and downstream publication mappings.
ISO/IEC 27001:2022	A.5.9 — Inventory of information and other associated assets	A metric glossary is an inventory of governed information assets and their ownership.
	A.5.12 — Classification of information	Glossary terms need consistent classification so consumers understand business meaning and sensitivity.
Recommendation — Maintain a current inventory of metric terms, owners, and linked implementations. Classify key metrics and their definitions so users apply the right interpretation and handling.

Practitioner Guidance

What to prioritise: Start with the highest-value metrics, especially those used in executive reporting, finance, customer health, or operational performance. Do not begin by trying to document every field in the warehouse, because glossary quality matters more than coverage on day one.

What to verify: Check that each published metric has one owner, one definition, one lineage path, and one agreed consumer-facing description. If a downstream tool can display the metric without showing its source definition, treat that as a trust gap rather than a UI convenience.

Decision rule: If a downstream team needs to change a calculation for local use, create a governed variant with a distinct name and purpose instead of silently reusing the canonical metric label. That keeps the shared glossary authoritative while still allowing legitimate analytical flexibility.

Practitioner takeaway: The winning pattern is to govern meaning centrally and execution consistently, so dbt and downstream tools can differ in implementation detail without ever diverging on what the metric is supposed to mean.