JSON-stat Builder

[Xavier Badosa]

The JSON-stat Builder is a browser-based tool for creating JSON-stat datasets interactively. Rather than hand-writing the verbose, error-prone JSON-stat format by hand, you describe your data through a guided wizard and the tool serializes a correct, validated dataset document for you — ready to copy or download.

It fills a real gap in the JSON-stat ecosystem. Today there are many tools that read or export from JSON-stat (to Excel, CSV, Tableau, Power BI, …) and a single one-way CSV importer, but nothing that lets you author a JSON-stat cube from scratch through an interactive, human-driven session. The builder is that authoring route.

Create JSON-stat datasets

The builder's job is to take you from an idea — "I have a table of figures I want to share as open statistical data" — to a finished JSON-stat document you can publish, archive, or feed into the rest of the JSON-stat toolchain. You stay focused on your content (what the numbers mean, how they are classified); the tool takes care of the syntax (the exact shape a JSON-stat dataset must have to be valid and interoperable). The output is plain JSON you fully own: dense arrays or sparse objects, with optional observation status metadata, ready to drop into any JSON-stat-aware consumer.

Learn the format by using it

JSON-stat is powerful but not obvious: dimensions, categories, roles, dense vs. sparse values, row-major ordering, the difference between what a field means and where it sits in the document. Reading the specification helps, but there is no substitute for building a cube yourself. The builder doubles as a learning environment — every choice you make is reflected live in the generated output, so you see, in real time, how a dimension becomes id + size, how categories become category.index, and how your grid of numbers becomes the value array. By the time you finish a dataset, you have not just produced a file; you genuinely understand the format behind it.

Think in cubes: data modelling comes first

A spreadsheet is a flat grid of rows and columns. A JSON-stat dataset is a cube: a multi-dimensional structure where every observation sits at the crossing of one category per dimension. Working with JSON-stat therefore starts with data modelling, not data entry. The builder enforces this discipline gently: before you type a single number, you name your dimensions (e.g. geography, sex, year), give each an ordered list of categories (e.g. Spain, France, Germany), and assign roles (time, geo, metric). This step is where the meaning of your data is fixed, and it is what turns a loose table into a well-defined statistical cube. The order you define dimensions in even governs how values are stored — a detail the tool makes tangible instead of hidden.

A guided, step-by-step workflow

Authoring a cube can feel daunting, so the builder breaks it into a clear, linear wizard of five steps:

1. Metadata — give the dataset a label, a source, an updated date, and an optional href: the descriptive context that makes the data citable.
2. Dimensions & categories — define each dimension and its categories, and assign roles. This is the modelling step described above.
3. Layout — place each dimension on the row or column axis of a cross-tab grid. This is presentation only: it shapes what you see while entering data, never the document you ultimately export.
4. Data — fill the grid with your numbers.
5. Output — generate, validate, preview, copy, and download.

You can move back and forth freely, so refining an earlier choice (adding a category, relabelling a dimension) is always one click away.

Feed it data your way

Real-world data does not arrive in one neat shape, so the builder accepts yours in several. You can enter information manually, one item at a time, or import it in bulk from text — and the importer is deliberately tolerant, auto-detecting whether you pasted tab-separated, semicolon-separated, comma-separated, or whitespace-separated content (a nod to European locales, where , is a decimal mark and ; a column separator). This applies both to classifications (a dimension's long list of categories, e.g. every municipality in a country, imported as id,label pairs) and to the data itself.

Where the numbers come from

The data you feed the grid can come straight from the tools you already use:

• Spreadsheet tables — copy a block of cells and paste it; the builder reads it into the grid shaped by your layout.
• CSV / TSV files — paste their contents directly.
• Tidy / long format — one observation per row (dim1,dim2,…,value), the natural shape of most analytical exports. The builder maps each row to its coordinate, so it works regardless of how you laid out the grid.
• Manual entry — type values directly into the grid for small datasets or quick edits.

An empty cell simply means a missing value (null), and you can annotate why a value is missing with free-form observation status codes (estimated, provisional, revised, …) — independently of the numbers.

Always valid, by construction

Whatever path you take, the promise is the same: the document you export is always a valid JSON-stat dataset. On every Generate, the output is checked with the official JSON-stat tooling — vendored so it works fully offline — which runs both structural (schema) and cross-field semantic checks, and then reads the document back through the JSON-stat Toolkit to confirm every cell can be reached. Copy and Download stay disabled until there are zero errors, so you can never walk away with a broken file. The result is a dataset you can trust to load anywhere in the JSON-stat ecosystem.

Xavier

[Xavier Badosa]

https://jsonstat.com/builder/