Write a metric contract that prevents dashboard arguments

A metric contract is a written, testable definition of a measure. It states which records qualify, what one contribution represents, how time and units are handled, and what the result does not mean. It reduces dashboard disagreement by making hidden assumptions visible.

The contract does not guarantee that everyone chooses the same business policy. It gives the team a precise rule to approve, implement and version when that policy changes.

Start with the decision and the measure

Suppose a manager asks for January “revenue.” Clarify whether the decision needs completed-order amount, recognized revenue, cash collection or another measure. These labels can require different sources and timing rules.

The original synthetic example uses completed-order amount. Each eligible order contributes its supplied amount once. This is deliberately narrower than an accounting revenue claim.

Name the metric accordingly. A clear name reduces the chance that another team interprets the same dashboard card as a different measure.

Write the essential fields

The machine-readable contract and source calculator implement this case. A real contract should also identify the accountable owner, approval process, refresh expectations and source-change procedure.

Attach examples that settle edge cases

A record exactly at January 1 midnight is eligible if completed. A record exactly at February 1 midnight is outside the period. An unmatched customer does not remove an otherwise eligible order. Two different orders with the same amount both contribute.

These examples are often more effective than adding abstract wording. They make it possible to test competing implementations against the same cases.

from calculator import contract,calculate

rules = contract()
result = calculate()
assert rules['metric_id']=='completed_order_amount'
assert result['period_start']=='2026-01-01T00:00:00'
assert result['period_end']=='2026-02-01T00:00:00'
assert result['timezone']=='Asia/Kolkata'
assert result['currency']=='INR' and result['unit']=='paise'
assert result['eligible_order_count']==8 and result['value']==104000
assert 'O1009' in result['evidence_order_ids']
print({'metric':result['metric_id'],'eligible_orders':8,
       'amount_paise':104000,'unmatched_order_included':True})

The expected total and eligible IDs provide a shared reference. A spreadsheet, SQL query and BI measure should agree under this same contract, even though their implementation syntax differs.

Separate policy disagreement from code failure

If one team intentionally excludes unmatched customers, it is using a different policy. Discuss whether that policy is suitable for its decision and give the measure a distinct definition or version.

If the agreed policy includes unmatched customers but the query uses an inner customer join, the implementation is wrong. The distinction matters: a code fix and a business-policy decision require different review.

Likewise, a 171,000-paise result caused by item-join fan-out violates the one-contribution-per-order rule. It is not an acceptable alternative interpretation of the same contract.

Version changes visibly

When the definition changes, record the effective date and whether historical values are restated. Do not silently overwrite a dashboard's meaning while preserving its old label.

Keep the previous definition available for explaining older reports. A report should identify which contract version it used, especially when users compare periods or export screenshots outside the dashboard.

Make the contract part of handover

Link the definition near the measure, include it in the project README and preserve it with generated report evidence. Treat a source-schema change as a reason to verify the contract's implementation, not merely to repair a broken column name.

Exercise: write a contract for refunded-order share. Specify whether the numerator counts orders or refund transactions and explain what the undated refund ledger prevents you from claiming.

NeuraPath's Data Analytics with Generative AI course connects business definitions with spreadsheet, SQL, BI and Python implementations. A metric contract gives those tools a common analytical meaning that can be checked rather than assumed.

Continue learning

This article is part of the Metrics, visualization and decision communication sequence. Use the neighbouring tasks when you need the prerequisite or the next application.

• Continue with Choose a chart from the comparison the reader needs.
• Then apply it in Avoid misleading axes in business reporting.