Configuration
Every chart config field, with defaults and types at a glance – the full szum grammar in one reference.
Only version, format, and marks are required. Everything else has sensible defaults.
Minimal config
The bare minimum – a version and one mark:
Full shape
{
"version": "2026-03-20",
"format": "svg",
"scale": 2,
"width": 640,
"height": 400,
"margin": {
"top": 15,
"right": 15,
"bottom": 15,
"left": 15
},
"title": "...",
"subtitle": "...",
"footer": "...",
"headerAlign": "left",
"attribution": true,
"theme": "clean",
"themeOverrides": {},
"data": [],
"marks": [],
"x": {
"type": "...",
"domain": [],
"label": "...",
"tickFormat": "..."
},
"y": {
"type": "...",
"domain": [],
"label": "...",
"tickFormat": "..."
},
"color": {
"type": "...",
"label": "...",
"domain": [],
"range": []
}
}Field reference
| Field | Type | Default | Description |
|---|---|---|---|
version | "2026-03-20" | – | Required. Schema version. |
format | "svg" | "png" | – | Required. Output image format. |
scale | 1–4 | 1 (svg) / 2 (png) | Pixel density. |
width | 1–4096 | 640 | Total image width in pixels. Cannot mix with plotWidth/plotHeight. See Sizing. |
height | 1–4096 | 480 | Total image height in pixels. Cannot mix with plotWidth/plotHeight. See Sizing. |
plotWidth | 1–4096 | – | Data area width. Cannot mix with width/height. See Sizing. |
plotHeight | 1–4096 | – | Data area height. Cannot mix with width/height. See Sizing. |
margin | object | auto | Override auto-computed margins: top, right, bottom, left. |
title | string | – | Chart title string. |
subtitle | string | – | Subtitle string. |
footer | string | – | Caption below the chart (a source line, methodology note, date). URLs, bare domains, and [label](url) links in it are auto-detected and rendered as inline links on every surface. |
headerAlign | "left" | "center" | "right" | "left" | Alignment of the whole header – title, subtitle, and legend. |
attribution | boolean | – | Show a "made with szum" credit. Forced on for free/keyless renders; Pro omits it by default, set true to opt in. |
theme | ThemeName | "editorial" | One of 6 built-in themes. |
themeOverrides | object | – | Override individual theme properties. |
data | Datum[] | – | Top-level dataset shared by all marks. See Data. |
marks | Mark[] | – | Required. One or more marks to render. |
x | AxisConfig | auto | X-axis configuration. See Scales. |
y | AxisConfig | auto | Y-axis configuration. See Scales. |
color | ColorConfig | auto | Color scale configuration. See Color. |
Automatic behaviors
Title wrapping: Long titles and subtitles wrap automatically to fit the chart width.
Margins: Auto-computed to accommodate axis labels, tick labels, title, subtitle, and legend. Override with explicit margin values – any omitted side keeps its auto-computed value.
Sizing constraint: You cannot specify both width/height and plotWidth/plotHeight – pick one sizing mode. See Sizing.
Attribution: Free and keyless renders show a small "made with szum" credit. Pro renders omit it by default; set attribution: true to keep it. See Sizing for how it affects layout.