Data and semantic roles

data is a flat array of objects. Values are strings, numbers, or null. Config remains data-free: its roles name the row fields Szum should interpret.

{
  "version": "2026-09-26",
  "config": {
    "version": "2026-09-26",
    "type": "column",
    "category": {
      "field": "quarter"
    },
    "values": {
      "type": "long",
      "field": "revenue"
    }
  },
  "data": [
    {
      "quarter": "Q1",
      "revenue": 42
    },
    {
      "quarter": "Q2",
      "revenue": 58
    }
  ],
  "output": {
    "format": "svg"
  }
}

Field roles

Chart types name roles rather than coordinates:

• column, bar, line, and area use category and values;
• scatter uses independent x and y roles, with optional id, size, interval, color, and labels;
• pie uses category and values;
• waterfall uses category, values, and a stepKind field that marks each row as a start, change, subtotal, or total.

Each role carries the scale and format for its field. Labels, tooltips, and accessible descriptions use that role’s format; an axis format changes only that axis’s tick labels.

Value modes

Long

long reads one numeric field. Add a series field when rows contain multiple named series.

{
  "values": {
    "type": "long",
    "field": "revenue",
    "series": { "field": "region" }
  }
}

Wide

wide treats several numeric fields as named series. It is useful when each row already contains one column per measure.

{
  "values": {
    "type": "wide",
    "fields": ["current", "previous"]
  }
}

Count

count counts rows instead of reading a numeric field. An optional series role splits the count into groups.

{ "values": { "type": "count", "series": { "field": "status" } } }

Pie accepts long or count values without a series, because its categories are the slices. Waterfall accepts only long values.

Aggregation

long and wide values may aggregate with sum, average, min, max, or median. Aggregation happens before ordering, stacking, labels, and scale planning, so every output uses the same derived values. Waterfall and ranged bars do not aggregate.

Omit aggregation when each category and series pair already has one value. Duplicates are a validation error rather than a silent choice between rows, except on lines and on areas without a series, where repeated positions stay as ordered points along the path.

Categories, dates, and numbers

Strings and numbers can act as categories. Use scale: { type: "utc" } when strings represent dates or years and chronological distance matters; omit the scale or use { type: "band" } for discrete labels. Line and area may use { type: "linear" } or { type: "log" } for compatible numeric category positions; column and bar categories may use band or UTC. See Scales and axes.

Numeric measure fields must contain finite numbers where the role requires them. Log scales additionally require positive values.

Missing and null values

Every field a role references must exist on every row; a missing key is an error. null marks a missing observation and is never converted to zero. Lines and areas leave a gap at a null row, while column, bar, scatter, and pie charts omit it with a diagnostic. Waterfall subtotal and total rows use null amounts because Szum computes them. A chart with no usable rows is invalid.

Diagnostics include bounded sample paths for affected rows without truncating or mutating the source data.

Color fields and explicit palettes

For categorical charts, the series or category determines color identity; color.domain and color.range customize the assignment. Scatter can map a separate field through categorical, sequential, or diverging color. Row values are never read as colors, even when they look like CSS colors, so changing data cannot change presentation.