Dashboards

Status: v0.2 — the two documents and their lifecycle (#10, lane L1a); the REST routes, the MCP tools and the permissions (§4, lane L1b). The transfer routes (L1c), the runtime (L2), the client runtime and the first-party page (L3), the visualization tests and their release gate (L4) and the dashboard key kind (L5) add their sections as they land. Owner: datapipelines.co core Depends on: Versioning (§3.5 — the lifecycle table), Pipeline Contract (§13.22, §13.23 — the codes), Metadata DB (§4.28–§4.33 — the tables), Enumerations (§31–§37), Configuration (§3.33 — the bounds), REST API (§22, §23 — the routes), MCP Server (§6.2.50–§6.2.60 — the tools), Auth (§7.6 — the permissions) Design: the dashboard implementation spec and the design record (decisions D1–D63) Last updated: 2026-09-29

A dashboard presents released pipeline results. It is built from two versioned artifacts: visualizations — a chart, table or KPI bound to named inputs, reusable across dashboards — and dashboards, which pin released pipelines as sources, map their results onto visualization inputs, and arrange visualizations, groups, actions and parameter controls on a 12-column layout. Both are authored through MCP and follow the draft/release lifecycle pipelines, templates and parameter sets already have.

1. The two artifacts

A visualization has no fixed pipeline: it is input-bound (D33). A dashboard supplies its inputs, so the same visualization release can appear in several dashboards — and more than once in one, under different occurrence names. References between artifacts are { "name": "<folder path>", "version": <n> }, resolved within the workspace and the kind the containing field names; a name is never renamed and never reused (D36).

Both documents are read by a strict reader: an explicit key table at every level, so an unknown key, a wrong JSON type or a missing key is refused *.validation.body_invalid naming the path, every problem reported at once. A JSON null at a schema level is absent. A refusal names a key or a path, never a value from the document. The name is outside the body: the stored body never carries it.

2. The documents

2.1 Visualization

{
  "display_name": "Monthly revenue",
  "description": "",
  "renderer": { "kind": "plotly", "version": "4" },
  "inputs": {
    "revenue": { "columns": [ { "name": "month", "type": "DATE", "nullable": false },
                              { "name": "amount", "type": "DECIMAL", "nullable": false } ] }
  },
  "transform": { "template": { "name": "finance/transforms/revenue_bars", "version": 2 },
                 "inputs": { "rows": "revenue" } },
  "config": { "data": [ { "type": "bar", "x": "$.x", "y": "$.y" } ], "layout": { "title": { "text": "Revenue" } } },
  "bindings": { "data[0].x": "month_labels", "data[0].y": "amounts" },
  "presentation": { "title": "Monthly revenue", "tokens": { "series": "categorical" } },
  "tests": { "cases": [ { "name": "twelve months", "fixtures": { "revenue": [ { "month": "2026-01-01", "amount": 10.5 } ] },
                          "assertions": [ { "kind": "rendered" }, { "kind": "trace_count", "equals": 1 } ] } ] }
}

(The document as submitted also carries its name, e.g. "finance/visualizations/monthly_revenue". The implementation spec's copy writes the fixture's amount as the string "10.5"; a DECIMAL is a JSON number on the wire, so it is 10.5 here.)

2.1.1 Binding paths

A key, then any run of .key and [index] steps: data[0].x, layout.title.text, columns[2].values. A key is [A-Za-z_][A-Za-z0-9_]*, an index 0–9999 without leading zeros, 256 characters at most. There is no wildcard, no filter and no root marker: a path names exactly one place, and that place must exist in the stored configuration — the author puts a placeholder there ("x": "$.x" above) — so the runtime's substitution can never create structure.

2.1.2 Renderer schemas

• plotly — an object whose data is a non-empty array (at most 64) of trace objects, each with a type from the two vendored bundles: scatter, bar, pie, histogram, box, heatmap (the 2D bundle, the default) and scatter3d, surface, mesh3d (the 3D bundle, loaded only for a dashboard that uses one — D63); layout and Plotly's own config are objects. Nothing else at the top level. Deeper Plotly attributes are judged by the vendored plot-schema when the tests lane adds it.
• table — columns: a non-empty array (at most 64) of {label, values, format?, align?} — label a non-blank string of at most 120 characters, values the placeholder a binding fills, format one of text, number, integer, percent, date, datetime, align one of left, center, right; page_size an integer 1–1000.
• kpi — label (required, as a table label), value (the placeholder a binding fills), format one of number, integer, percent, currency, unit (at most 16 characters), comparison {label, value}.

2.1.3 Test cases

Each case has a unique non-blank name, fixtures with rows for EVERY input — each row an object of the input's columns, every value a scalar, no null in a non-nullable column — and at least one assertion from a closed vocabulary (Enumerations §32): rendered, trace_count (equals), no_console_errors, text_visible (text), no_data, value_visible (text). An unrunnable case is visualization.validation.test_case_invalid. Fixture VALUES are judged by the transform engine's type gate when the case runs; a DECIMAL is a JSON number on the wire (type-system §3), so write 10.5, not "10.5".

2.2 Dashboard

{
  "display_name": "Revenue overview",
  "description": "",
  "parameter_set": { "name": "finance/parameters/reporting_period", "version": 1 },
  "sources": [
    { "name": "revenue_source", "pipeline": { "name": "finance/pipelines/monthly_revenue", "version": 7 },
      "parameters": { "year": { "parameter": "year" }, "currency": { "value": "USD" } } }
  ],
  "visualizations": [
    { "name": "revenue_chart", "type": "visualization",
      "visualization": { "name": "finance/visualizations/monthly_revenue", "version": 3 },
      "inputs": { "revenue": { "source": "revenue_source" } }, "timeout_seconds": 120 }
  ],
  "groups": [ { "name": "overview_group", "type": "group", "members": [ "year", "revenue_chart", "refresh_button" ] } ],
  "actions": [ { "name": "refresh_overview", "type": "refresh", "scope": "targets", "targets": [ "revenue_chart" ], "initial": true } ],
  "action_controls": [ { "name": "refresh_button", "type": "action_control", "action": "refresh_overview", "label": "Apply" } ],
  "parameter_scopes": { "year": [ "overview_group" ] },
  "parameter_state": { "dashboard": { "visible": "inherit", "enabled": "inherit" },
                       "parameters": { "currency": { "visible": "force_false" } } },
  "outgoing_overrides": { "revenue_source": { "currency": { "value": "USD" } } },
  "layout": { "parameter_set": { "position": "left" }, "parameter_placements": { "year": { "group": "overview_group" } },
              "grid": [ { "name": "revenue_chart", "x": 0, "y": 0, "w": 6, "h": 4 } ], "columns": 12 },
  "timeouts": { "refresh_seconds": 300 }
}

(The document as submitted also carries its name, e.g. "finance/dashboards/revenue_overview".)

A reference that names nothing — a member, a target, a control's action, a placement, a scope's group, an override's source or pipeline parameter — is dashboard.validation.unknown_object; a pinned visualization, pipeline or set version this workspace does not hold is dashboard.validation.dependency_not_found. The rules run whole at save, again at release, and against the pinned dependencies' current state whenever the runtime serves the dashboard.

2.3 Bounds

The readers check each collection's bound BEFORE they read its members (*.validation.body_invalid with details.reason too_many, or too_large, and details.config_key): visualizations per dashboard, test cases per visualization, fixture rows per case, config bytes, bindings and inputs per visualization, and columns per input — Configuration §3.33. A renderer configuration nests at most 32 levels and a literal at most 2, checked by a bounded walk.

3. The lifecycle

Both families follow Versioning §3.5 exactly: an authoring create lands version 1 as a DRAFT with no current version; the first change after a release opens the next version as a DRAFT (copy-on-write; an identical write changes nothing); every write, release, discard and purge carries the body_hash the caller based it on and is refused *.version.conflict when it is stale; a release flips the DRAFT and moves the pointer; a RELEASED version is discarded, never purged, and can be restored; the pointer can be switched to any live version this deployment's posture admits. The hash is computed by the database over the stored JSON, so key order and whitespace never change it. A promotion receiver refuses every authoring write (*.authoring.disabled) and still imports and switches.

3.1 Releasing a visualization

In this order, in ONE transaction for the last three steps: the DRAFT declares at least one test case (visualization.release.tests_missing); the §2.1 rules pass against the pin as it is now; the transform pin is RELEASED — or a DRAFT released with the visualization when the caller consents (release_pinned_templates, the cascade pipelines use for templates), otherwise visualization.release.dependency_not_released naming the pin; the release evidence passes — the agent's GREEN run for this exact content and the server's mechanical check (D56; visualization.release.tests_stale, visualization.release.tests_red, visualization.release.mechanical_failed). The evidence gate is installed by the tests lane (L4); until then every visualization release is refused visualization.release.tests_missing with details.reason = gate_not_installed.

A version that a live (DRAFT or RELEASED) dashboard version pins is never discarded or purged, and a visualization with any pinned version is never purged whole — visualization.version.pinned, details.pinned_by naming the dashboards.

3.2 Releasing a dashboard

The §2.2 rules pass against the dependencies' current state; the pinned set version is RELEASED; every pinned visualization version is RELEASED — or, when the caller consents (release_pinned_visualizations, D61), a DRAFT pin is released through the visualization's own release (§3.1, its gate included) in the dashboard's transaction, the dashboard's flip last, so a stale hash rolls every cascaded release back. Anything not released is dashboard.release.dependency_not_released, details.dependencies_not_released listing each. The consent does not reach a visualization's own draft transform pin, which needs that visualization's consent.

3.3 Export and import

An export is the CURRENT release's envelope: {"visualization": …, "templates": […], "manifest": {…}} — the transform pin's templates travel with it — and {"dashboard": …, "visualizations": [each pinned visualization's envelope], "manifest": {…}}, whose manifest names the pinned pipelines and set by reference: a dashboard assumes they were promoted first (D61's order: templates, parameter sets, pipelines, visualizations, dashboards). An import lands the templates, then the visualizations, then the dashboard, each at its exported version with its exported id; the envelope's shape is judged before anything lands, the lifecycle fields beside a body are ignored by name and any other unknown key refuses; the same version with the same hash is a no-op; a pin the target lacks is visualization.import.missing_template or dashboard.import.missing_dependency; an id another artifact on the server holds is *.import.id_taken — never re-issued (C29).

4. The surfaces

Both families are authored over REST (REST API §22, §23) and MCP (MCP Server §6.2.50–§6.2.60), addressed by id (P24); a multi-segment name never travels in a path. There is no UI page yet (L3). Every body a surface takes is read by §1's strict reader with §2.3's bounds, so REST and MCP refuse the same documents with the same codes.

4.1 Permissions

Fourteen rows of the permission catalog (Auth §7.6), the parameter sets' shape:

The two transport key roles (api_caller, promotion_receiver) hold none of them. The promoter's lens: a RELEASED dashboard newer than the promotion target's whose EVERY source pipeline her pipeline lens admits — so her dashboards never outrun her pipelines — and the visualizations those dashboards pin; anything else answers as an absent id. The two import rows land with the transfer routes (L1c), the execute row with the runtime (L2), and the key-binding row and the dashboard_viewer key column with the key kind (L5).

4.2 Validate is an author verb

POST /api/v1/dashboards/{id}/validate and dashboards_validate run §2.2's rules on the WORKING version against the dependencies as they are now, write nothing, and answer the verdict (valid and every failure) with a 200. The validator reads the pinned pipelines', set's and visualizations' statuses without a lens, so a refusal can name the state of a pin the caller could not otherwise see; the verb therefore sits on dashboard.update, not dashboard.read (owner ruling 2026-09-29): a viewer and a promoter never reach it.

4.3 What a source must declare

A dashboard source's release is judged at save by its status, its read-only verdict (the published-endpoint rule, through child pipelines) and its parameters. Its OUTPUT columns are judged against the visualization input it feeds (dashboard.validation.input_contract_mismatch) only when the release DECLARES them — when its caller node is a transform whose contract names a table output. A release with no caller node declares an empty output (every mapped input is refused); a SQL caller node declares nothing, and the check is left to the runtime, which judges the real columns (L2) — a guess would refuse or admit on nothing.

4.4 The tools

No tool releases or executes anything; the visualization test tools (visualizations_test_start, visualizations_test_submit) land with the test sessions (L4). The served manual's dashboards guide is the authoring loop in the order an agent needs it.

Appendix A: Change Log