Marketing Metric Contracts: Make the Definition as Reliable as the Dashboard

Last updated: 13 October 2026.

“Activation rate is down” sounds precise until someone asks whether activation means creating a project, inviting a teammate or completing a purchase. The next disagreement is often about the denominator: signups, verified accounts, trials or accounts old enough to finish onboarding.

These are product and growth decisions before they are SQL decisions. A founder needs to know whether the reported change reflects customer behavior, a different population or a revised definition. A useful contract makes those differences inspectable.

Our AI-ready data work includes this layer because an assistant querying inconsistent metrics can produce a confident answer to the wrong question. A semantic model can distribute a definition; the business still needs to agree on the definition being distributed.

What belongs in a metric contract?

Start with the decision the metric supports. “Monitor onboarding” is too broad. “Decide which acquisition cohorts need onboarding investigation after they have had seven days to activate” provides a concrete purpose and boundary.

Record these elements:

• Name and stable identifier: distinguish the display label from the machine reference.
• Business question: the decision the number supports and what it should not be used to infer.
• Entity and grain: whether the metric counts people, accounts, orders, subscriptions or events.
• Numerator and denominator: including the qualifying conditions for both.
• Time rule: the relevant timestamp, time zone, interval boundaries and observation window.
• Inclusions and exclusions: test accounts, internal activity, duplicates, cancelled records and missing data.
• Dimensions: which breakdowns are supported and how each is assigned.
• Freshness and revision policy: when a result is provisional, when it is reviewed and how late changes are handled.
• Implementation and evidence: source models, canonical calculation and acceptance fixtures.
• Ownership and change control: who decides meaning, who maintains code and how consumers learn about changes.

Not every metric needs a long document. It needs enough precision that two competent people can produce the same result from the same input without negotiating missing assumptions.

How is this different from a database or dbt model contract?

A structural contract protects the shape of data. dbt model contracts can check column names and types and apply supported constraints; enforcement varies by platform and materialization. Those checks do not establish that a column called revenue uses the business definition the finance or growth team intended. dbt model contracts

For example, a numeric column can pass a type check whether it contains gross order value, net value after refunds or recognized revenue. The schema is stable while the meaning differs substantially.

Use structural guarantees alongside semantic guarantees. The first helps prevent a field from disappearing or changing type unexpectedly. The second specifies what the field represents and proves it against representative examples.

Keep the business agreement readable outside the data team. A product manager should be able to challenge the eligibility rule without interpreting a compiled query. An engineer should be able to trace every clause of that agreement into code or a test.

A worked contract for seven-day account activation

The following is an illustrative specification, not a universal definition of activation and not executable dbt configuration. It describes a hypothetical collaboration product whose first useful outcome is a production project completed by an account.

metric_id: account_activation_7d_v1
display_name: Seven-day account activation rate
decision: Compare onboarding outcomes for mature signup cohorts
entity: account
cohort_timestamp: account_created_at
time_basis: UTC
window:
  start: account_created_at inclusive
  end: account_created_at plus 168 hours exclusive
denominator:
  include: external accounts with a complete observation window
  exclude: internal accounts and accounts marked as test at creation
numerator:
  include: denominator accounts with a first production project completed in window
identity: stable account_id
dimensions:
  acquisition_channel: assigned at account creation
  signup_plan: assigned at account creation
missing_input: mark result unavailable and investigate
zero_denominator: null
aggregation: sum activated accounts divided by sum eligible accounts
business_owner: Product growth owner
technical_owner: Analytics engineering owner

Several decisions in that specification are easy to miss in a dashboard label. It counts accounts, not users. It uses a rolling 168-hour opportunity, not seven calendar dates. The end boundary is exclusive. It evaluates the plan at signup, not the current plan after an upgrade.

The test-account rule is deliberately fixed at creation for this example. Another organization might use a reviewed exclusion registry. Either approach needs a documented revision policy; otherwise a later account reclassification silently changes earlier cohorts.

Also define the data cutoff. If the report runs at 10:00 UTC but event ingestion is complete only through 08:00 UTC, use the complete-data boundary to assess maturity. Wall-clock time alone does not prove that the full observation window has arrived in the warehouse.

The data freshness SLA guide explains how to make that completeness requirement operational.

What should the acceptance examples prove?

Give the contract a small set of records with expected outcomes. For this illustrative definition:

• Account A is eligible and completes its first production project after 24 hours: included in both counts.
• Account B is eligible but completes its first project after 169 hours: denominator only.
• Account C is an internal account: excluded from both counts.
• Account D has existed for only 80 hours at the complete-data cutoff: excluded as immature.
• Account E completes two production projects inside the window: counted once in the numerator and once in the denominator.

Among these five records, three are eligible and two activate, giving a rate of two-thirds, approximately 66.67%. The fixtures should also include an event exactly at the 168-hour boundary, a missing account ID and duplicated event delivery.

