Config and document
Reusable chart semantics and one complete document for validation, rendering, and saving.
Szum separates reusable chart semantics from the complete document used for validation, rendering, and saving.
ChartConfig
ChartConfig is data-free and includes its chart version. Its type selects one of six chart-specific schemas.
The smallest useful config names the current version, chart type, and required semantic roles:
{
"version": "2026-09-26",
"type": "column",
"category": {
"field": "quarter"
},
"values": {
"type": "long",
"field": "revenue"
}
}{
"version": "2026-09-26",
"type": "column",
"title": "Quarterly revenue",
"category": {
"field": "quarter"
},
"values": {
"type": "long",
"field": "revenue"
}
}Shared fields
| Field | Type | Default | Description |
|---|---|---|---|
version | "2026-09-26" | – | Required. The chart config version. |
type | ChartType | – | Required. The chart family. |
title | string | – | Chart title. |
subtitle | string | – | Supporting text beneath the title. |
caption | string | – | Caption below the chart for a source, methodology note, or date. |
accessibilityDescription | string | – | Accessible description of the chart's meaning. |
headerAlign | "start" | "center" | "end" | theme default | Horizontal alignment for the title and subtitle. Omit it to use the selected theme's alignment. |
locale | string | "en-US" | Locale identifier accepted by JavaScript Intl and associated with the chart content, such as en, pl, or zh-Hant. |
theme | ThemeName | "editorial" | One of 6 built-in themes. |
themeOverrides | ThemeOverrides | – | Override individual theme properties. |
Chart-specific fields are listed on each chart type page. Unknown fields are rejected. Omit optional values to use Szum or theme defaults; do not send null unless a row value is intentionally missing.
ChartDocument
A document pairs config with data. Presentation, size, and output are siblings of config because they control delivery, not chart meaning. version and config.version must match; both currently use 2026-09-26.
{
"version": "2026-09-26",
"config": {
"version": "2026-09-26",
"type": "column",
"title": "Quarterly revenue",
"category": {
"field": "quarter"
},
"values": {
"type": "long",
"field": "revenue"
}
},
"data": [
{
"quarter": "Q1",
"revenue": 42
},
{
"quarter": "Q2",
"revenue": 58
}
]
}| Field | Type | Default | Description |
|---|---|---|---|
version | "2026-09-26" | – | Required. The chart document version. |
config | ChartConfig | – | Required. The chart's semantic definition. |
data | ChartDatum[] | – | Required. Rows paired with the semantic roles in config. See Data. |
presentation | ChartPresentation | light, opaque | Light/dark mode and background policy. |
size | ChartSize | automatic | Automatic, canvas, or plot sizing. See Sizing. |
output | ChartOutput | { format: "svg" } | Output format and PNG resolution policy. |
Use the same document with validation, rendering, and saved-chart actions. Rendering does not save it. Saved charts, Studio, and Figma read and write that same shape. The historical GET parameter is still named config, but its value is the complete document.
Automatic behavior
Theme: omit theme to use editorial. Theme values remain effective defaults rather than being copied into config.
Presentation: static output resolves a deterministic light or dark scheme. Interactive surfaces may follow the live system setting.
Sizing: omit size to use family-aware automatic sizing. A fixed canvas describes the entire output; a fixed plot describes only the data area.
Output: omit output for SVG. PNG may use scale from 1–4 and defaults to 2 when scale is omitted.
Margins and text: Szum measures titles, subtitles, axes, legends, labels, caption, and attribution before allocating the plot. Explicit plot margins override only the sides you provide.
Versioning
The version identifies a chart-contract generation, not a product release. Config and document versions advance together when their authored contract changes after release. A document's outer version must match its nested config version.
For new integrations, use 2026-09-26. The documented subset of 2026-03-20 configs remains accepted; see older config compatibility.