Understanding JSON: The Backbone of Data Interchange

When two programs that developers write in different languages exchange data, those programs need a common format. JSON is one of the most popular formats for that exchange today. Whether you write code for a living or you are curious about how software works, you can think more clearly about data once you understand JSON.

Programmers write in many languages, and each language has its own way of laying out data in memory. JSON is a single text format that programs in all of those languages can read and write, so that a program in one language can pass information to a program in another. In this article I explain the core principles of JSON so that anyone, technical or not, can come away knowing how it works.

What is JSON?

JSON (JavaScript Object Notation) is a standardised, lightweight text format for exchanging data between different systems and platforms. The format has fixed rules for how to write each piece of data, which means that any program that follows those rules can read what another program writes.

To make this concrete, imagine that you want to record details about a book in your library. You'd list:

Title: The Lord of the Rings
Author: John Ronald Reuel Tolkien
Published: 1954

In JSON, that same information looks like this:

{
  "title": "The Lord of the Rings",
  "author": "John Ronald Reuel Tolkien",
  "published": 1954
}

In JSON, each piece of information is a key-value pair. The key ("title") is the name of the piece of data, while the value ("The Lord of the Rings") is the data itself. You write the whole record inside curly braces {} and put a comma between one pair and the next.

Where JSON came from

Around 2001, Douglas Crockford, a JavaScript developer, introduced JSON as a specification. He wanted a simpler data format that humans could read and write with ease and that machines could generate and without extra work.

Before JSON, XML was the dominant format for data exchange. XML works; however, in XML you put every piece of data inside tags, which means that the tags can take up more space than the content itself. JSON has less syntax, while its structure matches the data types that programmers were already using.

JSON became a global standard for data interchange, so nearly every programming language in active use now supports it.

How JSON works

JSON has two structures:

Objects are collections of labelled items, like the book record above with its title, its author, and its year. In JSON, you write an object with curly braces {} and fill it with key-value pairs.
Arrays are ordered lists. A shopping list of 'milk', 'eggs', and 'bread' is one; in JSON, you write that list as an array by wrapping the items in square brackets [].

Here's a JSON object for a person:

{
  "name": "Delali",
  "age": 28,
  "isStudent": false,
  "hobbies": ["reading", "coding", "traveling"]
}

Notice that the value of the "hobbies" key is an array (a list of strings). You can nest arrays inside objects and objects inside arrays to any depth, so you can represent complex data.

JSON value types

JSON has six types of values. Here's what each looks like in practice:

A string is text inside double quotes. Use strings for names, descriptions, and any other human-readable content.

{
  "greeting": "Hello, world",
  "language": "English"
}

Numbers can be integers or decimals, because JSON has one number type for both.

{
  "age": 28,
  "temperature": 36.6,
  "altitude": -150
}

A boolean is either true or false, which makes it useful for a flag or a toggle.

{
  "isActive": true,
  "hasSubscription": false
}

You write null to mark a value as absent on purpose while you keep the key in place.

{
  "middleName": null,
  "deletedAt": null
}

You can nest an object inside another object to group related data.

{
  "address": {
    "street": "123 Main St",
    "city": "Accra",
    "country": "Ghana"
  }
}

An array is an ordered list of values of any JSON type. Its items can be of mixed types, although the data is easier to work with when every item has the same type.

{
  "colors": ["red", "green", "blue"],
  "coordinates": [5.6037, -0.1870]
}

The rules of JSON

JSON has a strict syntax, which means that even a small mistake causes a parser to reject the entire document. Here are the rules that you need to follow:

1
Use double quotes for all keys and string values
Wrap every key and every string value in double quotes, because single quotes are not valid JSON.
{ "name": "Delali" }
2
Separate key-value pairs with commas
Put a comma after each pair except the last one, because a trailing comma after the final pair makes the parser reject the document.
{ "name": "Delali", "age": 28 }
3
Wrap objects in curly braces, arrays in square brackets
Write objects with {} and arrays with [], because a parser cannot read a document in which you swap the two.
4
Leave comments out
JSON has no comment syntax, so where you need to annotate your data, add a dedicated key such as "_comment" or keep the documentation in a separate file.
5
Leave out the trailing comma
JavaScript accepts a comma after the last item in an object or an array, but a JSON parser rejects it.
{ "colors": ["red", "green", "blue"] }

