Serializable spec

The builders you’ve met so far — createSpec, pipe, geom.*, scale.*, config — are convenience, not substance. Everything they produce is a plain, immutable object made only of objects, arrays, strings, numbers and booleans. A spec holds no functions, no class instances, no DOM references. That means it round-trips through JSON.stringify / JSON.parse unchanged: you can store a spec in a database, send it over the wire, generate it from another language, or write one by hand.

The builder is just sugar

pipe(...) and the geom.* / scale.* / config helpers just assemble and merge a plain object. This call:

import { createSpec, pipe, geom, scale, config } from '@graphysdk/react';

const spec = pipe(
  createSpec({ x: 'month', y: 'revenue', color: 'product' }),
  geom.line(),
  scale.x(),
  scale.y.continuous({ domainMin: 0 }),
  scale.color.palette(),
  config({ legend: { position: 'bottom' } })
);

produces exactly this object — and JSON.stringify(spec) gives you exactly this JSON (fields left undefined drop out):

{
  "mapping": { "x": "month", "y": "revenue", "color": "product" },
  "layers": [{ "type": "layer", "geom": "line" }],
  "scales": [
    { "type": "scale", "scaledAesthetic": "x", "scaleType": "inferred" },
    {
      "type": "scale",
      "scaledAesthetic": "y",
      "scaleType": "continuous",
      "domainMin": 0,
      "domainMax": null,
      "scheme": null,
      "domainMid": null
    },
    { "type": "scale", "scaledAesthetic": "color", "scaleType": "palette" }
  ],
  "transforms": [],
  "highlights": [],
  "config": { "legend": { "position": "bottom" } }
}

You could paste that JSON into your source and feed it straight to the renderer with no builder in sight. What the builders add is types, defaults and guardrails — autocomplete for aesthetics and params, sensible fallbacks, and a compile-time check that the shape is valid.

Every top-level key

createSpec seeds six keys — mapping, layers, scales, transforms, highlights and config — so they are present even when empty. The other three appear only once something is piped in:

Key	Holds
`mapping`	The spec-level aesthetic mapping
`layers`	One entry per geom
`scales`	One entry per declared scale
`transforms`	Spec-level transforms
`highlights`	Highlights
`config`	Chart chrome
`coords`	The coordinate system — a single object, not a list
`styles`	The stylesheet
`annotations`	Annotations, grouped by kind

A styled spec is still JSON

The stylesheet is the largest thing a spec carries, and it round-trips as plainly as the rest. A token('brand') reference is an ordinary object the compile stage inlines, and a light/dark colour pair is an ordinary object the renderer picks from at read time — so neither needs a function to survive the trip:

import {
  createSpec,
  pipe,
  geom,
  scale,
  styles,
  style,
  token,
} from '@graphysdk/react';

const spec = pipe(
  createSpec({ x: 'month', y: 'revenue' }),
  geom.bar(),
  scale.x(),
  scale.y(),
  styles({
    tokens: { brand: { light: '#0B5FFF', dark: '#6AA1FF' } },
    defaults: [style.geom({ color: token('brand') })],
  })
);

{
  "styles": {
    "type": "styles",
    "tokens": { "brand": { "light": "#0B5FFF", "dark": "#6AA1FF" } },
    "defaults": [
      {
        "select": { "target": "geom" },
        "declarations": { "color": { "token": "brand" } }
      }
    ]
  }
}

Writing the JSON by hand

Two things to know before you do. A layer’s aesthetic override is called aes on the builder and mapping in the object: geom.line({ aes: { y: 'profit' } }) serializes as { "type": "layer", "geom": "line", "mapping": { "y": "profit" } }. And a spec that uses a plugin geom, stat or transform still serializes — a custom layer is just { "geom": "candlestick", "params": { … } } — but the plugin itself is code, and it reaches the chart through the plugins array on GraphProvider rather than through the spec. Store the spec; ship the plugins with your app.

How a chart is built — the compile → render pipeline that consumes a spec
Data structure — the table a spec references by column name
Extending — custom geoms, stats and transforms, and the plugins they ship in

Get Started

Core concepts

Chart types

Annotations & emphasis

Rendering

Configuration

Advanced

Extending

The builder is just sugar

Every top-level key

A styled spec is still JSON

Writing the JSON by hand

Next

​The builder is just sugar

​Every top-level key

​A styled spec is still JSON

​Writing the JSON by hand

​Next

The builder is just sugar

Every top-level key

A styled spec is still JSON

Writing the JSON by hand

Next