# Chart Schema Reference

> For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt)

---
title: Chart Schema Reference
latest-operator-version: v26.2.4
latest-console-tag: v3.12.0
latest-connect-version: 4.113.1
latest-redpanda-tag: v26.2.4
docname: chart-schema-reference
page-component-name: agentic-data-plane
page-version: master
page-component-version: master
page-component-title: Agentic Data Plane
page-relative-src-path: chart-schema-reference.adoc
page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/chart-schema-reference.adoc
description: Look up the inline chart types, JSON data shapes, validation rules, and size limits for agent responses.
page-topic-type: reference
personas: agent_builder
learning-objective-1: Identify the chart type that matches your data
learning-objective-2: Describe the required fields and validation rules for each data shape
learning-objective-3: Identify chart size limits and compatibility behavior
page-git-created-date: "2026-09-23"
page-git-modified-date: "2026-09-24"
---

<!-- Source: https://docs.redpanda.com/agentic-data-plane/connect/chart-schema-reference.md -->

Look up the chart types, JSON fields, validation rules, and size limits for inline [agent](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#ai-agent) charts.

Use this reference to:

-   Identify the chart type that matches your data

-   Describe the required fields and validation rules for each data shape

-   Identify chart size limits and compatibility behavior


## [](#envelope)Chart block envelope

Emit one complete code fence tagged `chart` with a strict JSON body. Use double-quoted keys and strings, finite numeric values, and no comments, trailing commas, JavaScript, or callbacks. The examples on this page use synthetic data.

| Field | Required | Description |
| --- | --- | --- |
| type | Yes | A case-sensitive type from the chart type table. |
| title | No | A string displayed with the chart. When this field is absent, the renderer falls back to a string in options.plugins.title.text for compatibility. |
| data | Yes | An object matching the type’s data shape. All chart-specific fields belong here, including bins, cells, boxes, nodes, links, and gauge bounds. |

For example, this complete block draws a gauge:

````text
```chart
{
  "type": "gauge",
  "title": "Demo budget",
  "data": {"value": 65, "min": 0, "max": 100, "label": "Budget used (%)"}
}
```
````

The renderer controls colors, theme, layout, and interactions. Do not supply presentation options or renderer code. For a copyable system prompt and a Playground walkthrough, see [Draw Charts from an Agent](https://docs.redpanda.com/agentic-data-plane/connect/draw-charts/).

## [](#chart-types)Chart types

Each chart type uses one of the [data shapes](#data-shapes).

| Type | Data shape | Use for |
| --- | --- | --- |
| bar, horizontalBar | Labels and datasets | Category comparisons. Use horizontal bars for long labels. |
| stackedBar, percentBar | Labels and datasets | Additive breakdowns or percentage shares within each category. |
| line, area, stackedArea | Labels and datasets | Ordered trends, filled trends, or additive filled breakdowns. |
| pie, doughnut | Labels and datasets | Parts of a whole. |
| radar | Labels and datasets | At least three comparable metrics on a common scale. |
| polarArea | Labels and datasets | Category magnitudes in equal-angle sectors whose areas represent values. |
| scatter, bubble | Numeric points | Relationships between two numeric variables. Bubble area encodes a third value. |
| histogram | Histogram bins | Distributions with equal-width bins and supplied counts. |
| heatmap | Heatmap cells | Values across two categorical dimensions. |
| boxPlot | Five-number summaries | Distribution comparisons using supplied summaries. |
| gauge | Gauge bounds | One value within an explicit minimum and maximum. |
| treemap, sunburst | Hierarchy nodes | Hierarchical totals, represented by rectangles or concentric sectors. |
| sankey | Sankey nodes and links | Directed flows with known quantities and no cycles. |

## [](#data-shapes)Data shapes

Each JSON example is a complete chart configuration to place inside a `chart` fence. Numeric values and the derived ranges and totals must remain finite.

### [](#labels-datasets)Labels and datasets

Use this tabular shape for `bar`, `horizontalBar`, `stackedBar`, `percentBar`, `line`, `area`, `stackedArea`, `pie`, `doughnut`, `radar`, and `polarArea`. Each label is a string or finite number. Each dataset contains a `data` array and an optional string `label`, which defaults to `Series 1`, `Series 2`, and so on.

```json
{
  "type": "bar",
  "title": "Demo monthly orders",
  "data": {
    "labels": ["Jan", "Feb", "Mar"],
    "datasets": [{"label": "Orders", "data": [120, 190, 140]}]
  }
}
```

Supply one finite number or `null` per label in each dataset. A `null` value means missing, not zero. The parser requires exact array lengths for `horizontalBar`, `stackedBar`, `percentBar`, `area`, `stackedArea`, `radar`, and `polarArea`. Duplicate labels remain separate categories.

| Type | Additional rules |
| --- | --- |
| pie, doughnut, polarArea | Use exactly one dataset with nonnegative values. Zero and missing values remain in Data but produce no slice. Polar area sectors have equal angles and areas proportional to their values. |
| percentBar | Supply original nonnegative counts, not precomputed percentages. The chart normalizes each category against its currently visible series. Hiding a series recalculates the remaining shares. Categories with a zero total have no positive share. Data and tooltips retain the original counts. |
| radar | Use at least three labels and nonnegative values. Choose comparable metrics on a common scale. Do not normalize unrelated quantities without an agreed scale. |

For compatibility, `bar`, `line`, `pie`, and `doughnut` also accept finite numeric strings and arrays of unequal lengths. Bar and line charts also treat omitted `labels` or `datasets` arrays as empty. Pie and doughnut charts allow omitted `labels` but still require exactly one dataset.

### [](#xy-points)Numeric points

Use this shape for `scatter` and `bubble`. Each dataset contains an array of points with finite numeric `x` and `y` coordinates and can have a string `label`. An omitted dataset label defaults to `Series 1`, `Series 2`, and so on.

```json
{
  "type": "bubble",
  "title": "Demo request volume",
  "data": {
    "datasets": [{"label": "Requests", "data": [
      {"x": 10, "y": 2, "size": 5},
      {"x": 20, "y": 4, "size": 10}
    ]}]
  }
}
```

For scatter charts, omit `size`. For bubble charts, supply a positive finite `size` for every point. The bubble’s area, not its radius, is proportional to `size`.

### [](#histogram-bins)Histogram bins

Use `bins` for a histogram. Each bin requires finite numeric `start`, `end`, and `count` values.

```json
{
  "type": "histogram",
  "title": "Demo response-time counts",
  "data": {"bins": [
    {"start": 0, "end": 10, "count": 4},
    {"start": 10, "end": 20, "count": 7}
  ]}
}
```

Use `start < end`, nonnegative counts, and equal-width bins in increasing, nonoverlapping order. Unequal widths fail validation. Supply actual bin counts. An average alone does not determine a distribution.

### [](#heatmap-cells)Heatmap cells

Use `cells` for a heatmap. Each cell requires string categories `x` and `y` and a finite numeric `value`. Each `x`/`y` pair must be unique.

```json
{
  "type": "heatmap",
  "title": "Demo daily change",
  "data": {"cells": [
    {"x": "Mon", "y": "Orders", "value": -4},
    {"x": "Tue", "y": "Orders", "value": 8}
  ]}
}
```

Color represents the actual data range. When values span both signs, opposing hues distinguish negative and positive values around a neutral zero.

### [](#box-summaries)Five-number summaries

Use `boxes` for a box plot. Each box requires a string `label` and finite numeric `min`, `q1`, `median`, `q3`, and `max` values.

```json
{
  "type": "boxPlot",
  "title": "Demo response-time summary",
  "data": {"boxes": [
    {"label": "Search", "min": 1, "q1": 2, "median": 4, "q3": 6, "max": 9}
  ]}
}
```

Supply an ordered summary: `min <= q1 <= median <= q3 <= max`. The renderer uses these values directly. It does not calculate quartiles from a mean. Duplicate labels remain separate boxes.

### [](#gauge-bounds)Gauge bounds

Use explicit bounds for a gauge. The `value`, `min`, and `max` fields must be finite numbers with `min < max` and `min <= value <= max`. The optional string `label` defaults to `Value`.

```json
{
  "type": "gauge",
  "title": "Demo budget",
  "data": {"value": 65, "min": 0, "max": 100, "label": "Budget used (%)"}
}
```

### [](#hierarchy-nodes)Hierarchy nodes

Use `nodes` for treemap and sunburst charts. Each node requires a unique, nonempty string `id` and a string `label`.

```json
{
  "type": "treemap",
  "title": "Demo regional orders",
  "data": {"nodes": [
    {"id": "all", "label": "All orders"},
    {"id": "east", "parent": "all", "label": "East", "value": 5},
    {"id": "west", "parent": "all", "label": "West", "value": 3}
  ]}
}
```

Set `parent` to an existing node ID for each child, and omit it for root nodes. The hierarchy must have no cycles or self-parent references. Every leaf node requires a nonnegative finite `value`. Internal nodes must omit it. The renderer derives internal totals from their descendants to avoid double counting.

### [](#sankey-links)Sankey nodes and links

Use `nodes` and `links` for a Sankey chart. Each node requires a unique, nonempty string `id` and a string `label`.

```json
{
  "type": "sankey",
  "title": "Demo request flow",
  "data": {
    "nodes": [{"id": "agent", "label": "Agent"}, {"id": "search", "label": "Search"}],
    "links": [{"source": "agent", "target": "search", "value": 5}]
  }
}
```

Each link requires existing node IDs in `source` and `target`, plus a nonnegative finite `value`. The graph must have no cycles, including self-links. Positive link widths represent flow quantities. Zero-value links remain in **Data** but have no visible flow. Selecting a link selects its row in **Data**. Selecting a node clears the current link selection.

## [](#limits)Limits

The renderer rejects configurations that exceed these limits rather than silently truncating them.

| Item | Maximum per chart |
| --- | --- |
| Datasets for tabular, scatter, or bubble charts | 20 |
| Tabular labels | 2000 |
| Tabular values across all datasets | 2000. The value count is the sum of all dataset array lengths, including null entries. |
| Rendered tabular cells | 2000. The row count is the greater of the label count and the longest dataset length. The rendered cell count is the row count multiplied by the dataset count. |
| Points across all scatter or bubble datasets | 2000 |
| Histogram bins, heatmap cells, or box-plot summaries | 2000 |
| Hierarchy nodes | 500 |
| Sankey nodes | 100 |
| Sankey links | 1000 |

The palette contains 12 colors. Charts that need more colors reuse the palette and display a note rather than rejecting the data. For hierarchy charts, this threshold applies to top-level branches, not every leaf.

## [](#next-steps)Next steps

-   [Draw Charts from an Agent](https://docs.redpanda.com/agentic-data-plane/connect/draw-charts/)

-   [Write Effective System Prompts](https://docs.redpanda.com/agentic-data-plane/connect/system-prompts/)