Spec reference

Version 1. A spec is one JSON object. Unknown top-level keys are ignored, but keys that look like code are refused wherever they appear.

Top level

Field	Type	Required	Meaning
`version`	1	yes	The spec format. Only 1 is accepted today.
`seed`	integer, 0 to 4294967295	yes	Fixes every random choice. Same seed, same picture.
`theme`	`"light"` or `"dark"`	no, default light	Which colour tokens to use. See themes.
`canvas.width`	integer, 16 to 4096	yes	Width in CSS pixels.
`canvas.height`	integer, 16 to 4096	yes	Height in CSS pixels.
`elements`	array, at most 5000	yes	The things to draw, in order. Later elements draw on top.

Coordinates

Positions are normalised. 0 is the left or top edge of the canvas and 1 is the right or bottom edge, so a spec does not change when the canvas size does. Sizes that name a radius, a width or a weight of a shape are relative to the canvas where the element says so, and are pixels where the element says pixels. Each element's section below says which.

Colours

A spec never contains a colour. It names a token: "bg", "fg", "accent", "muted", "grid". The theme decides the value. A raw colour such as "#ff00ff" is refused with a message that lists the tokens.

Limits

Limit	Value
Whole spec, as JSON text	512 KB
Elements	5000
Points in one line or scatter, or dots in one random-dots element	100,000
Canvas side	16 to 4096 pixels

A spec over the size limit is refused before any other check runs, so an oversized document cannot make the validator slow.

Refused on purpose

Keys named code, script, eval, function, src, href, onload, onclick, html or innerHTML, at any depth.
Strings beginning javascript:, data: or vbscript:.
Functions of any kind.
Non-finite numbers (NaN, Infinity) where a number is expected.

A complete example

{
  "version": 1,
  "seed": 2024,
  "theme": "light",
  "canvas": { "width": 640, "height": 400 },
  "elements": [
    { "type": "rect", "x": 0, "y": 0, "w": 1, "h": 1, "stroke": "grid", "weight": 1 },
    { "type": "random-dots", "count": 900, "fill": "accent", "radius": [1, 4] }
  ]
}

Each element is described on the elements page.