The letters JSON stand for JavaScript Object Notation, but that doesn’t really help you understand what it is, and what it’s for. JSON may have it’s origins in JavaScript, but it’s moved on from there. JSON has become a very popular human-readable plain-text format for sending structured data between applications.

In short, JS is a way of representing data that both computers and humans can read and understand. Think of it as XML’s younger better looking cousin 🙂

Note that this article is intended to be a JSON primer, not an exhaustive description of the format.

Three Building Blocks

At it’s simplest level, JSON has just three building blocks – single values, lists of values, and sets of name-value pairs. Using just these three simple building blocks, JSON can represent very complex data structures. Let’s start by looking at each one individually:

Single Values

A single value is just one piece of data. It can be a number, a string of characters, or a boolean (true/false) value.

Numbers can be integers or floating point numbers, and are represented in JSON without any additional fluff – the following are all valid JSON numeric values:

42
1001
-33
3.1415
1256.56
-42.7

There are two valid boolean values in JSON:

true
false

Strings of characters must be enclosed within quotation marks

"This is a string"

The backslash character (\) is used to ‘escape’ special values within a string, e.g.:

  • \n represents a new line character
  • \t represents a tab character
  • \" represents a quotation mark
  • \\ represents a single backslash

JSON strings should always be encoded in UTF-8, so you can include accented characters in your strings directly:

"This cliché of a string is valid"
"this string\nis split over two lines"
"you can even include emoji in JSON strings: 💩"

Lists

A list is, as it’s name suggests, an ordered sequence of one or more values. In programmer-speak, they are arrays.

JSON represents an array as a comma-separated sequence of values enclosed between [ and ] characters. The following are valid JSON lists:

[1, 2, 3, 4, 5]
["hello there, I am one value", true, -3.1415, 22, "boo!"]

Dictionaries

A dictionary is a collection of name-value pairs, where the name is a string, and the value can be any valid JSON value. Programers might be more used to the terms Hash table, or hash reference for this kind of data structure.

In JSON, the name and value which make up a single name-value pair are separated by the : character, and the pairs that make up the dictionary separated by commas. The entire dictionary is enclosed between { and } characters.

{"name" : "Bart's Widget", "price" : 23.45, "currency" : "€"}

Building Bigger

Both lists and dictionaries store values, and, those values can be ANY valid JSON value, including lists and dictionaries. The support for nesting it what makes JSON so powerful.

As an example, the Crypt::HSXKPasswd perl module represents it’s configuration as a collection of name-value pairs, where some of those values are lists if strings. This means that JSON can be used to represent any valid Crypt::HSXKPasswd configuration, e.g.:

{
    "num_words": 3,
    "word_length_min": 5,
    "word_length_max": 7,
    "case_transform": "RANDOM",
    "separator_character": "RANDOM",
    "separator_alphabet": [
        "-",
        ":",
        ".",
        ","
    ],
    "padding_digits_before": 2,
    "padding_digits_after": 2,
    "padding_type": "FIXED",
    "padding_character": "RANDOM",
    "symbol_alphabet": [
        "!",
        "?",
        "@",
        "&"
    ],
    "padding_characters_before": 1,
    "padding_characters_after": 1,
    "random_increment": "AUTO"
}

Note that dictionaries and lists can be spread over multiple lines, allowing for nice human-readable data structures like the one above.