Definitions and metric specs

Two analysts open the same warehouse. Both are asked for “active customers.” One counts anyone who logged in during the last 30 days. The other counts paid seats with a successful API call in the last 7 days, excluding internal tenants. Both numbers are defensible. Both will be wrong for the meeting the other person prepared. The fight that follows will sound like a data quality problem. Often it is a missing metric specification.

This is Part 3 of Metrics that matter. Part 1 gave you the goal chain. Part 2 split leading and lagging. Now we write the boring page that keeps organizations honest: a metric spec with owner, grain, formula, filters, and known caveats. This is not a rewrite of All About KPIs. That prequel explains what KPIs are for. This part is the operating manual for one measure so two people can rebuild the same number on Monday morning.

What you’ll learn

Why verbal definitions rot under calendar pressure
The fields of a one-page metric spec you can copy
How owner, grain, formula, filters, and caveats each prevent a different failure
A fully worked “weekly active account” spec with a comparison table
How specs connect to data quality, SQL/Python implementation, and chart honesty

A metric without a spec is a rumor with a chart

Example:

Spec field quality

Example:

Filled one-page metric spec

Teams often “agree” in a meeting. Someone says “active means weekly engagement,” everyone nods, and three months later finance, product, and marketing each ship a different active metric into different decks. Nobody is trying to sabotage anyone. Ambiguity scaled.

A metric specification is a short contract. It is not a 40-page governance binder. One page (or one ticket with clear sections) is enough for most operational KPIs. The point is reconstructability: a competent colleague should rebuild the number from sources using only the written definition.

That standard matches how good quality work thinks. In the data quality series, “is this number fit for use?” depends on the use. A metric spec names the use, the population, and the known cracks. Without it, you are asking charts to carry meaning they were never given.

Rule of thumb: If the definition only lives in Slack, the number will drift the first time someone is out sick.

The one-page metric spec (template)

Copy this structure into a doc, wiki, or ticket. Keep each section short. Long prose is where definitions hide disagreement.

METRIC SPEC (one page)
======================
Name (business):
Name (technical / field):
Version + last reviewed:
Status: draft | active | deprecated

1. WHY THIS EXISTS
   Objective link (from goal chain):
   Decision it supports:
   Leading or lagging (or guardrail):

2. OWNERSHIP
   Business owner (can change process):
   Analytics owner (can change calculation):
   Escalation path when numbers disagree:

3. GRAIN
   One row / one unit means:
   Time grain (day, week, month, rolling window):
   Entity (user, account, order, ticket, ...):

4. FORMULA
   Plain-English formula:
   Formal expression (SQL sketch or math):
   Numerator:
   Denominator (if rate):
   Units:

5. POPULATION AND FILTERS
   Include:
   Exclude:
   Source systems of record:
   Join keys / identity rules:

6. TIME AND CADENCE
   Event timestamp used:
   Time zone / fiscal calendar:
   Refresh schedule:
   Late-arriving data policy:

7. TARGETS AND THRESHOLDS
   Target / bands:
   Comparison baseline (prior period, plan, cohort):
   Assumptions:

8. KNOWN CAVEATS AND SIDE EFFECTS
   Data quality risks:
   Gaming risks (light note):
   What this metric is NOT:

9. CHANGE LOG
   Date | change | reason | approver

You do not need perfect formality on day one. You need enough structure that “active customers” cannot silently mean three things.

Why each field earns its space

Owner: who can change the process vs the calculation

Split ownership. The business owner owns the behavior and the goal context. The analytics owner owns the calculation, lineage, and publication. When those roles collapse into “the data person owns the KPI,” you get beautiful dashboards that nobody can operationally fix, or process owners who quietly redefine success in a spreadsheet.

Also name the escalation path. When Finance and Marketing disagree by 4%, who convenes, what evidence is required, and how long until a decision? Without that, disagreements become endless Slack archaeology.

Grain: what one unit means

Grain is the silent killer of metric debates. Are you counting users or accounts? Orders or order lines? Tickets or ticket messages? Daily snapshots or rolling 28-day windows? If you cannot finish the sentence “one unit of this metric means ___,” stop building charts.

Grain also decides how you join data. Account-level activation joined carelessly to user-level events creates double counts that look like growth. This is the same grain discipline you need in tidy data and quality work: name the unit before you aggregate.

