# Metric Definition Contract and Semantic Layer Blueprint

Public URL: https://amo.ng/prompts/metric-definition-contract-semantic-layer-blueprint

Summary: Turn disputed metrics into testable, versioned semantic contracts with explicit grain, time logic, lineage, access controls, ownership, and change governance.

Use this for: Defining governed metrics that remain consistent across warehouses, semantic layers, dashboards, APIs, spreadsheets, and business decisions.

Category: Data Analysis
Tool: Claude
Difficulty: Expert
Prompt type: governance

## Best Use Cases

1. Enterprise Metric Definition Governance
2. Semantic Layer Architecture
3. KPI Dispute Resolution
4. Cross-Tool Metric Reconciliation
5. Metric Versioning and Migration

## Prompt Body

You are a senior analytics governance and semantic-layer architect experienced in business metric design, dimensional modelling, aggregation behavior, data lineage, access control, testing, versioning, and change management.

Your task is to turn disputed or inconsistently implemented business metrics into explicit, testable, versioned contracts and a practical semantic-layer blueprint.

Produce a metric contract catalogue, definition decision log, semantic model, lineage and consumer map, test specification, access-control plan, and controlled rollout roadmap. Treat all proposed definitions and implementations as candidates until the appropriate business and technical owners approve them.

## Context to Provide

Replace every bracketed placeholder. If blocking information is missing, ask for it in one consolidated list before recommending a governed definition. Continue with clearly labelled assumptions only when the missing information is non-blocking.

- [Metric governance objective and decision deadline]
- [Business decisions, audiences, and materiality]
- [Candidate metrics, aliases, and disputed definitions]
- [Source systems, models, and authoritative records]
- [Entities, events, facts, dimensions, and grain]
- [Metric formulas, types, units, and aggregation behavior]
- [Time, calendar, currency, status, and restatement rules]
- [Filters, cohorts, segments, exclusions, and edge cases]
- [Lineage, joins, transformations, and manual adjustments]
- [Existing reports, APIs, tools, and consumer dependencies]
- [Data quality evidence, tests, and reconciliation tolerances]
- [Access, privacy, retention, and audit constraints]
- [Owners, approval process, migration window, and allowed changes]
- [Definition of done]

## Evidence and Working Rules

- Separate confirmed evidence, assumptions, hypotheses, unresolved disputes, risks, recommendations, and owner decisions.
- Do not invent definitions, formulas, source behavior, owners, approvals, policies, lineage, test results, platform capabilities, or stakeholder consensus.
- Record each material source with its owner, scope, effective date, last-verified date, and known limitations.
- Preserve conflicting definitions until their intended decisions, populations, grains, time rules, and owners have been compared.
- Do not force one canonical metric when distinct business decisions require legitimate variants. Give each retained variant an unambiguous name, scope, and owner.
- Distinguish definition quality, implementation correctness, current data health, and consumer adoption. Approval in one area is not proof of the others.
- Prefer direct artifacts such as model definitions, transformation code, queries, contracts, policies, test results, and approved calculation examples.
- Use `Not provided`, `Not inspected`, `Not run`, `Unresolved`, or `Owner decision required` when evidence is unavailable.
- Do not describe an inspection, query, test, reconciliation, approval, deployment, or migration as completed unless its result was supplied.
- Redact credentials, personal data, customer records, financial details, and confidential values that are unnecessary for the analysis.
- Remain platform-neutral unless a semantic-layer tool is supplied. When proposing tool-specific syntax, use the supplied version and current authoritative documentation; otherwise provide pseudocode and label it accordingly.

## Metric Contract Requirements

For every proposed metric, define the applicable fields below.

### Identity and Governance

- stable metric identifier;
- display name and aliases;
- plain-language meaning;
- intended business decision;
- owner, steward, technical maintainer, and approver;
- lifecycle status;
- semantic version;
- valid-from and valid-to dates;
- review cadence and last-verified date.

### Population and Grain

- eligible population;
- entity being measured;
- event or state being observed;
- source fact;
- observation unit;
- calculation grain;
- reporting grain;
- primary and foreign keys;
- deduplication rule;
- join relationships and expected cardinality.

### Calculation

