JSON for Beginners: A Practical Guide

What is JSON?

JSON stands for JavaScript Object Notation. It represents information using a small set of structures and value types that are easy for software to exchange and relatively easy for people to read.

A simple JSON object might describe a tool:

Objects and key-value pairs

A JSON object is wrapped in curly braces. Inside it, each property has a key and a value separated by a colon. Property names are strings and therefore use double quotation marks.

Multiple properties are separated by commas. There should not be a comma after the final property in standard JSON.

Arrays

An array is an ordered list wrapped in square brackets. Its items can be strings, numbers, booleans, null values, objects or even other arrays.

The main JSON value types

A more realistic example

Objects and arrays can be nested to represent richer information:

Here, tools is an array containing two objects. Each object contains its own properties.

Formatting versus validity

Pretty formatting adds indentation and line breaks so JSON is easier for a person to inspect. Minified JSON removes unnecessary whitespace to make the text more compact. Either can be valid JSON.

Common JSON errors

• Using single quotes around keys or strings instead of double quotes.
• Forgetting a comma between properties or array items.
• Leaving a trailing comma after the final item.
• Missing a closing curly brace or square bracket.
• Putting quotation marks around values that were intended to be numbers or booleans.
• Writing True, False or None instead of JSON's lowercase true, false and null.
• Including comments in ordinary JSON, which standard JSON syntax does not support.

Example of invalid JSON

This has several problems: the first key uses single quotes, the boolean is incorrectly capitalised, and there is a trailing comma after the final property.

The corrected version

A simple debugging workflow

1. Start at the first error reported rather than trying to fix everything at once.
2. Check matching braces { } and brackets [ ].
3. Check that property names and text strings use double quotes.
4. Inspect commas between neighbouring items.
5. Check booleans and null values for the correct lowercase spelling.
6. Format the JSON so nested structures are easier to see.
7. Validate again after making the correction.

JSON is data, not a magic instruction format

Valid JSON means the text follows JSON syntax. It does not mean the values are accurate, safe or accepted by a particular application. An API can reject perfectly valid JSON because a required field is missing, a value is outside an allowed range or the data structure does not match its expected schema.