Metric Definitions and Semantic Contracts
A metric name is not a definition. “Activation rate” can vary by denominator, identity rule, success event, conversion window, timezone, and data cutoff. A semantic contract makes those choices reviewable and keeps dashboards, notebooks, and alerts from implementing different metrics under one label.
Prerequisites
Complete event taxonomies and tracking plans. Know how a ratio's numerator and denominator relate.
Learning goals
- Write all required fields of a worked metric contract.
- Distinguish event time, observation window, and reporting cutoff.
- Apply a deterministic duplicate and late-data policy.
- Version meaning changes separately from ordinary data restatement.
The complete contract
Every worked metric in metric-contracts-v1.json declares:
| Field | Question it answers |
|---|---|
| Metric grain | What can contribute at most once? |
| Population | Which entities are eligible for the denominator? |
| Window | Which event-time interval is measured? |
| Timezone | Where do calendar boundaries fall? |
| Exclusions | Which duplicates, invalid records, purposes, or consent states are removed? |
| Late-data policy | When is the first result closed and when may it be restated? |
| Identity policy | Which snapshot and link rule resolve actors? |
| Owner | Who approves meaning and handles incidents? |
| Semantic version | Which interpretation produced this value? |
| Expression | How do validated inputs become the result? |
For verified_activation_rate version 1.0.0, the grain is resolved actor by signup attempt. The population is actors with a valid consented signup_started event during 1 October UTC. The numerator is eligible actors with account_created. Duplicate IDs, malformed records, denied analytics collection, and non-measurement purposes are excluded.
The event-time window remains 1 October even when a record arrives later. The first reporting close is 3 October 00:00 UTC; a declared restatement admits events received through 4 October 00:00 UTC. Restating late data under the same definition is not a semantic-version change. Changing the denominator, success trigger, timezone, or identity rule changes meaning and should produce a new metric version with an impact note.
Worked example
import json
from datetime import datetime
from pathlib import Path
root = Path("tests/fixtures/product-analytics")
bundle = json.loads((root / "metric-contracts-v1.json").read_text())
events = [json.loads(line) for line in (root / "events-v1.jsonl").read_text().splitlines()]
events = list({row["event_id"]: row for row in reversed(events)}.values())
identity = json.loads((root / "tracking-plan-v1.json").read_text())["identity_snapshot"]["links"]
parse = lambda value: datetime.fromisoformat(value.replace("Z", "+00:00"))
actor = lambda row: row["user_id"] or identity.get(row["anonymous_id"], row["anonymous_id"])
def count(name, close):
return {actor(row) for row in events if row["event_name"] == name
and row["analytics_consent"] and row["purpose"] == "product_measurement"
and parse(row["received_at"]) <= parse(close)}
starters = count("signup_started", "2026-10-03T00:00:00Z")
first = count("account_created", "2026-10-03T00:00:00Z")
restated = count("account_created", "2026-10-04T00:00:00Z")
print(f"metric=verified_activation_rate version={bundle['semantic_version']} timezone={bundle['metrics'][1]['timezone']}")
print(f"on_time={len(first)}/{len(starters)} rate={len(first)/len(starters):.3f} restated={len(restated)}/{len(starters)} rate={len(restated)/len(starters):.3f}")
Expected output:
metric=verified_activation_rate version=1.0.0 timezone=UTC
on_time=1/2 rate=0.500 restated=2/2 rate=1.000
The large change is caused by one known late event in a tiny fixture. It demonstrates why a result needs a cutoff and revision label; it does not estimate a real activation rate.
Limitations and common mistakes
- A SQL expression without prose leaves eligibility and meaning implicit.
- Mixing local calendar days and UTC shifts events between windows.
- Silently accepting late data makes past reports irreproducible; never accepting it leaves known omissions uncorrected.
- A metric owner is accountable for semantics and incidents, not empowered to ignore privacy review.
- Semantic versioning documents compatibility; it does not prove that a metric is useful or valid.
Practice
Change the activation denominator from actors to signup attempts. Identify which contract fields and semantic-version component should change, and explain how repeated attempts affect interpretation.
Next steps
Place contracted metrics into a decision system in North Star, input, and guardrail metrics.
Primary sources
Checked 2026-10-19: dbt Labs, dbt Semantic Layer and Semantic models; Preston-Werner, Semantic Versioning 2.0.0; OpenTelemetry, event timestamps.