Formula: numerator, denominator, units

Write the formula in plain English first, then in a sketch people can implement. Rates need both numerator and denominator. “Conversion” without a denominator is a vibe. Units prevent comedy: is revenue in USD contracted, USD cash collected, or local currency rolled with a stale FX table?

A SQL sketch is allowed and useful even if the final model lives in a BI tool. The sketch is documentation, not production code. If you later implement in pandas from the Python for analytics series, the same formula text should still hold. Tools change. Meaning should not.

Filters: include, exclude, source of truth

Filters are where ethics and accuracy meet. Excluding internal tenants is normal. Excluding a region because it looks bad is not. Write inclusions and exclusions as lists. Name the system of record. If CRM is source for stage and warehouse is source for revenue, say how they reconcile.

Identity rules belong here too. How do you treat merges, duplicates, and guest checkouts? If quality work has not finished dedupe (see the quality series), the metric spec should say “known duplicate risk in X” under caveats rather than pretend precision.

Caveats: honesty that protects trust

Caveats are not weakness. They are professional. Late-arriving events, partial instrumentation, definition changes, and known gaming vectors should be visible next to the number. The charts series will tell you to annotate; the metric spec is where those annotations start as policy, not as last-minute slide footnotes.

Also write what the metric is not. “Weekly active accounts is not a revenue forecast.” “First response time is not customer effort.” Boundaries stop people from over-claiming in meetings.

Worked example: Weekly Active Accounts (WAA)

We will specify one metric end to end. Context: a B2B product team wants a leading health signal for product engagement (Part 2), tied to the objective “customers get ongoing value, not only a successful onboarding.”

Filled one-pager (narrative form)

Name: Weekly Active Accounts (WAA). Technical: metrics.waa_weekly. Version 1.2, reviewed 2026-07-01. Status: active.

Why: Leading indicator of product engagement for paid accounts. Supports the decision: “Do we invest in activation and core workflow quality this sprint, or is engagement healthy enough to focus elsewhere?” Not a board-level lagging success metric by itself.

Owners: Business owner: Head of Product Operations. Analytics owner: Product Analytics lead. Escalation: if WAA and finance “paid logos” disagree by more than 3% for two weeks, Product Ops convenes a 30-minute definition review with Analytics and Finance.

Grain: One row per account per ISO week (Monday through Sunday, America/New_York). Entity is account_id in the billing system, mapped to product tenant_id via the identity table.

Formula (plain English): Count of distinct paid accounts with at least one qualifying product event during the ISO week.

Qualifying event: any of: report export, dashboard share, or API write call. Page views alone do not count.

Filters: Include paid accounts in good standing as of week end. Exclude internal, test, partner sandbox, and churned accounts with cancel date on or before week start. Exclude events from staff impersonation sessions.

Cadence: Rebuild daily for the current week (partial) and finalize T+2 days after week end for late events. Timestamp used: event occurred_at in UTC, converted to America/New_York for week assignment.

Target: Hold WAA at or above 72% of paid accounts; investigate if week-over-week drop exceeds 4 points without a known outage.

Caveats: Mobile app events were under-instrumented before March; do not compare pre-March WAA to current without a break note. API write calls can be scripted; monitor accounts with extreme API-only activity. WAA is not revenue and is not seat utilization.

SQL sketch (documentation, not production gospel)

SELECT
  date_trunc('week', e.occurred_at AT TIME ZONE 'America/New_York')::date
    AS week_start_ny,
  COUNT(DISTINCT a.account_id) AS waa
FROM billing.accounts AS a
JOIN map.account_to_tenant AS m
  ON m.account_id = a.account_id
JOIN product.events AS e
  ON e.tenant_id = m.tenant_id
WHERE a.status = 'paid'
  AND a.is_internal = FALSE
  AND a.is_test = FALSE
  AND e.event_name IN ('report_export', 'dashboard_share', 'api_write')
  AND e.is_staff_impersonation = FALSE
  AND e.occurred_at >= DATE '2026-03-01'  -- post instrumentation fix
GROUP BY 1
ORDER BY 1;

Real production may use dbt models, incremental tables, or a semantic layer. The sketch still earns its place because it forces event names, joins, and exclusions into the open.

Weak vs strong definition side by side

