[dashboard-language-spec] Dashboard Language Specification: define deterministic ordering for non-entity grouped outputs

Summary

The specification contains one actionable renderability gap for custom charts and tables that need deterministic series ordering within grouped outputs. Several realistic dashboard requirements require ordering by a grouped dimension or aggregate after grouping, but the current ordering model and tie-break rule become undefined for non-entity aggregate groups because no canonical entity ID exists at that output grain.

Simulated profile checks

• Backend Engineer: daily run failures by workflow over 30d filtered to rollout-mode: live is representable as a custom chart from runs with temporal x, counted y, and color: workflow.
• Frontend Developer: open findings table with severity, summary, and PR link filtered to one repository is representable with findings, columns, and href: pull-request-link.
• DevOps Engineer: top 10 repositories by summed aic in the last 7d is representable with usage, aggregate: sum, order-by, and limit.
• QA Tester: eval results by day for one eval filtered to YES|NO|UNKNOWN outcomes is representable with eval-observations and temporal bucketing.
• Product Manager: operational-value timeline by definition over 30d is representable with operational-values and temporal x.
• Program Manager: repository ranking by run count in review rollout over 30d is representable with runs, count, order-by, and limit.
• Designer: accessible findings table with textual severity/status labels and labeled links is representable via DLS-SAFE-008 to DLS-SAFE-010 and link semantics.
• Legal / Compliance: stale or partial findings view with provenance and no fabricated links is representable via Sections 8, 9, and 13.
• Information Worker: workflows table filtered to workflow-active: unknown with run links is representable with workflows or runs sources and explicit unknown filtering.

Affected requirements and sections

• Section 7.4, DLS-AGG-008
• Section 11.2, custom-page ordering semantics
• Section 11.3, DLS-VIEW-010 and DLS-VIEW-012
• Appendix B, DLS-E010 consequences

Observed ambiguity

The specification requires rankings to apply limit after ordering and then order ties by canonical entity ID ascending. It also says omitted order-by leaves aggregate groups ordered by encoded dimensions ascending. However, many valid grouped outputs are not entity-grain rows and may have no canonical entity ID at all, for example:

- id: run-conclusions-by-day
  data:
    source: runs
    order-by:
      - field: day
        direction: asc
  mark: chart
  encoding:
    x:
      field: started-at
      type: temporal
      time-unit: day
      as: day
    y:
      field: run
      type: quantitative
      aggregate: count
    color:
      field: run-conclusion

The output grain here is (day, run-conclusion). No requirement defines what the canonical entity ID tie-break means for such rows, whether ordering by one grouped dimension implies a deterministic secondary ordering over the remaining grouped dimensions, or how a presenter should order grouped tables and chart series before applying limit when multiple rows share the same ordered value. A conforming presenter would have to invent semantics for grouped outputs, especially for stacked/grouped chart series, top-N grouped tables, and any post-aggregation result keyed only by temporal or categorical dimensions.

Proposed normative change

1. DLS-AGG-008 SHOULD be revised so that tie-breaking is defined for every post-aggregation output grain, not only entity-grain outputs.
2. The specification MUST define a canonical output-row ordering key for grouped results with no entity ID. At minimum, when order-by does not fully determine a total order, the presenter MUST break remaining ties by the remaining unaggregated output dimensions in encoding order, using ascending canonical field values after time bucketing.
3. If an output row still cannot be totally ordered because no canonical comparison is defined for one of the remaining dimensions, the validator MUST reject the view with DLS-E010 rather than requiring presenter invention.
4. Section 11.2 and DLS-VIEW-012 MUST align omitted-order and explicit-order behavior so both use the same canonical post-aggregation row-order algorithm.
5. The specification SHOULD state that chart series and table rows inherit this canonical post-aggregation row order, while not constraining visual styling beyond the existing mark defaults.

Renderer and validator consequences

• Presenters gain a deterministic rule for grouped outputs, including time-bucketed charts and non-entity aggregate tables.
• Validators can detect views whose requested ordering cannot be resolved into a total post-aggregation order.
• limit becomes reproducible for grouped outputs because the rows retained after ordering no longer depend on renderer-specific iteration order.
• Compliance tests can add grouped non-entity fixtures and verify stable ordering without requiring implementation-specific assumptions.

Acceptance criteria

• A grouped custom view with no entity ID has a fully specified deterministic row order.
• Explicit order-by and omitted order-by use aligned post-aggregation ordering semantics.
• The tie-break rule no longer depends exclusively on canonical entity ID.
• A validator rejects grouped outputs whose order cannot be totally determined under the normative rule.
• Compliance fixtures include at least one time-bucketed grouped chart and one grouped table that demonstrate deterministic ordering and limiting.

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

• expires on Sep 5, 2026, 7:46 AM UTC