JSON basics for non-developers

JSON stands for JavaScript Object Notation. It was described by Douglas Crockford in the early 2000s and standardised as ECMA-404 and RFC 8259. Despite the name, it has nothing to do with running JavaScript: every mainstream language, database and spreadsheet tool can read and write it, which is exactly why it became the default way for programs to exchange data.

You meet it in three typical places. Exports: many web apps offer “download as JSON” for contacts, orders or analytics. Configuration: editors, build tools and desktop apps keep their settings in files such as settings.json or package.json. And APIs: when one service asks another for data, the answer is almost always a JSON document, so support tickets and integration questions often include one.

Everything in JSON is one of six things. An object is a group of name–value pairs inside curly braces; names are always strings in double quotes and are separated from their value by a colon. An array is an ordered list inside square brackets. The remaining four are the leaves: strings in double quotes, numbers written plainly (no quotes, no thousands separators, no currency signs), the two literals true and false, and null, which means “no value”.

{
  "name": "Mari Tamm",
  "age": 34,
  "active": true,
  "manager": null,
  "tags": ["wholesale", "repeat"],
  "address": { "city": "Tallinn", "postalCode": "10111" }
}

Notice two things in that example. The value of address is itself an object — nesting is how JSON expresses structure, and it can go as deep as the author likes. And postalCode is a string even though it looks numeric: quotes tell software to keep it exactly as written, which matters for anything with leading zeros or dashes, such as phone numbers, ZIP codes and IDs.

JSON is strict on purpose, so that every program reads a file the same way. The mistakes that trip people up are always the same few. A trailing comma after the last item of an object or array is invalid, even though JavaScript and most programming languages accept it. Single quotes are not allowed anywhere; both keys and strings need double quotes. Keys cannot be bare words: {name: 1} is not JSON, {"name": 1} is.

Comments do not exist in standard JSON. Some tools (VS Code's settings, TypeScript's tsconfig) read a relaxed dialect called JSONC that permits // and /* */ comments, but an export or an API will reject them. Line breaks inside a string must be written as the two characters \n, and a literal double quote inside a string as \". Finally, a document holds exactly one top-level value: two objects one after another are not a valid file, though wrapping them in an array is.

When a program says “Unexpected token” it rarely points at the real cause. A validator that reports a line, a column and a plain-language reason (“trailing comma before }”) saves most of the guesswork. JSON Loomly does this as you type and underlines the spot in the editor.

Exports are often delivered minified: one enormous line with no spaces, which is efficient for machines and unreadable for people. The first step is always to format it — two spaces of indentation per level is the common convention — so that each key sits on its own line and nesting becomes visible as indentation. The content does not change; only whitespace is added.

For deeply nested data a tree view is faster than scrolling. Collapse the branches you do not care about, expand the one you do, and note the path to the value you are looking at — for example orders[2].customer.email. Paths are how developers will refer to the same value, so quoting one in a bug report or a question makes you instantly understood. Sorting keys alphabetically also helps when two documents should be compared by eye.

Keep the original file untouched and work on a copy. Make one change at a time, and re-validate after each: a missing quote in line 40 will be reported immediately instead of surfacing later as a cryptic failure in another tool. When you change a value, keep its kind — replace a number with a number and a string with a string, and do not turn null into an empty string unless you know the receiving program treats them the same.

Before you send the edited file anywhere, compare it with the original. A structural diff lists exactly which paths were added, removed or changed and ignores differences that do not matter, such as key order or indentation. If the list contains anything you did not intend, you have caught it before anyone else did.

A few limits are worth knowing. There is no date type: dates are strings by convention, usually in the ISO 8601 form 2026-06-14T09:30:00Z, and it is up to the reader to interpret them. Numbers are stored as decimal text, but most programs read them as 64-bit floating point, so integers above 2^53 (about 9 quadrillion) and long numeric identifiers can lose digits — which is why serious APIs send such IDs as strings.

The standard also says nothing about duplicate keys or key order. Most parsers keep the last duplicate and preserve the order they read, but neither is guaranteed, so a file that depends on either is fragile. If you need order, use an array; if you need a value only once, make sure the key appears only once.