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 a chart-specific schema.
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 the same shape. The GET render endpoint’s query parameter is named config for historical reasons, but it takes the complete document.
Automatic behavior
Theme: omit theme to use editorial. Theme values remain effective defaults rather than being copied into config.
Presentation: omit presentation for light, opaque output. A system scheme follows the viewer’s setting on interactive surfaces and uses its systemFallback for static output; see presentation mode.
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 sizing the plot. With a fixed plot, margin sets the outer padding for each side you provide; measured text still fits inside it.
Versioning
The version names a compatibility generation of the chart contract, not a product release. A new chart type can join the current version when existing charts keep their meaning; an incompatible change to an existing chart needs a new version and an explicit migration, and config and document versions advance together. Older SDK or plugin builds may need an update before they can read a newly added chart type.
For new integrations, use 2026-09-26. The documented subset of 2026-03-20 configs remains accepted; see older config compatibility.