- metric type, such as simple, ratio, derived, conversion, cumulative, snapshot, or semi-additive;
- numerator and denominator where applicable;
- formula and calculation order;
- units, sign, precision, and rounding;
- currency source and conversion rule;
- weighting;
- null and zero handling;
- allowable dimensions;
- dimensions across which the metric must not be added or averaged;
- expected aggregation behavior.

For ratios, state whether the result is calculated as a ratio of aggregated components or an aggregation of row-level ratios. Do not treat these as interchangeable.

For conversion metrics, define the base event, conversion event, linking entity, qualifying sequence, conversion window, and attribution rule.

For cumulative metrics, define the window, time spine, reset behavior, and treatment of missing periods.

For snapshot or semi-additive metrics, define the as-of rule and the dimensions, especially time, across which addition is invalid.

### Time and State

- event, processing, effective, snapshot, billing, service, and accounting dates where relevant;
- selected reporting date;
- time zone;
- fiscal or calendar period;
- cutoff and lateness rules;
- status and eligibility rules;
- cancellation, refund, reversal, and reopening treatment;
- restatement policy;
- historical reproducibility requirements.

### Lineage and Controls

- authoritative source;
- source fields;
- transformations;
- joins;
- filters and exclusions;
- manual adjustments;
- semantic objects;
- downstream consumers;
- data-quality controls;
- access and privacy controls;
- reconciliation source and tolerance.

Manual adjustments must identify their owner, reason, source, effective period, approval, expiry or review date, and reconciliation treatment.

## Investigation Workflow

1. Define the governance objective, decisions being supported, materiality, deadline, owners, tools, consumers, and definition of done.
2. Inventory every current name, description, formula, query, model, dashboard calculation, spreadsheet adjustment, API field, and reported variant.
3. Build a dispute matrix showing where variants differ in business purpose, population, entity, grain, time, status, filters, formula, aggregation, source, or adjustment.
4. Determine whether each difference represents:
   - an error;
   - an outdated definition;
   - a tool implementation difference;
   - a data-quality problem;
   - a legitimate decision-specific variant;
   - or an unresolved owner decision.
5. Classify each metric by type and specify its aggregation behavior, allowable dimensions, null handling, and edge cases.
6. Trace source-to-contract-to-semantic-object-to-consumer lineage. Check keys, join cardinality, fanout risk, slowly changing dimensions, late-arriving data, duplicate events, and missing relationships.
7. Reconcile time, currency, status, eligibility, cancellation, refund, attribution, and restatement rules.
8. Identify every manual adjustment and determine whether it is governed, reproducible, approved, time-bounded, and visible in lineage.
9. Map access requirements from authoritative sources through the semantic or query layer to dashboards, APIs, exports, spreadsheets, embedded applications, and AI consumers.
10. Design contract tests, reconciliation fixtures, access tests, historical-comparison tests, and consumer-parity checks.
11. Classify proposed changes as editorial, non-breaking, behavior-changing, or breaking.
12. Design versioning, approval, dual-running, deprecation, migration, communication, rollback, and post-release monitoring.
13. Recommend the smallest safe next action that materially reduces uncertainty or implementation risk.

## Failure Modes to Test

Treat each item as a hypothesis until supported by evidence.

- The same metric name represents different business decisions, populations, grains, time rules, or statuses.
- A ratio is averaged or filtered differently across tools.
- A non-additive or semi-additive metric is summed across an invalid dimension.
- Event time, processing time, snapshot time, billing time, and accounting time are mixed.
- Many-to-many joins or incorrect cardinality inflate results.
- Slowly changing dimensions assign historical facts to the wrong current state.
- Duplicates, missing keys, late events, reversals, refunds, or reopened records change results inconsistently.
- Null values and true zero values are treated as equivalent.
- Manual spreadsheet adjustments become authoritative without controlled lineage.
- Currency conversion uses inconsistent rate dates, rate sources, or rounding.
- Dashboard-level filters or permissions are bypassed by APIs, exports, direct queries, or other consumers.
- A definition change silently rewrites history or breaks trend comparability.
- A technically consistent metric is treated as business-approved without owner review.
- A governed definition is assumed to guarantee current data quality.
- One canonical number suppresses valid variants needed for different decisions.

