Docs · Chart spec

One JSON object in, a living chart out

Everything the engine draws is described by one spec. This page is the full reference — the same contract whether the spec arrives through a maker, an embed, an MCP tool call, or the render API.

{
  "type": "column",
  "theme": "editorial",
  "title": "Weekly signups",
  "source": "Product analytics",
  "data": {
    "labels": [
      "Mon",
      "Tue",
      "Wed",
      "Thu",
      "Fri"
    ],
    "series": [
      {
        "name": "Signups",
        "values": [
          12,
          19,
          14,
          27,
          22
        ]
      }
    ]
  }
}

That chart is this exact spec, rendered live.

The shape

Two required fields — type and data — and sensible defaults for the rest. Most types use labels and series. The status matrix takes data.columns and data.cells, the live table data.columns and data.rows; hierarchy, rank, stream, distribution and flow types use the formats described below. Unknown chart types, missing required data and non-numeric values are rejected with structured errors — nothing fails silently. For labels-and-series data, every series carries exactly one value per label: a series with the wrong count is refused, never padded with zeros or trimmed. A value written as null is a gap — a point with no data — drawn as a break in a line, no bar or dot, "No data" in the tooltip and the hidden table (not allowed on number and dotplot).

Negative values are rejected for every type except number — bars and areas measured from a zero baseline cannot show them honestly, and a structured error beats a misleading picture. A negative target is rejected everywhere.

{
  "type": "sankey",
  "data": {
    "links": [
      {
        "source": "Income",
        "target": "Budget",
        "value": 120
      },
      {
        "source": "Budget",
        "target": "Spending",
        "value": 100
      }
    ]
  }
}

{
  "type": "ridgeline",
  "data": {
    "groups": [
      {
        "id": "monday",
        "label": "Monday",
        "observations": [
          12,
          15,
          16,
          19,
          24
        ]
      }
    ]
  },
  "options": {
    "bandwidth": 2
  }
}

{
  "type": "bump",
  "data": {
    "labels": [
      "Jan",
      "Feb",
      "Mar"
    ],
    "series": [
      {
        "name": "Atlas",
        "values": [
          40,
          30,
          45
        ]
      },
      {
        "name": "Birch",
        "values": [
          35,
          42,
          45
        ]
      }
    ]
  },
  "options": {
    "rankMode": "values",
    "rankDirection": "descending"
  }
}

{
  "type": "treemap",
  "title": "City budget",
  "data": {
    "nodes": [
      {
        "id": "spaces",
        "label": "Public spaces"
      },
      {
        "id": "parks",
        "parentId": "spaces",
        "label": "Parks",
        "value": 32
      },
      {
        "id": "libraries",
        "parentId": "spaces",
        "label": "Libraries",
        "value": 18
      }
    ]
  },
  "options": {
    "showValues": true,
    "precision": 0,
    "variant": "auto"
  }
}

The twenty-five types

Changing type on a mounted chart does not redraw it — the engine morphs the existing shapes into the new ones. That is the whole point of the project.

For column with one series, options.histogram: true draws square bins in one palette color, touching with a 1px gap; omit it for ordinary columns.

{ "type": "column", "options": { "histogram": true },
  "data": { "labels": ["0–10", "10–20", "20–30"], "series": [{ "values": [9, 27, 38] }] } }

Themes and variants

Five themes, each in a light and a dark variant — ten looks in total. options.variant picks one: "light" and "dark" pin it, and "auto" follows the host page first — a data-theme attribute or a dark class on html or body, or its color-scheme — then the visitor's OS, and switches live when either changes. Omitting the field does neither — each theme then shows its own canonical side (editorial, glass and mint are light by nature; ink and neon are dark). A page that resolves its theme itself can still pass "light" or "dark" explicitly.

Annotations

Honesty as a feature: options.notes pins a caveat to a label — a cut-off date, a known-part-only total, an unverified claim. Each noted label grows a small ring on bar, column, lollipop, line, area, donut, scatter and number charts (an i glyph; ! for "warn" — a "partial" note keeps the warn tint); the matrix marks the row's cells with a corner dot. Hover or tap the ring to read the full text, click to keep it open; it also sits in the hidden accessible table, so the fine print travels with the chart instead of dying in a footnote.

"options": {
  "notes": [
    { "label": "Vanilla", "text": "Updates stop from 1 January 2025", "kind": "warn" },
    { "label": "Circle", "text": "Known part only; processing is extra", "kind": "partial" }
  ]
}

The status matrix

matrix reads cells instead of series: rows come from data.labels, features from data.columns, and every cell is a status from the fixed vocabulary yes | no | partial | unknown | na — a string, or { "status", "note" } to attach fine print to one cell. Statuses draw as shapes (check, cross, half-disc, question mark, dash), never as color alone, and options.legend renames them for the legend, tooltip and accessible table. Unknown and not-applicable are distinct states on purpose — the chart never dresses a missing fact as a no.

{
  "type": "matrix",
  "data": {
    "labels": ["Discourse", "Flarum"],
    "columns": ["Licence fee", "Server", "Updates"],
    "cells": [
      ["yes", "no", "yes"],
      ["yes", "no", { "status": "partial", "note": "Community builds only" }]
    ]
  },
  "options": { "legend": { "yes": "None to pay / included", "no": "On the team / paid" } }
}

