noted.do
The Tech Guy

JSON, Explained Without the Jargon

If you've poked around an API, a config file or your browser's developer tools, you've seen JSON. Curly braces, quoted words, colons. It looks a bit like code because it sort of is. JSON stands for JavaScript Object Notation, and it started as a way of writing data that happened to look like a JavaScript object. These days basically every language can read and write it, and it's become the default way programs pass data to each other over the web.

Here's a small example:

{
  "name": "Ada",
  "age": 36,
  "subscribed": true,
  "nickname": null,
  "languages": ["English", "French"],
  "address": {
    "city": "London",
    "postcode": "W1"
  }
}

That's pretty much the whole language. There are six kinds of value:

  • Strings, in double quotes: "Ada"
  • Numbers: 36, 3.14, -2, 1e6
  • Booleans: true or false
  • null, meaning "nothing here"
  • Arrays, an ordered list in square brackets: ["English", "French"]
  • Objects, a set of key and value pairs in curly braces, where the keys are always strings

Objects and arrays can contain each other as deeply as you like, which is how you describe pretty much any structure, from a single user to a whole order with line items and shipping details.

The reason it took over is that it's simple enough for people to read and simple enough for computers to parse quickly. Before it caught on, XML was the usual choice, and XML is a lot wordier to say the same thing.

The rules that trip people up

JSON is strict, and most "invalid JSON" errors come from a handful of mistakes.

Keys and strings need double quotes. Single quotes aren't allowed. {'name': 'Ada'} is fine in Python or JavaScript but it isn't JSON.

No trailing commas. ["a", "b",] will be rejected. This one gets everyone who writes JSON by hand.

No comments. There's no // or #. If you need notes in a config file, that's one reason formats like YAML, TOML or JSONC (JSON with comments, used by some editors) exist.

No dates. There's no date type, so people usually store them as strings in ISO 8601 format, like "2024-05-01T14:30:00Z", and convert them in code.

Big numbers can lose precision. JSON itself doesn't limit number size, but JavaScript stores numbers as 64-bit floating point, so integers bigger than 253 get rounded when parsed. This is why some APIs send large IDs as strings. If you see "id": "1234567890123456789" with quotes, that's probably why.

Reading and writing it in code

In JavaScript:

const user = JSON.parse('{"name": "Ada", "age": 36}');
console.log(user.name); // Ada

const text = JSON.stringify(user, null, 2); // pretty-printed with 2-space indent

In PHP:

<?php
$user = json_decode('{"name": "Ada", "age": 36}', true, 512, JSON_THROW_ON_ERROR);
echo $user['name']; // Ada

$text = json_encode($user, JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR);

That JSON_THROW_ON_ERROR flag is worth getting in the habit of using. Without it, json_decode just returns null when the input is broken, which looks exactly the same as valid JSON that contains null. The flag makes it throw an exception you can actually catch.

And a safety note: always parse JSON with a real parser. Never run it through eval() or anything like it, even if it "works." Data from outside your program is data, not code.

Handy tools

Your browser can pretty-print JSON responses if you open them directly, and the network tab in developer tools shows the JSON going back and forth on any site. On the command line, jq is fantastic for slicing up big JSON files: jq '.address.city' user.json pulls out just the city. And most code editors will format and validate JSON for you, which is the quickest way to find that one stray comma.

Once you can read it comfortably, a lot of the web gets less mysterious. Most of what apps send each other is just this, back and forth, all day long.

Comments

Be kind. See the rules.