These examples expose disagreements earlier than a production chart. If a stakeholder expects Account B to count, the issue is the chosen window, not a mysterious reporting discrepancy.

Use negative cases as seriously as positive ones. A metric that includes a successful example correctly can still overcount test traffic, repeat events or immature cohorts. Write the expected reason for exclusion, not just the final Boolean value.

Why does aggregation belong in the contract?

A rate is not generally additive, and an unweighted average of group rates can misrepresent the combined population.

Suppose a mature self-serve cohort has 90 eligible accounts and 54 activated accounts. Its activation rate is 60%. A sales-assisted cohort has ten eligible accounts and nine activated accounts, giving 90%.

The combined rate is:

(54 + 9) / (90 + 10) = 63 / 100 = 63%

The average of 60% and 90% is 75%, which is not the combined account activation rate. The groups have different sizes. Preserve the numerator and denominator so downstream tools can recompute the appropriate ratio.

dbt's metric definitions distinguish ratio metrics with numerator and denominator inputs from other metric types. The exact configuration depends on the version and specification in use; the business contract should remain understandable independently of that syntax. Creating metrics

Also decide whether groups overlap. If an account can belong to multiple segments, summing the segment denominators may double-count it. In that case, a total must be calculated from the underlying eligible population, not by adding overlapping chart rows.

For revenue metrics, specify whether totals are additive across time and dimensions. A monthly recurring revenue snapshot should not be summed across daily snapshots to produce monthly revenue. The SaaS MRR data model covers that distinction in more detail.

Which dimensions are safe to use?

A metric's meaning can change when the dimension changes scope. Google Analytics explicitly distinguishes first-user, session and event-scoped traffic-source dimensions. They answer different acquisition or attribution questions even when the visible channel label is the same. Traffic-source scopes

Your contract should therefore name the exact channel assignment used. “By source” is incomplete. “By the account's acquisition channel at signup” is a defined choice, assuming the assignment logic is also documented.

Record whether a dimension is current, historical or fixed at an earlier milestone. A current industry classification may be useful for account planning while an as-of-signup classification is necessary for a historical cohort comparison. Neither should quietly substitute for the other.

Joins introduce another risk. One account can have several contacts and several campaign touches. Joining those tables before aggregation can multiply the account's contribution. Looker's symmetric aggregates address certain fanout problems, but they depend on correctly defined primary keys and join relationships. Symmetric aggregates

List allowed join paths or provide a canonical model that already establishes the right grain. Then test the metric with and without relevant dimensions. The same underlying cohort should not gain eligible accounts merely because a contact attribute was added to the chart.

Where should the definition live?

Keep one authoritative record that links the business specification, implementation and validation evidence. That can begin as a versioned file beside the model. It does not need a large governance platform to become useful.

Semantic systems can make definitions reusable across consumers. In dbt, semantic models describe entities, dimensions and metric relationships used by MetricFlow. The current documentation distinguishes version-specific configuration, so check the installed runtime before copying an example into a project. Semantic models

The important operating rule is that dashboards, exports and assistants should refer to the same approved metric identifier and version. A spreadsheet can still be a valid consumer if it records the source and avoids silently rewriting the calculation.

Expose the minimum context beside the number: definition version, period, filters, completeness state and last successful data update. Put the full specification one click away. Readers need enough information to interpret the result without turning every chart into a technical manual.

For an AI assistant, include supported dimensions and known limitations in its metric context. If someone asks for a breakdown the model cannot represent safely, a useful answer explains that limitation rather than inventing a join.

How should you change a metric without destroying comparability?

Separate corrections from definition changes. Fixing an implementation that omitted valid records restores the agreed definition. Changing activation from a first project to a first shared project creates a different definition, even if the label stays similar.

For a proposed change, record the reason, expected affected population, effective date, historical treatment and consumer list. Decide whether to restate history, preserve the old series, or display both during a transition.

Run the old and new definitions on the same controlled period. Explain the difference through record sets. Which accounts entered or left the numerator? Did the denominator change? Did a time-zone or maturity rule move records between cohorts?

Open full diagram

The dbt backfill guide covers the execution side of a historical repair. The metric contract explains why the repair is being made and what users should expect afterward.

Do not silently redraw a historical chart under a new definition and describe the result as improved customer behavior. Report the definition change separately from the business trend. That distinction matters for budget allocation and product decisions.

How do you introduce contracts without slowing every analysis?

Start with the numbers that drive recurring decisions: activation, qualified pipeline, acquisition cost, retained revenue or a core conversion rate. Exploratory questions can remain exploratory, provided their outputs are labeled and do not quietly become production metrics.

For each priority metric, ask one business owner and one technical owner to resolve the ambiguous cases. Use actual disagreements from recent meetings as the starting material. A contract that prevents a repeated argument has immediate value.

Measure the process by fewer unexplained discrepancies and faster decisions, not by the number of specification fields completed. If the contract cannot help someone diagnose a wrong number or choose the right one, it needs clearer examples rather than more formal language.