Metric catalog: Implementation and data quality
Specifies storage, interfaces, validation, access, freshness, monitoring, and failure behavior for metric catalog, so adopters can make every business measure a versioned, reviewable contract instead of an unexplained identifier or formula hidden in code.
Package status: reference context ready for human review. The contract and test scenarios are complete, but no claim is made that an adopting implementation has passed them.
Decision
For Metric catalog, implement the semantic contract through owned, typed boundaries so adopters can make every business measure a versioned, reviewable contract instead of an unexplained identifier or formula hidden in code. The catalog defines metric meaning and allowed analytical use; it does not grant data access or execute a query. This is a reference contract: database products, numeric budgets, jurisdictions, retention, organizational defaults, and accountable owners remain explicit adoption choices.
Scope
- The Metric catalog actors, inputs, outputs, states, versions, and externally visible outcomes needed to make every business measure a versioned, reviewable contract instead of an unexplained identifier or formula hidden in code.
- The role-specific focus of this block: implement the semantic contract through owned, typed boundaries, including primary, cached, asynchronous, export, support, and recovery paths where applicable.
- Adoption-specific configuration, ownership, rollout, evidence retention, and review responsibilities needed to use the contract safely.
Outside this block
- The catalog defines metric meaning and allowed analytical use; it does not grant data access or execute a query.
- Choosing a universal database, model, renderer, vendor, numeric threshold, retention period, timezone, jurisdiction, or service-level objective.
- Claiming that packaged scenarios ran against a downstream implementation or that this reference grants security, privacy, accessibility, analytical, or legal approval.
Contract
- The implemented Metric catalog boundary enforces this rule: A metric entry has a stable machine ID, a separately editable display name, a plain-language description, and a version that changes when meaning changes.
- The implemented Metric catalog boundary enforces this rule: The definition states the business question, intended decision, unit, favorable direction, and whether zero, null, negative, or partial values have special meaning.
- The implemented Metric catalog boundary enforces this rule: Formula metadata names numerator, denominator, aggregation, population, exclusions, event time, timezone, window, and late-data treatment without requiring a reader to inspect SQL.
- The implemented Metric catalog boundary enforces this rule: Allowed dimensions, filters, grains, comparison modes, and minimum safe populations are explicit; unsupported combinations are rejected rather than approximated silently.
- The implemented Metric catalog boundary enforces this rule: Every entry identifies semantic owner, technical owner, source lineage, freshness target, access classification, lifecycle status, and replacement when deprecated.
- The implemented Metric catalog boundary enforces this rule: Aliases and localized labels may improve discovery but always resolve to one canonical metric version before execution.
- The implemented Metric catalog boundary enforces this rule: Metric changes preserve prior versions long enough to reproduce historical dashboards and disclose discontinuities across a comparison period.
- The implemented Metric catalog boundary enforces this rule: The registry API returns descriptions and caveats with the identifier so a user is never left alone with an abbreviation or internal code name.
Implementation guidance
- Store the versioned semantic object separately from database-specific compiled artifacts and presentation-specific documents.
- Validate at ingestion, registry, query, result, and rendering boundaries and keep one normalized representation through downstream steps.
- Roll out additively, compare old and new evidence over frozen fixtures, and keep a reversible migration until consumers adopt the new version.
- Instrument success, rejection, staleness, partial results, version conflicts, and repair without recording sensitive payloads.
Failure handling and safeguards
- For Metric catalog, An unknown, ambiguous, deprecated-without-replacement, or unauthorized metric is rejected with safe alternatives and no query execution.
- For Metric catalog, A missing owner, formula component, time rule, access class, or freshness contract prevents the entry from becoming selectable.
- For Metric catalog, If two catalog versions disagree during rollout, the response pins one version and labels the conflict instead of combining results.
Verification and operations
- For the implementation evidence of Metric catalog, recompute representative metrics from frozen fixtures and compare values, labels, units, and exclusions with the registered definition.
- For the implementation evidence of Metric catalog, ask non-specialist reviewers to explain the metric from its description and record misunderstood terms as catalog defects.
- For the implementation evidence of Metric catalog, diff catalog versions and prove that changed semantics create a new version and a visible dashboard discontinuity warning.
Adoption assumptions
- The adopting product has authenticated identity, a versioned authorization policy, owned metric definitions, bounded telemetry, and a controlled path for change.
- Names and values in the example are fictional adoption fixtures, not universal defaults, production credentials, performance promises, or business targets.
- Referenced specifications constrain protocol, security, accessibility, or vendor behavior; the adopting team must confirm current applicability before promotion.
The executable-looking examples in this package are fixtures and acceptance contracts. Run the collection validator to check structure and metadata, then translate and execute the scenarios in the target repository before recording implementation evidence.