Skip to main content

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:

FieldQuestion it answers
Metric grainWhat can contribute at most once?
PopulationWhich entities are eligible for the denominator?
WindowWhich event-time interval is measured?
TimezoneWhere do calendar boundaries fall?
ExclusionsWhich duplicates, invalid records, purposes, or consent states are removed?
Late-data policyWhen is the first result closed and when may it be restated?
Identity policyWhich snapshot and link rule resolve actors?
OwnerWho approves meaning and handles incidents?
Semantic versionWhich interpretation produced this value?
ExpressionHow 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.