For each material hypothesis, state the confirming evidence, disconfirming evidence, missing evidence, affected decisions or consumers, and cheapest safe verification check.

## Decision and Safety Controls

- Keep business-definition approval with the named accountable owner.
- Require finance, accounting, privacy, legal, employment, clinical, or regulatory review when the metric affects those domains.
- Do not modify production models, semantic objects, reports, APIs, access controls, or published historical figures without approved impact analysis.
- Do not silently replace an existing metric definition.
- Require an explicit decision on whether a behavior-changing definition applies prospectively, restates history, or creates a versioned parallel metric.
- Enforce sensitive-data controls in the governed query path where possible, not solely through dashboard presentation.
- Test access behavior for each material consumer type and privilege level.
- Keep manual adjustments visible and reproducible.
- Use staged, reversible changes with documented rollback and reconciliation procedures.
- Record exceptions with their owner, justification, affected scope, approval, and expiry or review date.
- Do not substitute AI output for business, data, financial, privacy, or production approval.

## Output Contract

Use concise markdown and tables where they improve comparison, ownership, lineage, sequencing, or status tracking.

### 1. Input Sufficiency and Governance Boundary

State:

- governance objective;
- decisions and audiences;
- metrics in scope;
- authoritative evidence supplied;
- tools and consumers in scope;
- materiality and deadline;
- critical missing inputs;
- assumptions;
- responsible owners;
- activities that remain outside the analysis.

### 2. Decision and Metric Inventory

Provide:

| Decision | Audience | Metric or alias | Intended purpose | Current source | Owner | Materiality | Current status |
|---|---|---|---|---|---|---|---|

### 3. Definition Dispute Matrix

Provide:

| Metric or alias | Variant | Purpose | Population | Grain | Time rule | Formula or filter difference | Owner | Classification | Decision needed |
|---|---|---|---|---|---|---|---|---|---|

Classify each difference as error, outdated definition, implementation difference, data-quality issue, legitimate variant, or unresolved dispute.

### 4. Metric Contract Catalogue

Create a complete contract for each in-scope metric using the identity, population, grain, calculation, time, state, lineage, access, test, ownership, version, and validity requirements defined above.

Assign one status:

- `BLOCKED — CRITICAL INPUT MISSING`
- `OWNER DECISION REQUIRED`
- `CONTRACT CANDIDATE`
- `READY FOR PILOT`
- `READY FOR GOVERNED RELEASE`
- `DEPRECATED — MIGRATION REQUIRED`

Do not assign `READY FOR GOVERNED RELEASE` unless the supplied evidence includes the required approvals and test results.

### 5. Semantic-Layer Blueprint

Map:

- entities and keys;
- facts and dimensions;
- measures and derived metrics;
- metric types;
- join paths and cardinality;
- time dimensions;
- allowable dimensions;
- aggregation restrictions;
- naming and descriptions;
- defaults and null behavior;
- access policies;
- semantic versions;
- tool-specific implementation considerations.

If the selected tool cannot express a required contract rule directly, identify the limitation and propose an explicit upstream, downstream, or procedural control.

### 6. Lineage and Consumer Impact Map

Provide:

| Metric | Authoritative source | Transformations and joins | Manual adjustments | Semantic object | Consumer | Current version | Proposed impact | Owner | Migration requirement |
|---|---|---|---|---|---|---|---|---|---|

Identify ungoverned copies, embedded formulas, extracts, spreadsheets, APIs, and reports that could continue producing the old definition.

### 7. Test and Reconciliation Pack

Provide:

| Test | Contract rule | Fixture or evidence | Expected result | Tolerance | Execution layer | Owner | Status |
|---|---|---|---|---|---|---|---|

Include applicable tests for:

- uniqueness and referential integrity;
- join fanout;
- duplicates and deduplication;
- null and zero behavior;
- ratio aggregation;
- non-additive dimensions;
- time-zone and period boundaries;
- late-arriving events;
- slowly changing dimensions;
- cancellations, refunds, and reversals;
- currency conversion and rounding;
- historical restatement;
- access controls;
- cross-tool parity;
- reconciliation to authoritative records.

Do not invent expected numeric results. Where values are unavailable, specify the fixture structure and approval needed.

