grafana/dashboard-schemas

Dashboard Schemas

Schema description documents for Grafana Dashboard JSON and core panels.

Note: This directory is experimental. The schemas are not currently implemented or enforced in Grafana.

Schemas are defined in Cue. Cue was chosen because it strongly facilitates our primary use cases - schema definition, data validation, and code generation/extraction.

Schema Organization

Each schema describes part of a dashboard. Dashboard.cue is the main dashboard schema object. All other schemas describe nested objects within a dashboard. They are grouped in the following directories:

• panels - schemas for panels.
• targets - targets represent queries. Each data source type has a unique target schema.
• variables - schemas for variables.
• transformations - schemas for transformations.

The following somewhat conveys how they fit together when constructing a dashboard:

+-----------+      +-----------+
| Dashboard +------> Variables |
+---------+-+      +-----------+
          |    +--------+    +---------+
          +----> Panels +----> Targets |
               +------+-+    +---------+
                      |      +-----------------+
                      +------> Transformations |
                             +-----------------+

Definitions

All schemas are Cue definitions. Schemas intended to be exported must begin with a capital letter. For example, Gauge. Definitions beginning with a lowercase letter will not be exported. These are reusable components for constructing the exported definitions. For example, #panel is intended to be a base schema for panels. #Gauge extends #panel with the following:

#Gauge: panel & {
	...
}

Exporting OpenAPI

OpenAPI schemas can be exported from these CUE sources.

Command Line

While you can use cue export to output OpenAPI documents, it does not expand references which makes the output unusable.

cue export --out openapi -o - ./...

Using Go

You need to use Go to generate useable OpenAPI schemas. This directory contains a Go program that will output just the OpenAPI schemas for one or many Cue packages.

go run . <entrypoint> ...