What is JSON? A guide to its structure and syntax

Read a JSON document, one layer at a time

Imagine an app returning this profile. The outer braces hold one object. Each property has a name (also called a key), a colon, and a value. For example, "name" is a key and "Maya" is its string value.

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

The interests array contains two items in a specific order. The address value is another object, nested inside the profile. To find the city, follow address and then city. Indentation makes these layers visible; it does not create the structure.

Use an object when values need names, such as a profile’s fields. Use an array when you need a sequence, such as a list of profiles. Objects and arrays can contain each other, and empty containers ({} and []) are valid.

Choose Validate & Pretty Print after opening the example. Try changing a value or removing a quote to see how validation responds. Pasted JSON is processed in your browser.

The six JSON value types

String

"Maya"

Text wrapped in double quotes. Dates are usually represented as strings too.

Number

28 or 3.5

A numeric value without quotes. JSON has no separate integer syntax type.

Boolean

true or false

A yes/no value, written in lowercase without quotes.

Null

null

An explicit empty value. It is different from leaving a property out.

Array

["cycling", "cooking"]

An ordered list of values inside square brackets.

Object

{"city": "Boston"}

Named properties inside curly braces.

Types matter: 28 is a number, while "28" is text. Likewise, false is a boolean but "false" is a string. A complete JSON document may be any one JSON value, even true or a single number; an API may require an object or array instead.

What makes the syntax valid?

• Wrap property names and strings in double quotes. Single quotes and unquoted keys are not JSON.
• Put a colon between a key and its value, and commas between properties or array items. Do not add a comma after the final item.
• Match every opening brace or bracket with its closing partner. A document holds one top-level value, not two adjacent objects.
• Escape quotation marks and backslashes inside strings with a backslash. Write a newline inside a string as \n, rather than an actual line break.
• Leave out comments, functions, undefined, NaN, and Infinity. These are not JSON values.

Spaces and line breaks between tokens are optional. Pretty printing adds readable spacing without changing the values. Keep object keys unique: duplicate names can be handled differently by different parsers, so they are a poor way to represent multiple values.

JSON resembles a JavaScript object literal, but it has stricter rules. In JavaScript, JSON.parse(text) reads JSON text into a value; JSON.stringify(value) produces JSON text from supported values. See the JSON syntax diagrams or the JSON standard (RFC 8259) for the formal grammar.

How is a document’s structure defined?

JSON’s grammar defines valid punctuation and value types. Your application defines which fields it expects. A document can be valid JSON and still be wrong for an API—for example, if a required name is missing.

JSON Schema lets you write those expectations as a separate JSON document. This small schema requires an object with a string name. If age is present, it must be a nonnegative integer:

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

Under this schema, {"name":"Maya"} passes. {"age":28} fails because the name is missing, and {"name":"Maya","age":"28"} fails because the age is text. Extra properties are allowed by this example. JSON Tidy checks JSON syntax; it does not currently validate against a schema.