Documentation Grafana documentation Observability as Code JSON schema v2

Dashboard JSON schema v2

Grafana dashboards are represented as JSON objects that store metadata, panels, variables, and settings.

Observability as Code works with all versions of the JSON model, and it’s fully compatible with version 2.

Before you begin

Schema v2 is automatically enabled with the Dynamic Dashboards feature toggle, dashboardNewLayouts. It also requires the new dashboards API feature toggle, kubernetesDashboards, to be enabled as well.

For more information on how dashboards behave depending on your feature flag configuration, refer to Notes and limitations.

Accessing the JSON Model

To view the JSON representation of a dashboard:

1. Toggle on the edit mode switch in the top-right corner of the dashboard.
2. Click the gear icon in the top navigation bar to go to Settings.
3. Select the JSON Model tab.
4. Copy or edit the JSON structure as needed.

JSON fields

json Copy

Expand code

{
  "annotations": [],
  "cursorSync": "Off",
  "editable": true,
  "elements": {},
  "layout": {
    "kind": GridLayout, // Can also be AutoGridLayout, RowsLayout, or TabsLayout
    "spec": {
      "items": []
    }
  },
  "links": [],
  "liveNow": false,
  "preload": false,
  "tags": [], // Tags associated with the dashboard.
  "timeSettings": {
    "autoRefresh": "",
    "autoRefreshIntervals": [
      "5s",
      "10s",
      "30s",
      "1m",
      "5m",
      "15m",
      "30m",
      "1h",
      "2h",
      "1d"
    ],
    "fiscalYearStartMonth": 0,
    "from": "now-6h",
    "hideTimepicker": false,
    "timezone": "browser",
    "to": "now"
  },
  "title": "",
  "variables": []
},

The dashboard JSON sample shown uses the default GridLayoutKind. The JSON in a new dashboard for the other three layout options, AutoGridLayout, RowsLayout, and TabsLayout, are as follows:

AutoGridLayout

json Copy

  "layout": {
    "kind": "AutoGridLayout",
    "spec": {
      "columnWidthMode": "standard",
      "items": [],
      "fillScreen": false,
      "maxColumnCount": 3,
      "rowHeightMode": "standard"
    }
  },

RowsLayout

json Copy

  "layout": {
    "kind": "RowsLayout",
    "spec": {
      "rows": []
  },

TabsLayout

json Copy

  "layout": {
    "kind": "TabsLayout",
    "spec": {
      "tabs": []
  },

DashboardSpec

The following table explains the usage of the dashboard JSON fields. The table includes default and other fields:

annotations

The configuration for the list of annotations that are associated with the dashboard. For the JSON and field usage notes, refer to the annotations schema documentation.

elements

Dashboards can contain the following elements:

• PanelKind
• LibraryPanelKind

layout

Dashboards can have four layout options:

• GridLayoutKind
• AutoGridLayoutKind
• RowsLayoutKind
• TabsLayoutKind

For the JSON and field usage notes about each of these, refer to the layout schema documentation.

links

The configuration for links with references to other dashboards or external websites.

For the JSON and field usage notes, refer to the links schema documentation.

tags

The tags associated with the dashboard:

[...string]

timesettings

The TimeSettingsSpec defines the default time configuration for the time picker and the refresh picker for the specific dashboard. For the JSON and field usage notes about the TimeSettingsSpec, refer to the timesettings schema documentation.

variables

The variables schema defines which variables are used in the dashboard.

There are eight variables types:

• QueryVariableKind
• TextVariableKind
• ConstantVariableKind
• DatasourceVariableKind
• IntervalVariableKind
• CustomVariableKind
• GroupByVariableKind
• AdhocVariableKind

For the JSON and field usage notes about the variables spec, refer to the variables schema documentation.

Notes and limitations

Existing dashboards

With schema v2 enabled, you can still open and view your pre-existing dashboards. Upon saving, they’ll be updated to the new schema where you can take advantage of the new features and functionalities.

Dashboard behavior with disabled feature flags

If you disable the dashboardNewLayouts or kubernetesDashboards feature flags, you should be aware of how dashboards will behave.

Disable dashboardNewLayouts

If dashboardNewLayouts feature toggle is disabled, depending on how the dashboard was built, it will behave differently:

• Dashboards built on the new schema through the UI - View only
• Dashboards built on Schema v1 - View and edit
• Dashboards built on the new schema by way of Terraform or the CLI - View and edit
• Provisioned dashboards built on the new schema - View and edit, but the edit experience will be the old experience

Disable dashboardNewLayouts and kubernetesDashboards

You’ll be unable to view or edit dashboards created or updated in the new schema.

Import and export

From the UI, dashboards created on schema v2 can be exported and imported like other dashboards. When you export them to use in another instance, references of data sources are not persisted but data source types are. You’ll have the option to select the data source of your choice in the import UI.