JSON for non-developers: what the braces mean

JSON looks like a secret code, but it is closer to a very strict recipe: a small set of characters arranged by a few unbreakable rules. Once the rules are visible, every JSON document in the world — an API response, a config file, an export from a spreadsheet — becomes readable as the same structure. Here is the whole system in one page.

The three characters that carry the meaning

The entire language is three shapes:

• Curly braces { } wrap an object: a collection of named values — “key”: “value” pairs. The braces say “this is a single thing with named parts.”
• Square brackets [ ] wrap an array: an ordered list of values. The brackets say “these items belong together, in this order.”
• Quotes wrap every name — the key on the left side of each colon is always a quoted string.

The values themselves can be five kinds of thing: a string (“warsaw”), a number (52.2), a true/false boolean, null (meaning “nothing here”), or — the part that makes JSON powerful — another object or array. Because values can nest, one document can describe a structure of any depth: a company with employees, each employee with an address, each address with coordinates.

Reading a document

Here is a small real-world-shaped response, formatted so the structure is visible:

{
  "status": "ok",
  "items": [
    { "id": 1, "name": "A" },
    { "id": 2, "name": "B" }
  ]
}

Read it top to bottom: the outer braces open an object with two named parts — “status”, whose value is the string “ok”, and “items”, whose value is an array. The array holds two objects, each with an “id” (a number) and a “name” (a string). In plain English: “the request succeeded, and here are two items with their identifiers and names.” The indentation is a courtesy — the same document in its compact form is one line, 65 characters:

{"status":"ok","items":[{"id":1,"name":"A"},{"id":2,"name":"B"}]}

Both versions are the identical document. The compact one is what travels between computers — smaller is faster — and the formatted one is what humans read.

The rules that make it strict

The strictness is the feature, not a developer’s pedantry. JSON exists to be handed between systems that know nothing about each other — a browser and a server, a spreadsheet and a script — and the only way that works is a grammar every side agrees on, with no room for interpretation:

• Keys are always double-quoted. {name: "A"} is invalid; {"name": "A"} is valid. Single quotes are rejected too.
• No trailing commas. The last item in a list or object has no comma after it — [1, 2,] is invalid, [1, 2] is valid.
• No comments. A JSON document is pure data; there is nowhere for an explanation to live.
• No unquoted or apostrophe variants, no undefined, no functions. If it is not one of the five value types, it does not belong.

These rules exist because a document that “almost” parses on your system might parse differently on the next one — and the point of the format is that every reader gets the same data out of the same text. That is also why a validator matters: it checks grammar, not meaning. A document can be perfectly valid JSON and still contain the wrong data — the wrong key, the wrong number — which is a problem no tool can detect, because it is a problem about the world, not about the syntax.

Why it is everywhere

The same structure shows up in three places, and each is the same text:

• API responses — every app you use fetches data as JSON. A weather widget, a search result, a price feed: the server sends a document with braces and brackets, and the app reads the keys it knows.
• Config files — tools store their settings as JSON: {"theme": "dark", "checkInterval": 300} is a perfectly normal config document.
• Spreadsheet exports — the bridge from tabular data. A CSV file (comma-separated values) is the tabular form; converting it to JSON turns each row into an object with the column names as keys.

The interesting one is the last. A spreadsheet’s columns are keys and its rows are objects — the conversion is structural, not magical: the first row of the CSV names the keys, every data row becomes one object, and the result is an array of objects. Quoted fields, embedded commas, and multi-line cells are handled by the standard CSV rules (RFC 4180), so the export from any spreadsheet tool converts cleanly into the JSON shape an API or a script expects.

What the tools actually change — and do not

Two of the most-used JSON utilities exist precisely because the format is strict and the whitespace is free:

• Formatting re-indents a document so the structure is readable — one property per line, two spaces per nesting level. It changes nothing about the data: for valid JSON, the parse-and-re-stringify round trip is lossless. The stats row shows the cost of readability: our 65-byte document becomes 129 bytes formatted — and stays 65 bytes when compacted.
• Minifying does the reverse: strips every byte of insignificant whitespace to produce the smallest valid form, byte-for-byte the same data. The 129-byte formatted document becomes 65 bytes — a 49% saving that matters when an API quota or a stored blob counts bytes.

Both operate on the same guarantee: the data survives exactly, key order included. Neither can fix an invalid document, but both tell you where the grammar breaks — and a validator that reports “trailing comma at position 66” has done the debugging for you, because that position is where the parser stopped.

Let the calculator do it

The JSON formatter & validator takes any document — an API response, a config file, a hand-edited fixture — and returns the indented form with precise error messages and position when the document is invalid, plus input, formatted, and minified sizes in bytes. The JSON minifier compresses a document to its smallest valid form with the exact bytes saved. And the CSV to JSON converter turns spreadsheet exports into JSON objects, auto-detecting the delimiter and mapping the header row to keys. All three run entirely in the browser — nothing is uploaded, logged, or stored, which makes them safe for documents that carry tokens, customer lists, or personal data.

The one rule

A JSON document is always the same three shapes — objects in braces, lists in brackets, names in quotes — nested as deep as the data requires. Read it by asking “what is this object made of”, and treat any strictness you meet as the guarantee that the document means the same thing to everyone who reads it. The tools only move whitespace; the meaning is in the structure.