JSON is based on JavaScript object literals

In the English language, the word “literal” is an adjective used to imply that what is being said is exact, not a metaphor. When your friend says, “She showed up out of nowhere and I literally dropped my sandwich,” he is stating that the dropping of the sandwich is not a metaphor.

In programming, the word “literal” is a noun. A literal is a value that is represented literally with data. It is written precisely as it is meant to be interpreted. If you aren’t familiar with programming concepts, then this might seem strange. Let’s take a quick look at literals.

Do you carry cash in your wallet, or a debit card? When I stop off at the sandwich shop and hand the cashier a five dollar bill for my sandwich, I physically watch my five dollars leave my wallet. When I swipe my debit card to pay for a sandwich, I know I have five dollars less in my back account, even though I didn’t see it happen.

In programming, we often use variables to represent values. For example, I might use a variable I call x in an expression like:

x = 5

Then, later on, I might want to add five more to x:

x = x + 5

At this point, we know the value of x is 10, but we don’t see 10. In this example, x was the variable, and 5 was a literal. In our sandwich shop example, we could say that the five dollars cash was a literal, and the debit card was a variable. When we see the actual value, it is a literal value.

In the “x = 5″ example, 5 is a number literal. A number is a data type. Other types of data are strings (made up of characters), boolean (true or false), null (nothing), collections of values, and objects. Representing a number value in a way that we can see is simple, and we use a number character. Representing a boolean value is also simple and we can use true/false 0/1. If you are familiar with the concept of objects, you will understand that representing an object is no easy or simple matter. If you aren’t familiar with the concept of objects, that is OK too.

In programming, the concept of an object is similar to how you would describe a real-world object, such as your shoes. You could describe your shoes with attributes or properties such as color, style, brand, and the type of insole. Some of these attribute values could be a number, such as shoe size, and others could be a boolean (true/false) such as “has laces.” The example below shows an example.

Using JSON to describe the shoes I’m wearing right now

{
    "brand": "Crocs",
    "color": "pink",
    "size": 9,
    "hasLaces": false
}

Don’t be too concerned just yet about the syntax in the shoe example. The main point of the shoe example is that you (even a human) can literally read the attributes of my shoe. The data type for my JSON shoe example is object. The literal value of the object exposes the properties or attributes in a way which we can see (and read). These attributes or properties of the shoe object are represented as name-value pairs.

JSON is based on JavaScript object literals. The key phrase here is “based on.” In JavaScript (and most programming languages with objects), the object can include a function. So not only could I represent the properties of my shoe with the JavaScript object, but I could create a function called “walk.”

However, data interchange is about data, so JSON does not include the functions of JavaScript object literals. The way that JSON is based on JavaScript object literals is purely in the syntactic representation of the object literal and its properties. This representation of properties is achieved with name-value pairs.

Name-Value Pairs

The concept of name-value pairs is widespread in computing. They are called by other names as well: key-value pairs, attribute-value pairs, and field-value pairs. In this book, we will refer to them as name-value pairs.

If you are familiar with the concept of name-value pairs, JSON will seem natural to you. If you aren’t familiar with name-value pairs, that’s OK too. Let’s take a quick look at name-value pairs.

In a name-value pair, you first declare the name. For example, "animal". Now, pair implies two things: a name and a value. So let’s give our name (in this case, "animal") a value. To simplify this concept here, let’s use a string value. With name-value pairs in JSON, the value can also be a number, a boolean, null, an array, or an object. For this name-value pair, which has the name "animal", we will use the string value, "cat":

"animal" : "cat"

"animal" is the name and "cat" is the value. There are many ways that we could choose to delimit, or separate, the name and the value. If I were to provide you with a directory of a company’s employees with their job titles, I’d probably hand you a list that looks something like this:

• Bob Barker, Chief Executive Officer
• Janet Jackson, Chief Operations Officer
• Mr. Ed, Chief Financial Officer

For my employee directory, I used commas to separate my job titles (names) and employee names (values). I also placed the value on the left and the name on the right.

JSON uses the colon character (:) to separate the names and values. The name is always on the left and the value is always on the right. Let’s take a look at a few more:

