An Introduction to JSON for Non-Programmers

Created 2/19/2025, 12:55:05 AM

[ Table of Contents ]
  + 1. Values
    + 1.1. Numbers
    + 1.2. Strings
      + 1.2.1. Escape Sequences
    + 1.3. Booleans
    + 1.4. Null
    + 1.5. Arrays
    + 1.6. Objects
  + 2. Playground
  + Footnotes
  + References

1. Values

A document formatted in JSON contains /values/, which may be of different /types/. For example, we may have the /value/ `5`, which is of the /type/ `number` (since `5` is well, a number). JSON has a list of permitted types that you may use, each with its rules on how they should be written. Some values may have other values within them (as with the /object/ and /array/ types) while others are more simple. A JSON document consists of a single object, that all other data is contained within.

Below is a list of all possible value types:

1.1. Numbers

Numbers are, well, numbers. These may be whole numbers, but may also contain decimals, or use scientific notation. Only arabic numerals (i.e. 0-9, the numbers we're all familiar with) may be used as a number, and numbers may not start with zero.

Examples:

1.2. Strings

/String/ is Computer Science jargon for text.* Strings in JSON are enclosed by double quotes (`"`), in order to differentiate them from numbers and other text that may be in a file.

Examples:

1.2.1. Escape Sequences

A keen reader might now be curious about how you would write quotes themselves inside of a string. After all, if we tried to just put a quote there, A JSON parser would just think it's the end of the string! Situations like this are where something called /escape sequences/ come along. They let us represent things that we would not be able to put in a string otherwise. The way this works is that we start an escape sequence with a backslash (`\`), then put some other characters after it, depending on what we want. For example, if we wanted to put a quote in a string, we would use the sequence `\"`. Of course, now one may ask how you represent `\` itself? Well, just put another backslash before it, like so: `\\`.

So, let's say we wanted to represent the string:

And she said, "A backslash is \".

We would do it like this: 

"And she said, \"A backslash is \\\"."

Of course, there's more escape sequences than `\\` and `\"`. Below is a list of escape sequences in JSON:

1.3. Booleans

A /boolean/ is a value that can be either `true` or `false`. They may be used to represent anything that has two possible states, such as whether a certain feature is enabled or not.

1.4. Null

`null` is a special value that represents the absence of a value. This is typically used as a placeholder, in order to signal something along the lines of "something should be here but isn't".

1.5. Arrays

An array is a sequence of values. This sequence is enclosed in brackets (`[]`) and every element in this sequence /must/ be separated by a comma. As well as that, commas /must not/ be placed anywhere else besides between multiple elements. JSON is generally very strict with where different characters should go, and violating these rules will cause an application that uses JSON to reject your data.

Arrays are used whenever you need a list of something, for example it could be used in a list of users on a website or a list of objects in a scene.

Examples:

Examples of invalid arrays:

1.6. Objects

An object is a sequence of pairs, enclosed in braces `{}`. Each pair contains a /key/, and a /value/. Keys must be unique; there must not exist two pairs inside an object whose keys are equal. Values however, do not need to be unique. The key and value are separated from eachother with a colon (`:`), and the key /must/ be a string. The pairs themselves are separated from eachother via commas. Like arrays, the rules are very stringent: commas /must/ only be placed between pairs, and colons /must/ only be placed between the key and the value. If either of these rules are violated, then the JSON will be rejected.

Objects are used for things where a named list of properties make sense. For example, we could represent a person with the following JSON object: 

{
	"firstName": "John",
	"lastName": "Doe",
	"age": "31",
	"location": "Washington, DC",
	"hobbies": ["Programming", "Baking"]
}

Other examples:

Invalid examples:

2. Playground

Below is a playground where you can expriment with writing JSON. Once you've written some JSON, you can press "Validate" and it will look for any errors in the JSON you've written and tell you in a human-friendly way.

[TODO: actually make the playground]

Footnotes

References

Groups

Guides