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, color, and labels fields;
• pie uses category and one value role.

The role carries scale and formatting intent close to the field it describes. Axes and labels use the same formatted values, so one decision stays consistent across the chart.

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 uses the equivalent values: { type: "long", field: ... } or value: { type: "count" } shape.

Aggregation

Value roles may aggregate with sum, average, min, max, or median. Aggregation happens before ordering, stacking, labels, and scale planning, so every output consumes the same derived values.

Omit aggregation when each semantic category/series pair already has one value. If duplicate groups would make the result ambiguous, validation reports it rather than choosing a row silently.

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 required role must refer to a field present in the submitted rows. null can represent a missing observation, but it is not silently converted to zero. Family semantics decide whether a missing value creates a gap, excludes a point, or makes the input 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 semantics determine color identity; color.domain and color.range customize assignment. Scatter can map a separate field through categorical or sequential color. Literal source strings are not interpreted as colors merely because they look like CSS values.

This keeps field meaning explicit and prevents data changes from accidentally becoming presentation instructions.