Metrics dictionary template: define your numbers in an afternoon

"Active clients" is 212 in your report and 247 in the account team's. Both are right. You count clients with a paid invoice in the last 60 days, and they count 90. Nobody wrote either rule down, so the meeting goes to the number instead of the decision.

A metrics dictionary fixes this with a page of plain sentences. This template has 11 fields and 5 worked examples. Download the CSV, open it in your spreadsheet, and replace the examples with your own.

What is a metrics dictionary?

A metrics dictionary is a list of the numbers your team reports, with one entry per number that says what it counts, how it's calculated, where the rows come from, and who owns it.

It's a close cousin of the data dictionary, which the U.S. Geological Survey describes as a way "to catalog and communicate the structure and content of data." A data dictionary describes columns: what Invoice date means, which values Status can take. A metrics dictionary describes the numbers you build from those columns. NIST's glossary sets the floor for a dictionary entry: an unambiguous identifier, a term, and a definition. The other fields exist so that 2 people get the same number from the same rows.

Teams with data engineers keep the same information inside their tools. dbt's Semantic Layer centralizes metric definitions so that different teams work from the same definitions whatever tool they use. Looker defines measures in LookML, and Power BI defines measures as formulas in the model. Without those tools, a shared sheet does the same job on a smaller scale.

Which fields does a metrics dictionary need?

These are the 11 columns in the template, filled in for Active clients.

3 fields do most of the work. Filters and Rows left out are where numbers quietly drift apart: 2 people agree on "paid invoices," but only one drops test clients. Data tools make these part of the metric: a dbt metric can carry a filter its docs compare to a WHERE clause, and a LookML measure can carry filters. Owner settles arguments: when a definition has to change, one named person decides.

Write dates as YYYY-MM-DD. RFC 3339, the standard for internet timestamps, notes that dates ordered from year to day sort correctly as plain text, so your change log sorts the same way in any spreadsheet.

How do you write a one-sentence definition?

A good definition lets someone who has never seen your sheet predict whether a given row counts. Build it from 4 parts:

1. What is counted. Start with the noun: clients, orders, projects, days.
2. The condition. What makes a row count: paid, delivered on time, status Green.
3. The window. This week, the last 90 days, as of the latest update.
4. The unit. A count, US dollars, a percentage, days.

"Revenue" isn't a definition. "Paid orders in the period, minus refunds issued in the period, in US dollars" is. It answers the 2 questions people argue about: are refunds subtracted, and in which period?

Keep formulas and column codes out of the sentence. They go in Calculation. Avoid words that need their own definition, like "qualified" or "engaged," unless another entry defines them. The formal version is ISO/IEC 11179-4, a standard for writing data definitions.

Then test it: give the sentence and the raw rows to a colleague and ask for last week's number. A different answer means the sentence is missing a rule.

Finally, put the sentence where people pick the number. Microsoft notes that people building Power BI reports see only a measure's name and description when they choose which measure to use. Looker shows a field's description behind an information icon and when someone hovers over the column. In a spreadsheet, use a note next to the number or a linked definitions tab.

How should you date changes?

Definitions change. The renewal cycle moves to 90 days, or refunds start counting in the month they're issued. Change is fine. Silent change is the problem. Version each metric, not the whole dictionary:

• Bump the version when the number would change for the same rows. A new window, filter, source, or left-out rule is a new version. A typo fix isn't.
• Date it. Changed on is the day the new version took effect. Change note says what changed from what: "Window changed from 60 to 90 days," not "Updated definition."
• Keep the old version. Copy the old row to a Changes tab before you edit it. When someone asks why August looks different from September, the answer is in the file.
• Show the break once. In the first report under the new version, give both numbers for the same week. Say Active clients was 212 under v1 and 247 under v2: the 35 extra clients are a definition change, not growth.
• Footnote the version. "Active clients (v2, since September 14, 2026)."

What do finished entries look like?

Here are 5 hypothetical entries from teams in a 150-person company. The CSV has all 11 fields for each.

Each entry makes one decision visible. Paid revenue v2 counts a refund in the period it's issued, so a September refund no longer changes a reported August. Projects on track v2 stopped counting Amber as on track, so in this example the count fell from 10 of 12 to 8 of 12 the week it changed, with no project getting worse. Time to fill uses the median, so one role that took 200 days doesn't hide the typical case. For more project office definitions, see PMO dashboard metrics.

How do you build one in an afternoon?

Block 4 hours, and ask a colleague for 30 minutes at 3:15.

1. 1:00 to 1:30, list the numbers. Write down every number in the last 4 reports you sent. Mark the 5 to 7 that someone uses to make a decision.
2. 1:30 to 2:30, write the definitions. One sentence each, using the 4 parts above. Write them before you look at the formulas, so you capture what people think the number means.
3. 2:30 to 3:15, fill in the mechanics. Fill in Calculation, Source, Filters, and Rows left out from what the formulas actually do. Flag every place where formula and sentence disagree.
4. 3:15 to 3:45, test one number. Have your colleague recompute last week's value for one metric from the entry alone. If it doesn't match what you reported, fix the entry or the report.
5. 3:45 to 4:30, review with the owners. Each owner reads their entry, resolves the flags, approves it, and agrees on the refresh schedule.
6. 4:30 to 5:00, publish version 1. Set every metric to v1 with today's date, save the dictionary next to the report, and link it from the top of the report.

You're done when every number in the report has an entry, an owner who approved it, and a v1 date. For the report itself, see our weekly KPI dashboard guide.

Where Every Number fits

We build every dashboard from the decision, then the metrics, then their definitions. In the $99 concierge pilot, a 15-minute call covers who reads the dashboard, what they decide with it, and how often. You then get 5 to 7 metrics, each with a plain-English definition you approve before anything is built, and a receipt behind every number. A metrics dictionary with versions, and impact analysis when a definition changes, are planned after launch. How it works shows the steps.

If your metrics already live in dbt, LookML, or Power BI measures, you don't need us for this. Keep the definitions there, next to the calculation, rather than in a second copy that can drift.