The live table

table is the one type that is not a picture: <live-chart> mounts a real HTML table (loaded as a second small file only when a table is on the page). Columns carry a kind — text, number (with the usual format), status (the matrix vocabulary, drawn as a chip with a shape and an optional label) or note — and each cell is a string, a number, null, { "status", "label", "note" } or { "text", "kind", "note" } (note is optional). The table sorts on a header click, filters by status chips, draws a mini-bar behind every number, expands notes on click, and scrolls sideways below 480 px of width. Set options.mobile: "cards" to use cards instead. Its "Chart" button hands a numeric column — or a status column whose chips carry numbers — to the engine as a lollipop. There is no SVG export (a structured refusal says so); PNG renders through the local MCP (Pro).

{
  "type": "table",
  "title": "What you are buying",
  "data": {
    "columns": [
      { "name": "Product" },
      { "name": "Licence cost", "kind": "status" },
      { "name": "Monthly", "kind": "number", "format": "currency:USD" },
      { "name": "What still lands on the team", "kind": "note" }
    ],
    "rows": [
      ["Discourse", { "status": "yes", "label": "None" }, 100, "Server and an SMTP mail service"],
      ["Vanilla", "yes", null, { "text": "Updates stop from 1 January 2025", "kind": "warn" }]
    ]
  },
  "options": { "sort": { "column": 2, "dir": "desc" }, "sticky": true }
}

In a text or note column, { "text": "Limited claim", "kind": "warn", "note": "Full explanation" } keeps the claim visible and opens the explanation with the ! button. Use note, warn or partial for kind. The explanation is plain text, up to 4000 Unicode characters; noteText and detail return validation errors. Without note, text remains visible and the glyph explains its meaning. A status cell's existing + note still works. Paste the complete table JSON into the table maker to preserve typed cells and layout; Download JSON saves them without the share-link size limit.

Target lines

A goal, a limit, an SLA: options.target draws a dashed line at a value across column, bar, line, area, stacked, scatter and dotplot charts, with an optional label. The scale always stretches to include it.

"options": {
  "target": { "value": 120, "label": "Goal" }
}

Lines and parts

options.curve shapes a line or area between its points: "smooth" (the default), "linear" for straight segments, "step" for stairs — every value a plateau centered on its label, the riser midway between labels (see step charts live). A slope takes exactly two labels, the two states, and names every series at both ends with its exact value; a null on either side gaps that line and reads "—". A heatmap uses the ordinary data shape — labels are the columns, series are the rows — and shades each cell from the theme background to its first palette color; options.scale { "min", "max" } pins that range (values outside clamp), a null cell stays flat and unlabeled. A waffle lays the first series out as options.units squares (1–400, default 100) by largest remainders, so the squares always sum to the units; its legend is the donut's, and hovering any square lights the whole part.

{ "type": "line",    "options": { "curve": "step" } }
{ "type": "slope",   "data": { "labels": ["2024", "2025"], "series": [{ "name": "Search", "values": [31, 44] }] } }
{ "type": "heatmap", "options": { "scale": { "min": 0, "max": 50 } },
  "data": { "labels": ["Mon", "Tue"], "series": [{ "name": "North", "values": [12, 30] }, { "name": "South", "values": [8, null] }] } }
{ "type": "waffle",  "options": { "units": 100 }, "data": { "labels": ["Yes", "No"], "series": [{ "values": [73, 27] }] } }

Number formats

options.format runs through every surface at once — axis ticks, value labels, stacked totals, the big number, tooltips. "percent" adds the sign; "currency:XXX" prefixes $, € or £ for USD, EUR and GBP and falls back to the code itself for anything else (CAD 1,234.5). A unit of your own is affix:["before","after"]: affix:[""," lb"] reads 1,234.5 lb, affix:["~",""] reads ~1,234.5 — up to 12 characters a side, a space included, and the values are never converted. Numbers a reader reads are exact: value labels, tooltips, the big number and table cells keep the decimals the data carries (99.98% reads 99.98%, $201.5 reads $201.50), group thousands (12,345) and never shorten; only axis ticks stay compact ($48k). options.precision (0–4) sets the decimals by hand. Two deliberate exceptions stay plain: a donut slice's share (already a percentage) and a dot plot's counts (neither money nor a share).

"options": { "format": "percent" }        // 99.98 -> 99.98% on the bar, 100% on the axis
"options": { "format": "currency:USD" }   // 48200 -> $48,200 on the bar, $48k on the axis
"options": { "precision": 2 }             // 5 -> 5.00 everywhere a reader reads it

Errors are structured

Parsing never throws and never guesses. A bad spec comes back as a list of {path, message, hint} objects pointing at the exact field — the same shape in the browser, over MCP and from the render API, designed to be read by people and agents alike.

{
  "ok": false,
  "errors": [{
    "path": "data.series[0].values[2]",
    "message": "Value \"abc\" is not a finite number",
    "hint": "Use numeric values, e.g. 42 or 3.14"
  }]
}