Common mistakes

These errors are the ones to check first when a parser rejects your document:

Single quotes around strings are invalid, because a JSON string must be in double quotes, which is why {'name': 'Delali'} fails.
A trailing comma, as in {"a": 1, "b": 2,}, causes a parse error.
An unquoted key, as in {name: "Delali"}, is invalid, because every key must be a string in double quotes.
The value undefined is invalid, because the only marker for a missing value in JSON is null.
Comments in the file make a parser reject the document; remove every // and /* */ comment before you parse it.

A complete example

Here's a larger example of a small library, with objects, arrays, and nesting in it:

{
  "library": {
    "name": "Accra City Library",
    "location": {
      "city": "Accra",
      "country": "Ghana"
    },
    "books": [
      {
        "title": "The Lord of the Rings",
        "author": "J.R.R. Tolkien",
        "published": 1954,
        "genres": ["fantasy", "adventure"],
        "available": true
      },
      {
        "title": "Things Fall Apart",
        "author": "Chinua Achebe",
        "published": 1958,
        "genres": ["fiction", "historical"],
        "available": false
      },
      {
        "title": "Homegoing",
        "author": "Yaa Gyasi",
        "published": 2016,
        "genres": ["fiction", "historical"],
        "available": true
      }
    ],
    "totalBooks": 3
  }
}

In this single document there are nested objects (the library, its location, and each book), arrays (the list of books and each book's genres), strings, numbers, and booleans. A program that receives this data can parse it and find the library's name, its location, the books that it holds, and which of them are available.

Real-world use cases

JSON appears across software. Here are some of the places where you'll meet it:

Web APIs

When your weather app fetches the current temperature, the server usually sends back JSON. Web APIs (Application Programming Interfaces) commonly return JSON, because it is lightweight and a program in any language can parse it.

{
  "city": "Accra",
  "temperature": 31,
  "unit": "Celsius",
  "condition": "Sunny"
}

Configuration files

Tools such as VS Code, ESLint, and Prettier store their settings in JSON files, which means that when you customise your editor's behaviour, you are editing JSON.

{
  "editor.fontSize": 14,
  "editor.tabSize": 2,
  "editor.wordWrap": "on"
}

Data storage

Databases such as MongoDB and Firebase store documents as JSON, or as BSON, a binary variant of it. Because the format's structure is flexible, you can store records of differing shapes, whereas in a table every record would have to match one fixed .

Internationalisation (i18n)

Applications that support multiple languages commonly store their translations in JSON files, with one file per language:

{
  "welcome": "Akwaaba",
  "goodbye": "Nante yie",
  "thankYou": "Medaase"
}

If you want to experiment with JSON, open your browser's developer console (press F12) and type JSON.parse('{"name": "test"}'). The browser's built-in parser converts that string into a JavaScript object that you can work with, while JSON.stringify() converts an object back into a JSON string.

Data exchange between services

In any system where multiple services communicate (a payment processor that sends results to an order system, for example), JSON is the shared format that both sides use. Because JSON is plain text that every language can parse, a Python service can send it to a Go service when each side has its own JSON library.

Why JSON matters

JSON became the default data format for the web because people can read it and machines can parse it quickly. It is simple enough for a non-technical person to read and understand, yet structured enough for software to parse and generate in large volumes.

Nearly every language, framework, and platform supports JSON natively, which means that when you choose JSON for data interchange, the other side can already read it.

JSON is the format that you will meet most, whether you are building APIs, configuring tools, storing data, or working out how the systems around you communicate. Once you know its structure and rules, you can apply that knowledge across software development.