Grafana dashboard schema with composed core plugin schemas, less optional fields

dashboard.cue

{
	// Theme of dashboard.
	style: *"light" | "dark"
	// Whether a dashboard is editable or not.
	editable: *true | bool
	// 0 for no shared crosshair or tooltip (default).
	// 1 for shared crosshair.
	// 2 for shared crosshair AND shared tooltip.
	graphTooltip: *0 | >=0 & <=2
	// Version of the JSON schema, incremented each time a Grafana update brings
	// changes to said schema.
	// FIXME this is the old schema numbering system, and will be replaced by scuemata
	schemaVersion: *30 | number

	// TODO docs
	#FieldColorModeId: "thresholds" | "palette-classic" | "palette-saturated" | "continuous-GrYlRd" | "fixed"

	// TODO docs
	#FieldColorSeriesByMode: "min" | "max" | "last"

	// TODO docs
	#FieldColor: {
		// The main color scheme mode
		mode: "thresholds" | "palette-classic" | "palette-saturated" | "continuous-GrYlRd" | "fixed" | string
	}

	// TODO docs
	#Threshold: {
		// TODO docs
		color: string
	}
	#ThresholdsMode: "absolute" | "percentage"
	#ThresholdsConfig: {
		mode: "absolute" | "percentage"

		// Must be sorted by 'value', first value is always -Infinity
		steps: [...]
	}

	// TODO docs
	// FIXME this is extremely underspecfied; wasn't obvious which typescript types corresponded to it
	#Transformation: {
		id: string
		options: {}
	}

	// Schema for panel targets is specified by datasource
	// plugins. We use a placeholder definition, which the Go
	// schema loader either left open/as-is with the Base
	// variant of the Dashboard and Panel families, or filled
	// with types derived from plugins in the Instance variant.
	// When working directly from CUE, importers can extend this
	// type directly to achieve the same effect.
	#Target: {}

	// Dashboard panels. Panels are canonically defined inline
	// because they share a version timeline with the dashboard
	// schema; they do not vary independently. We create a separate,
	// synthetic Family to represent them in Go, for ease of generating
	// e.g. JSON Schema.
	#Panel: {
		{
			type: "barchart"
			panelSchema: {
				maj: 0
				min: 0
			}
			options: {
				orientation: "auto" | "vertical" | "horizontal"
				// TODO this default is a guess based on common devenv values
				stacking:  *"none" | "normal" | "percent"
				showValue: "auto" | "never" | "always"
				barWidth:  number
				// FIXME this field is non-optional in the corresponding TS type
				legend?: VizLegendOptions
				// FIXME this field is non-optional in the corresponding TS type
				tooltip?:   VizTooltipOptions
				text?:      VizTextDisplayOptions
				groupWidth: number
			}
			fieldConfig: {
				defaults: {
					custom: {
						lineWidth?:         number
						fillOpacity?:       number
						axisPlacement?:     AxisPlacement
						axisLabel?:         string
						axisWidth?:         number
						axisSoftMin?:       number
						axisSoftMax?:       number
						hideFrom?:          HideSeriesConfig
						gradientMode?:      ui.GraphGradientMode
						scaleDistribution?: ScaleDistributionConfig
					}
				}
			}
		} | {
			type: "bargauge"
			panelSchema: {
				maj: 0
				min: 0
			}
			options: {
				displayMode: "basic" | "lcd" | "gradient"
				reduceOptions: {
					// If true show each row value
					values?: bool
					// if showing all values limit
					limit?: number
					// When !values, pick one value for the whole field
					calcs: []
					// Which fields to show.  By default this is only numeric fields
					fields?: string
				}
				text?:        VizTextDisplayOptions
				showUnfilled: bool
				orientation:  "auto" | "vertical" | "horizontal"
			}
			fieldConfig: {
				defaults: {
					custom: {}
				}
			}
		} | {
			type: "gauge"
			panelSchema: {
				maj: 0
				min: 0
			}
			options: {
				showThresholdLabels: bool
				reduceOptions: {
					// If true show each row value
					values?: bool
					// if showing all values limit
					limit?: number
					// When !values, pick one value for the whole field
					calcs: []
					// Which fields to show.  By default this is only numeric fields
					fields?: string
				}
				text?:                VizTextDisplayOptions
				showThresholdMarkers: bool
				orientation:          "auto" | "vertical" | "horizontal"
			}
			fieldConfig: {
				defaults: {
					custom: {}
				}
			}
		} | {
			type: "table"
			panelSchema: {
				maj: 0
				min: 0
			}
			options: {
				frameIndex: *0 | number
				showHeader: *true | bool
				sortBy?: [...ui.TableSortByFieldState]
			}
			fieldConfig: {
				defaults: {
					custom: {
						width?:       int
						minWidth?:    int
						align?:       string | *"auto"
						displayMode?: string | *"auto"
						filterable?:  bool
					}
				}
			}
		} | {
			type: "text"
			panelSchema: {
				maj: 0
				min: 0
			}
			options: {
				mode:    *"markdown" | "html"
				content: *"""
					# Title

					For markdown syntax help: [commonmark.org/help](https://commonmark.org/help/)
					""" | string
			}
			fieldConfig: {
				defaults: {
					custom: {}
				}
			}
		} | {
			type: "dashlist"
			panelSchema: {
				maj: 0
				min: 0
			}
			options: {
				showStarred:        *true | bool
				showRecentlyViewed: *false | bool
				showSearch:         *false | bool
				showHeadings:       *true | bool
				maxItems:           *10 | int
				query:              *"" | string
				folderId?:          int
				tags:               *[] | []
			}
			fieldConfig: {
				defaults: {
					custom: {}
				}
			}
		} | {
			type: "histogram"
			panelSchema: {
				maj: 0
				min: 0
			}
			options: {
				bucketSize?:  int
				bucketOffset: *0 | int
				// FIXME this field is non-optional in the corresponding TS type
				legend?: VizLegendOptions
				// FIXME this field is non-optional in the corresponding TS type
				tooltip?: VizTooltipOptions
				combine?: bool
			}
			fieldConfig: {
				defaults: {
					custom: {
						drawStyle?:         DrawStyle
						gradientMode?:      GraphGradientMode
						lineColor?:         string
						lineWidth?:         number
						lineInterpolation?: LineInterpolation
						lineStyle?:         LineStyle
						fillColor?:         string
						fillOpacity?:       number
						showPoints?:        PointVisibility
						pointSize?:         number
						pointColor?:        string
						axisPlacement?:     AxisPlacement
						axisLabel?:         string
						axisWidth?:         number
						axisSoftMin?:       number
						axisSoftMax?:       number
						barAlignment?:      BarAlignment
						barWidthFactor?:    number
						stacking?:          StackingConfig
						hideFrom?:          HideSeriesConfig
						thresholdsStyle?:   GraphThresholdsStyleConfig
						spanNulls?:         bool | number
						fillBelowTo?:       string
						pointSymbol?:       string
						scaleDistribution?: ScaleDistributionConfig
						barMaxWidth?:       number
					}
				}
			}
		} | {
			type: "news"
			panelSchema: {
				maj: 0
				min: 0
			}
			options: {
				// empty/missing will default to grafana blog
				feedUrl?:   string
				useProxy?:  bool
				showImage?: bool | *true
			}
			fieldConfig: {
				defaults: {
					custom: {}
				}
			}
		} | {
			type: "stat"
			panelSchema: {
				maj: 0
				min: 0
			}
			options: {
				graphMode:   "none" | "line" | "area"
				colorMode:   "value" | "background" | "none"
				justifyMode: "auto" | "center"
				reduceOptions: {
					// If true show each row value
					values?: bool
					// if showing all values limit
					limit?: number
					// When !values, pick one value for the whole field
					calcs: []
					// Which fields to show.  By default this is only numeric fields
					fields?: string
				}
				text?:       VizTextDisplayOptions
				textMode:    "auto" | "value" | "value_and_name" | "name" | "none"
				orientation: "auto" | "vertical" | "horizontal"
			}
			fieldConfig: {
				defaults: {
					custom: {}
				}
			}
		} | {
			type: "state-timeline"
			panelSchema: {
				maj: 0
				min: 0
			}
			options: {
				// FIXME ts comments indicate this shouldn't be in the saved model, but currently is emitted
				mode?:        #TimelineMode
				showValue:    *"auto" | "never" | "always"
				rowHeight:    *0.9 | number
				colWidth?:    number
				mergeValues?: bool | *true
				// FIXME this field is non-optional in the corresponding TS type
				legend?: VizLegendOptions
				// FIXME this field is non-optional in the corresponding TS type
				tooltip?:    VizTooltipOptions
				alignValue?: #TimelineValueAlignment | *"left"
			}
			fieldConfig: {
				defaults: {
					custom: {
						lineWidth?:   number | *0
						hideFrom?:    HideSeriesConfig
						fillOpacity?: number | *70
					}
				}
			}
		} | {
			type: "status-history"
			panelSchema: {
				maj: 0
				min: 0
			}
			options: {
				showValue: "auto" | "never" | "always"
				rowHeight: number
				colWidth?: number
				// FIXME this field is non-optional in the corresponding TS type
				legend?: VizLegendOptions
				// FIXME this field is non-optional in the corresponding TS type
				tooltip?:   VizTooltipOptions
				alignValue: *"left" | "center" | "right"
			}
			fieldConfig: {
				defaults: {
					custom: {
						lineWidth?:   number | *1
						hideFrom?:    HideSeriesConfig
						fillOpacity?: number | *70
					}
				}
			}
		} | {
			type: "timeseries"
			panelSchema: {
				maj: 0
				min: 0
			}
			options: {
				legend: {
					displayMode: "list" | "table" | "hidden"
					placement:   "bottom" | "right"
					asTable:     *false | bool
					isVisible:   *false | bool
					calcs: []
				}
				tooltip: {
					mode: "single" | "multi" | "none"
				}
			}
			fieldConfig: {
				defaults: {
					custom: {
						drawStyle?:         DrawStyle
						gradientMode?:      GraphGradientMode
						lineColor?:         string
						lineWidth?:         number
						lineInterpolation?: LineInterpolation
						lineStyle?:         LineStyle
						fillColor?:         string
						fillOpacity?:       number
						showPoints?:        PointVisibility
						pointSize?:         number
						pointColor?:        string
						axisPlacement?:     AxisPlacement
						axisLabel?:         string
						axisWidth?:         number
						axisSoftMin?:       number
						axisSoftMax?:       number
						barAlignment?:      BarAlignment
						barWidthFactor?:    number
						stacking?:          StackingConfig
						hideFrom?:          HideSeriesConfig
						thresholdsStyle?:   GraphThresholdsStyleConfig
						spanNulls?:         bool | number
						fillBelowTo?:       string
						pointSymbol?:       string
						scaleDistribution?: ScaleDistributionConfig
						barMaxWidth?:       number
					}
				}
			}
		}

		// The panel plugin type id.
		type?: !=""
		// Whether to display the panel without a background.
		transparent: *false | bool
		// Direction to repeat in if 'repeat' is set.
		// "h" for horizontal, "v" for vertical.
		repeatDirection: *"h" | "v"
		transformations: [...]

		// The allowable options are specified by the panel plugin's
		// schema.
		// FIXME same conundrum as with the closed validation for fieldConfig.
		options: {}
		fieldConfig: {
			defaults: {}
			overrides: [...]
		}
	}

	// Row panel
	#RowPanel: {
		type?:     "row"
		collapsed: *false | bool
		id:        number
		panels: [...]
	}

	// Support for legacy graph panels.
	#GraphPanel: {
		type?: "graph"
		thresholds: [...]
		timeRegions: [...]
		// FIXME this one is quite complicated, as it duplicates the #Panel object's own structure (...?)
		seriesOverrides: [...]

		// TODO docs
		bars: *false | bool
		// TODO docs
		dashes: *false | bool
		// TODO docs
		dashLength: *10 | number

		// TODO docs
		hiddenSeries: *false | bool

		// FIXME idk where this comes from, leaving it very open and very wrong for now
		legend: {}

		// TODO docs
		// TODO tighter constraint
		lines: *false | bool
		// TODO docs
		nullPointMode: *"null" | "connected" | "null as zero"
		// TODO docs
		percentage: *false | bool
		// TODO docs
		points: *false | bool
		// TODO docs
		// TODO tighter constraint
		renderer: string
		// TODO docs
		spaceLength: *10 | number
		// TODO docs
		stack: *false | bool
		// TODO docs
		steppedLine: *false | bool
	}
}