Spec field	Weak (causes fights)	Strong (rebuildable)
Name	Active users	Weekly Active Accounts (WAA) v1.2
Owner	Data team	Product Ops (business) + Product Analytics (calc)
Grain	Weekly activity	Distinct paid account per ISO week (Mon through Sun, NY)
Formula	People who use the product	Distinct paid accounts with export, share, or API write
Filters	Ignore tests if possible	Exclude internal, test, sandbox, churned, staff impersonation
Time	Last 7 days-ish	ISO week; finalize T+2 for late events
Caveats	(none)	Pre-March mobile gap; API scripting risk; not revenue

How to introduce specs without bureaucracy theater

You do not need a metric council for every tile on a personal explore dashboard. Start where disagreement is expensive:

Anything on an exec scorecard
Anything tied to compensation or vendor bonuses
Anything used in public claims (customers, press, board)
Anything two teams already argued about twice

Store specs where work already happens: the wiki next to the dashboard, the dbt docs, the BI metric layer description, or a shared “metric catalog” page. Link the dashboard tile to the spec. If the tile cannot link, put the version number in the subtitle. Small friction, large clarity.

When definitions change, version them. Do not silently edit history. A change log line protects trust better than a perfect first draft.

Specs, quality, and charts are one system

A clean chart of a vague metric is still vague. An honest axis (from the viz series) cannot fix an unnamed population. A quality scorecard cannot decide whether pageviews count as active. The metric spec is the contract that lets quality engineers, analysts, and managers share a language.

Foundations still apply: if the objective is mush, the perfect WAA will not save you. Go back to Part 1’s chain. If you only look at lagging revenue, Part 2’s pairing still applies. Specs make either type of metric safer to run.

For paths across metrics, quality, Python, SQL, and charts, start from Learn. For the friendly “what is a KPI” prequel, stay with All About KPIs.

Common mistakes

Definition by demo. Someone clicks filters live and calls that the standard.
One owner for everything. Analytics cannot own process change; process owners cannot silently own SQL.
Grain left implied. Users vs accounts vs seats will ambush you.
Rate without denominator. “Conversion is up” from what base?
Hidden exclusions. If you drop a segment, write it down and say why.
No late-data policy. Monday’s partial week gets treated like a final verdict.
Silent redefinition to hit a target. That is fiction. Version and restate.
Forty-page specs nobody reads. One page that is used beats a binder that is not.
Specs only for lagging finance metrics. Leading metrics need definitions even more, because they are easier to game.

How to practice this week

Pick one metric that already causes questions in meetings.
Fill the one-page template without looking at the dashboard first. Use only what you can state from memory. The blanks are the risk map.
Ask a colleague to rebuild the number from your page alone. Note every question they ask. Those questions become fields you underwrote.
Add a version number and a review date. Put a link on the dashboard or in the slide footer.
List two caveats you have been saying out loud but never wrote down. Write them.
If implementation is wrong, fix the spec first, then the query. Do not “just patch SQL” without updating meaning.

Next in the series: North Star metrics versus team scorecards, when one number is too few and when a dozen is too many. You will reuse this spec format there so each scorecard line is still rebuildable.

Quick recap

Verbal metric definitions drift; written specs keep rebuildability.
One page is enough: why, owners, grain, formula, filters, time, targets, caveats, change log.
Split business ownership and analytics ownership.
Grain and filters prevent most “why don’t our numbers match?” fights.
Caveats and versioning protect trust when the world or the instrumentation changes.
Specs make quality work and chart work point at the same meaning.

Sources

What Matters, OKRs explained (measurable results need clear definitions): https://www.whatmatters.com/okrs-explained
Amplitude, leading vs lagging (context for which metrics need tight specs): https://amplitude.com/blog/leading-lagging-indicators
Analytics Made Simple, All About KPIs: https://analyticsmadesimple.com/analytics/all-about-kpis/
Analytics Made Simple, Data quality series: https://analyticsmadesimple.com/series/data-quality/
Analytics Made Simple, Charts that make sense: https://analyticsmadesimple.com/series/data-viz/
Analytics Made Simple, Python for analytics: https://analyticsmadesimple.com/series/python/
Analytics Made Simple, Analytics foundations: https://analyticsmadesimple.com/series/analytics-foundations/
Analytics Made Simple, Learn hub: https://analyticsmadesimple.com/learn/