Defines a dashboard as a versioned measurement product with named decisions, metric grain, dimensions, filters, comparison rules, freshness, quality tests, access controls, and traceable drill-down.
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
Start from decisions the dashboard supports, then define each metric from governed data at one explicit grain. Display time zone, coverage, freshness, filters, comparison period, and quality state on the dashboard itself.
Scope
- Audience, decisions, metric definitions, grain, dimensions, filters, time, comparisons, targets, drill-down, freshness, quality, access, and ownership.
- Operational or product dashboards backed by governed analytical models.
- Implementation and acceptance evidence.
Outside this block
- Using a chart collection as a substitute for a decision question.
- Combining differently defined metrics because their labels look similar.
Contract
- Every dashboard names audience, decisions, owner, data owner, refresh objective, and last successful refresh.
- Each metric specifies numerator, denominator, inclusion/exclusion, unit, grain, aggregation, time field, timezone, and version.
- Dimensions define null/unknown behavior and whether filters change numerator, denominator, or cohort.
- Comparisons use complete equivalent periods unless explicitly labeled partial.
- Tiles expose quality/freshness state and never display stale data as current without warning.
- Drill-down preserves access control and filter context and reconciles to the aggregate within documented latency.
Implementation guidance
- Build semantic models and tests before visualization-specific calculations.
- Use a calendar table for period logic and label user, event, account, and transaction grains clearly.
- Keep dashboard configuration and metric definitions version-controlled.
- Provide a plain-language annotation for material definition or source changes.
Failure handling and safeguards
- If a critical quality test fails, hide or mark affected metrics rather than publishing plausible numbers.
- If refresh is late, retain the last valid data with its timestamp and visible warning.
- If a user lacks row access, filters, counts, exports, and drill-down all apply the same policy.
Verification and operations
- Measure refresh duration/failure, source lag, quality-test result, reconciliation delta, query latency, usage by decision path, and broken drill links.
- Test filter combinations, timezone boundaries, partial periods, empty cohorts, and row-level access.
- Review unused or unactionable tiles with dashboard owners.
The executable-looking examples in this package are fixtures and acceptance contracts. Run
python tools/validate.py from the collection root to check package structure and metadata; then
implement and execute the scenarios in the target repository.
Adoption assumptions
- Names and numeric values in
example.yamlare an adoption profile, not universal defaults. - The adopting team must map actors, data classes, error vocabulary, and ownership to its system.
References
- No external normative source is required; this package defines a project decision.