The CanvasXpress Spec

Every CanvasXpress figure serializes to one portable JSON object — a data matrix plus a config — that the same engine re-renders identically across JavaScript, R and Python. As of v67.5 that object carries a schemaVersion, so a figure is self-describing and version-aware. This page publishes the format as a contract, not just a feature.

Two schemas describe the format. Agents and tools can fetch them to emit and validate specs without trial and error:

• cxfigure-1.0.schema.json — the persisted {data, config} figure (the contract you save and share).
• cxplot-1.0.schema.json — the materialized grammar-of-graphics snapshot (mapping/layers/scales/coord/facet).

The version is MAJOR.MINOR. Our commitment: any spec ever emitted still renders in a current engine, via migration if needed.

• Additive (MINOR). New optional keys may appear in a minor bump. A reader on an older minor ignores unknown keys and still renders.
• Breaking (MAJOR). Removing, renaming, or changing the meaning of a key is a major bump, and the engine ships a migration that upgrades an older spec on load.
• Forward-render guarantee. A spec written by an old version opens in a new one. The reverse is best-effort — unknown keys are ignored, not fatal.
• Deprecation. A key slated for removal is marked deprecated in the schema for at least one major line before it can be dropped.

The engine ships two spec-contract utilities:

• CanvasXpress.cxdiff(a, b) / specsEqual(a, b) — a structural diff of two figures (added/removed/changed paths), for reviewers, for git, and for the round-trip guarantee.
• CanvasXpress.provenanceHash(figure) — an optional, verifiable fingerprint over the canonicalized figure, so a figure in a report or filing can be checked by recomputing the hash.

A versioned, published spec is the difference between a figure you can defend and a picture you have to trust. It underpins reproducibility, the audit trail, and regulated-environment workflows. See the architecture for how the grammar engine consumes it.