Semantic Layer contracts for trustworthy metrics

Define business terms once and execute them consistently across BI, APIs and agents.

Why it matters

Without semantic contracts, every team computes the same metric differently. The cost is silent KPI drift and cross-team mistrust.

A semantic layer defines business terms — entities, dimensions, measures — once, so every consumer (BI, APIs, agents) computes them identically. Without it, three teams write three definitions of 'active customer' and the numbers silently diverge.

{
  "measures": {
    "gross_revenue": {"expr": "sum(order_amount)", "default_filters": ["status != 'cancelled'"]},
    "active_customers_30d": {"expr": "count_distinct(customer_id)", "window": "30d"}
  },
  "contracts": {"refund_rate": {"numerator": "refunded_orders", "denominator": "completed_orders", "owner": "revops"}}
}

Grain and default filters are where drift hides. 'Revenue' means nothing until you fix the grain (per order? per line item?) and the implicit filters (does it exclude cancelled orders?). Encoding these once in the contract is what makes a metric the same number everywhere it's consumed.

Each metric needs an owner. A contract with owner: revops means there's a single accountable party for what 'refund_rate' means — so when an agent and a dashboard disagree, there's an authority to resolve it instead of an argument.

Why agents need this. An LLM agent asked 'what's our refund rate?' must compute the governed metric, not invent a plausible SQL. The semantic layer gives the agent a trustworthy, consistent definition to call — turning 'sounds right' into 'is the official number'.

A semantic layer is the single source-of-truth recipe card in a restaurant chain. Every branch makes the 'house sauce' identically because the recipe (grain, filters, owner) is defined once — not reinvented by each cook, which is how a brand ends up tasting different in every city.

• Metric defined per team. Symptom: diverging KPIs. Fix: define once in the semantic layer.
• Unspecified grain. Symptom: same metric, different numbers. Fix: pin grain + default filters.
• No owner. Symptom: unresolvable disputes. Fix: an owner per contract.
• Agents writing ad-hoc SQL. Symptom: plausible-but-wrong metrics. Fix: agents call governed measures.