What is JSON?

When two software applications need to exchange structured data, they need a common format that is lightweight, simple and understandable for both systems (and ideally for any humans involved too). 

Today, that format is almost always JSON. Created in the early 2000s to simplify data exchange within web applications without weighing down the network, it has become the standard for REST APIs, configuration files and data storage in several databases.

What is the JSON format

JSON stands for JavaScript Object Notation. It is a text-based format for structuring and exchanging data that is easy to read for both humans and machines.

JSON was described in the early 2000s by Douglas Crockford. It was Crockford himself who, in April 2001, sent the first JSON message, addressed to Chip Morningstar, his colleague at Electric Communities.

Although it is based on a subset of JavaScript (Standard ECMA-262), JSON is a text format that is completely independent of any programming language. However, it uses conventions that are very familiar to anyone working with C and C++, Java, Perl, Python and other programming languages.

JSON became an ECMA standard in 2013 and was last updated in 2017, with the publication of the ISO/IEC 21778 standard.

JSON: how is it structured?

A JSON file looks like a text file based on two fundamental structures:

• Object, a set of key-value pairs enclosed in curly braces;
• Array, an ordered list of values enclosed in square brackets.

Within the file, keys (or names) must always be enclosed in double quotes (for example: “name”). Values and key-value pairs are separated by a comma. And within an object, each key is followed by a colon, which introduces its value.

For example, a JSON file might look like this:

{

  "name": "Marco",

  "age": 30,

  "student": false,

  "interests": ["programming", "reading", "travel"],

  "address": {

    "city": "Rome",

    "postal_code": "00100"

  },

  "phone": null

}

What values does the JSON format support?

In terms of values, the JSON format supports a few fundamental data types:

• Booleans (true, false);
• Numbers, both integers and decimals;
• Strings enclosed in double quotes;
• Arrays (ordered sequences of values, separated by commas and enclosed in square brackets);
• Objects (other blocks enclosed in curly braces, nested inside);
• null, the special value indicating the absence of data.

As for strings, they can be of any kind. The current ECMA standard states that:

"The JSON syntax does not impose any restrictions on the strings used as names, does not require that name strings be unique, and does not assign any significance to the ordering of name/value pairs."

The JSON format in REST APIs

Because it is lightweight, human-readable (human readable text) and supported by all major programming languages, JSON has become the default data format for REST APIs, as well as for configuration files and several databases, such as MongoDB and PostgreSQL. Essentially, it is used wherever two programs exchange structured data.

In REST APIs specifically, the server sends JSON in the response body and labels it with the Content-Type: application/json header. 

In this context, the format is used asymmetrically depending on the operation:

• In read requests (GET), search parameters usually travel in the URL and the server responds by returning a JSON payload;
• In write requests such as POST, PUT or PATCH, on the other hand, the client sends a JSON payload directly in the request body to create or update a resource on the server.

In both cases, the body of the messages exchanged between client and server is structured entirely in this format.