[dashboard-language-spec] Dashboard Language Specification: define deterministic custom-view empty and unavailable rendering states

Summary

The specification is broadly expressive for built-in pages and many custom views, but it has one actionable renderability gap: custom views cannot deterministically express or validate empty and unavailable states at the view level when a profile requirement depends on a link-bearing or status-bearing table/chart over a source that may return no rows or no usable result. The data-state section normatively requires presenters to expose availability, completeness, freshness, provenance, and source identity for every page or view, but the custom-view model does not define what semantic output a presenter must emit for a view whose aggregate channels become absent, whose href channel disappears for all rows, or whose result is unavailable before any rows exist. This leaves validators and presenters without a shared contract for how a valid YAML custom view maps to a deterministic rendered state.

Simulated profile requirements and assessment

Backend Engineer: a runs page filtered to one workflow and last 7 days showing run conclusions by day. Renderable via built-in runs or custom chart using runs, started-at day, and count(run); specification is sufficient.
Frontend Developer: a findings table linking open findings to pull requests. Renderable via findings source, table columns, and href: pull-request-link; specification is sufficient for linked rows.
DevOps Engineer: a usage chart grouped by engine over 30d using AIC and rollout-mode filter. Renderable via usage source, engine, sum(aic), and filters; specification is sufficient.
QA Tester: an evals page showing YES/NO/UNKNOWN results for one eval over time. Renderable through built-in evals; specification is sufficient.
Product Manager: an operational-value timeline for one definition and operational case with maturity status. Renderable through built-in operational-value; specification is sufficient.
Program Manager: a repository ranking of top 10 repositories by run count for live rollout mode. Renderable via repositories built-in or custom table with order-by; specification is sufficient.
Designer: a chart and metric that must expose textual equivalents and non-color semantics. Accessibility requirements are explicit enough for conforming presenters.
Legal / Compliance: a findings page that must preserve provenance, freshness, and not fabricate absent links. Built-in findings page requirements are sufficient.
Information Worker: a custom table of recent findings with issue links that must still render deterministically when the effective filter returns no findings or when the findings source is unavailable. This is not fully specified for custom views.

Affected sections and requirement IDs

Section 8: Data States
- DLS-DATA-003
- DLS-DATA-004
- DLS-DATA-005
- DLS-DATA-008
Section 11: Custom Pages
- DLS-VIEW-012
- DLS-VIEW-013
- DLS-VIEW-014
Section 12: Validation and Errors
- DLS-VAL-003
Appendix B
- DLS-E012

Observed ambiguity

The specification requires every page or view to expose availability, completeness, freshness, provenance, effective scope, effective time range, and effective filters. It also distinguishes empty from unavailable and requires aggregate outputs over an empty selection to produce zero only for count and distinct-count, with other aggregates absent. However, the custom-view section does not define the required semantic output shape or rendering behavior for a custom metric, table, or chart when:

the effective selection is empty before any rows exist;
the selected source is unavailable before any rows exist;
every row lacks the optional href field, so the view has no navigable datum;
a metric's aggregated value is absent because the aggregate is not count or distinct-count; or
a chart or table has no data rows but still must remain a valid rendered view with textual data-state output.

As written, a presenter can satisfy DLS-VIEW-013 only by inventing implementation-specific empty-state semantics such as placeholder cards, empty tables, synthetic zero rows, or omitted views. Those behaviors are materially different and affect usability, accessibility, and deterministic rendering. A validator also lacks a normative basis for determining when a valid custom view is representable versus when its state handling is underspecified.

Proposed normative change

Add a custom-view data-state contract stating that a conforming presenter:

MUST compute and expose one view-level availability state of available, empty, or unavailable for every custom view before mark-specific rendering;
MUST preserve view validity when availability is empty or unavailable and MUST NOT omit the view solely because no rows or usable result exist;
MUST expose a textual state message for empty and unavailable that includes the affected source identity and the effective scope, time range, and filters;
MUST render metric with no numeric value when its aggregate is absent under empty or unavailable, except that count and distinct-count over empty MUST render as zero;
MUST render table and chart with zero data rows or points under empty and with no fabricated rows or points under unavailable;
MUST NOT synthesize placeholder observations, zero-valued non-count aggregates, or links to satisfy the mark contract;
MUST treat an href channel whose referenced link field is absent for every resulting datum as a valid unlinked rendering, not as a validation error; and
MUST use DLS-E012 only when required source metadata needed to determine these states is missing, not merely because the effective result is empty or unavailable.

Minimal YAML example

language-version: "0.1.0"
dashboard:
  id: recent-findings
  title: Recent Findings
  pages:
    - id: findings-page
      kind: custom
      views:
        - id: open-findings
          data:
            source: findings
            filters:
              finding-status: open
            time:
              range: 7d
          mark: table
          encoding:
            columns:
              - field: finding-summary
              - field: issue-link
                title: Issue
            href:
              field: issue-link

If the filtered findings selection is empty, the presenter needs normative guidance that the table still renders as the same view with zero rows plus textual empty state metadata. If the findings source is unavailable, the presenter needs normative guidance that the same view renders as unavailable without fabricated rows or hidden content.

Renderer consequences

Presenters gain a deterministic obligation to surface view-level state independent of mark type.
Renderers can distinguish zero rows from unavailable data without inventing placeholder records.
Accessibility output becomes consistent because every custom view has a textual state representation even when no data rows or metric value exist.
Link rendering remains deterministic when href is absent on all resulting rows.

Validator consequences

Validators can accept valid custom views whose effective runtime result may be empty or unavailable.
Validators can reject only missing required source metadata under DLS-E012, instead of conflating empty data with invalid view shape.
Compliance tests can add positive fixtures for empty and unavailable custom metric/table/chart states and negative fixtures for missing metadata.

Acceptance criteria

A new normative requirement defines one view-level availability state for every custom view.
A new normative requirement defines mark-specific behavior for metric, table, and chart under empty and unavailable.
The specification explicitly forbids fabricated rows, points, links, or zero-valued non-count aggregates in those states.
The specification clarifies that all-row-absent href remains a valid unlinked rendering.
Appendix B and compliance tests clearly distinguish missing metadata errors from valid empty or unavailable runtime states.

Generated by 📊 Daily Dashboard Language Specification Review · pi · gpt54 · 4.29 AIC · ⌖ 6.15 AIC · ⊞ 3.7K · ◷

expires on Sep 4, 2026, 5:48 PM UTC