Dashboard JSON spec

Every Cardinal UI dashboard is stored as one JSON document, the dashboard spec. It describes the panels, the queries behind them, how they are laid out, and any variables. The same document is used in three places:

• Export on an open dashboard downloads it.
• Dashboards → Add Dashboard → Import from JSON creates a dashboard from it.
• The Dashboards API takes it as the spec field.

A machine-readable JSON Schema is published at /schemas/dashboard.schema.json. Point your editor or CI at it to get completion and validation while you generate specs from code.

Round trip: build in the UI, then template it

Hand-writing a spec from scratch is rarely the fastest route. Instead:

1. Build one dashboard in the UI the way you want it.
2. Click Export to download its JSON.
3. Use that file as a template: substitute service names, thresholds or queries in your own tooling. If you exported a dashboard you added from the gallery, delete its libraryRef field before creating new dashboards from it; otherwise they show the gallery’s version instead of your spec.
4. Load the results back with Import from JSON, or send the file’s spec field (jq .spec export.json) to the API.

File formats Import accepts

Import from JSON accepts either of these:

• The export envelope that Export produces:

  {
    "schemaVersion": 2,
    "name": "Login health",
    "exportedAt": "2026-09-23T18:00:00.000Z",
    "spec": { "duration": "1h", "panels": { }, "sections": [ ] }
  }

  name pre-fills the dashboard name in the import dialog.

• A bare spec, i.e. just the spec object. The dialog then uses the file name as the dashboard name.

The dialog also asks for a category, which decides where the dashboard is listed.

Import is forgiving. A panel with an unknown kind, or one missing id, title or queries, is dropped with a warning instead of failing the whole file. The same goes for an invalid variable or grid cell. The schema is stricter: it rejects unknown fields. So a spec that validates against the schema imports without warnings.

A few problems still reject the whole file: a missing duration, panels that isn’t an object, or a section without a cells list. If variables’ scope settings depend on each other in a loop, Import removes those scopes and warns you.

Top-level fields

Sections and layout

Panels are placed on a 24-column grid inside sections. Sections stack vertically, and each can be collapsed.

"sections": [
  {
    "title": "Logins",
    "cells": [
      { "i": "logins_rate", "x": 0,  "y": 0, "w": 16, "h": 8 },
      { "i": "logins_now",  "x": 16, "y": 0, "w": 8,  "h": 8 }
    ]
  }
]

A panel that isn’t referenced by any cell is kept in the spec but not shown.

Panels

Every panel has these fields:

Queries

{ "query": "sum by (app) (rate(login_success_total[5m]))", "name": "{{app}}" }

timeseries

A line, area or bar chart over time. This is the kind to use for most metrics.

bar

A stacked bar chart over time, one stack segment per series.

stat and gauge

A single number, or an arc for gauge.

label

One card per series the query returns, e.g. one per service_name when the query groups by it.

pie

One slice per series, reduced with reducer (default last).

log-events

Log lines with a volume chart above them. Set queries to [], and give either rawLogql (a LogQL log selector and pipeline) or logqlState (the Logs Explore builder’s state, easiest to get from an export). Add limit (default 100) to cap the number of lines, or set distributionOnly: true to show just the per-service severity chart.

service-graph

A service dependency graph built from traces. Set queries to []. Options:

• metric: requests (default), errors or latency
• serviceName: centre the graph on this service; a $variable works here
• maxHops: how far out from serviceName to go (default 3)

service-gauges and service-memory-bars

Purpose-built panels for Cardinal’s system dashboards. Each expects a fixed set of queries in a fixed order. Copy one from an exported gallery dashboard rather than writing it by hand.

Variables

Variables add drop-down pickers to the dashboard. A variable named app is substituted wherever a query contains $app or ${app}.

"variables": [
  {
    "name": "app",
    "label": "Application",
    "kind": "query",
    "source": { "signal": "metrics", "metric": "login_success_total", "label": "app" },
    "multi": true,
    "includeAll": true
  }
]

Complete example

This dashboard charts login successes and failures for one or more applications. It shows the current failure count as a single number that turns red at 5 or more.

{
  "schemaVersion": 2,
  "category": "applications",
  "duration": "6h",
  "variables": [
    {
      "name": "app",
      "label": "Application",
      "kind": "query",
      "source": { "signal": "metrics", "metric": "login_success_total", "label": "app" },
      "multi": true,
      "includeAll": true
    }
  ],
  "panels": {
    "logins": {
      "id": "logins",
      "kind": "timeseries",
      "title": "Logins per minute",
      "yAxisLabel": "Logins",
      "unit": "/min",
      "queries": [
        { "query": "sum by (app) (rate(login_success_total{app=~\"$app\"}[5m])) * 60", "name": "{{app}} success" },
        { "query": "sum by (app) (rate(login_failure_total{app=~\"$app\"}[5m])) * 60", "name": "{{app}} failure", "color": "#ef4444" }
      ]
    },
    "failures_now": {
      "id": "failures_now",
      "kind": "label",
      "title": "Failed logins (last 5m)",
      "reducer": "last",
      "thresholds": [
        { "value": 0, "color": "#22c55e" },
        { "value": 5, "color": "#ef4444" }
      ],
      "queries": [
        { "query": "sum by (app) (increase(login_failure_total{app=~\"$app\"}[5m]))", "name": "{{app}}" }
      ]
    }
  },
  "sections": [
    {
      "title": "Logins",
      "cells": [
        { "i": "logins", "x": 0, "y": 0, "w": 16, "h": 8 },
        { "i": "failures_now", "x": 16, "y": 0, "w": 8, "h": 8 }
      ]
    }
  ]
}

Dashboards show metrics. To be notified when a condition holds for a while (for example, more than 5 failed logins per minute for 10 minutes), create an alert rule with a For duration.

Versions

Axis titles (yAxisLabel, xAxisLabel) and sharedCrosshair need Cardinal UI v1.96.0 or later. Earlier versions accept a spec that contains them but don’t draw them.