E.g. lines with your own answers.
Fill in Setup first, then choose your north star, tier 1 and tier 2 metrics on the KPI definitions page, ideally with the people who tend to argue about numbers in the same room. Source of truth, ownership and attribution come next. Metric formulas can be added gradually, starting with your north star and tier 1 metrics. Expect to update the dictionary as questions come up, and review it on a schedule rather than only when something breaks.
1
Settle what you measure
Fill in Setup, then your north star, tier 1 and tier 2 metrics in KPI definitions. This is the part worth doing live, with whoever ends up arguing about numbers later, rather than as individual homework.
2
Settle how you measure it
Source of truth, ownership and attribution. These sections are what keep two people from getting two different answers to the same question.
3
Write the formulas
One block per metric, starting with the north star and tier 1. The worked example with real numbers is where a broken definition reveals itself, so don’t skip it.
4
Register where things live
Link your flat file, dashboards, and reports so this page becomes the one place anyone can find any of them.
5
Keep it current
Log decisions and changes as they happen, and review the whole dictionary on a set schedule.
Setup
The basics that identify this dictionary and who’s accountable for it:
What this business gets paid for, in one sentence:
E.g. Doughnut Labs sells a direct-to-consumer subscription box of small-batch doughnut kits.
Concept review: Setup
Concept review: Setup
These fields exist so anyone opening the dictionary can place it in seconds: whose numbers these are, what kind of business they run, and when the definitions are next checked. The one-sentence business description matters more than it looks. A metric like “conversion” or “customer” means something different for a business selling one-time purchases than one selling subscriptions, and writing the model down up front keeps that distinction visible everywhere else in the document.
KPI tiers
Every metric in this dictionary carries one KPI tier. You choose the north star, tier 1 and tier 2 metrics on the KPI definitions page. Everything else is Tracked.Concept review: KPI tiers
Concept review: KPI tiers
A KPI is a metric that changes what you do. If it moved 20% and nobody would act differently, it’s Tracked, not a KPI. The tiers exist so a report can explain, not just state: when a tier 1 outcome moves, tier 2 says why, and Tracked metrics say why a driver moved. See reporting framework concepts for how to choose the north star and each tier.
Attribution
The rule for deciding which touch gets credit for a result. Attribution windows differ by browser and by platform, so no single window holds everywhere. Handle attribution case by case, label where each number comes from, and test.
Where your numbers are known to be wrong:
How you test it:
Log each test result in Decisions and changes.
Concept review: Attribution
Concept review: Attribution
Add up what every ad platform reports and the total will exceed actual orders, because each platform claims every conversion it touched under its own window. This is normal, not a tracking bug, and it’s why platform numbers can’t be summed.Windows also shift with things you don’t control: browser privacy rules, cookie limits and each platform’s own defaults. A window written into the dictionary would be wrong for some of your traffic on the day you wrote it. Labeling the source of each number, keeping a blended check alongside, and testing with holdouts is what keeps the reading honest. See reporting framework concepts for more.
Source of truth
One approved system per metric. When two systems disagree, the approved one wins.
Name the exact field, not just the system. “Revenue from the ecommerce platform” is ambiguous; gross sales, net sales, and total sales are three different numbers in the same admin panel.
Expected discrepancies
Systems will disagree. Recording the normal gap turns a change in that gap into a signal instead of a monthly crisis.Data lag
Concept review: Source of truth
Concept review: Source of truth
When two systems produce different numbers for the same metric, the useful question is “which one is approved,” not “which one seems more trustworthy right now.” Naming the source ahead of time turns that moment from a debate into a lookup.The most common mistake is treating an analytics platform as the source for revenue. Analytics tools miss sales lost to ad blockers or consent rejection and don’t know about refunds after the fact; revenue belongs to whichever system actually took the money. See reporting framework concepts for how to assign a source by which system owns the underlying event, and how a metric that spans several systems, like contribution margin, needs a join rule recorded alongside its source.
Ownership
No role can be blank. One person can hold several roles.Concept review: Ownership
Concept review: Ownership
Every metric needs one name attached, not a team. A metric with shared ownership tends to drift silently, since someone adjusts a filter, someone else changes a date range, and eventually two views of the same number disagree with no record of why. One owner doesn’t mean one person does all the work; it means there’s one person to ask when the definition needs a decision.A definition should only change when its owner approves the change, and the change gets logged with an effective date below in What changed and when, so old reports don’t quietly stop matching new ones. See reporting framework concepts for what breaks when a definition changes silently instead.
Metric formulas
One block per metric. Copy the block as many times as you need. Start with your north star and tier 1 metrics; you don’t need every metric defined before you start reporting. Targets and floors live in KPI definitions.Concept review: Metric formulas
Concept review: Metric formulas
The worked example is the part most templates skip and the part that matters most. Calculate it with real numbers before adopting a metric; if the answer doesn’t roughly match what people already expect, the definition has a problem, and it’s far cheaper to find that now than in a meeting where two people are holding different numbers.This block is also where the ambiguity in a metric name actually gets resolved. “Revenue” sounds like one number until you write down whether it includes tax, whether a refund gets deducted the day it happens or the day the original order shipped, and which time zone a date belongs to. None of those calls has a universally right answer; what matters is making the call once and writing it down, so it doesn’t get made differently by whoever happens to be pulling the number that week.
Where everything lives
Update this whenever you build something.The flat file
Metric names in the flat file must match the metric formulas above. Channel and source names must match Source of truth. See the flat file template for the schema.
The budget plan
The budget tables in the weekly and monthly reports read their targets and totals from this plan. How the plan gets set is covered in budget planning.
Dashboards
Reports
Leave a row’s fields blank for a cadence you don’t yet produce. Most brands start with a dashboard plus a monthly report and add weekly once spend justifies it.
Report library
Every sent report gets logged, by cadence, in the weekly, monthly, quarterly, and annual report archives.Concept review: Where everything lives
Concept review: Where everything lives
A dictionary that only defines metrics, without saying where the flat file, dashboards, and reports actually live, leaves a reader with the definitions but not the destination. This section is what turns the dictionary into the front door for the whole reporting system: anyone with a question about a number can start here and reach the actual file, dashboard, or report without asking around for a link.Metric and channel names have to match exactly between this section, the formulas above, and the flat file itself. A metric that’s spelled one way in the dictionary and another way in the flat file is the same ambiguity the dictionary exists to prevent, just moved one level down.
Decisions and changes
Why we decided what we decided
One entry per significant choice. The “rejected because” field is what stops the same debate from reopening every few months.What changed and when
Anything that could change how a number should be read. Log it the day it happens, not at report time.
Log campaign launches, promotions, price changes, site deploys, outages, stockouts, tracking changes, definition changes, and competitor moves. Skip routine bid adjustments and normal creative rotation; log what would actually break a comparison, not everyday tuning.
Open questions
Anything unresolved. Each needs a name and a date, or it becomes permanent.Concept review: Decisions and changes
Concept review: Decisions and changes
The decision log exists because the same debate tends to resurface every few months if the reasoning behind a choice isn’t written down anywhere. Recording what was considered and why it was rejected is what lets a future conversation start from “we already looked at that” instead of relitigating it from zero.The change log answers a different, more immediate question: why did this number move on that date. Without it, an unusual spike or dip in a report becomes a small investigation every time, even when the cause was a known promotion or a tracking change logged weeks earlier and simply forgotten.
Sign-off
Everyone agrees these are the numbers, calculated this way, from these systems, until the decisions and changes section says otherwise.Related resources
- KPI definitions Your north star, tier 1 and tier 2 metrics, with targets and floors.
- Reporting framework concepts The reasoning behind every section on this page.
- Flat file template Where the raw numbers this dictionary defines actually get stored.
- Ecommerce metrics starter pack and Sales-led metrics starter pack Pre-researched metric definitions if you’d rather start from a reference than a blank page.
- Weekly, monthly, quarterly, and annual report templates The reports this dictionary’s definitions feed.
MCP wiring
MCP wiring
Type: brief
Domains: reporting, tracking
Provides:
Uses:
Domains: reporting, tracking
Provides:
data-dictionaryUses:
budget-plan, concept:reporting, flat-file, kpi-definitions, library:report, report-templateTriggers: “Help me set up a data dictionary” · “Define how we calculate our marketing metrics” · “Where should our reporting numbers come from?” · “Write a formula for contribution margin” · “Log a definition change”Asks, in order:- What’s the brand, and what does it get paid for in one sentence? Options: your answer. Skip when: brand context already on file.
- What business model is it? Options:
business-model. Skip when: customer-profile or brand file states it. - Have your north star and tier 1/2 metrics been chosen yet? Options:
kpi-definitions. Skip when: kpi-definitions filled. - Should platform-reported numbers appear in reports, and labeled how? Options: your answer.
- For each tier 1 metric, which system is the approved source and exact field? Options: your answer.
- Who owns each role: metric, data, weekly report, monthly report, decision? Options: your answer.
- How do you treat test orders, refunds, cancellations, tax, shipping and discounts? Options: metric formulas.
- Where do the flat file, budget plan and dashboards live? Options: your answer. Skip when: not yet built.
Get the complete Marketing OS
Subscribe to Snow Doughnut, our free weekly newsletter, and get the Notion workspace where you do the work: tasks, a marketing calendar, name generators, briefs, and more.
Have us run it for you
We implement this system, use it to help you grow and scale, then hand it all off to you when you’re ready.