What is JSON? A guide to its structure and syntax

How to read a JSON document

Say an app sends you this user profile. The outer curly braces make it one object. Inside are properties, each a name (or key) in quotes, a colon, and a value. "name" is a key and "Maya" is its value.

{
  "name": "Maya",
  "age": 28,
  "subscribed": true,
  "nickname": null,
  "interests": [
    "cycling",
    "cooking"
  ],
  "address": {
    "city": "Boston"
  }
}

interests holds an array, a list of two items in a fixed order. address holds another object nested inside the profile, so to get the city you go to address, then city. The indentation just makes the nesting easier to see. The braces and brackets are what actually define it.

In general, use an object when each value needs a name, like the fields of a profile, and an array when you have a list of similar things, like a list of profiles. They can be nested inside each other as deep as you need, and empty ones ({} and []) are fine.

The JSON format guide goes further into numbers, strings, dates, null, and how to design JSON that’s easy to work with.

Try deleting a quote or a comma to see what the error looks like.

The six JSON value types

String

"Maya"

Text in double quotes. Dates usually end up as strings too, since JSON has no date type.

Number

28 or 3.5

Written without quotes. JSON doesn’t have separate types for whole numbers and decimals.

Boolean

true or false

Always lowercase, and never in quotes.

Null

null

Means “no value.” It isn’t the same as leaving the property out.

Array

["cycling", "cooking"]

An ordered list in square brackets. The items can be any type.

Object

{"city": "Boston"}

Named values in curly braces, each written as a key, a colon, and a value.

The quotes matter. 28 is a number but "28" is a string, and false is a boolean but "false" is text. A JSON document can be any single value, even just true or a number, though most APIs expect an object or an array at the top.

JSON syntax rules

JSON is strict, and most errors come from one of these:

• Keys and strings need double quotes. Single quotes and unquoted keys aren’t allowed.
• A colon goes between each key and its value, and commas go between items, but not after the last one.
• Every { and [ needs a matching } or ], and a document holds one top-level value, not two objects side by side.
• Quotes and backslashes inside a string have to be escaped with a backslash. A line break inside a string is written as \n, not as an actual new line.
• Comments, functions, undefined, NaN, and Infinity aren’t valid JSON.

Spaces and line breaks between values don’t matter, so formatting JSON never changes what it means. Keys should be unique within an object, because different parsers handle duplicates differently.

JSON looks a lot like a JavaScript object, but the rules are tighter. In JavaScript, JSON.parse(text) turns JSON text into a value and JSON.stringify(value) turns a value back into JSON. The syntax diagrams on json.org and the JSON standard (RFC 8259) have the full grammar.

Valid JSON vs. the right JSON

The syntax rules only say whether something is JSON. Whether it has the fields your app needs is a separate question. A profile with no name can be perfectly valid JSON and still get rejected by an API.

JSON Schema is the usual way to write those requirements down, as a JSON document of its own. This one says the profile must be an object with a string name, and that age, if it’s there, has to be a whole number of 0 or more:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "age": {
      "type": "integer",
      "minimum": 0
    }
  },
  "required": [
    "name"
  ]
}

{"name":"Maya"} passes. {"age":28} fails because there’s no name, and {"name":"Maya","age":"28"} fails because the age is a string. Any other properties are allowed, since the schema doesn’t say otherwise.

Try this schema in the JSON Schema validator, or read the JSON Schema guide to write your own.