What a KPI dictionary is for
A metric name is a label, and labels drift. "Conversion rate" can divide purchases by sessions, by users or by clicks; it can count every purchase event or only the first per session; it can use the analytics tool's count or the order system's. Each choice is defensible and each produces a different number, and without a dictionary the choice is made silently by whoever built each report. The dictionary makes the choice once, in writing, and gives it an owner. It is the human-readable face of a metrics layer, and the metrics layer guide explains how the same definitions are enforced in code; this page is the document that comes first, because a definition has to be agreed before it can be enforced.
The dictionary also serves the measurement plan. Every KPI the plan names should have a row here, and every row here should descend from a question in some plan, which is what keeps the dictionary from becoming a list of everything the tools can report. The KPI trees guide shows how metrics relate to one another arithmetically; the dictionary records the leaves and the branches of those trees with their definitions. For the general meaning of each metric, the glossary and the core metrics guide are the references; the dictionary is where a business pins the general meaning to its own data. It sits with the other two documents in the measurement templates hub.
The dictionary schema
Each metric is one row with the fields below. The fields are deliberately few; a dictionary that asks for twenty attributes per metric is never completed.
| Field | What to write | Why it is there |
|---|---|---|
| Name | The short name used in reports, exactly as it will appear | Reports and the dictionary must use the same string |
| Definition | One sentence in plain words stating what is counted and what is excluded | The sentence a non-analyst reads to know what the number means |
| Formula | Numerator and denominator, or the aggregation, in terms of named events or fields | The arithmetic a second analyst can reproduce |
| Grain | The unit the metric is computed at: session, user, order, click, day, campaign | The same formula at two grains gives two numbers |
| Data source | The system of record and the table or report the inputs come from | Decides which number is right when systems disagree |
| Owner | One named person who approves changes to this row | Definitions without owners drift |
| Direction | Whether higher is better, lower is better, or the metric is a guardrail with a range | Prevents "improvement" being read the wrong way |
| Caveats | Known limits: consent gaps, modelled values, attribution window, lag before the number settles | The context that stops the metric being over-read |
| Version and date | The current version number and the date it changed, with a one-line note | A restated history can be explained |
Direction deserves a note. Some metrics are inputs to be pushed, some are outputs to be watched and some are guardrails that must stay within a range; a cost metric that falls because tracking broke is not an improvement, and the caveat field is where that failure mode is recorded.
Starter entries
The table below is a starting set for a business that runs paid media and sells or generates leads online. Each row follows the schema with the formula written in terms of fields a typical analytics export or ad platform report provides. Adjust the sources to the systems in use and replace the placeholder owner roles with names. Formulas use the convention that "spend" means media cost excluding fees unless a business decides otherwise, and that decision belongs in the caveats column.
| Name | Definition | Formula | Grain | Data source | Owner | Direction | Caveats |
|---|---|---|---|---|---|---|---|
| Sessions | Visits to the site as the analytics tool counts them | Count of sessions | Session | Analytics property | Analytics owner | Context, not a target | Consent gaps; bot filtering; session timeout rules |
| Click-through rate (CTR) | Share of impressions that produced a click | Clicks ÷ Impressions | Campaign, ad | Ad platform report | Paid media lead | Higher is better, within reason | Platform-specific definitions of a click; viewability not counted |
| Cost per click | Media cost of one click | Spend ÷ Clicks | Campaign | Ad platform report | Paid media lead | Lower is better | Depends on auction and targeting; not comparable across platforms |
| Cost per thousand impressions | Media cost of a thousand impressions | Spend ÷ Impressions × 1,000 | Campaign | Ad platform report | Paid media lead | Lower is better for reach buys | Impression definitions vary by platform and format |
| Conversion rate (CVRShare of visits or clicks that convert.) | Share of sessions that include a key event | Sessions with the key event ÷ Sessions | Session | Analytics property | Analytics owner | Higher is better | Grain must match reports; a user grain gives a different value |
| Cost per acquisition (CPA) | Media cost of one tracked conversion | Spend ÷ Conversions | Campaign, channel | Ad platform spend; analytics conversions | Paid media lead | Lower is better | Attribution window and model; platform and analytics counts differ |
| Return on ad spend (ROAS) | Revenue attributed to ads per unit of spend | Attributed revenue ÷ Spend | Campaign, channel | Order system revenue; ad platform spend | Paid media lead | Higher is better | Returns and cancellations; attribution window; revenue excludes tax and shipping |
| Average order value | Revenue per order | Revenue ÷ Orders | Order | Order system | Ecommerce lead | Higher is usually better | Discounts and returns; define whether shipping is included |
| Repeat purchase rate | Share of customers with more than one order in the period | Customers with a second order ÷ Customers with a first order | Customer | Order system | Retention owner | Higher is better | Period length changes the value; define the window |
| Customer lifetime value (LTVTotal value a customer brings over time.) | Margin a customer is expected to produce over a defined horizon | Average margin per order multiplied by expected orders in the horizon | Customer cohort | Order system; finance margin | Finance partner | Higher is better | Projected, not observed; state the horizon and the model |
| Customer acquisition cost | Spend to acquire one new customer | Acquisition spend ÷ New customers | Month, channel | Ad platform spend; order system | Finance partner | Lower is better | Which costs count as acquisition spend is a finance decision |
| Lead to opportunity rate | Share of leads the sales team accepted | Accepted leads ÷ Leads | Lead | CRM | Sales operations | Higher is better | Lag between lead and acceptance; definition of "accepted" |
The same starter set follows as plain CSV, with all nine schema fields, so that it can be pasted into a spreadsheet or a repository without the page's formatting. Replace the placeholder version and date with the real values, and the owner roles with names, before publishing it.
name,definition,formula,grain,data_source,owner,direction,caveats,version_and_date
Sessions,Visits to the site as the analytics tool counts them,Count of sessions,Session,Analytics property,Analytics owner,"Context, not a target",Consent gaps; bot filtering; session timeout rules,"1.0, YYYY-MM-DD, first entry"
Click-through rate (CTR),Share of impressions that produced a click,Clicks ÷ Impressions,"Campaign, ad",Ad platform report,Paid media lead,"Higher is better, within reason",Platform-specific definitions of a click; viewability not counted,"1.0, YYYY-MM-DD, first entry"
Cost per click,Media cost of one click,Spend ÷ Clicks,Campaign,Ad platform report,Paid media lead,Lower is better,Depends on auction and targeting; not comparable across platforms,"1.0, YYYY-MM-DD, first entry"
Cost per thousand impressions,Media cost of a thousand impressions,"Spend ÷ Impressions × 1,000",Campaign,Ad platform report,Paid media lead,Lower is better for reach buys,Impression definitions vary by platform and format,"1.0, YYYY-MM-DD, first entry"
Conversion rate (CVR),Share of sessions that include a key event,Sessions with the key event ÷ Sessions,Session,Analytics property,Analytics owner,Higher is better,Grain must match reports; a user grain gives a different value,"1.0, YYYY-MM-DD, first entry"
Cost per acquisition (CPA),Media cost of one tracked conversion,Spend ÷ Conversions,"Campaign, channel",Ad platform spend; analytics conversions,Paid media lead,Lower is better,Attribution window and model; platform and analytics counts differ,"1.0, YYYY-MM-DD, first entry"
Return on ad spend (ROAS),Revenue attributed to ads per unit of spend,Attributed revenue ÷ Spend,"Campaign, channel",Order system revenue; ad platform spend,Paid media lead,Higher is better,Returns and cancellations; attribution window; revenue excludes tax and shipping,"1.0, YYYY-MM-DD, first entry"
Average order value,Revenue per order,Revenue ÷ Orders,Order,Order system,Ecommerce lead,Higher is usually better,Discounts and returns; define whether shipping is included,"1.0, YYYY-MM-DD, first entry"
Repeat purchase rate,Share of customers with more than one order in the period,Customers with a second order ÷ Customers with a first order,Customer,Order system,Retention owner,Higher is better,Period length changes the value; define the window,"1.0, YYYY-MM-DD, first entry"
Customer lifetime value (LTV),Margin a customer is expected to produce over a defined horizon,Average margin per order multiplied by expected orders in the horizon,Customer cohort,Order system; finance margin,Finance partner,Higher is better,"Projected, not observed; state the horizon and the model","1.0, YYYY-MM-DD, first entry"
Customer acquisition cost,Spend to acquire one new customer,Acquisition spend ÷ New customers,"Month, channel",Ad platform spend; order system,Finance partner,Lower is better,Which costs count as acquisition spend is a finance decision,"1.0, YYYY-MM-DD, first entry"
Lead to opportunity rate,Share of leads the sales team accepted,Accepted leads ÷ Leads,Lead,CRM,Sales operations,Higher is better,"Lag between lead and acceptance; definition of ""accepted""","1.0, YYYY-MM-DD, first entry"
The rows are a vocabulary, not a verdict. A business that does not sell online removes the order rows; one that sells through a sales team adds pipeline rows. What matters is that every metric that appears on a dashboard or in a target has a row, and that the row says which system wins when numbers disagree.
Resolving a conversion rate dispute at an online tutoring service
An online tutoring service reports a "trial conversion rate" of 4.6 percent on the marketing dashboard
and 3.1 percent in the monthly board pack. The marketing dashboard divides trial_started events by
sessions in the analytics tool; the board pack divides trials recorded in the CRM by unique users from the
same tool. Neither is wrong, but neither is defined. The analyst adds one row to the dictionary: trial
conversion rate, defined as unique users who visit a pricing page and then start a trial, divided by unique
users who visit a pricing page, computed at user grain. The visitor list comes from the analytics tool and
the trial status from the CRM, which is the system of record for whether a trial started; the two are
joined on the analytics user ID that the sign-up form stores on the CRM record, and only trials whose user
ID is in the visitor list count in the numerator, so both sides describe the same people. CRM trials with
no matching pricing-page visit, such as people who declined analytics cookies or signed up without
visiting the page, are left out of the rate and reported as a separate unmatched count. The owner is the
growth lead; the direction is higher is better; the caveats record the join key, the unmatched count and a
two-day lag before CRM trials settle. Both reports are rebuilt from the row and show 3.4 percent, for
instance 1,020 matched trial starters among 30,000 pricing-page visitors. The 1.5 point gap that had been
discussed for two meetings disappears, and the difference between the old figures is recorded in the
version note so that nobody re-opens it.
Governance
A dictionary is only trusted if it is stable, and only useful if it can change. The rules below balance the two. Every row has one owner, and only the owner approves a change; a request from anyone else is a proposal. Changes are versioned: the row's version increments, the date is set, and a one-line note says what changed and why, so that a chart which steps on the date of the change can be explained. Where a change restates history, the note says whether past reports were recalculated or left as they were, and the dashboard carries an annotation on the date. A metric that is retired stays in the dictionary with a retired status rather than being deleted, because old reports still reference it.
New rows arrive through the measurement plan: a KPI appears in a plan, the plan's owner proposes a row, and the dictionary owner checks that no existing row already covers it under another name. Reviews happen on a fixed cadence, monthly for a small team and quarterly for a stable one, and after any event that changes a source: a new analytics property, a CRM migration, a change to the order system's revenue definition. The review is simple: for each row, does the formula still match the dashboard, does the source still exist, and is the owner still in the role? The metrics layer guide describes how the same rows become code so that enforcement does not depend on people remembering the document; until that exists, the dictionary and a monthly reconciliation are the enforcement.
Common mistakes
- Definitions without grain. The same formula at session and user grain gives different numbers; state the grain on every row.
- No system of record. When analytics and the order system disagree, the row must say which wins; otherwise the dispute recurs monthly.
- Owners who are teams. "Marketing" cannot approve a change; a person can.
- Every available metric. A dictionary of everything the tools can export is never read. Rows exist because a plan asked a question.
- Silent restatements. Changing a formula without a version note turns every historical chart into a mystery.
- Direction left blank. A falling cost metric is read as good until someone notices tracking stopped; the direction and caveat fields are where that reading is corrected.
- Treating the glossary as the dictionary. The glossary says what a metric generally means; the dictionary says what it means here, from which source, at which grain.
