The Spec Is the Whole Truth: Hand-Writing, Diffing, and Migrating a CanvasXpress Dashboard

Part 2 of the CanvasXpress Dashboards series. The builder and the chat assistant are conveniences. Underneath both is one JSON document you can read, diff, review, and version — and that document is the dashboard.

Most dashboard tools keep the real definition somewhere you can’t reach: a binary workbook, a row in a vendor’s database, a tangle of GUI state. You edit it through their editor and hope the export round-trips. canvasxpress-dashboards inverts that. The spec is the whole truth — a single JSON document that fully describes the board. The builder edits it, the chat assistant produces it, but neither owns it. You can open it in a text editor, commit it to Git, review it in a pull request, and generate it from a script.

This post is about what that buys you.

Everything in that board — nine coordinated panels, their layout, their data bindings — is a single JSON file. No hidden state, no vendor workbook. That’s the claim; here’s how it holds up.

One document, four concerns

A spec has four parts, and that’s most of what there is to learn:

layout places panels on a responsive 12-column grid. data declares named sources once. panels binds each view to a source by dataRef and hands the rest straight to new CanvasXpress — so there is no subset of the chart library you "can't get to" from a dashboard. If CanvasXpress can draw it standalone, a panel can draw it.

The important property is that nothing lives off to the side. There’s no hidden per-panel state the GUI remembers and the file forgets. What you see in the document is what renders.

Because it’s text, it’s reviewable

A dashboard that is one JSON file is a dashboard you can treat like code.

• Diff it. Change a graph type or a color and the diff is two lines, not an opaque “workbook modified.” A reviewer sees exactly what moved.
• Review it. A board ships through the same pull request as the analysis it visualizes. The reviewer reads the spec, not a screenshot.
• Generate it. Twelve near-identical cohort boards are a for loop over a template, not twelve afternoons in a GUI.
• Keep it in the repo next to the data. The board and the pipeline that feeds it version together, so a board from last quarter still describes last quarter.

None of this needs a special API. It’s a JSON file; use the tools you already have for JSON files.

Derived data lives in the spec too

The spec isn’t only layout and chart config — a source can carry its own derivations, so the same transformation feeds every panel, filter, and join that reads it. Calculated fields are declared on the source and computed once:

Two things worth noting. First, the formula language is CanvasXpress’s own — a real tokenizer and parser, never eval — so a spec carries no executable JavaScript and is safe to accept from elsewhere. Second, because the fields are computed on the source, Margin exists identically in the bar chart, the table, the Filters panel, and anything joined onto orders. You define the derivation once, in the document, and it's part of the board's definition forever after.

Get Isaac Neuhaus’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

Because the spec is complete, a board can even export its own provenance — the toolbar’s Download → Reproducible bundle writes a zip with the self-contained spec, a data snapshot, per-panel R and Python regeneration code, and a methods.md, and each panel carries an auto-derived method line in its footer. The document isn't just what renders; it's the full record of how.

Forward-compatible by design

A board you save today has to open next year, possibly against a newer engine. Two rules make that safe:

• Unknown fields are ignored. A field a future version adds doesn’t break an older reader; it’s simply skipped. So a new capability doesn’t invalidate every board that predates it.
• A version field gates migrations. When the shape of the spec genuinely changes, the version tells the renderer how to read an older document and bring it forward. Old boards keep opening; they don't get stranded on an engine that no longer understands them.

This is the quiet half of “the spec is the whole truth.” It isn’t only that the document is complete — it’s that the document stays readable as the software moves underneath it.

The builder is just an editor for this file

It’s worth being precise about what the no-code builder and the chat assistant are, because it changes how you think about them. They are not the dashboard. They are two ways to produce the same JSON:

• Drag a panel, resize it, pick a data source → the builder writes layout and data.
• Open a panel’s ⚙ customizer, change the graph type and colors → CanvasXpress’s own widgets edit panel.config, read back through getConfig().
• Describe the board in plain English → the assistant emits a panel into the same document.

Any of those actions, you could have performed by typing JSON. The GUI is faster and friendlier; the file is authoritative. Which means you’re never locked into the editor: export the spec, hand-tune a value the GUI doesn’t expose yet, re-import it, and keep going. You reconfigure; you never fork.

Why this matters

The deepest reason to make the spec the whole truth isn’t convenience — it’s reproducibility. A finding you can’t reproduce is an anecdote. When the entire board is one text document, “here is the figure” and “here is exactly how to rebuild the figure” are the same artifact. You hand a colleague the spec, they open it, and they are looking at your board — not a rendering of it, not an export that lost something, but the board itself.

That’s the thing a cloud BI document locked in someone else’s database can’t give you, and it’s the foundation the rest of this series builds on: a dashboard you can talk to (Part 3), bind to live data (Part 4), author in R (Part 5), and run on your own hardware (Part 6) — all of it, still, just this one document.

Try it: npm install canvasxpress-dashboards canvasxpress, or open the live builder at canvasxpress.org/dashboards. Source and the full spec reference: github.com/neuhausi/canvasxpress-dashboards.

Next: A Dashboard You Can Talk To — the natural-language assistant, and why no API key lives in the app.