"animal" : "horse"

"animal" : "dog"

Simple, right? A name and a value, and you have a name-value pair.

Proper JSON Syntax

Now let’s take a look at what proper JSON syntax entails. The name, which in our example is "animal", is always surrounded in double quotes. The name in the double quotes can be any valid string. So, you could have a name that looks like this, and it would be perfectly valid JSON:

"My animal": "cat"

You can even place an apostrophe in the name:

"Lindsay's animal": "cat"

Now that you know that this is valid JSON, I’m going to tell you why you shouldn’t do this. The name-value pairs used in JSON are a friendly data structure to many systems. Having a space or special character (other than a–z, 0–9) in the name would not be taking portability into consideration. We can do things in our JSON data that decrease portability; therefore, we say it is important to avoid spaces or special characters for maximum portability.

The name in the name-value pair of your JSON, if it is to be loaded in memory by a system as an object, will become a “property” or “attribute.” A property or attribute in some systems can include an underscore character (_) or numbers, but in most cases it is considered good form to stick to the characters of the alphabet, A–Z or a–z. So, if I wanted to include multiple words in my name, I would format like so:

"lindsaysAnimal": "cat"

or

"myAnimal": "cat"

The "cat" value in the example has double quotes. Unlike the name in the name-value pair, the value does not always have double quotes. If our value is a string data type, we must have double quotes. In JSON, the remaining data types are number, boolean, array, object, and null. These will not be surrounded in double quotes.

JSON stands for JavaScript Object Notation. So, the only thing we are missing is the syntax that makes it an object. We need curly brackets surrounding our name-value pair to make it an object. So, one before…

{ "animal" : "cat" }

…and one after. When you are formatting your JSON, picture a knighting ceremony where the master of the ceremony dubs the new knight on the shoulders with a sword. You are the master of the ceremony, and you must dub your JSON as an object on each side with a curly bracket. “I dub thee, sir JSON.” The ceremony would not be complete without a tap on each shoulder.

In JSON, multiple name-value pairs are separated by a comma. So, to extend the animal/cat example, let’s add a color:

{ "animal" : "cat", "color" : "orange" }

Another way to look at JSON syntax would be through the eyes of the machine that is reading it. Unlike humans, machines are very rigidly rule- and instruction-oriented creatures. When you use any of the following characters outside of a string value (not surrounded in quotes), you are providing an instruction on how your data   is to be read:

• { (left curly bracket) says “begin object”
• } (right curly bracket) says “end object”
• [ (left square bracket) says “begin array”
• ] (right square bracket) says “end array”
• : (colon) says “separating a name and a value in a name-value pair”
• , (comma) says “separating a name-value pair in an object” or “separating a value in an array”; can also be read as “here comes another one”

If you forget to say “end object” with a right curly bracket, then your object will not be recognized as an object. If you place a comma at the end of your list of name-value pairs, you are giving the instruction “here comes another one” and then not providing it. Therefore, it is important to be correct in your syntax.

A Story: The Double Quotes of JSON

One day I was peering over a student’s shoulder, looking at his computer screen. He was showing me some JSON that he was about to validate.

The “JSON” that would not validate

{
    title : "This is my title.",
    body : "This is the body."
}

Upon validation he received a parsing error and became frustrated. He said, “Look, there’s nothing wrong with it!”

I pointed out to him that he was missing quotes around "title" and "body". He said, “But I’ve seen JSON formatted both ways, with and without quotes around the names.” “Ah,” I said. “When you saw it without quotes around the names, that was not JSON. It was a JavaScript object.”

This confusion is understandable. JSON is based on JavaScript object literals, so it looks much the same. A JavaScript object literal does not need quotes around the name of the name-value pair. In JSON, it is absolutely required.

Another point of confusion can be the usage of single quotes instead of double quotes. In JavaScript, an object may have single quotes for syntax instead of double quotes (see below).

This is not valid JSON

{
    'title': 'This is my title.',
    'body': 'This is the body.'
}

In JSON, only double quotes are used, and they are absolutely required around the name of the name-value pair (see below).

Valid JSON

{
    "title": "This is my title.",
    "body": "This is the body."
}