Json

In the early 2000s Douglas Crockford created json to be minimal, portable, and textual. A subset of JavaScript, json came into popularity around the same time. It was standardized in 2013, and published in 2017 as RFC8259, the Internet Engineering Task Force (IETF) standard for the Internet.

Json grew out of a need for stateless, real-time server-to-browser communication. It aimed to be a lightweight alternative to XML to allow for easy parsing of JavaScript on the web.

Although json was designed around JavaScript, it is not restricted to use with JavaScript.

Json's simplicity is part of its appeal. It's easy to write, easy to read, and easy to translate between the data structures of most languages. Let's take a look at what makes up a json object, the data types that json supports, and other specifics with the syntax of this markup language.

If you have ever worked with an API or looked through the documentation for one you have probably encountered json. The criteria for a valid json file is rather simple, though it can be used to describe complex data. The structure of a json object is as follows:

• Curly braces ({}) hold objects
• The data is in Key/Value pairs
• Square brackets ([]) hold arrays
• Each data element is enclosed with if it is a character, or without quotes if it is a numeric value
• Commas are used to separate pieces of data

Here is a basic example:

{
  "name": "John Lennon",
  "born": 1940,
  "died": 1980
}

The key of our first object is name and the value is John Lennon in the above example. We can also see that our second and third objects have a numeric value assigned to them.

Json also allows us to nest json structures like this:

{
  "band_members": [
    { "name": "John Lennon", "born": 1940 },
    { "name": "Paul McCartney", "born": 1942 },    
    { "name": "George Harrison", "born": 1943 },
    { "name": "Ringo Star", "born": 1940 },
  ]
}

In this example we can see that a primary object with a single key (band_members) has an array as its value. Within that array, each item is itself an object, similar to the earlier simple example. Objects and arrays are values that can hold other values, so there's an unlimited nesting that could happen with json data. That allows json to describe most data types, from to tabular to even more complex.

Now that we have seen the structure of json, let's look into what data types are supported. We have seen some of them in the above example and there are only a couple more to cover. Here is the complete list of json data types:

string

Literal text that's enclosed with quotes.

number

Positive or negative integers or floating point numbers

object

A Key/Value pair enclosed in curly braces.

array

A collection of one or more json objects.

boolean

A value that is either true or false with no quotes.

null

Indicates the absence of data for a Key/Value pair, represented as null with no quotes.

Here is an example of a json object that includes all of these data types:

{
  "name": "John Lennon",
  "born": 1940,
  "instruments": ["vocals", "keyboards", "guitars"],
  "mathmatician": false,
  "current_location": null
}

We have already covered the structure of json, which provides the basics of the syntax. In this section we will suggest some best practices to avoid common json errors:

Always enclose the Key/Value pair within double quotes. Most json parsers don't like to parse json objects with single quotes:

{ "name": "John Lennon" }

Never use hyphen in your key fields. Use underscores (_), all lower case, or camel case:

{ "first_name": "John", "last_name": "Lennon" }

Use a json linter to confirm valid json. Install a command line linter or use an online tool like JSONLint. If you copy this next example into a json linter, you should get a parse error the single quotes around the value for last_name:

{ "first_name": "John", "last_name": 'Lennon' }

That pretty covers json as the syntax and structure are quite simple. Unlike yaml whitespace and indentation don't matter as long as your syntax is right. Interestingly since yaml is a superset of json, yaml files can be converted to json files most of the time with easy using a converter like json2yaml. Yaml does have a lot more features than json so this may not always be possible without some editing including the fact that yaml even allows you to embed other markup languages including json so that can be another great reason to at least be familiar with json.

I also have notes on jsonnet which is a templating language for json files.