Metric Registry

The Metric Registry is the discovery and reuse layer for governed definitions. It helps teams find the right metric before they create another one, inspect whether a definition is trustworthy, understand how metrics relate, and decide what will be affected when a definition changes.

Use this page for the public operating model. The product page explains the value proposition at a higher level: Metric Registry feature page.

The registry is part of the context layer. A warehouse can show tables and SQL. A semantic layer can expose runtime measures. The registry shows the business context around the metric: what it means, who owns it, which lifecycle state it is in, whether it has validation evidence, how it relates to other definitions, and which version downstream consumers should treat as current.

What the registry is for

Use the registry before authoring, reviewing, changing, or consuming a metric.

Before authoring, search for existing metrics with the same concept, owner, domain, or name. If a useful metric already exists, reuse it. If the existing definition is close but not exact, create a managed variant with an explicit relationship instead of creating a hidden duplicate.

Before review, inspect ownership, lifecycle state, policy tier, validation recency, relationships, and version history. Reviewers should be able to answer whether the metric is draft, validated, a release candidate, approved, released, deprecated, carrying an open objection, or still missing evidence.

Before changing a metric, use relationship and impact context to understand who and what may depend on it. A small logic change can affect derived metrics, domain variants, replacement chains, dashboards, AI agents, or operating reviews.

Before API consumption, confirm that the metric selected by search is the correct governed definition. Name matches are not enough. Lifecycle state, owner, version, validation evidence, and disambiguation context should shape which metric a downstream system uses.

Search and filters

Registry search and filters should expose practical discovery context: name, description, concept, owner, lifecycle state, governance tier, validation recency, version context, metric type, template source, and scope. The goal is not just to find text. The goal is to find the definition that is safe for a specific decision.

Search terms often begin broad. A user may search for "revenue," "churn," "pipeline," or "activation." Useful results should expose enough context at scan speed that the user can distinguish the enterprise-canonical definition from a domain-specific variant, an exploratory draft, or a deprecated metric that remains visible for history.

The registry should also make it natural to move from search result to detail view. The detail view is where the user can inspect the full definition, SQL or expression context, validation evidence, governance history, reasoning trail, relationships, version history, and API-facing contract context.

Trust signals

Trust signals make reuse safer. Useful registry entries expose:

• Owner or owning team.
• Lifecycle state, such as draft, validated, released, approved, or deprecated.
• Policy tier or governance class.
• Validation status and recency.
• Definition version or current released version.
• Template source when a template shaped the metric.
• Metric type, including base or derived.
• Relationship badges for variants, replacements, conflicts, related metrics, and derived inputs.
• Reasoning Trail availability and pinned context where appropriate.

These signals are operational, not decorative. A metric that is released, recently validated, owned by Finance, and marked enterprise-canonical should be treated differently from a draft with no owner and stale validation. AI agents and BI workflows should respect those differences instead of treating every matching metric name as interchangeable.

Duplicate and overlap detection

Overlap detection helps prevent metric sprawl across base metrics, derived metrics, and managed variants. When someone searches the registry or authors a new metric in Metric Studio, ClariLayer can surface possible duplicates, related definitions, and conflicting concepts.

Early overlap detection can use exact name matching and scored name or description matching. Concept, template source, owner context, relationships, and SQL or expression context can help reviewers interpret a match when those signals are available. The public expectation is simple: the workflow should help users notice that "Net Revenue," "Recognized Revenue," and "Finance Revenue" might be related before another disconnected metric is created.

When overlap is detected, the user should decide what the relationship means. The right answer may be to reuse the existing metric, replace an older metric, create a managed variant, mark a conflict, or document that the metrics are related but intentionally separate.

Managed variants

Managed variants are how ClariLayer handles legitimate differences without pretending every disagreement is a defect. Finance, Sales, Product, and Customer Success may need related metrics with different inclusion rules, time windows, or consumer contexts.

A managed variant should make the difference explicit. It should have its own owner, lifecycle state, validation evidence, version history, and reasoning. It should also point back to the metric it varies from so humans and AI agents can see that the definitions are connected.

Use managed variants when the difference is intentional, durable, and tied to a real consumer need. Do not use a variant to hide an unresolved argument, a one-off spreadsheet adjustment, or a temporary data-quality issue. Those should remain comments, caveats, or draft work until the organization decides how to govern them.

Relationships

Metric relationships describe how definitions connect. The registry and detail view can use these relationships to support discovery, overlap review, impact analysis, and composition.

variant_of

The source metric is an approved or intentional variant of another metric.

derived_from

The source metric depends on another metric as an input to a derived metric expression.

replaces

The source metric supersedes an older definition.

conflicts_with

The definitions should not be treated as interchangeable, and the disagreement matters.

related_to

The metrics are connected, but the relationship is informational rather than a stronger governance claim.

Relationships should stay org-scoped and explicit. They are part of the context layer because they explain not only what a metric is, but how it should be interpreted relative to other definitions.

Impact analysis

Impact analysis answers the question: what might be affected if this metric changes?

For public docs, think of impact analysis as relationship-aware review. It can follow downstream dependencies across relationships such as derived_from, variant_of, and replaces, then show the affected metrics so reviewers can decide whether the change is safe. A depth-limited, cycle-safe traversal prevents a relationship graph from becoming an unbounded review.

Impact analysis is especially important before changing a released metric. If an approved Revenue metric feeds Gross Margin, Net Revenue, LTV, quota attainment, and an AI agent contract, the reviewer needs to see that blast radius before approving a new version.

Derived metrics and composition

Derived metrics are metrics computed from other metrics rather than directly from raw warehouse logic. For example, Gross Margin can be expressed from Revenue and Cost. In ClariLayer's composition model, a derived metric stores an arithmetic expression tree and a deduplicated list of metric dependencies.

When a derived metric is created or its expression changes, derived_from relationships are managed automatically for the referenced input metrics. The system also prevents dependency cycles so a metric cannot depend on itself through a chain of derived definitions.

In the registry, derived metric context should help users answer three questions:

• Which input metrics does this metric depend on?
• Which downstream metrics depend on this metric?
• Would changing an input definition change the interpretation of this metric?

That composition context turns derived metrics from hidden formulas into governed assets with visible dependencies.

Version history

Version history preserves the change record for a metric definition. A useful registry detail view should show what version is current, which older versions exist, when changes happened, who owned or approved them, and why the definition moved from one version to the next.

Version history matters because metric meaning changes should not be silent. If the customer exclusion logic changes, the next version should carry its own definition, validation evidence, governance history, and reasoning. Downstream consumers can then decide whether they need the current version, a historical version, or a migration note.

How registry reuse fits the lifecycle

The registry is not the end of the workflow. It is the place where governed context becomes searchable and reusable.

1. Use Metric Studio to author or import metric definitions.
2. Use the registry to find related definitions, avoid duplicates, and choose whether to reuse, replace, or create a managed variant.
3. Use validation and governance evidence to decide whether the metric is ready for release or downstream use.
4. Use the API v1 docs, metrics list/detail reference, and metrics contract endpoint when a BI tool, AI agent, or internal service needs read-only access to the governed context.

Good registry hygiene keeps the context layer useful. Metrics should be findable, owned, versioned, related, and honest about their lifecycle state.