[dashboard-language-spec] Dashboard Language custom views need normative aggregate-output identifiers for deterministic rankings

Summary

The custom-page vocabulary cannot deterministically express ranked dashboards that are explicitly required by the review scenarios and by built-in page semantics, because order-by is defined against source fields or encoded aggregate outputs but aggregate outputs have no normative identifier model and no requirement ties row ordering to the aggregated field definitions used in encoding.

Affected requirements and sections

• Section 7.4, DLS-AGG-008
• Section 11.2 (order-by)
• Section 11.3, DLS-VIEW-010 and DLS-VIEW-012
• Appendix B, DLS-E006 and DLS-E010

Observed ambiguity

The specification requires rankings to disclose the ranked measure, direction, filters, time range, scope, and tie behavior, and built-in pages rely on rankings such as repository run count, AIC spend, and workflow activity. However, custom pages have no normative way to identify an aggregated result for ordering.

data.order-by allows fields that “exist in the selected source or be encoded aggregate outputs,” but Section 11 does not define how an aggregate output is named when multiple encodings reference the same source field with different aggregates, when a table column is aggregated but not uniquely identifiable, or when the ranked measure is not otherwise encoded as a standalone output name. As a result, a presenter would need to invent semantics such as “order by the only aggregated aic column” or derive implementation-specific synthetic names.

This prevents deterministic rendering for realistic requirements including:

• Backend Engineer: top repositories by distinct failed runs in the last 7 days;
• DevOps Engineer: top workflows by summed AIC in live rollout;
• Product Manager: repositories ranked by mean operational value under one definition; and
• Information Worker: recent findings table ordered by newest observation then severity.

Some of these can only be expressed if aggregate outputs are orderable without renderer guesses; others need a validator to reject ambiguous ranking references consistently.

Proposed normative change

The specification SHOULD define explicit aggregate-output identifiers for custom views and MUST require order-by.field to reference either:

1. a source field name used without aggregation at the output grain; or
2. an explicitly named aggregate output produced by an encoding field definition.

To support that behavior, Section 4.2 and Section 11.1/11.3 SHOULD add an optional as property to field definitions. The following requirements SHOULD be added or updated:

• A field definition with aggregate other than none MAY include as; if omitted, the validator MUST derive a canonical output identifier as <aggregate>-<field>.
• If the same output identifier would be produced more than once within a view, the validator MUST reject the document.
• data.order-by.field MUST reference either a source field valid at the post-aggregation output grain or one aggregate-output identifier.
• If order-by.field matches multiple possible outputs, or references a source field that is no longer unique after aggregation, the validator MUST reject the document with a defined aggregation/order error.
• A presenter MUST apply ranking order using the resolved output identifier before limit, then apply the existing tie rule from DLS-AGG-008.

Minimal clarifying example:

- id: largest-spenders
  data:
    source: usage
    order-by:
      - field: sum-aic
        direction: desc
    limit: 10
  mark: table
  encoding:
    columns:
      - field: repository
      - field: aic
        aggregate: sum
        as: sum-aic

Renderer and validator consequences

Renderers would be able to produce ranked tables and charts without inventing names for aggregated measures. Validators would gain deterministic rejection behavior for ambiguous or invalid ranking specifications, especially where the same source field appears with different aggregates or where ordering refers to a pre-aggregation field that no longer exists at output grain.

Acceptance criteria

• A custom view can normatively rank grouped results by an aggregated measure without implementation-specific naming.
• The specification defines how aggregate outputs are identified for ordering.
• Ambiguous aggregate-order references are validator errors.
• Ordering and limiting of rankings are deterministic across conforming presenters.
• Existing built-in ranking requirements remain consistent with custom-view validation semantics.

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

• expires on Sep 4, 2026, 11:27 AM UTC