grafana/docs/sources/observability-as-code/schema-v2/layout-schema.md

description	keywords	labels	menuTitle	title	weight
A reference for the JSON layout schema used with Observability as Code.	[configuration as code as-code dashboards git integration git sync github layout]	[{products [cloud enterprise oss]}]	layout schema	layout	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 - Corresponds to the Custom option in the UI. You define panel size and panel positions using x- and y- settings.
• 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 - Groups panels into rows.
• 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:

    "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
    • GridLayoutRowKind
      • kind: "GridLayoutRow"
      • spec: 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 from dashboard.spec.elements expressed as JSON Schema reference.
repeat?	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:

Name	Usage
y	integer. Position of the row y-axis
collapsed	bool. Whether or not the row is collapsed
title	Row title
elements	[...GridLayoutItemKind]. 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 Configured row repeat options, if any

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:

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

AutoGridLayoutKind consists of:

• kind: "AutoGridLayout"
• spec: AutoGridLayoutSpec

AutoGridLayoutSpec

The following table explains the usage of the auto grid layout JSON fields:

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: kind: "AutoGridLayoutItem" spec: AutoGridLayoutItemSpec

AutoGridLayoutItemSpec

The following table explains the usage of the auto grid layout item JSON fields:

Name	Usage
element	ElementReference. Reference to a PanelKind from dashboard.spec.elements expressed as JSON Schema reference.
repeat?	AutoGridRepeatOptions. Configured repeat options, if any.
conditionalRendering?	ConditionalRenderingGroupKind. Rules for hiding or showing panels, if any. Consists of: kind: "ConditionalRenderingGroup" spec: ConditionalRenderingGroupSpec

AutoGridRepeatOptions

The following table explains the usage of the auto grid repeat option JSON fields:

Name	Usage
mode	RepeatMode - "variable"
value	String

ConditionalRenderingGroupSpec

Name	Usage
visibility	Options are show and hide
condition	Options are and and or
items	Options are: ConditionalRenderingVariableKind kind: "ConditionalRenderingVariable" spec: ConditionalRenderingVariableSpec ConditionalRenderingDataKind kind: "ConditionalRenderingData" spec: ConditionalRenderingDataSpec ConditionalRenderingTimeRangeSizeKind kind: "ConditionalRenderingTimeRangeSize" spec: ConditionalRenderingTimeRangeSizeSpec

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:

    "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

The following table explains the usage of the rows layout row JSON fields:

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: kind: "ConditionalRenderingGroup" spec: ConditionalRenderingGroupSpec
repeat?	RowRepeatOptions. Configured repeat options, if any.
layout	Supported layouts are: GridLayoutKind RowsLayoutKind AutoGridLayoutKind TabsLayoutKind

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:

    "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

The following table explains the usage of the tabs layout tab JSON fields:

Name	Usage
title?	The title of the tab.
layout	Supported layouts are: GridLayoutKind RowsLayoutKind AutoGridLayoutKind TabsLayoutKind
conditionalRendering?	ConditionalRenderingGroupKind. Rules for hiding or showing panels, if any. Consists of: kind: "ConditionalRenderingGroup" spec: ConditionalRenderingGroupSpec