Dynatrace document structure - Dashboards

• Latest Dynatrace
• Reference
• 8-min read
• Updated on Jun 08, 2026

A Dynatrace dashboard is stored as a JSON document. Understanding the structure helps you create and modify dashboards using the API or by editing JSON directly in Dashboards.

Overview

A dashboard document consists of four required properties—version, variables, tiles, and layouts—plus optional properties such as settings and annotations. Tiles define the content displayed on the dashboard, and layouts control their position on the grid.

Top-level structure

{
  "version": 21,
  "variables": [],
  "tiles": {},
  "layouts": {}
}

Optional properties: settings, annotations.

Tile IDs in tiles must match IDs in layouts. IDs are strings (typically numeric strings such as "1", "2").

Tiles

Tiles are stored in content.tiles as an object whose keys are tile IDs. There are four tile types.

Markdown tile

A markdown tile displays static text content formatted with Markdown.

{
  "type": "markdown",
  "content": "# Section Header\n\nSome text here."
}

Data tile

A data tile runs a DQL query and displays the results as a visualization.

{
  "type": "data",
  "title": "Tile Name",
  "query": "timeseries avg(dt.host.cpu.usage), by:{host.name}",
  "visualization": "lineChart",
  "visualizationSettings": {},
  "querySettings": {}
}

Code tile

A code tile executes JavaScript and optionally displays results as a visualization.

{
  "type": "code",
  "title": "Custom",
  "input": "// JavaScript code here",
  "visualization": "lineChart",
  "visualizationSettings": {}
}

SLO tile

An SLO tile displays a Service-Level Objective by its ID.

{
  "type": "slo",
  "title": "SLO Name",
  "input": "slo-id",
  "visualizationSettings": {}
}

Visualization types

The visualization property of a data tile determines how query results are rendered. Each visualization requires specific field types in the query result. If the query produces the wrong types, the tile renders blank or shows an error.

Field types: timestamp, timeframe, long, double, duration, string, numericArray

Legend: R = required, O = optional, C = conditional

Time-series charts

lineChart, areaChart, barChart display metric data over time.

When using timeseries or makeTimeseries, values are numericArray and an interval field must be present in the query result.

bandChart has the same requirements plus two additional required numericArray slots for band min and band max values.

Categorical charts

categoricalBarChart, pieChart, donutChart show values grouped by categories. Typical query pattern: summarize <aggregation>, by:{category}.

Single value and gauge

singleValue displays a single metric value.

meterBar and gauge display a numeric value on a scale.

Tabular

table, raw, and recordList accept any data shape with no field type requirements.

Other visualizations

davis, histogram, honeycomb, choropleth, dotMap, connectionMap, bubbleMap, heatmap, scatterplot, and treemap are also available, each with their own slot requirements.

Layout

Tile positions are stored in content.layouts as an object whose keys match the tile IDs in content.tiles. Every tile in tiles must have a matching entry in layouts.

"layouts": {
  "1": { "x": 0, "y": 0, "w": 24, "h": 1 },
  "2": { "x": 0, "y": 1, "w": 12, "h": 8 },
  "3": { "x": 12, "y": 1, "w": 12, "h": 8 },
  "4": { "x": 0, "y": 9, "w": 24, "h": 8 }
}

The grid is 24 columns wide. Common widths:

Common heights:

Tiles with x + w > 24 wrap to the next row.

Variables

Variables provide dynamic filtering across tiles. Defined in content.variables as an array, they are referenced in DQL queries using $key.

All variable types share these properties:

Query variables

Query variables populate their options by running a DQL query. The query must return exactly one field.

{
  "version": 2,
  "key": "Service",
  "type": "query",
  "visible": true,
  "editable": true,
  "input": "smartscapeNodes SERVICE | fields name | sort name asc",
  "multiple": false
}

For multi-select with all values selected by default, set "multiple": true and use the all-selected default token:

{
  "version": 2,
  "key": "Services",
  "type": "query",
  "visible": true,
  "editable": true,
  "input": "smartscapeNodes SERVICE | fields name | sort name asc",
  "multiple": true,
  "defaultValue": "3420b2ac-f1cf-4b24-b62d-61ba1ba8ed05*"
}

Use version: 2 for new dashboards (supports fetch, expand, summarize). version: 1 is legacy.

Text variables

Text variables accept free-form user input.

{
  "version": 1,
  "key": "Threshold",
  "type": "text",
  "visible": true,
  "editable": true,
  "defaultValue": ""
}

CSV variables

CSV variables provide a static predefined list of values.

{
  "version": 1,
  "key": "Status",
  "type": "csv",
  "visible": true,
  "editable": true,
  "input": "WARN,ERROR,INFO,NONE",
  "multiple": true,
  "defaultValue": "3420b2ac-f1cf-4b24-b62d-61ba1ba8ed05*"
}

Variable reference syntax

Reference a variable in DQL using $key.

Use modifiers when the default string substitution is not appropriate:

Variables can reference other variables. A dependent variable recalculates when the variable it depends on changes. Circular dependencies are not allowed.

Settings

settings is an optional object. If present, it can be empty ({}) or contain dashboard-level configuration.

"settings": {
  "defaultTimeframe": {
    "value": {
      "from": "now()-2h",
      "to": "now()"
    },
    "enabled": true
  }
}

defaultTimeframe sets the time range shown in tiles that don't override the timeframe. It also determines the window for which annotations are evaluated.

Dashboard validation

Dynatrace validates a dashboard's JSON when you save changes in the JSON editor. If validation fails, the editor shows the error and prevents saving until you fix it.

When you open a dashboard that has validation errors, a notification appears in the lower-left corner. The actions available depend on your permissions:

Missing required property 'type'

Error

Missing required property 'type' of tile id '10'. Expected one of: 'data', 'code', 'markdown', 'slo'

Cause: The tile is missing a required type property. A common cause is uploading a classic dashboard to Dashboards, which uses a different JSON schema.

Fix: Add a valid type property to the tile. Supported values are data, code, markdown, and slo.

Invalid value for 'subType'

Error

Invalid value 'graph' for property 'subType' of tile id '10'. Expected one of: 'dql-builder-logs', 'dql-builder-metrics', 'dql-builder-biz-events', 'dql-builder-events', 'dql-builder-traces', 'dql-builder-problems', 'dql-builder-user-sessions', 'dql-builder-user-events', 'dql-builder-security-events', 'davis-copilot'

Cause: The subType property contains a value not recognized by Dashboards.

Fix: Change subType to one of the supported values listed in the error message.

Invalid type for 'timeframe'

Error

Invalid type for property 'timeframe' of tile id '10' (expected object, received string)

Cause: The timeframe property is a string (for example, "timeframe": "last 24h") instead of an object.

Fix: Replace the string value with the correct object format:

"timeframe": {
  "tileTimeframeEnabled": true,
  "tileTimeframe": {
    "from": "now()-24h",
    "to": "now()"
  }
}

Related topics