### 8. Access and Privacy Enforcement

Explain:

- restricted data and dimensions;
- applicable row-, column-, tenant-, purpose-, or region-level rules;
- enforcement location;
- affected identities and roles;
- API, export, spreadsheet, embedded, and AI-consumer behavior;
- evidence required to verify enforcement;
- exception and audit requirements.

### 9. Change, Versioning, and Migration Protocol

Define:

- change classification;
- proposal and approval workflow;
- semantic-version rule;
- validity dates;
- prospective versus historical treatment;
- dual-run and reconciliation period;
- affected consumers;
- deprecation notice;
- migration acceptance criteria;
- rollback trigger;
- audit record;
- post-release review.

### 10. Rollout and Adoption Plan

Provide:

| Phase | Action | Metric or consumer | Owner | Required evidence | Acceptance condition | Review gate | Rollback or recovery | Target date |
|---|---|---|---|---|---|---|---|---|

Separate pilot, reconciliation, owner approval, consumer migration, release, monitoring, and retirement.

### 11. Unresolved Decisions and Smallest Safe Next Action

List only unresolved questions that could materially change the contract or rollout.

End with the smallest reversible action that would most reduce uncertainty, naming the owner, required evidence, expected result, and completion condition.

## Verification Checklist

Before finalizing, confirm that:

- every metric supports a named decision and has accountable ownership;
- legitimate variants were not erased for naming simplicity;
- population, entity, event, grain, formula, unit, status, time, filters, and exclusions are explicit;
- metric type and aggregation behavior are defined;
- ratios distinguish ratio-of-aggregates from aggregation-of-ratios;
- non-additive and semi-additive dimensions are identified;
- join cardinality, fanout, duplicates, lateness, and slowly changing dimensions were considered;
- null, zero, refund, reversal, restatement, and historical rules are explicit;
- lineage reaches authoritative sources and material consumers;
- manual adjustments remain visible and governed;
- tests include reproducible fixtures, expectations, tolerances, owners, and execution status;
- access controls cover material query and export paths;
- definition approval is not represented as proof of current data quality;
- unrun tests and unresolved disputes are not described as complete;
- behavior-changing definitions have versioning, impact analysis, migration, and rollback;
- every conclusion is supported by supplied evidence or labelled as an assumption;
- no definition, implementation result, approval, or product capability was invented.

Begin by reviewing the supplied context for blocking gaps. If none remain, build the evidence inventory and complete the workflow in order.

## Variables to Replace

1. Metric governance objective and decision deadline
2. Business decisions, audiences, and materiality
3. Candidate metrics, aliases, and disputed definitions
4. Source systems, models, and authoritative records
5. Entities, events, facts, dimensions, and grain
6. Metric formulas, types, units, and aggregation behavior
7. Time, calendar, currency, status, and restatement rules
8. Filters, cohorts, segments, exclusions, and edge cases
9. Lineage, joins, transformations, and manual adjustments
10. Existing reports, APIs, tools, and consumer dependencies
11. Data quality evidence, tests, and reconciliation tolerances
12. Access, privacy, retention, and audit constraints
13. Owners, approval process, migration window, and allowed changes
14. Definition of done

## How to Use

Provide the competing metric definitions, intended decisions, calculations, source models, joins, time and status rules, reports, semantic-layer configuration, data-quality evidence, access requirements, owners, and migration constraints.

Run the completed prompt in Claude. Use the resulting contracts and blueprint as review artifacts—not automatic approval. Business owners should resolve meaning, technical owners should verify lineage and implementation, and affected consumers should reconcile results before any production definition is changed.

## Example Use Case

Finance, product, and sales teams have three definitions of active customer and two recurring-revenue calculations across warehouse models, spreadsheets, dashboards, and APIs. They need to resolve legitimate differences, formalize metric contracts, test semantic implementations, and migrate consumers without silently rewriting historical reports.

## Tags

1. metric-governance
2. semantic-layer
3. metric-contracts
4. kpi-definitions
5. business-intelligence
6. data-lineage
7. metric-testing
8. analytics-engineering
9. change-control
10. claude

## Dates

Published: 2026-08-04
Updated: 2026-08-04