Dynatrace document structure - Notebooks

• Latest Dynatrace
• Reference
• 6-min read
• Updated on Sep 30, 2026

A Dynatrace notebook is stored as a JSON document. Understanding the structure helps you create and modify notebooks using the API.

Overview

A notebook document consists of version, defaultTimeframe, defaultSegments, and sections. Sections are ordered sequentially and stack vertically in the order they appear in the array. Each section is either a Markdown block or a DQL query with its own visualization and query settings.

Top-level structure

{
  "version": "7",
  "defaultTimeframe": { "from": "now()-2h", "to": "now()" },
  "defaultSegments": [],
  "sections": []
}

Sections

Sections are stored in sections as an ordered array. The order in the array is the display order in the notebook. There are three section types: markdown, dql, and function.

Sections stack vertically in array order.

Markdown section

A markdown section displays static text content formatted with Markdown.

{
  "id": "97eae716-f594-4d8a-90ea-bcc00d1c0db4",
  "type": "markdown",
  "markdown": "# Title\n\nSection content."
}

DQL section

A DQL section runs a query and displays the results as a visualization. Query and visualization properties are nested inside a state object.

{
  "id": "5151a253-30a3-4e54-95d4-816e48c7e08f",
  "type": "dql",
  "title": "Query Section",
  "height": 293,
  "showInput": true,
  "filterSegments": [],
  "drilldownPath": [],
  "previousFilterSegments": [],
  "state": {
    "input": {
      "value": "fetch logs | summarize count()",
      "timeframe": { "from": "now()-2h", "to": "now()" }
    },
    "visualization": "table",
    "visualizationSettings": {
      "autoSelectVisualization": true,
      "chartSettings": {}
    },
    "querySettings": {
      "maxResultRecords": 1000,
      "defaultScanLimitGbytes": 500,
      "maxResultMegaBytes": 1,
      "defaultSamplingRatio": 10,
      "enableSampling": false
    }
  }
}

Section-level properties:

state properties:

Function section

A function section runs a JavaScript function in the Dynatrace Functions runtime and optionally displays the result as a visualization.

{
  "id": "54beb22f-3ef2-4809-93aa-06a3cab3f702",
  "type": "function",
  "title": "Users fetched from API",
  "showTitle": true,
  "showInput": true,
  "drilldownPath": [],
  "state": {
    "input": {
      "value": "export default async function () {\n  const res = await fetch('https://example.com/api/data');\n  return res.json();\n}"
    },
    "visualization": "table",
    "visualizationSettings": {
      "autoSelectVisualization": true
    }
  }
}

Visualization types

Notebooks support the following visualization types for DQL sections:

davis, table, histogram, honeycomb, singleValue, donutChart, pieChart, categoricalBarChart, dotMap, choropleth, bubbleMap, connectionMap, meterBar, gauge, heatmap, lineChart, areaChart, barChart, bandChart, scatterplot, raw, recordView, treemap

Setting "autoSelectVisualization": true in state.visualizationSettings lets Dynatrace choose the most appropriate visualization for the query result automatically. Use this unless you need a specific type.

For field type requirements per visualization type, see Visualization types.

Notebook validation

Dynatrace validates notebook JSON when you upload or open a notebook. Strict validation is enabled by default.

When validation fails, a message displays the affected paths and error messages. For a description of the validation notifications and the options available, see Fix notebook validation errors.

Notebook validation errors

Common notebook validation errors are described below.

To fix such errors

Invalid type for 'version'

Error

Invalid input: expected string, received number — $.version

Cause: The version property is a number instead of a string. This often happens when notebook JSON is generated programmatically and the version value is not quoted.

Fix: Wrap the value of version in quotes so it is a string.

Invalid:

{
  "version": 7,
  "defaultTimeframe": {
    "from": "now()-30d",
    "to": "now()"
  }
}

Valid:

{
  "version": "7",
  "defaultTimeframe": {
    "from": "now()-30d",
    "to": "now()"
  }
}

Invalid discriminator value for 'type'

Error

Invalid discriminator value. Expected 'markdown' | 'dql' | 'function' — $.sections.N.type

Where N is the zero-based index of the invalid section in the sections array.

Cause: A section's type property is missing or set to an unsupported value. Supported values are markdown, dql, and function.

Fix: Set type on the affected section to one of the supported values.

Invalid:

{
  "id": "06c77a86-f5c3-4d9f-b173-d15b6c322131",
  "type": "code"
}

Valid:

{
  "id": "06c77a86-f5c3-4d9f-b173-d15b6c322131",
  "type": "function"
}

Related topics