How to document KPI definitions: nine fields for metrics you can rely on
How to write KPI definitions that business stakeholders and the BI team read the same way and can trace all the way back to their data sources.
A good KPI definition answers three questions without anyone having to ask: what does the metric measure, how is it calculated, and who owns its meaning? A short name is not enough, and neither is a formula on its own. The business statement, the scope, the unit, the time frame, the owner and the technical lineage all have to be documented together.
The goal is not to write as much text as possible. The goal is a definition that a new colleague can apply correctly, that a business team can validate, and that a BI developer can trace all the way down to the sources.
The nine essential fields of a KPI definition
A repeatable template stops every metric from being described in its own way. These nine fields cover both the business and the technical core:
| Field | Guiding question | Example |
|---|---|---|
| Name | What is the metric called, unambiguously? | Gross margin |
| Business definition | What does it actually tell you? | Share of gross profit in net revenue |
| Calculation logic | How are the numerator and denominator formed? | (Net revenue - Cost of sales) / Net revenue |
| Unit | How is the value displayed? | Percent |
| Time frame and grain | Which period and level does it apply to? | Month, product group |
| Scope | What is included or excluded? | Excludes internal revenue |
| Owner | Who decides on business questions? | Head of Finance |
| Status | How binding is the definition? | Certified |
| Sources and dependencies | Which data objects and KPIs does it rely on? | FactSales, FactCost, Net revenue |
Synonyms are a useful addition. They help people find the metric, but they must not replace the single standard name. "Gross margin", "trade margin" and "gross profit margin" can all point to the same definition.
Document KPI definitions in six steps
1. Start with the decision
First ask what the metric will be used for. A KPI for monthly corporate steering may need different scoping than an operational metric for individual campaigns. The usage context makes it clear which details you absolutely have to document.
2. State the business meaning in one sentence
The first sentence should be understandable without a formula. A reliable structure is:
The metric measures [subject] relative to [comparison base] within [time frame or scope], to support [decision].
Avoid phrasings like "shows revenue" or "calculates the margin". They just repeat the name and explain neither the content nor the scope.
3. Expose the numerator, denominator and filters
Do not just document the finished formula. Describe which business events flow into the numerator and denominator, which filters apply, and how edge cases are handled. For a ratio, explicitly distinguish a denominator of 0 from a missing value. "Not calculable" is not the same as a result of 0 percent.
4. Fix the unit, time frame and grain
"Revenue" can mean EUR, USD or a currency-adjusted group currency. "Active customers" can be measured daily, monthly or on a rolling 30-day basis. Unit and time reference therefore belong in structured fields, not just in the report title.
5. Assign ownership and status
The business owner decides on meaning and scope. The BI team owns the technical implementation, but should not have to resolve business conflicts on its own. A status model separates draft, approved, certified and deprecated definitions.
6. Link sources and dependencies
Do not name data sources only in prose. Link the KPI to tables, fields and dependent metrics. ID-based references are more stable than names: if a table is renamed, the relationship stays intact.
End-to-end example: gross margin
Name: Gross margin
The example below is fictional. The cost scope and posting rules have to be agreed on for each individual company.
Business definition: Here, gross margin shows what share of net revenue remains after deducting the cost of sales attributed to the products sold. It supports assessing the profitability of product groups.
Formula: (Net revenue - Cost of sales) / Net revenue
Unit: Percent
Time frame and grain: Calendar month; can be broken down by product group and region
Scope: Internal revenue is excluded. Returns reduce net revenue in the month in which they are posted; the related cost corrections are accounted for consistently. Marketing, sales and administrative costs stay outside the cost of sales in this example.
Owner: Head of Finance
Status: Certified
Sources and dependencies: Net revenue from FactSales; cost of sales from FactCost; product group mapping via DimProduct. Both amounts are aggregated to the same period, currency and product group before the division.
Edge cases: When net revenue is 0 or costs are missing, no percentage is reported. The report shows the reason as "not calculable" or "costs incomplete".
Checking with numbers: why the average of the margins can be wrong
Product group A generates 100 EUR of net revenue at 60 EUR cost of sales: the margin is 40 percent. Product group B generates 900 EUR at 810 EUR of costs: the margin is 10 percent.
Together this gives (1,000 - 870) / 1,000 = 13 percent. The simple average of 40 and 10 percent would be 25 percent and answers a different question. The documentation therefore has to record: sum the amounts first, then calculate the ratio. The formula value 0.13 is displayed as 13 percent; multiplying by 100 again in a percent format would be wrong.
A review should include this normal case as well as a month with no revenue and a missing cost value. That is how a plausible description turns into a verifiable calculation agreement.
Weak and reliable definitions compared
| Weak | Reliable |
|---|---|
| "Margin after costs." | Names the statement, numerator, denominator and relevant cost types. |
| "Revenue minus COGS as a percent." | Also explains time frame, returns, internal revenue and grain. |
| "Calculated by the finance team." | Names a concrete business-accountable role. |
| "Source: Power BI." | Links the models, tables and fields that are actually used. |
| "Valid." | Uses a defined status with a traceable review. |
A definition is reliable when two independent people would expect the same value. If both can calculate plausible but different results, at least one scoping rule is missing.
Review checklist before approval
- Is the business meaning understandable without a formula?
- Are the numerator, denominator, filters and edge cases described?
- Are the unit, time frame and grain unambiguous?
- Is it documented what is explicitly not included?
- Is there exactly one business owner?
- Does the status match the actual review?
- Are source tables, fields and KPI dependencies linked?
- Have synonyms been added without creating several standard names?
- Can a new person apply the definition without any extra verbal information?
The reviewer should not just check spelling. What matters is whether the definition is complete, free of contradictions and technically traceable.
Seven common mistakes
1. The name is repeated as the definition
"Monthly Recurring Revenue is the revenue that recurs each month" does not explain which contract types, discounts or currencies are included.
2. The formula replaces the business explanation
A correct DAX or SQL formula can be unreadable for business users. It also does not automatically explain the purpose of the metric.
3. Time references stay implicit
Calendar month, rolling 30 days and fiscal year all produce different values. The time frame has to be part of the definition.
4. Owners are recorded as a team name with no decision authority
"BI team" is often the technical contact, but not the business decision-maker. Name the role that can approve scoping rules.
5. Every report variant gets its own KPI
Slight filter variants should build on a shared definition wherever possible. Otherwise the metrics catalog grows faster than the shared understanding.
6. Sources live only in free text
Textual names go stale on renames and are hard to use for lineage or impact analysis. Structured references are more reliable.
7. Deprecated definitions are deleted
An old KPI should be marked as deprecated and linked to its successor. Deleting it takes away the context users need for existing reports.
Frequently asked questions
How long should a KPI definition be?
The core business sentence should be short, usually one to three sentences. Scope, formula, unit and sources belong in their own fields. That keeps the definition readable without losing important details.
Who is allowed to approve a KPI?
Business accountability should sit with a named owner. In MetricsMap, reviewers and admins can certify; editors capture and revise definitions.
Do technical field names belong in the definition?
Not in the core business sentence. Technical tables and fields should be linked in a structured way, so the definition stays readable while the lineage remains traceable.
How often should KPI definitions be reviewed?
On every business or technical change, and regularly for decision-critical metrics. A fixed review cadence is especially useful when sources, organizational structures or business models change frequently.
Review a definition with your team
Pick a metric that triggers follow-up questions today. Fill in the nine fields and have a second person work through one normal case and two edge cases. If the results differ, add the missing rule before approval. In MetricsMap you fill in these nine fields per KPI in a structured way and link sources and dependencies directly to tables and fields.