What is a JSON file?

JSON is a plain-text format you can open in any editor. It is used for moving data between programs and the web.

The extension is .json, and the full name is JavaScript Object Notation. Both matter less than what the file can hold, which is what the rest of this page is about.

It dates from 2001. The specification is RFC 8259.

Age is worth knowing here for one practical reason: the older a format is, the more programs have had time to learn it.

It is published in full, so anyone can implement it from the document rather than by inspection, which is why it turns up in so many programs and why files written twenty years ago still open. A published specification is not the same thing as a royalty-free one: where a format wraps a codec, the patent licensing is a separate question the standard does not settle.

JSON stores its content exactly. Saving it again changes nothing, so it can be opened, edited and re-saved as often as you like without accumulating damage — which is what makes it a working format rather than a delivery one.

JSON has no comment syntax. Anything explanatory has to live outside the file, which is worth knowing before choosing it for something a human will edit by hand.

Visual Studio Code, jq and Postman read it, and so do most programs of the same kind.

If a file will not open, the format is rarely the problem — it is more often that the program predates it. Converting to something older is the reliable way past that, and it is what the rest of this site is for.

Every current browser reads it.

That makes it a safe thing to put on a page or attach to a message without wondering what the other end has installed.

JSON is meant to be opened and changed. Keep the file in this format for as long as the work is going on, and export from it whenever a finished copy is needed.

A JSON document is built from objects, arrays, strings, numbers, booleans and null. That is the entire vocabulary, and the shortness of the list is the reason the format took over: every programming language already has all six, so reading a document means calling one function and getting back native values with nothing to map.

The specification fits on a few pages. It was described rather than designed — Douglas Crockford took the object literal syntax JavaScript already had and wrote down what was already working — which is why it feels obvious rather than clever.

JSON has no comments, deliberately, and it is the format’s most-complained-about property. The reasoning was that comments invite parsing directives, and the result is that JSON is a poor configuration language however good it is as a wire format.

Three workarounds are in circulation. A key called something like an underscore-comment, which every parser will accept and every schema validator will reject. JSON5 and JSONC, which add comments and trailing commas and are not JSON — Visual Studio Code’s settings file is JSONC, which is why editing it in a strict tool fails. And the honest answer, which is to use TOML or YAML for anything a human maintains.

JSON does not distinguish integers from floating point. Most parsers read every number as a double, and a double holds integers exactly only up to about nine quadrillion.

Past that, values change silently. A 64-bit database identifier, a Twitter-style snowflake ID, a large financial amount in the smallest unit — all can come back as a different number from the one that was sent, with no error anywhere. The remedy is to send such values as strings, which every serious API does, and it is worth checking rather than assuming when integrating with one that might not.

Duplicate keys are not forbidden. Parsers differ in what they do — most keep the last, some keep the first, a few error — and a document relying on either behaviour is relying on an implementation rather than on JSON.

Key order is likewise not guaranteed to be preserved, so treating an object as an ordered structure is a mistake; use an array if order matters. And there are no dates: the universal convention is ISO 8601 strings, and every parser hands you a string that something else has to interpret.

JSON is UTF-8. The specification says so for anything exchanged between systems, and the practical corollary is that a byte order mark is not allowed — those three invisible bytes at the start of a file cause a parse failure whose message usually blames the first character rather than naming the cause.

If a JSON file fails to parse and looks perfect in an editor, that is the first thing to check. "UTF-8 without BOM" is the setting, and it is the same advice as for every other text format on this site, with the difference that here it is genuinely fatal rather than merely irritating.

A JSON document has to be complete before it can be parsed — the closing bracket is what makes it valid — so a ten-gigabyte array of records must be read entirely into memory before the first one is available. For large exports and log pipelines that is fatal.

NDJSON, also called JSON Lines, solves it by putting one complete JSON object on each line with no surrounding array. Each line parses independently, so a file of any size streams row by row, and a process can start work on the first record immediately. Data exports, log shipping and machine-learning datasets almost all use it, and it is the format to reach for whenever a JSON file is measured in gigabytes.

JSON Schema is the standard way to describe what a valid document looks like, and it is worth using for any interface between two systems — it turns "the API returned something odd" into a specific error naming the field. Support is good and less uniform than XML’s equivalent.

For everyday work, an editor with JSON support gives you the important half for free: a missing comma or a trailing one is flagged in place, and machine-generated JSON that arrived as a single long line can be pretty-printed into something readable. Both are two-second operations that save a surprising amount of time.