Agentic Data Plane

Chart Schema Reference

Look up the chart types, JSON fields, validation rules, and size limits for inline 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

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:

```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.

Chart types

Each chart type uses one of the 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

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 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.

{
  "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.

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.

{
  "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

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

{
  "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

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.

{
  "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.

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.

{
  "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

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.

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

Hierarchy nodes

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

{
  "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.

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

{
  "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

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