Our JSON formatter does one job well: it takes a wall of JSON and adds line breaks and indentation so you can read it. For a small document that is all you need. For the JSON you meet at work, a 4,000 line API response or a config file nested eight levels deep, formatting only turns an unreadable line into an unreadable page. The JSON visualizer is the tool for that next step. It draws the document as a diagram so you can see its shape at a glance instead of scrolling through it. This post covers what it is for, which problems it solves and how it works.
What it is
The JSON visualizer takes a JSON document and renders it as a diagram of connected boxes. Every object and array becomes a box, every nested object or array becomes a child box with a line to its parent, and the plain values inside an object are listed in the box itself. The result is a picture of the structure. You pan and zoom it like a map, and it redraws live as the JSON changes.
It is built for the moment after the JSON is valid and formatted, when the question is no longer "is this correct" but "what is in here and how is it organised". That moment comes up constantly: the first time you call a new API, when a colleague sends you a config file, when a webhook payload is not what the docs promised, when you inherit a project with a 2,000 line settings file.
The first release is a VS Code extension, because most of the JSON we read is already open in an editor. A web version on this site, with the same engine, follows it.
The pain it solves
JSON was designed to be easy for machines to parse and reasonable for people to read. The second half only holds while the document is small. As it grows, a few specific things go wrong, and each of them is something we hit ourselves often enough to build a tool for.
- Depth becomes invisible. At six or seven levels of nesting the indentation is so wide that you cannot tell which closing brace belongs to which opening brace. You end up counting brackets by hand, or collapsing and expanding regions in the editor and losing your place.
- Arrays hide their size and their shape. An array of 500 objects, each with twenty keys, is 10,000 formatted lines. You cannot see that it has 500 items, or that item 137 is missing a field, without scrolling through all of it.
- Structure is repeated instead of described. If every user object has the same eight keys, a formatted view shows you those eight keys 500 times. What you want to know is the shape, once.
- The path to a value is guesswork. You can see a value on screen, but writing the path to it, something like
data.orders[12].items[0].sku, means scrolling upward and tracking every level you pass. - Explaining the structure to someone else is hard. A pull request description or an API doc that says "the response looks like this" and pastes 200 lines of JSON gets skimmed, not read. A screenshot goes stale the week after.
Text is a poor medium for hierarchical data. JSON is a tree, and a tree is understood fastest when it is drawn as one.
What you get from a diagram
A drawn tree fixes those problems in a direct way.
- The whole shape in one screen. Depth is horizontal distance, not indentation. A document nested eight deep is eight columns of boxes, and you can see all eight without losing track of the nesting.
- Arrays read as one box. An array shows how many items it holds, and its items fan out from it. Five hundred similar objects still take space, but the layout makes it obvious that they are five hundred of the same thing, rather than five hundred separate things to read.
- Every value sits next to its key, inside its object. Long strings are cut to a readable length, objects with dozens of keys are trimmed with a count of what was left out, and the box stays compact enough to scan.
- Live update. Edit the JSON and the diagram redraws. When you are hand editing a config file, this is the fastest way to confirm you put the new block inside the right parent.
- Big files stay usable. There is a node limit, 300 by default and adjustable, so a huge document draws the top of the tree quickly and tells you it was cut, instead of freezing your editor while it tries to lay out ten thousand boxes.
As with every tool on this site, your JSON never leaves your machine. The extension runs inside VS Code with no network access, and the web version will run entirely in the browser. You can point it at production data.
How the diagram is built: Mermaid
Under the hood the visualizer converts the JSON into a Mermaid flowchart and renders that. Mermaid is a text based diagram language that GitHub, GitLab, Notion, Obsidian and most Markdown tools render natively. Choosing it was deliberate, because it means the diagram is not just a picture on screen. It is text you can copy into a README or a pull request and have it render there, with no image files to maintain.
A document like this:
{
"user": { "id": 1, "name": "Ada", "roles": ["admin", "editor"] },
"session": { "token": "...", "expires": "2026-10-01" }
}becomes a Mermaid definition along these lines:
graph LR
root --> user
root --> session
user["id: 1
name: "Ada""]
user --> user_roles["roles [2]"]
user_roles --> r0[""admin""]
user_roles --> r1[""editor""]
session["token: "..."
expires: "2026-10-01""]Paste that into a Markdown file on GitHub and it shows up as a diagram. That is a quick way to document what an API returns, and because the source is text it diffs cleanly when the response changes.
Getting this right took more care than it sounds. Mermaid labels go through an HTML parser, so quotes, angle brackets and even semicolons inside your JSON values have to be escaped or the diagram breaks. Mermaid also rewrites anything that looks like #word; into a placeholder, which bites the moment a string contains a colour code or an entity. The converter handles all of that, so a value like <div class="x"> renders as text instead of breaking the graph.
Layout choices
Two settings cover most of what people want to tweak.
- Direction. Left to right is the default, which suits deep documents because depth runs across a wide screen. Top to bottom works better for shallow documents with many siblings, such as a flat list of records.
- Node limit. The default of 300 keeps drawing fast. Raise it for a big file you really want to see whole, or lower it on a slow machine.
How it fits with the formatter
The two tools are meant to be used in order. The JSON formatter is the right choice when a document may be broken, when you want to sort keys or minify it, or when you need line and column numbers for a syntax error. Once it is valid and you need to understand it, the visualizer takes over. If you work with jq on the command line, our guide to working with JSON from the command line covers that side, and the diagram is a good way to work out which path to feed jq.
What is next
The extension is being finished for the VS Code Marketplace, and the web version comes after it. On the list for both: click a node to copy its path in dot or bracket notation, search that filters the tree to matching branches, and a shape summary for arrays of objects that lists which keys appear and how often, so optional and inconsistent fields stand out without reading every item.
If a feature would make this useful for your work, a diff between two documents, a schema export, a specific diagram style, send it through the Contact page. Requests that arrive early have a good chance of getting in.