root
/
grafana
mirror of https://github.com/grafana/grafana.git
1
0
Fork 0
Code Issues Actions 90 Packages Projects Releases Wiki Activity

Add schema v2 new files (#104858) 

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Isabel Matwawana <76437239+imatwawana@users.noreply.github.com>
Co-authored-by: Isabel Matwawana <isabel.matwawana@grafana.com>
This commit is contained in:
Irene Rodríguez 2025-05-02 18:21:03 +02:00 committed by GitHub
parent a8c4c824b9
commit 09153c25be
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
8 changed files with 1619 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

233
docs/sources/observability-as-code/schema-v2/_index.md Normal file
View File

@ -0,0 +1,233 @@
---
description: A reference for the JSON dashboard schemas used with Observability as Code, including the experimental V2 schema.
keywords:
- configuration
- as code
- dashboards
- git integration
- git sync
- github
labels:
products:
- cloud
- enterprise
- oss
title: JSON schema v2
weight: 200
---
# Dashboard JSON schema v2
Grafana dashboards are represented as JSON objects that store metadata, panels, variables, and settings.
{{< docs/experimental product="Dashboard JSON schema v2" featureFlag="`dashboardNewLayouts`" >}}
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, `kubernetesDashboard`, to be enabled as well.
For more information on how dashboards behave depending on your feature flag configuration, refer to [Notes and limitations](#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.
1. Click the gear icon in the top navigation bar to go to **Settings**.
1. Select the **JSON Model** tab.
1. Copy or edit the JSON structure as needed.
## JSON fields
```json
{
"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
"layout": {
"kind": "AutoGridLayout",
"spec": {
"columnWidthMode": "standard",
"items": [],
"fillScreen": false,
"maxColumnCount": 3,
"rowHeightMode": "standard"
}
},
```
**`RowsLayout`**
```json
"layout": {
"kind": "RowsLayout",
"spec": {
"rows": []
},
```
**`TabsLayout`**
```json
"layout": {
"kind": "TabsLayout",
"spec": {
"tabs": []
},
```
### `DashboardSpec`
The following table explains the usage of the dashboard JSON fields.
The table includes default and other fields:
<!-- prettier-ignore-start -->
| Name | Usage |
| ------------ | ------------------------------------------------------------------------- |
| annotations | Contains the list of annotations that are associated with the dashboard. |
| cursorSync | Dashboard cursor sync behavior.<ul><li>`Off` - No shared crosshair or tooltip (default)</li><li>`Crosshair` - Shared crosshair</li><li>`Tooltip` - Shared crosshair and shared tooltip</li></ul> |
| editable | bool. Whether or not a dashboard is editable. |
| elements | Contains the list of elements included in the dashboard. Supported dashboard elements are: PanelKind and LibraryPanelKind. |
| layout | The dashboard layout. Supported layouts are:<ul><li>GridLayoutKind</li><li>AutoGridLayoutKind</li><li>RowsLayoutKind</li><li>TabsLayoutKind</li></ul> |
| links | Links with references to other dashboards or external websites. |
| liveNow | bool. When set to `true`, the dashboard redraws panels at an interval matching the pixel width. This keeps data "moving left" regardless of the query refresh rate. This setting helps avoid dashboards presenting stale live data. |
| preload | bool. When set to `true`, the dashboard loads all panels when the dashboard is loaded. |
| tags | Contains the list of tags associated with dashboard. |
| timeSettings | All time settings for the dashboard. |
| title | Title of the dashboard. |
| variables | Contains the list of configured template variables. |
<!-- prettier-ignore-end -->
### `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](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/json-models/schema-v2/annotations-schema/).
### `elements`
Dashboards can contain the following elements:
- [PanelKind](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/json-models/schema-v2/panel-schema/)
- [LibraryPanelKind](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/json-models/schema-v2/librarypanel-schema/)
### `layout`
Dashboards can have four layout options:
- [GridLayoutKind](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/json-models/schema-v2/layout-schema/#gridlayoutkind)
- [AutoGridLayoutKind](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/json-models/schema-v2/layout-schema/#autogridlayoutkind)
- [RowsLayoutKind](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/json-models/schema-v2/layout-schema/#rowslayoutkind)
- [TabsLayoutKind](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/json-models/schema-v2/layout-schema/#tabslayoutkind)
For the JSON and field usage notes about each of these, refer to the [layout schema documentation](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/json-models/schema-v2/layout-schema/).
### `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](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/json-models/schema-v2/links-schema/).
### `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](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/json-models/schema-v2/timesettings-schema/).
### `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](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/json-models/schema-v2/variables-schema/).
## 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 `kubernetesDashboard` 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 `kubernetesDashboard`
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.

83
docs/sources/observability-as-code/schema-v2/annotations-schema.md Normal file
View File

@ -0,0 +1,83 @@
---
description: A reference for the JSON annotations schema used with Observability as Code.
keywords:
- configuration
- as code
- as-code
- dashboards
- git integration
- git sync
- github
- annotations
labels:
products:
- cloud
- enterprise
- oss
menuTitle: annotations schema
title: annotations
weight: 100
---
# `annotations`
The configuration for the list of annotations that are associated with the dashboard.
```json
"annotations": [
{
"kind": "AnnotationQuery",
"spec": {
"builtIn": false,
"datasource": {
"type": "",
"uid": ""
},
"enable": false,
"hide": false,
"iconColor": "",
"name": ""
}
}
],
```
`AnnotationsQueryKind` consists of:
- kind: "AnnotationQuery"
- spec: [AnnotationQuerySpec](#annotationqueryspec)
## `AnnotationQuerySpec`
| Name | Type/Definition |
| ---------- | ----------------------------------------------------------------- |
| datasource | [`DataSourceRef`](#datasourceref) |
| query | [`DataQueryKind`](#dataquerykind) |
| enable | bool |
| hide | bool |
| iconColor | string |
| name | string |
| builtIn | bool. Default is `false`. |
| filter | [`AnnotationPanelFilter`](#annotationpanelfilter) |
| options | `[string]`: A catch-all field for datasource-specific properties. |
### `DataSourceRef`
| Name | Usage |
| ----- | ---------------------------------- |
| type? | string. The plugin type-id. |
| uid? | The specific data source instance. |
### `DataQueryKind`
| Name | Type |
| ---- | ------ |
| kind | string |
| spec | string |
### `AnnotationPanelFilter`
| Name | Type/Definition |
| -------- | ------------------------------------------------------------------------------ |
| exclude? | bool. Should the specified panels be included or excluded. Default is `false`. |
| ids | `[...uint8]`. Panel IDs that should be included or excluded. |

336
docs/sources/observability-as-code/schema-v2/layout-schema.md Normal file
View File

@ -0,0 +1,336 @@
---
description: A reference for the JSON layout schema used with Observability as Code.
keywords:
- configuration
- as code
- as-code
- dashboards
- git integration
- git sync
- github
- layout
labels:
products:
- cloud
- enterprise
- oss
menuTitle: layout schema
title: layout
weight: 400
---
# `layout`
There are four layout options offering two types of panel control:
**Panel layout options**
These options control the size and position of panels:
- [GridLayoutKind](#gridlayoutkind) - Corresponds to the **Custom** option in the UI. You define panel size and panel positions using x- and y- settings.
- [AutoGridLayoutKind](#autogridlayoutkind) - Corresponds to the **Auto grid** option in the UI. Panel size and position are automatically set based on column and row parameters.
**Panel grouping options**
These options control the grouping of panels:
- [RowsLayoutKind](#rowslayoutkind) - Groups panels into rows.
- [TabsLayoutKind](#tabslayoutkind) - Groups panels into tabs.
## `GridLayoutKind`
The grid layout allows you to manually size and position grid items by setting the height, width, x, and y of each item.
This layout corresponds to the **Custom** option in the UI.
Following is the JSON for a default grid layout, a grid layout item, and a grid layout row:
```json
"kind": "GridLayout",
"spec": {
"items": [
{
"kind": "GridLayoutItem",
"spec": {
"element": {...},
"height": 0,
"width": 0,
"x": 0,
"y": 0
}
},
{
"kind": "GridLayoutRow",
"spec": {
"collapsed": false,
"elements": [],
"title": "",
"y": 0
}
},
]
}
```
`GridLayoutKind` consists of:
- kind: "GridLayout"
- spec: GridLayoutSpec
- items: GridLayoutItemKind` or GridLayoutRowKind`
- GridLayoutItemKind
- kind: "GridLayoutItem"
- spec: [GridLayoutItemSpec](#gridlayoutitemspec)
- GridLayoutRowKind
- kind: "GridLayoutRow"
- spec: [GridLayoutRowSpec](#gridlayoutrowspec)
### `GridLayoutItemSpec`
The following table explains the usage of the grid layout item JSON fields:
| Name | Usage |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| x | integer. Position of the item x-axis. |
| y | integer. Position of the item y-axis. |
| width | Width of the item in pixels. |
| height | Height of the item in pixels. |
| element | `ElementReference`. Reference to a [`PanelKind`](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/json-models/schema-v2/panel-schema/) from `dashboard.spec.elements` expressed as JSON Schema reference. |
| repeat? | [RepeatOptions](#repeatoptions). Configured repeat options, if any |
#### `RepeatOptions`
The following table explains the usage of the repeat option JSON fields:
| Name | Usage |
| ---------- | ---------------------------------------------------- |
| mode | `RepeatMode` - "variable" |
| value | string |
| direction? | Options are `h` for horizontal and `v` for vertical. |
| maxPerRow? | integer |
### `GridLayoutRowSpec`
The following table explains the usage of the grid layout row JSON fields:
<!-- prettier-ignore-start -->
| Name | Usage |
| ---- | ----- |
| y | integer. Position of the row y-axis |
| collapsed | bool. Whether or not the row is collapsed |
| title | Row title |
| elements | [`[...GridLayoutItemKind]`](#gridlayoutitemspec). Grid items in the row will have their y value be relative to the row's y value. This means a panel positioned at `y: 0` in a row with `y: 10` will be positioned at `y: 11` (row header has a height of 1) in the dashboard. |
| repeat? | [RowRepeatOptions](#rowrepeatoptions) Configured row repeat options, if any</p> |
<!-- prettier-ignore-end -->
#### `RowRepeatOptions`
| Name | Usage |
| ----- | ------------------------- |
| mode | `RepeatMode` - "variable" |
| value | string |
## `AutoGridLayoutKind`
With an auto grid, Grafana sizes and positions your panels for the best fit based on the column and row constraints that you set.
This layout corresponds to the **Auto grid** option in the UI.
Following is the JSON for a default auto grid layout and a grid layout item:
<!-- prettier-ignore-end -->
```json
"kind": "AutoGridLayout",
"spec": {
"columnWidthMode": "standard",
"fillScreen": false,
"items": [
{
"kind": "AutoGridLayoutItem",
"spec": {
"element": {...},
}
}
],
"maxColumnCount": 3,
"rowHeightMode": "standard"
}
```
`AutoGridLayoutKind` consists of:
- kind: "AutoGridLayout"
- spec: [AutoGridLayoutSpec](#autogridlayoutspec)
### `AutoGridLayoutSpec`
The following table explains the usage of the auto grid layout JSON fields:
<!-- prettier-ignore-start -->
| Name | Usage |
| ---- | ----- |
| maxColumnCount? | number. Default is `3`. |
| columnWidthMode | Options are: `narrow`, `standard`, `wide`, and `custom`. Default is `standard`. |
| columnWidth? | number |
| rowHeightMode | Options are: `short`, `standard`, `tall`, and `custom`. Default is `standard`. |
| rowHeight? | number |
| fillScreen? | bool. Default is `false`. |
| items | `AutoGridLayoutItemKind`. Consists of:<ul><li>kind: "AutoGridLayoutItem"</li><li>spec: [AutoGridLayoutItemSpec](#autogridlayoutitemspec)</li></ul> |
<!-- prettier-ignore-end -->
#### `AutoGridLayoutItemSpec`
The following table explains the usage of the auto grid layout item JSON fields:
<!-- prettier-ignore-start -->
| Name | Usage |
| ---- | ----- |
| element | `ElementReference`. Reference to a [`PanelKind`](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/json-models/schema-v2/panel-schema/) from `dashboard.spec.elements` expressed as JSON Schema reference. |
| repeat? | [AutoGridRepeatOptions](#autogridrepeatoptions). Configured repeat options, if any. |
| conditionalRendering? | `ConditionalRenderingGroupKind`. Rules for hiding or showing panels, if any. Consists of:<ul><li>kind: "ConditionalRenderingGroup"</li><li>spec: [ConditionalRenderingGroupSpec](#conditionalrenderinggroupspec)</li></ul> |
<!-- prettier-ignore-end -->
##### `AutoGridRepeatOptions`
The following table explains the usage of the auto grid repeat option JSON fields:
| Name | Usage |
| ----- | ------------------------- |
| mode | `RepeatMode` - "variable" |
| value | String |
##### `ConditionalRenderingGroupSpec`
<!-- prettier-ignore-start -->
| Name | Usage |
| ---- | ----- |
| visibility | Options are `show` and `hide` |
| condition | Options are `and` and `or` |
| items | Options are:<ul><li>ConditionalRenderingVariableKind<ul><li>kind: "ConditionalRenderingVariable"</li><li>spec: [ConditionalRenderingVariableSpec](#conditionalrenderingvariablespec)</li></ul></li><li>ConditionalRenderingDataKind<ul><li>kind: "ConditionalRenderingData"</li><li>spec: [ConditionalRenderingDataSpec](#conditionalrenderingdataspec)</li></ul></li><li>ConditionalRenderingTimeRangeSizeKind<ul><li>kind: "ConditionalRenderingTimeRangeSize"</li><li>spec: [ConditionalRenderingTimeRangeSizeSpec](#conditionalrenderingtimerangesizespec)</li></ul></li></ul> |
<!-- prettier-ignore-end -->
###### `ConditionalRenderingVariableSpec`
| Name | Usage |
| -------- | ------------------------------------ |
| variable | string |
| operator | Options are `equals` and `notEquals` |
| value | string |
###### `ConditionalRenderingDataSpec`
| Name | Type |
| ----- | ---- |
| value | bool |
###### `ConditionalRenderingTimeRangeSizeSpec`
| Name | Type |
| ----- | ------ |
| value | string |
## `RowsLayoutKind`
The `RowsLayoutKind` is one of two options that you can use to group panels.
You can nest any other kind of layout inside a layout row.
Rows can also be nested in auto grids or tabs.
Following is the JSON for a default rows layout row:
```json
"kind": "RowsLayout",
"spec": {
"rows": [
{
"kind": "RowsLayoutRow",
"spec": {
"layout": {
"kind": "GridLayout", // Can also be AutoGridLayout or TabsLayout
"spec": {...}
},
"title": ""
}
}
]
}
```
`RowsLayoutKind` consists of:
- kind: RowsLayout
- spec: RowsLayoutSpec
- rows: RowsLayoutRowKind
- kind: RowsLayoutRow
- spec: [RowsLayoutRowSpec](#rowslayoutrowspec)
### `RowsLayoutRowSpec`
The following table explains the usage of the rows layout row JSON fields:
<!-- prettier-ignore-start -->
| Name | Usage |
| ---- | ----- |
| title? | Title of the row. |
| collapse | bool. Whether or not the row is collapsed. |
| hideHeader? | bool. Whether the row header is hidden or shown. |
| fullScreen? | bool. Whether or not the row takes up the full screen. |
| conditionalRendering? | `ConditionalRenderingGroupKind`. Rules for hiding or showing rows, if any. Consists of:<ul><li>kind: "ConditionalRenderingGroup"</li><li>spec: [ConditionalRenderingGroupSpec](#conditionalrenderinggroupspec)</li></ul> |
| repeat? | [RowRepeatOptions](#rowrepeatoptions). Configured repeat options, if any. |
| layout | Supported layouts are:<ul><li>[GridLayoutKind](#gridlayoutkind)</li><li>[RowsLayoutKind](#rowslayoutkind)</li><li>[AutoGridLayoutKind](#autogridlayoutkind)</li><li>[TabsLayoutKind](#tabslayoutkind)</li></ul> |
<!-- prettier-ignore-end -->
## `TabsLayoutKind`
The `TabsLayoutKind` is one of two options that you can use to group panels.
You can nest any other kind of layout inside a tab.
Tabs can also be nested in auto grids or rows.
Following is the JSON for a default tabs layout tab and a tab:
```json
"kind": "TabsLayout",
"spec": {
"tabs": [
{
"kind": "TabsLayoutTab",
"spec": {
"layout": {
"kind": "GridLayout", // Can also be AutoGridLayout or RowsLayout
"spec": {...}
},
"title": "New tab"
}
}
]
}
```
`TabsLayoutKind` consists of:
- kind: TabsLayout
- spec: TabsLayoutSpec
- tabs: TabsLayoutTabKind
- kind: TabsLayoutTab
- spec: [TabsLayoutTabSpec](#tabslayouttabspec)
### `TabsLayoutTabSpec`
The following table explains the usage of the tabs layout tab JSON fields:
<!-- prettier-ignore-start -->
| Name | Usage |
| ---- | ----- |
| title? | The title of the tab. |
| layout | Supported layouts are:<ul><li>[GridLayoutKind](#gridlayoutkind)</li><li>[RowsLayoutKind](#rowslayoutkind)</li><li>[AutoGridLayoutKind](#autogridlayoutkind)</li><li>[TabsLayoutKind](#tabslayoutkind)</li></ul> |
| conditionalRendering? | `ConditionalRenderingGroupKind`. Rules for hiding or showing panels, if any. Consists of:<ul><li>kind: "ConditionalRenderingGroup"</li><li>spec: [ConditionalRenderingGroupSpec](#conditionalrenderinggroupspec)</li></ul> |
<!-- prettier-ignore-end -->

65
docs/sources/observability-as-code/schema-v2/librarypanel-schema.md Normal file
View File

@ -0,0 +1,65 @@
---
description: A reference for the JSON library panel schema used with Observability as Code.
keywords:
- configuration
- as code
- as-code
- dashboards
- git integration
- git sync
- github
- library panel
labels:
products:
- cloud
- enterprise
- oss
menuTitle: LibraryPanelKind schema
title: LibraryPanelKind
weight: 300
---
# `LibraryPanelKind`
A library panel is a reusable panel that you can use in any dashboard.
When you make a change to a library panel, that change propagates to all instances of where the panel is used.
Library panels streamline reuse of panels across multiple dashboards.
Following is the default library panel element JSON:
```json
"kind": "LibraryPanel",
"spec": {
"id": 0,
"libraryPanel": {
name: "",
uid: "",
}
"title": ""
}
```
The `LibraryPanelKind` consists of:
- kind: "LibraryPanel"
- spec: [LibraryPanelKindSpec](#librarypanelkindspec)
- libraryPanel: [LibraryPanelRef](#librarypanelref)
## `LibraryPanelKindSpec`
The following table explains the usage of the library panel element JSON fields:
| Name | Usage |
| ------------ | ------------------------------------------------ |
| id | Panel ID for the library panel in the dashboard. |
| libraryPanel | [`LibraryPanelRef`](#librarypanelref) |
| title | Title for the library panel in the dashboard. |
### `LibraryPanelRef`
The following table explains the usage of the library panel reference JSON fields:
| Name | Usage |
| ---- | ------------------ |
| name | Library panel name |
| uid | Library panel uid |

63
docs/sources/observability-as-code/schema-v2/links-schema.md Normal file
View File

@ -0,0 +1,63 @@
---
description: A reference for the JSON links schema used with Observability as Code.
keywords:
- configuration
- as code
- as-code
- dashboards
- git integration
- git sync
- github
- links
labels:
products:
- cloud
- enterprise
- oss
menuTitle: links schema
title: links
weight: 500
---
# `links`
The `links` schema is the configuration for links with references to other dashboards or external websites.
Following are the default JSON fields:
```json
"links": [
{
"asDropdown": false,
"icon": "",
"includeVars": false,
"keepTime": false,
"tags": [],
"targetBlank": false,
"title": "",
"tooltip": "",
"type": "link",
},
],
```
## `DashboardLink`
The following table explains the usage of the dashboard link JSON fields.
The table includes default and other fields:
<!-- prettier-ignore-start -->
| Name | Usage |
| ----------- | --------------------------------------- |
| title | string. Title to display with the link. |
| type | `DashboardLinkType`. Link type. Accepted values are:<ul><li>dashboards - To refer to another dashboard</li><li>link - To refer to an external resource</li></ul> |
| icon | string. Icon name to be displayed with the link. |
| tooltip | string. Tooltip to display when the user hovers their mouse over it. |
| url? | string. Link URL. Only required/valid if the type is link. |
| tags | string. List of tags to limit the linked dashboards. If empty, all dashboards will be displayed. Only valid if the type is dashboards. |
| asDropdown | bool. If true, all dashboards links will be displayed in a dropdown. If false, all dashboards links will be displayed side by side. Only valid if the type is dashboards. Default is `false`. |
| targetBlank | bool. If true, the link will be opened in a new tab. Default is `false`. |
| includeVars | bool. If true, includes current template variables values in the link as query params. Default is `false`. |
| keepTime | bool. If true, includes current time range in the link as query params. Default is `false`. |
<!-- prettier-ignore-end -->

302
docs/sources/observability-as-code/schema-v2/panel-schema.md Normal file
View File

@ -0,0 +1,302 @@
---
description: A reference for the JSON panel schema used with Observability as Code.
keywords:
- configuration
- as code
- as-code
- dashboards
- git integration
- git sync
- github
- panels
labels:
products:
- cloud
- enterprise
- oss
menuTitle: PanelKind schema
title: PanelKind
weight: 200
---
# `PanelKind`
The panel element contains all the information about the panel including the visualization type, panel and visualization configuration, queries, and transformations.
There's a panel element for each panel contained in the dashboard.
Following is the default panel element JSON:
```json
"kind": "Panel",
"spec": {
"data": {
"kind": "QueryGroup",
"spec": {...},
"description": "",
"id": 0,
"links": [],
"title": "",
"vizConfig": {
"kind": "",
"spec": {...},
}
}
```
The `PanelKind` consists of:
- kind: "Panel"
- spec: [PanelSpec](#panelspec)
## `PanelSpec`
The following table explains the usage of the panel element JSON fields:
<!-- prettier-ignore-start -->
| Name | Usage |
| ------------ | --------------------------------------------------------------------- |
| data | `QueryGroupKind`, which includes queries and transformations. Consists of:<ul><li>kind: "QueryGroup"</li><li>spec: [QueryGroupSpec](#querygroupspec)</li></ul> |
| description | The panel description. |
| id | The panel ID. |
| links | Links with references to other dashboards or external websites. |
| title | The panel title. |
| vizConfig | `VizConfigKind`. Includes visualization type, field configuration options, and all other visualization options. Consists of:<ul><li>kind: string. Plugin ID.</li><li>spec: [VizConfigSpec](#vizconfigspec)</li></ul> |
| transparent? | bool. Controls whether or not the panel background is transparent. |
<!-- prettier-ignore-end -->
### `QueryGroupSpec`
<!-- prettier-ignore-start -->
| Name | Usage |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| queries | `PanelQueryKind`. Consists of:<ul><li>kind: PanelQuery</li><li>spec: [PanelQuerySpec](#panelqueryspec)</li></ul> |
| transformations | `TransformationKind`. Consists of:<ul><li>kind: string. The transformation ID.</li><li>spec: [DataTransformerConfig](#datatransformerconfig)</li></ul> |
| queryOptions | [`QueryOptionsSpec`](#queryoptionsspec) |
<!-- prettier-ignore-end -->
#### `PanelQuerySpec`
| Name | Usage |
| ----------- | --------------------------------- |
| query | [`DataQueryKind`](#dataquerykind) |
| datasource? | [`DataSourceRef`](#datasourceref) |
##### `DataQueryKind`
| Name | Type |
| ---- | ------ |
| kind | string |
| spec | string |
##### `DataSourceRef`
| Name | Usage |
| ----- | ---------------------------------- |
| type? | string. The plugin type-id. |
| uid? | The specific data source instance. |
#### `DataTransformerConfig`
Transformations allow you to manipulate data returned by a query before the system applies a visualization.
Using transformations you can: rename fields, join time series data, perform mathematical operations across queries, or use the output of one transformation as the input to another transformation.
<!-- prettier-ignore-start -->
| Name | Usage |
| --------- | ------------------------------------------- |
| id | string. Unique identifier of transformer. |
| disabled? | bool. Disabled transformations are skipped. |
| filter? | [`MatcherConfig`](#matcherconfig). Optional frame matcher. When missing it will be applied to all results. |
| topic? | `DataTopic`. Where to pull `DataFrames` from as input to transformation. Options are: `series`, `annotations`, and `alertStates`. |
| options | Options to be passed to the transformer. Valid options depend on the transformer id. |
<!-- prettier-ignore-end -->
##### `MatcherConfig`
Matcher is a predicate configuration.
Based on the configuration a set of field or values, it's filtered to apply an override or transformation.
It comes with in id (to resolve implementation from registry) and a configuration that’s specific to a particular matcher type.
| Name | Usage |
| -------- | -------------------------------------------------------------------------------------- |
| id | string. The matcher id. This is used to find the matcher implementation from registry. |
| options? | The matcher options. This is specific to the matcher implementation. |
#### `QueryOptionsSpec`
| Name | Type |
| ----------------- | ------- |
| timeFrom? | string |
| maxDataPoints? | integer |
| timeShift? | string |
| queryCachingTTL? | integer |
| interval? | string |
| cacheTimeout? | string |
| hideTimeOverride? | bool |
### `VizConfigSpec`
| Name | Type/Definition |
| ------------- | --------------------------------------- |
| pluginVersion | string |
| options | string |
| fieldConfig | [FieldConfigSource](#fieldconfigsource) |
#### `FieldConfigSource`
The data model used in Grafana, namely the _data frame_, is a columnar-oriented table structure that unifies both time series and table query results.
Each column within this structure is called a field.
A field can represent a single time series or table column.
Field options allow you to change how the data is displayed in your visualizations.
<!-- prettier-ignore-start -->
| Name | Type/Definition |
| ---------- | ------------------------------------- |
| defaults | [`FieldConfig`](#fieldconfig). Defaults are the options applied to all fields. |
| overrides | The options applied to specific fields overriding the defaults. |
| matcher | [`MatcherConfig`](#matcherconfig). Optional frame matcher. When missing it will be applied to all results. |
| properties | `DynamicConfigValue`. Consists of:<ul><li>`id` - string</li><li>value?</li></ul> |
<!-- prettier-ignore-end -->
##### `FieldConfig`
<!-- prettier-ignore-start -->
| Name | Type/Definition |
| ------------------ | --------------------------------------- |
| displayName? | string. The display value for this field. This supports template variables where empty is auto. |
| displayNameFromDS? | string. This can be used by data sources that return an explicit naming structure for values and labels. When this property is configured, this value is used rather than the default naming strategy. |
| description? | string. Human readable field metadata. |
| path? | string. An explicit path to the field in the data source. When the frame meta includes a path, this will default to `${frame.meta.path}/${field.name}`. When defined, this value can be used as an identifier within the data source scope, and may be used to update the results. |
| writeable? | bool. True if the data source can write a value to the path. Auth/authz are supported separately. |
| filterable? | bool. True if the data source field supports ad-hoc filters. |
| unit? | string. Unit a field should use. The unit you select is applied to all fields except time. You can use the unit's ID available in Grafana or a custom unit. [Available units in Grafana](https://github.com/grafana/grafana/blob/main/packages/grafana-data/src/valueFormats/categories.ts). As custom units, you can use the following formats:<ul><li>`suffix:<suffix>` for custom unit that should go after value.</li><li>`prefix:<prefix>` for custom unit that should go before value.</li><li> `time:<format>` for custom date time formats type for example</li><li>`time:YYYY-MM-DD`</li><li>`si:<base scale><unit characters>` for custom SI units. For example: `si: mF`. You can specify both a unit and the source data scale, so if your source data is represented as milli (thousands of) something, prefix the unit with that SI scale character.</li><li>`count:<unit>` for a custom count unit.</li><li>`currency:<unit>` for custom a currency unit.</li></ul> |
| decimals? | number. Specify the number of decimals Grafana includes in the rendered value. If you leave this field blank, Grafana automatically truncates the number of decimals based on the value. For example 1.1234 will display as 1.12 and 100.456 will display as 100. To display all decimals, set the unit to `string`. |
| min? | number. The minimum value used in percentage threshold calculations. Leave empty for auto calculation based on all series and fields. |
| max? | number. The maximum value used in percentage threshold calculations. Leave empty for auto calculation based on all series and fields. |
| mappings? | `[...ValueMapping]`. Convert input values into a display string. Options are: [`ValueMap`](#valuemap), [`RangeMap`](#rangemap), [`RegexMap`](#rangemap), [`SpecialValueMap`](#specialvaluemap). |
| thresholds? | `ThresholdsConfig`. Map numeric values to states. Consists of:<ul><li>`mode` - `ThresholdsMode`. Options are: `absolute` and `percentage`.</li><li>`steps` - `[...Threshold]`</li></ul> |
| color? | [`FieldColor`](#fieldcolor). Panel color configuration. |
| links? | `[...]`. The behavior when clicking a result. |
| noValue? | string. Alternative to an empty string. |
| custom? | `{...}`. Specified by the `FieldConfig` field in panel plugin schemas. |
<!-- prettier-ignore-end -->
###### `ValueMap`
Maps text values to a color or different display text and color.
For example, you can configure a value mapping so that all instances of the value 10 appear as Perfection! rather than the number.
<!-- prettier-ignore-start -->
| Name | Usage |
| ------- | -------- |
| type | `MappingType` & "value". `MappingType` options are: `value`, `range`, `regex`, and `special`. |
| options | string. [`ValueMappingResult`](#valuemappingresult). Map with `<value_to_match>`: `ValueMappingResult`. For example: `{ "10": { text: "Perfection!", color: "green" } }`. |
<!-- prettier-ignore-end -->
###### `RangeMap`
Maps numerical ranges to a display text and color.
For example, if a value is within a certain range, you can configure a range value mapping to display Low or High rather than the number.
<!-- prettier-ignore-start -->
| Name | Usage |
| ------- | ---------------------------------------------------------------------------------------------------- |
| type | `MappingType` & "range". `MappingType` options are: `value`, `range`, `regex`, and `special`. |
| options | Range to match against and the result to apply when the value is within the range. Spec:<ul><li>`from` - `float64` or `null`. Min value of the range. It can be null which means `-Infinity`.</li><li>`to` - `float64` or `null`. Max value of the range. It can be null which means `+Infinity`.</li><li>`result` - [`ValueMappingResult`](#valuemappingresult) |
<!-- prettier-ignore-end -->
###### `RegexMap`
Maps regular expressions to replacement text and a color.
For example, if a value is `www.example.com`, you can configure a regex value mapping so that Grafana displays www and truncates the domain.
<!-- prettier-ignore-start -->
| Name | Usage |
| ------- | --------------------------------------------------------------------------------------------- |
| type | `MappingType` & "regex". `MappingType` options are: `value`, `range`, `regex`, and `special`. |
| options | Regular expression to match against and the result to apply when the value matches the regex. Spec:<ul><li>`pattern` - string. Regular expression to match against.</li><li>`result` - [`ValueMappingResult`](#valuemappingresult) |
<!-- prettier-ignore-end -->
###### `SpecialValueMap`
Maps special values like Null, NaN (not a number), and boolean values like true and false to a display text and color.
See `SpecialValueMatch` in the following table to see the list of special values.
For example, you can configure a special value mapping so that null values appear as N/A.
<!-- prettier-ignore-start -->
| Name | Usage |
| ------- | ----------------------------------------------------------------------------------------------- |
| type | `MappingType` & "special". `MappingType` options are: `value`, `range`, `regex`, and `special`. |
| options | Spec:<ul><li>`match` - `SpecialValueMatch`. Special value to match against. Types are:<ul><li>true</li><li>false</li><li>null</li><li>nan</li><li>empty</li></ul> </li><li>`result` - [`ValueMappingResult`](#valuemappingresult) |
<!-- prettier-ignore-end -->
###### `ValueMappingResult`
Result used as replacement with text and color when the value matches.
| Name | Usage |
| ----- | ----------------------------------------------------------------------------- |
| text | string. Text to display when the value matches. |
| color | string. Color to use when the value matches. |
| icon | string. Icon to display when the value matches. Only specific visualizations. |
| index | int32. Position in the mapping array. Only used internally. |
###### `FieldColor`
Map a field to a color.
<!-- prettier-ignore-start -->
| Name | Usage |
| ----------- | -------------------------------------------------------------------- |
| mode | [`FieldColorModeId`](#fieldcolormodeid). The main color scheme mode. |
| FixedColor? | string. The fixed color value for fixed or shades color modes. |
| seriesBy? | `FieldColorSeriesByMode`. Some visualizations need to know how to assign a series color from by value color schemes. Defines how to assign a series color from "by value" color schemes. For example for an aggregated data points like a timeseries, the color can be assigned by the min, max or last value. Options are: `min`, `max`, and `last`. |
<!-- prettier-ignore-end -->
###### `FieldColorModeId`
Color mode for a field.
You can specify a single color, or select a continuous (gradient) color schemes, based on a value.
Continuous color interpolates a color using the percentage of a value relative to min and max.
Accepted values are:
<!-- prettier-ignore-start -->
| Name | Description |
| --- | ---- |
| thresholds | From thresholds. Informs Grafana to take the color from the matching threshold. |
| palette-classic | Classic palette. Grafana will assign color by looking up a color in a palette by series index. Useful for graphs and pie charts and other categorical data visualizations. |
| palette-classic-by-name | Classic palette (by name). Grafana will assign color by looking up a color in a palette by series name. Useful for Graphs and pie charts and other categorical data visualizations |
| continuous-GrYlRd | Continuous Green-Yellow-Red palette mode |
| continuous-RdYlGr | Continuous Red-Yellow-Green palette mode |
| continuous-BlYlRd | Continuous Blue-Yellow-Red palette mode |
| continuous-YlRd | Continuous Yellow-Red palette mode |
| continuous-BlPu | Continuous Blue-Purple palette mode |
| continuous-YlBl | Continuous Yellow-Blue palette mode |
| continuous-blues | Continuous Blue palette mode |
| continuous-reds | Continuous Red palette mode |
| continuous-greens | Continuous Green palette mode |
| continuous-purples | Continuous Purple palette mode |
| shades | Shades of a single color. Specify a single color, useful in an override rule. |
| fixed | Fixed color mode. Specify a single color, useful in an override rule. |
<!-- prettier-ignore-end -->

84
docs/sources/observability-as-code/schema-v2/timesettings-schema.md Normal file
View File

@ -0,0 +1,84 @@
---
description: A reference for the JSON timesettings schema used with Observability as Code.
keywords:
- configuration
- as code
- as-code
- dashboards
- git integration
- git sync
- github
- time settings
labels:
products:
- cloud
- enterprise
- oss
menuTitle: timesettings schema
title: timesettings
weight: 600
---
# `timeSettings`
The `TimeSettingsSpec` defines the default time configuration for the time picker and the refresh picker for the specific dashboard.
Following is the JSON for default time settings:
```json
"timeSettings": {
"autoRefresh": "",
"autoRefreshIntervals": [
"5s",
"10s",
"30s",
"1m",
"5m",
"15m",
"30m",
"1h",
"2h",
"1d"
],
"fiscalYearStartMonth": 0,
"from": "now-6h",
"hideTimepicker": false,
"timezone": "browser",
"to": "now"
},
```
`timeSettings` consists of:
- [TimeSettingsSpec](#timesettingsspec)
## `TimeSettingsSpec`
The following table explains the usage of the time settings JSON fields:
<!-- prettier-ignore-start -->
| Name | Usage |
| ---- | ----- |
| timezone? | string. Timezone of dashboard. Accepted values are IANA TZDB zone ID, `browser`, or `utc`. Default is `browser`. |
| from | string. Start time range for dashboard. Accepted values are relative time strings like `now-6h` or absolute time strings like `2020-07-10T08:00:00.000Z`. Default is `now-6h`. |
| to | string. End time range for dashboard. Accepted values are relative time strings like `now-6h` or absolute time strings like `2020-07-10T08:00:00.000Z`. Default is `now`. |
| autoRefresh | string. Refresh rate of dashboard. Represented by interval string. For example: `5s`, `1m`, `1h`, `1d`. No default. In schema v1: `refresh`. |
| autoRefreshIntervals | string. Interval options available in the refresh picker drop-down menu. The default array is `["5s", "10s", "30s", "1m", "5m", "15m", "30m", "1h", "2h", "1d"]`. |
|quickRanges? | Selectable options available in the time picker drop-down menu. Has no effect on provisioned dashboard. Defined in the [`TimeRangeOption`](#timerangeoption) spec. In schema v1: `timepicker.quick_ranges`, not exposed in the UI. |
| hideTimepicker | bool. Whether or not the time picker is visible. Default is `false`. In schema v1: `timepicker.hidden`. |
| weekStart? | Day when the week starts. Expressed by the name of the day in lowercase. For example: `monday`. Options are `saturday`, `monday`, and `sunday`. |
| fiscalYearStartMonth | The month that the fiscal year starts on. `0` = January, `11` = December |
| nowDelay? | string. Override the "now" time by entering a time delay. Use this option to accommodate known delays in data aggregation to avoid null values. In schema v1: `timepicker.nowDelay`. |
<!-- prettier-ignore-end -->
### `TimeRangeOption`
The following table explains the usage of the time range option JSON fields:
| Name | Usage |
| ------- | ---------------------------------- |
| display | string. Default is `Last 6 hours`. |
| from | string. Default is `now-6h`. |
| to | string. Default is `now`. |

453
docs/sources/observability-as-code/schema-v2/variables-schema.md Normal file
View File

@ -0,0 +1,453 @@
---
description: A reference for the JSON variables schema used with Observability as Code.
keywords:
- configuration
- as code
- as-code
- dashboards
- git integration
- git sync
- github
- variables
labels:
products:
- cloud
- enterprise
- oss
menuTitle: variables schema
title: variables
weight: 700
---
# `variables`
The available variable types described in the following sections:
- [QueryVariableKind](#queryvariablekind)
- [TextVariableKind](#textvariablekind)
- [ConstantVariableKind](#constantvariablekind)
- [DatasourceVariableKind](#datasourcevariablekind)
- [IntervalVariableKind](#intervalvariablekind)
- [CustomVariableKind](#customvariablekind)
- [GroupByVariableKind](#groupbyvariablekind)
- [AdhocVariableKind](#adhocvariablekind)
## `QueryVariableKind`
Following is the JSON for a default query variable:
```json
"variables": [
{
"kind": "QueryVariable",
"spec": {
"current": {
"text": "",
"value": ""
},
"hide": "dontHide",
"includeAll": false,
"multi": false,
"name": "",
"options": [],
"query": defaultDataQueryKind(),
"refresh": "never",
"regex": "",
"skipUrlSync": false,
"sort": "disabled"
}
}
]
```
`QueryVariableKind` consists of:
- kind: "QueryVariable"
- spec: [QueryVariableSpec](#queryvariablespec)
### `QueryVariableSpec`
The following table explains the usage of the query variable JSON fields:
<!-- prettier-ignore-start -->
| Name | Usage |
| ------------ | ---------------------------------------------- |
| name | string. Name of the variable. |
| current | "Text" and a "value" or [`VariableOption`](#variableoption) |
| label? | string |
| hide | `VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`. |
| refresh | `VariableRefresh`. Options are `never`, `onDashboardLoad`, and `onTimeChanged`. |
| skipUrlSync | bool. Default is `false`. |
| description? | string |
| datasource? | [`DataSourceRef`](#datasourceref) |
| query | `DataQueryKind`. Consists of:<ul><li>kind: string</li><li>spec: string</li></ul> |
| regex | string |
| sort | `VariableSort`. Options are:<ul><li>disabled</li><li>alphabeticalAsc</li><li>alphabeticalDesc</li><li>numericalAsc</li><li>numericalDesc</li><li>alphabeticalCaseInsensitiveAsc</li><li>alphabeticalCaseInsensitiveDesc</li><li>naturalAsc</li><li>naturalDesc</li></ul> |
| definition? | string |
| options | [`VariableOption`](#variableoption) |
| multi | bool. Default is `false`. |
| includeAll | bool. Default is `false`. |
| allValue? | string |
| placeholder? | string |
<!-- prettier-ignore-end -->
#### `VariableOption`
| Name | Usage |
| -------- | -------------------------------------------- |
| selected | bool. Whether or not the option is selected. |
| text | string. Text to be displayed for the option. |
| value | string. Value of the option. |
#### `DataSourceRef`
| Name | Usage |
| ----- | ---------------------------------- |
| type? | string. The plugin type-id. |
| uid? | The specific data source instance. |
## `TextVariableKind`
Following is the JSON for a default text variable:
```json
"variables": [
{
"kind": "TextVariable",
"spec": {
"current": {
"text": "",
"value": ""
},
"hide": "dontHide",
"name": "",
"query": "",
"skipUrlSync": false
}
}
]
```
`TextVariableKind` consists of:
- kind: TextVariableKind
- spec: [TextVariableSpec](#textvariablespec)
### `TextVariableSpec`
The following table explains the usage of the query variable JSON fields:
| Name | Usage |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| name | string. Name of the variable. |
| current | "Text" and a "value" or `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) under `QueryVariableKind`. |
| query | string |
| label? | string |
| hide | `VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`. |
| skipUrlSync | bool. Default is `false`. |
| description? | string |
## `ConstantVariableKind`
Following is the JSON for a default constant variable:
```json
"variables": [
{
"kind": "ConstantVariable",
"spec": {
"current": {
"text": "",
"value": ""
},
"hide": "hideVariable",
"name": "",
"query": "",
"skipUrlSync": true
}
}
]
```
`ConstantVariableKind` consists of:
- kind: "ConstantVariable"
- spec: [ConstantVariableSpec](#constantvariablespec)
### `ConstantVariableSpec`
The following table explains the usage of the constant variable JSON fields:
| Name | Usage |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| name | string. Name of the variable. |
| query | string |
| current | "Text" and a "value" or `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) under `QueryVariableKind`. |
| label? | string |
| hide | `VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`. |
| skipUrlSync | bool. Default is `false`. |
| description? | string |
## `DatasourceVariableKind`
Following is the JSON for a default data source variable:
```json
"variables": [
{
"kind": "DatasourceVariable",
"spec": {
"current": {
"text": "",
"value": ""
},
"hide": "dontHide",
"includeAll": false,
"multi": false,
"name": "",
"options": [],
"pluginId": "",
"refresh": "never",
"regex": "",
"skipUrlSync": false
}
}
]
```
`DatasourceVariableKind` consists of:
- kind: "DatasourceVariable"
- spec: [DatasourceVariableSpec](#datasourcevariablespec)
### `DatasourceVariableSpec`
The following table explains the usage of the data source variable JSON fields:
| Name | Usage |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| name | string. Name of the variable. |
| pluginId | string |
| refresh | `VariableRefresh`. Options are `never`, `onDashboardLoad`, and `onTimeChanged`. |
| regex | string |
| current | `Text` and a `value` or `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) under `QueryVariableKind`. |
| options | `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) under `QueryVariableKind`. |
| multi | bool. Default is `false`. |
| includeAll | bool. Default is `false`. |
| allValue? | string |
| label? | string |
| hide | `VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`. |
| skipUrlSync | bool. Default is `false`. |
| description? | string |
## `IntervalVariableKind`
Following is the JSON for a default interval variable:
```json
"variables": [
{
"kind": "IntervalVariable",
"spec": {
"auto": false,
"auto_count": 0,
"auto_min": "",
"current": {
"text": "",
"value": ""
},
"hide": "dontHide",
"name": "",
"options": [],
"query": "",
"refresh": "never",
"skipUrlSync": false
}
}
]
```
`IntervalVariableKind` consists of:
- kind: "IntervalVariable"
- spec: [IntervalVariableSpec](#intervalvariablespec)
### `IntervalVariableSpec`
The following table explains the usage of the interval variable JSON fields:
| Name | Usage |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| name | string. Name of the variable. |
| query | string |
| current | `Text` and a `value` or `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) under `QueryVariableKind`. |
| options | `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) under `QueryVariableKind`. |
| auto | bool. Default is `false`. |
| auto_count | integer. Default is `0`. |
| refresh | `VariableRefresh`. Options are `never`, `onDashboardLoad`, and `onTimeChanged`. |
| label? | string |
| hide | `VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`. |
| skipUrlSync | bool. Default is `false` |
| description? | string |
## `CustomVariableKind`
Following is the JSON for a default custom variable:
```json
"variables": [
{
"kind": "CustomVariable",
"spec": {
"current": defaultVariableOption(),
"hide": "dontHide",
"includeAll": false,
"multi": false,
"name": "",
"options": [],
"query": "",
"skipUrlSync": false
}
}
]
```
`CustomVariableKind` consists of:
- kind: "CustomVariable"
- spec: [CustomVariableSpec](#customvariablespec)
### `CustomVariableSpec`
The following table explains the usage of the custom variable JSON fields:
| Name | Usage |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| name | string. Name of the variable. |
| query | string |
| current | `Text` and a `value` or `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) under `QueryVariableKind`. |
| options | `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) under `QueryVariableKind`. |
| multi | bool. Default is `false`. |
| includeAll | bool. Default is `false`. |
| allValue? | string |
| label? | string |
| hide | `VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`. |
| skipUrlSync | bool. Default is `false`. |
| description? | string |
## `GroupByVariableKind`
Following is the JSON for a default group by variable:
```json
"variables": [
{
"kind": "GroupByVariable",
"spec": {
"current": {
"text": [
""
],
"value": [
""
]
},
"datasource": {},
"hide": "dontHide",
"multi": false,
"name": "",
"options": [],
"skipUrlSync": false
}
}
]
```
`GroupByVariableKind` consists of:
- kind: "GroupByVariable"
- spec: [GroupByVariableSpec](#groupbyvariablespec)
### `GroupByVariableSpec`
The following table explains the usage of the group by variable JSON fields:
| Name | Usage |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| name | string. Name of the variable |
| datasource? | `DataSourceRef`. Refer to the [`DataSourceRef` definition](#datasourceref) under `QueryVariableKind`. |
| current | `Text` and a `value` or `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) under `QueryVariableKind`. |
| options | `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) under `QueryVariableKind`. |
| multi | bool. Default is `false`. |
| label? | string |
| hide | `VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`. |
| skipUrlSync | bool. Default is `false`. |
| description? | string. |
## `AdhocVariableKind`
Following is the JSON for a default ad hoc variable:
```json
"variables": [
{
"kind": "AdhocVariable",
"spec": {
"baseFilters": [],
"defaultKeys": [],
"filters": [],
"hide": "dontHide",
"name": "",
"skipUrlSync": false
}
}
]
```
`AdhocVariableKind` consists of:
- kind: "AdhocVariable"
- spec: [AdhocVariableSpec](#adhocvariablespec)
### `AdhocVariableSpec`
The following table explains the usage of the ad hoc variable JSON fields:
| Name | Usage |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| name | string. Name of the variable. |
| datasource? | `DataSourceRef`. Consists of:<ul><li>type? - string. The plugin type-id.</li><li>uid? - string. The specific data source instance.</li></ul> |
| baseFilters | [AdHocFilterWithLabels](#adhocfilterswithlabels) |
| filters | [AdHocFilterWithLabels](#adhocfilterswithlabels) |
| defaultKeys | [MetricFindValue](#metricfindvalue) |
| label? | string |
| hide | `VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`. |
| skipUrlSync | bool. Default is `false`. |
| description? | string |
#### `AdHocFiltersWithLabels`
The following table explains the usage of the ad hoc variable with labels JSON fields:
| Name | Type |
| ------------ | ------------- |
| key | string |
| operator | string |
| value | string |
| values? | `[...string]` |
| keyLabel | string |
| valueLabels? | `[...string]` |
| forceEdit? | bool |
#### `MetricFindValue`
The following table explains the usage of the metric find value JSON fields:
| Name | Type |
| ----------- | ---------------- |
| text | string |
| value? | string or number |
| group? | string |
| expandable? | bool |