JSON Syntax Explained: Objects, Arrays, Brackets and the Rules That Make JSON Valid

Square brackets vs curly braces: arrays vs objects

Start with the question that brings most people here: what do the square brackets mean in JSON? Square brackets [ ] always denote an array - an ordered list of values - while curly braces { } always denote an object - a collection of named key-value pairs. They are not interchangeable, and picking the right one is the core decision in shaping any piece of JSON.

An array is a sequence. The values sit between the square brackets, separated by commas, and their position is what identifies them. There are no names. This is the right shape for a list of similar things where order carries meaning:

["red", "green", "blue"]

An object is a labelled record. Each entry is a key (always a quoted string) followed by a colon and then a value, and entries are separated by commas. You reach a value by its key, and the order of the keys is not significant:

{
  "name": "Ada",
  "age": 36,
  "active": true
}

So the quick rule of thumb is: if you find yourself wanting to write item one, item two, item three, you want an array and square brackets. If you want each value to have a name - title, price, colour - you want an object and curly braces. The two combine constantly, which is what the nesting section below covers.

The six JSON data types

The JSON standard defines exactly six value types, and every valid document is built from them in combination. There is nothing else - no dates, no functions, no undefined - which is part of why JSON travels so cleanly between different programming languages.

A few details are worth pinning down. Strings must use double quotes, never single quotes. Numbers are written bare, with no surrounding quotes, and JSON does not support the special values infinity or NaN that some languages allow. Booleans and null are always lowercase. Crucially, an array can hold values of mixed types, and both objects and arrays can contain other objects and arrays, which is how JSON describes deeply structured data.

Nesting objects and arrays

Real-world JSON is rarely flat. Because any value can itself be an object or an array, you can build a tree of arbitrary depth. The trick to reading it is to keep asking, at each bracket, am I looking at a list (square) or a labelled record (curly)? Here is a typical example mixing both:

{
  "user": {
    "name": "Ada",
    "roles": ["admin", "editor"],
    "address": {
      "city": "London",
      "postcode": "SW1A 1AA"
    }
  },
  "tags": ["json", "syntax", "guide"],
  "verified": true
}

Walk through it. The whole document is one object (outermost { }). Its user key holds another object. Inside that, roles holds an array of two strings, and address holds yet another object. Back at the top level, tags is an array of strings and verified is a boolean. An array of objects - the shape most API list endpoints return - looks like this:

[
  {"id": 1, "name": "Ada"},
  {"id": 2, "name": "Grace"},
  {"id": 3, "name": "Alan"}
]

That is the single most common pattern you will meet: an array (square brackets) whose every element is an object (curly braces) with the same set of keys. Once the bracket-by-bracket reading becomes second nature, even large documents stop looking intimidating. If a document is so densely packed onto one line that you cannot trace the nesting, paste it into a formatter (covered below) and the indentation will make the tree obvious.

Valid vs invalid JSON: the rules that matter

JSON is governed by two interchangeable standards, ECMA-404 and RFC 8259, and they are strict. A document either follows every rule and parses, or it has a single mistake and fails completely. These are the rules that decide it:

• Double quotes only. Every string and every object key must use double quotes. Single quotes are invalid.
• Keys must be quoted strings. Unquoted keys such as {name: "Ada"} are valid JavaScript but invalid JSON.
• Commas separate, never trail. A comma goes between items only; never after the last element of an array or the last pair of an object.
• Colons pair keys to values. Inside an object, each key is joined to its value with a single colon.
• No comments. There is no comment syntax in JSON at all (see the next section).
• Brackets must balance and match. Every { needs a closing } and every [ a closing ], correctly nested.

Putting those together, here is a document that breaks several rules at once:

{
  name: 'Ada',          // unquoted key, single quotes, and a comment
  "roles": ["admin",],  // trailing comma in the array
  "age": 36,            // trailing comma after the last pair
}

And the corrected, valid version of the same data:

{
  "name": "Ada",
  "roles": ["admin"],
  "age": 36
}

Because a single error invalidates the whole document, the fastest way to find the problem is to let a parser point you straight at the offending line and column rather than hunting by eye.

Why JSON has no comments (and what to do instead)

One of the most frequent questions about the format is why you cannot add a // note or /* note */ to a JSON file. The answer is that comments were left out on purpose. Douglas Crockford, who specified JSON, removed comment support so the format would remain a clean, portable data-interchange syntax and could not be misused to smuggle parsing directives into a file. Neither ECMA-404 nor RFC 8259 defines any comment grammar, so a strict parser will reject a document that contains one.

When you genuinely need to annotate JSON, the practical options are:

• Add a string field. Include a normal key such as "_comment": "Generated nightly; do not edit by hand". It is just data, so it stays valid, and tools simply ignore keys they do not recognise.
• Keep documentation outside the file. Put the explanation in a README, in code, or in API docs rather than inside the data itself.
• Use a JSON superset during development. Formats like JSON5 and JSONC do allow comments; you write them while editing, then strip the comments to produce plain JSON before shipping or transmitting.

The common pitfalls: trailing commas and quoting

Most invalid JSON fails for one of a handful of reasons, and nearly all of them come from treating JSON as if it were JavaScript. JSON is deliberately stricter. These are the traps that account for the vast majority of parse errors:

• Trailing commas. [1, 2, 3,] and {"a": 1, "b": 2,} are invalid. JavaScript tolerates the dangling comma; JSON does not. Delete it.
• Single quotes. 'hello' is not a JSON string. Only double quotes are allowed, for both values and keys.
• Unquoted keys. {name: "Ada"} must become {"name": "Ada"}. Keys are always quoted strings.
• Missing commas. Forgetting the comma between two array items or two object pairs is an error, just as an extra one is.
• Unescaped characters in strings. A literal double quote, backslash or newline inside a string must be escaped - \", \\, \n - or the string ends early and the parse breaks.
• Stray comments. As above, any // or /* */ invalidates the document.
• Wrong literals. Booleans and null must be lowercase (true, false, null); True or NULL will fail.

The reason these matter so much is that JSON gives no partial credit: a single trailing comma buried deep in a thousand-line file fails the entire parse. That is precisely why a validator that reports the exact line and column of the first error saves so much time.

How to validate and format JSON

Two operations cover almost everything you will want to do with a JSON document by hand: validating it (confirming the syntax is correct and locating any error) and formatting it (re-indenting it so the structure is readable, or minifying it to remove whitespace before transmission).

• Validate when a parser is rejecting your data and you need to know why. A good validator parses the document and reports the first syntax error with its position, turning a frustrating hunt into a one-line fix.
• Pretty-print when you have received a compact, single-line blob from an API and need to read it. Consistent indentation makes the object-and-array tree visible at a glance.
• Minify when you are about to send JSON over the wire and want to strip every unnecessary space and newline to cut the payload size.

JSON also rarely lives alone. If you are working with configuration that is authored in YAML but consumed as JSON, the YAML to JSON converter translates between the two formats. When you receive JSON that has been wrapped in a transport encoding - common in tokens, data URIs and email payloads - the Base64 encoder and decoder unwraps it back to readable text. And when your data lives in spreadsheets, the CSV to JSON converter turns tabular rows into the array-of-objects shape described earlier.

Related tools & reading

• JSON Formatter and Validator - validate, pretty-print and minify JSON, with exact error locations.
• YAML to JSON Converter - convert configuration between YAML and JSON.
• Base64 Encoder / Decoder - encode and decode Base64-wrapped JSON and other text.
• CSV to JSON Converter - turn spreadsheet rows into an array of JSON objects.
• Back to the Learning Center