diff --git a/docs/sources/visualizations/dashboards/build-dashboards/view-dashboard-json-model/index.md b/docs/sources/visualizations/dashboards/build-dashboards/view-dashboard-json-model/index.md index 77279767846..4075461be31 100644 --- a/docs/sources/visualizations/dashboards/build-dashboards/view-dashboard-json-model/index.md +++ b/docs/sources/visualizations/dashboards/build-dashboards/view-dashboard-json-model/index.md @@ -56,6 +56,10 @@ This is because of the evolution of the dashboard JSON schema. - **Classic**: The classic or v1 JSON schema. This schema was used by dashboards created before the dashboards experience released experimentally in Grafana v 12.0. - **V1 Resource**: The classic or v1 schema, using the resources structure. The legacy schema is included under the `spec` property of the V1 Resource. This schema is the one used by all dashboards created using the classic schema within the new editing experience. +{{< admonition type="note" >}} +[Observability as Code](https://grafana.com/docs/grafana/latest/as-code/observability-as-code/) works with all versions of the JSON model, and it's fully compatible with version 2. +{{ /admonition }} + ## Access and update the JSON model (#view-json) To access the JSON representation of a dashboard: @@ -66,7 +70,7 @@ To access the JSON representation of a dashboard: 1. Update the JSON structure as needed. 1. Click **Save changes**. -## JSON Schema v2 (Dashboard JSON schema v2) +## V2 Resource (JSON schema v2) {{< admonition type="caution" >}} @@ -78,8 +82,6 @@ Dashboard JSON schema v2 is an [experimental](https://grafana.com/docs/release-l To view the detailed v2 JSON schema, refer to the [Swagger documentation](https://play.grafana.org/swagger?api=dashboard.grafana.app-v2beta1). -[Observability as Code](https://grafana.com/) 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. @@ -118,13 +120,79 @@ From the UI, dashboards created on schema v2 can be exported and imported like o 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. -## JSON Resourve v1 +## V1 Resource -TBD +To view the detailed V1 Resource schema, refer to the [Swagger documentation](https://play.grafana.org/swagger?api=dashboard.grafana.app-v1beta1). -## Classic JSON fields {#json-fields} +When you open a dashboard created before (version?) using the new editing experience, the schema uses the Kubernetes-style structure and includes the classic schema (v1 schema) under the `spec` property: -When a user creates a new dashboard, a new dashboard JSON object is initialized with the following fields: +```json +{ + "apiVersion": "dashboard.grafana.app/v1beta1", + "kind": "Dashboard", + "metadata": { + "name": "isnt5ss", + "namespace": "stacks-521104", + "uid": "92674c0e-0360-4bb4-99ab-fb150581376d", + "resourceVersion": "1764705030717045", + "generation": 1, + "creationTimestamp": "2025-12-02T19:50:30Z", + "labels": { + "grafana.app/deprecatedInternalID": "1329" + }, + "annotations": { + "grafana.app/createdBy": "user:u000000002", + "grafana.app/folder": "", + "grafana.app/saved-from-ui": "Grafana Cloud (instant)" + } + }, + "spec": { + "annotations": { + "list": [ + { + "builtIn": 1, + "datasource": { + "type": "grafana", + "uid": "-- Grafana --" + }, + "enable": true, + "hide": true, + "iconColor": "rgba(0, 211, 255, 1)", + "name": "Annotations & Alerts", + "type": "dashboard" + } + ] + }, + "editable": true, + "fiscalYearStartMonth": 0, + "graphTooltip": 0, + "id": 1329, + "links": [], + "panels": [], + "preload": false, + "schemaVersion": 42, + "tags": [], + "templating": { + "list": [] + }, + "time": { + "from": "now-6h", + "to": "now" + }, + "timepicker": {}, + "timezone": "Africa/Abidjan", + "title": "Graphite suggestions", + "uid": "isnt5ss", + "version": 1, + "weekStart": "" + }, + "status": {} +} +``` + +## Classic JSON (Schema v1) {#json-fields} + +Before (version?), when you created a new dashboard, a new dashboard JSON object was initialized with the following fields: {{< admonition type="note" >}} In the following JSON, id is shown as null which is the default value assigned to it until a dashboard is saved. Once a dashboard is saved, an integer value is assigned to the `id` field. @@ -162,24 +230,28 @@ In the following JSON, id is shown as null which is the default value assigned t Each field in the dashboard JSON is explained below with its usage: -| Name | Usage | -| ----------------- | ----------------------------------------------------------------------------------------------------------------- | -| **id** | unique numeric identifier for the dashboard. (generated by the db) | -| **uid** | unique dashboard identifier that can be generated by anyone. string (8-40) | -| **title** | current title of dashboard | -| **tags** | tags associated with dashboard, an array of strings | -| **style** | theme of dashboard, i.e. `dark` or `light` | -| **timezone** | timezone of dashboard, i.e. `utc` or `browser` | -| **editable** | whether a dashboard is editable or not | + + +| Name | Usage | +| ----------------- | ------------------------------------------------------------------------------------------ | +| **id** | unique numeric identifier for the dashboard. (generated by the db) | +| **uid** | unique dashboard identifier that can be generated by anyone. string (8-40) | +| **title** | current title of dashboard | +| **tags** | tags associated with dashboard, an array of strings | +| **style** | theme of dashboard, i.e. `dark` or `light` | +| **timezone** | timezone of dashboard, i.e. `utc` or `browser` | +| **editable** | whether a dashboard is editable or not | | **graphTooltip** | 0 for no shared crosshair or tooltip (default), 1 for shared crosshair, 2 for shared crosshair AND shared tooltip | -| **time** | time range for dashboard, i.e. last 6 hours, last 7 days, etc | -| **timepicker** | timepicker metadata, see [timepicker section](#timepicker) for details | -| **templating** | templating metadata, see [templating section](#templating) for details | -| **annotations** | annotations metadata, see [annotations](ref:annotations) for how to add them | -| **refresh** | auto-refresh interval | -| **schemaVersion** | version of the JSON schema (integer), incremented each time a Grafana update brings changes to said schema | -| **version** | version of the dashboard (integer), incremented each time the dashboard is updated | -| **panels** | panels array, see below for detail. | +| **time** | time range for dashboard, i.e. last 6 hours, last 7 days, etc | +| **timepicker** | timepicker metadata, see [timepicker section](#timepicker) for details | +| **templating** | templating metadata, see [templating section](#templating) for details | +| **annotations** | annotations metadata, see [annotations](ref:annotations) for how to add them | +| **refresh** | auto-refresh interval| +| **schemaVersion** | version of the JSON schema (integer), incremented each time a Grafana update brings changes to said schema | +| **version** | version of the dashboard (integer), incremented each time the dashboard is updated | +| **panels** | panels array, see below for detail. | + + ### Panels @@ -254,18 +326,22 @@ The grid has a negative gravity that moves panels up if there is empty space abo Usage of the fields is explained below: -| Name | Usage | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -| **collapse** | whether timepicker is collapsed or not | -| **enable** | whether timepicker is enabled or not | -| **notice** | | -| **now** | | -| **hidden** | whether timepicker is hidden or not | -| **nowDelay** | override the now time by entering a time delay. Use this option to accommodate known delays in data aggregation to avoid null values. | -| **quick_ranges** | custom quick ranges | -| **refresh_intervals** | interval options available in the refresh picker dropdown | -| **status** | | -| **type** | | + + +| Name | Usage | +| --------------------- | --------------------------------------------------------- | +| **collapse** | whether timepicker is collapsed or not | +| **enable** | whether timepicker is enabled or not | +| **notice** | | +| **now** | | +| **hidden** | whether timepicker is hidden or not | +| **nowDelay** | override the now time by entering a time delay. Use this option to accommodate known delays in data aggregation to avoid null values. | +| **quick_ranges** | custom quick ranges | +| **refresh_intervals** | interval options available in the refresh picker dropdown | +| **status** | | +| **type** | | + + ### templating