Every company that has ever had a meeting where two people presented different numbers for the same metric needed a KPI dictionary. It is, in the most practical sense, a documented agreement about what your metrics mean — the business definition, the technical formula, the authoritative source, the owner, and the caveats. Without it, every number in your reporting is an interpretation. With it, a number is a fact.
The concept is simple enough that most organizations assume they don't need to formalize it. Their metrics are obvious. Everyone knows what "revenue" means. The definitions are in the SQL. The problem is that none of those things are actually true — and the moment you ask Finance, Sales, and Customer Success to each define their most important KPIs from scratch, the divergence becomes impossible to ignore.
"Everyone knows what revenue means" is the sentence that precedes the discovery that three departments are measuring it three different ways.
What a KPI dictionary actually is.
And what it isn't
A KPI dictionary is not a data catalog. It's not a list of database tables. It's not a technical data dictionary mapping columns to descriptions. Those things are useful, but they serve a different purpose and a different audience.
A KPI dictionary is a business document that captures the agreed-upon meaning of each metric your organization uses to make decisions. It's written in plain language that a COO can read, but with enough technical specificity that a data engineer can implement it without ambiguity. It lives somewhere central and accessible — not in a BI tool's metadata, not in a data engineer's notebook, not in the head of whoever built the original dashboard.
The audience is everyone: executives who read the numbers, analysts who calculate them, engineers who build the pipelines, and business owners who are responsible for them. The document has to serve all of them simultaneously.
The twelve fields every entry needs.
Required vs. optional — start with required, add optional as you mature
The canonical name — used everywhere, always. If Finance calls it "Net Revenue" and Sales calls it "Bookings," that conflict surfaces here and has to be resolved before anything else.
Example: "Monthly Recurring Revenue (MRR)"
Business definition Required
One or two plain-English sentences a non-analyst can read and understand. No SQL. No jargon. The definition a CFO would read and say "yes, that's what I mean when I say that."
Example: "The total value of active recurring subscription contracts, measured on the last day of the month."
Technical definition Required
How it's actually calculated — field names, filters, logic. Specific enough that two analysts independently implementing it would produce the same number.
Example: "SUM(contract_value) WHERE subscription_status = 'active' AND billing_interval = 'monthly', measured at month-end snapshot."
The single authoritative source for this metric. If the answer is "it depends" or "we pull from two places," that's a governance problem that needs resolving before the entry can be complete.
Example: "Salesforce CRM — Opportunities table, closed-won records."
A specific person — not a team or a role — who is responsible for the definition, accountable when the number is questioned, and empowered to resolve disputes about it.
Example: "Sarah Chen, VP Revenue Operations"
The person responsible for the pipeline, query, or model that produces the number. The person you call when the metric looks wrong.
Example: "Marcus Webb, Senior Analytics Engineer"
Filters & exclusions Required
Explicit list of what's included and excluded. This is where most definition conflicts live — one team includes trials, another doesn't; one team uses contract date, another uses invoice date.
Example: "Excludes: trial subscriptions, paused accounts, accounts in dunning. Includes: monthly and annual contracts (annual annualized)."
The level of detail at which the metric is meaningful. A metric without grain is ambiguous — "revenue" by day, week, month, and year are four different numbers.
Example: "Monthly. Not meaningful at daily grain due to monthly billing cycles."
How often the number updates and when to expect it. Critical for avoiding "that dashboard is stale" confusion.
Example: "Updated daily at 6:00 AM ET from nightly Salesforce sync. Month-end snapshot locked on the 3rd business day."
Historical issues, known edge cases, or upcoming changes that affect interpretation. This field prevents the same confusion from surfacing in every quarterly business review.
Example: "Pre-2023 data excludes acquired company Acme Corp. Integration complete Q1 2024."
Metrics this one is often compared to, calculated from, or confused with. Helps readers navigate the dictionary and understand context.
Example: "See also: ARR, Net Revenue Retention, Churn Rate."
Last updated / approved by Optional
Date of last review and who approved the current definition. Creates accountability and signals whether the entry is current.
Example: "Updated 2026-01-15. Approved by Sarah Chen and CFO."
A complete example entry.
Monthly Recurring Revenue — the metric most commonly defined inconsistently
Business definition
The total normalized monthly value of all active recurring subscription contracts, measured on the last calendar day of the month.
Technical definition
SUM(normalized_monthly_value) from subscriptions WHERE status = 'active' AND type IN ('monthly','annual') at month-end snapshot. Annual contracts divided by 12.
Source system
Salesforce CRM → Opportunities (closed-won). Synced nightly to data warehouse (subscriptions table).
Excludes
Trial subscriptions · Paused/dunning accounts · One-time professional services revenue · Pilot contracts not yet converted
Grain
Monthly. Not reported at daily grain.
Refresh
Daily at 6 AM ET. Month-end value locked on 3rd business day of following month.
Business owner
Sarah Chen, VP Revenue Operations — responsible for definition, dispute resolution
Technical owner
Marcus Webb, Analytics Engineering — responsible for pipeline, data quality
Known caveats
Pre-2023 data excludes Acme Corp (acquired Q3 2022, integrated Q1 2023). Restatement available on request.
Last updated
2026-01-15 · Approved: Sarah Chen, CFO
How to build it without it dying in a committee.
The process that actually works at a growing company
Most KPI dictionary efforts stall for one of three reasons: they start too big (trying to document every metric at once), they're built in the wrong format (a database nobody accesses), or they have no owner (it gets written and immediately starts decaying). Here's the sequence that avoids all three.
Step 1: Start with your ten most-argued-about metrics. Not all metrics — just the ones that cause the most confusion in meetings. "Revenue," "active customers," "churn," "pipeline," "headcount." Ask leadership: which number, when it appears in a meeting, is most likely to generate a "which version of that are you using?" response. Those are your starting ten.
Step 2: Run a definition workshop — don't write it in isolation. Get the business owners in a room (or on a call) for each metric. Ask: what does this mean to you? What does it include? What does it exclude? What date field do you use? What happens to contracted-but-not-started accounts? The disagreements that surface in this conversation are the metric conflicts the dictionary is designed to resolve. Document them, negotiate a resolution, and record the agreed-upon answer.
Step 3: Put it where people actually work. A KPI dictionary buried in a SharePoint folder that requires three clicks to find is a dictionary nobody reads. It should live in the same place your team does day-to-day work — a shared Notion database, a Confluence page with a prominent link, a Slack bookmark. The format matters less than the accessibility.
Step 4: Name a dictionary owner and a review cadence. The dictionary needs one person responsible for it — not a committee, not "the data team." One person who fields questions about definitions, resolves disputes, and triggers a review when something changes. A quarterly review of the top 20 entries is sufficient for most organizations.
The four signs your KPI dictionary is working.
- When a metric question comes up in a meeting, someone says "let me check the dictionary" instead of "let me ask the data team."
- A new analyst can onboard and understand your core metrics without a two-hour walkthrough from a senior colleague.
- When the same dispute comes up again, someone can close it by pointing to the documented definition rather than relitigating it.
- When a metric needs to change, there's a process: proposed change, business owner approval, technical update, version history.
Start here, not there
The most common mistake: trying to build the dictionary in a data catalog tool before the definitions themselves are agreed upon. The tool is irrelevant until the human agreement exists. A Google Sheet with ten rows of agreed definitions is more valuable than a sophisticated data catalog with fifty undefined metrics. Start with the agreement. The tool follows.