Why does a metric contract include `parallel_versions: true`?

So a major-version definition change can ship while the previous version keeps serving existing consumers during a deprecation window — exactly like a REST API

To run two warehouses in parallel

So a major-version definition change can ship while the previous version keeps serving existing consumers during a deprecation window — exactly like a REST API

Metric Contracts, Versioning & Lineage — Semantic Web Academy

Overview

Metrics deserve API discipline

Once a metric has more than two consumers, it stops being a convenience and becomes an API. Every API discipline applies:

Versioning (semver) — revenue@2.1.0. Bug fixes bump patch, additive dimensions bump minor, definition changes bump major and keep @1 running for a deprecation window.
Ownership — every metric has a single human-team owner (finance@example.com). Alerts route there, review-requests block on them.
Freshness SLA — metric: revenue, slo: 24h freshness. Monitored as a first-class signal next to uptime.
Lineage — every metric carries a back-pointer to the semantic models, dbt models and source tables it depends on. OpenLineage events let you trace a board number back to a Fivetran sync.

The metric_contract.yaml shape

metric: revenue
version: 2.1.0
owner: finance@example.com
description: Net revenue in USD; refunds & VAT excluded.
slo:
  freshness: 24h
  pct_query_under_500ms: 95
supported_grains: [day, week, month, quarter, year]
supported_dimensions: [country, plan_tier, channel]
deprecation_policy:
  major_change_notice: 60d
  parallel_versions: true

Cross-link: see data-management-governance Level 4 for full data-contract patterns; this lesson is the metric-specific specialisation.

Metrics are APIs

A metric contract is a published REST API spec. Clients integrate against /v1/orders knowing the team has committed to a deprecation policy. Without the spec, every silent change breaks downstream integrations. Without a metric contract, every silent SQL refactor breaks executive dashboards — and worse, the breakage is invisible: the dashboard still renders, just with a wrong number.

Reflect

The single highest-leverage governance move when rolling out a semantic layer: add an owner: field to every metric on day one. Even before contracts, even before versioning, ownership routes problems to a human and ends the 'whose number is wrong?' tug-of-war.

›If a top-line metric in your stack returns a wrong number tomorrow, who is the named human owner — and is that name in code, or in someone's memory?
›What's the most expensive metric change your company shipped in the last year that *should* have been a major-version bump?

Reading in progress · 0 of 1 activity done