Dashboard JSON schema

Overview

A dashboard is a single JSON document. It is what osuite dashboard pull writes to disk and what osuite dashboard apply sends back to the platform (see dashboards as code). This page documents every field.

A file is recognized as a dashboard only if it has a top-level name. The platform assigns id and created_at — you never set them by hand.

Dashboard object

Field	Type	Required	Notes
name	string	yes	The dashboard name.
id	integer	no	Assigned by the platform. Omit on a new dashboard; never change it on an existing one.
description	string	no	Free-text description.
tags	string[]	no	Labels for organizing dashboards. Defaults to [].
published	boolean	no	Whether the dashboard is published. Defaults to false.
created_at	string (date-time)	no	Set by the platform.
widgets	Widget[]	no	The panels. Defaults to [].
variables	Variable[]	no	Template variables. Defaults to [].

Widget object

A widget is one panel. Widgets are placed on a 24-column grid.

Field	Type	Required	Notes
id	string	yes	Stable identifier for the widget. Never change it on an existing widget.
chart_type	string (enum)	yes	One of the chart types below.
title	string	yes	Panel heading.
description	string	no	Optional panel description.
pos_x	integer	yes	Column offset on the grid (0–23).
pos_y	integer	yes	Row offset on the grid.
width	integer	yes	Column span, 1–24 (12 = half width, 24 = full width).
height	integer	yes	Row span; a positive integer, typically 6–12.
queries	NamedQuery[]	yes	One or more PromQL queries backing the panel.
config	object	no	Formatting config. Defaults to {}. See config.

chart_type values

chart_type is a fixed enum. Any other value is rejected locally by osuite dashboard plan and apply before anything is sent.

line, area, stacked-area, bar, stacked-bar, scatter, pie, bar-gauge, gauge, stats, table, service-graph.

See the dashboards overview for what each one is used for.

config

config holds panel formatting. Set the display unit with {"type": "<unit>"}, where <unit> is one of:

number, percentage, bytes, bytes_per_second, duration_ms.

Pick the unit that matches the metric — bytes for memory, duration_ms for latency, percentage for a utilization ratio.

NamedQuery object

Field	Type	Required	Notes
name	string	yes	Query name. Queries within a widget are named sequentially: A, B, C, …
query	string	yes	The PromQL query.
legend	string	no	Legend template for the series, for example {{status_code}}.

Variable object

A template variable is referenced in queries as $name (see template variables).

Field	Type	Required	Notes
id	string	yes	Stable identifier for the variable.
name	string	yes	Referenced in queries as $name.
order	integer	yes	Position among the selectors.
var_type	string	no	Variable type.
display_label	string	no	Label shown in the selector control; queries still use name.
multi	boolean	no	Allow selecting multiple values. Defaults to false.
query_type	string (enum)	no	Source of the values: label_name, label_value, or metrics.
label_name	string	no	The label to read values from, when query_type is label_value.
metric	string	no	The metric to scope the values to.
custom_key_values	array of objects	no	A fixed value list; each entry is a { "<key>": "<value>" } map. Defaults to [].

Validation

osuite dashboard plan and apply validate each file locally before contacting the platform. A file fails if any widget:

• is missing chart_type, or has a chart_type outside the enum,
• is missing id or title (must be strings),
• is missing pos_x, pos_y, width, or height (must be numbers),
• is missing the queries array, or
• has a width outside the 1–24 range.

Complete example

{
  "name": "Payments service",
  "description": "Golden signals for the payments service",
  "tags": ["apm", "payments"],
  "published": true,
  "variables": [
    {
      "id": "var-service",
      "name": "service",
      "order": 0,
      "display_label": "Service",
      "multi": false,
      "query_type": "label_value",
      "label_name": "service"
    }
  ],
  "widgets": [
    {
      "id": "request-rate",
      "chart_type": "line",
      "title": "Request rate",
      "description": "Requests per second by status code",
      "pos_x": 0,
      "pos_y": 0,
      "width": 12,
      "height": 8,
      "queries": [
        {
          "name": "A",
          "query": "sum(rate(http_requests_total{service=\"$service\"}[5m])) by (status_code)",
          "legend": "{{status_code}}"
        }
      ],
      "config": { "type": "number" }
    },
    {
      "id": "p99-latency",
      "chart_type": "line",
      "title": "p99 latency",
      "pos_x": 12,
      "pos_y": 0,
      "width": 12,
      "height": 8,
      "queries": [
        {
          "name": "A",
          "query": "histogram_quantile(0.99, sum(rate(http_request_duration_seconds_bucket{service=\"$service\"}[5m])) by (le))"
        }
      ],
      "config": { "type": "duration_ms" }
    }
  ]
}

Related

• Dashboards as code — the pull / plan / apply workflow
• Template variables — how variables behave
• Dashboards overview — chart types and panels