Dashboard schema and widgets

Dashboards are YAML-defined views attached to jobs. They execute authored read queries, display run or business data, edit approved job configuration, and dispatch confirmed actions.

Top-level schema

dashboard:
  title: Migration status
  description: Track progress and review errors
  refresh_interval_seconds: 30
  allow_public_input: false
  default_scope: production
 
  scope:
    production: |
      { "environment": "production" }
 
  shared_queries: {}
 
  pages:
    - id: overview
      title: Overview
      public: true
      widgets: []

Common fields:

• title, description;
• refresh_interval_seconds;
• navbar_ctas;
• scope and default_scope;
• shared_queries;
• allow_public_input;
• pages[].

A legacy top-level widgets list is normalized as one main page. Widget IDs must be unique across the complete dashboard.

Page schema

Each page has:

• id — stable URL identity;
• title — navigation label;
• widgets — ordered widget list;
• public — set false to exclude the page from a share.

Layout

Widgets use a responsive grid. width controls relative span. Keep related controls together, put headings before sections, and verify narrow screens.

Display widgets

heading

Displays a heading, descriptive Markdown, or callout. Use it for instructions and section structure.

stat

Displays one value and optional label, comparison, or formatting. Feed it a bounded count or aggregate.

progress

Displays current and total values. Define behavior for zero or missing totals.

Charts

bar_chart, line_chart, and pie_chart render bounded datasets. Aggregate at the connector and provide explicit label and value fields.

table

Displays a fixed, bounded result with declared columns and formatting. Use explorer for large or interactive collections.

steps

Shows authored process stages and their status.

people

Displays role or contact records.

task_progress

Reads the latest run state for one job task key:

type: task_progress
task: migrate_tickets
refresh_interval_seconds: 5

Data access

A data widget names a connector method and authored arguments. Read calls run server-side through the job's connector mapping.

Use shared_queries when several widgets need the same call. A query is resolved once per refresh, then each widget can derive its value with JSONata.

Queries must remain read-only and bounded.

explorer

Explorer supports server-side paging, filtering, sorting, projection, and streaming export:

type: explorer
data:
  connector: staging
  resource: migration_errors
  base_query:
    filter:
      migration_id: fixed-scope
columns:
  - { field: source_id, label: Source ID, sortable: true }
  - { field: message, label: Error }
default_sort:
  updated_at: -1
page_size: 25
features: [filter, sort, columns, export]

Viewer filters are combined with base_query and cannot remove it. Declared columns form the viewer field allowlist. Mark only supported indexed fields sortable.

Input widgets

form

Edits one object in job configuration using typed text, number, boolean, select, or multiselect fields.

field_mapping

Edits source-to-target mapping rows with optional transforms. Option sources must be read-only and pageable for large lists.

The canonical configuration schema should live in job-template job_config.

action

type: action
label: Run validation
confirm_message: Run validation now?
cooldown_seconds: 30
allow_public: false
action:
  kind: job_run
  tasks: [validate]
  skip_deps: false

Action kinds are run_task, job_run, and connector_method. Actions require confirmation, prevent duplicate in-flight execution per widget, apply cooldown, and create audit records.

Public execution requires additional gates. See Public dashboard widget execution.

Authoring guidance

See Author an operational dashboard for design and testing and Job configuration reference for input schemas.