A Practical Guide to JSON for Non-Developers

What JSON is

JSON — JavaScript Object Notation — is a plain-text way of writing structured data: numbers, text, true/false values, lists, and groups of named values, nested inside one another as deeply as needed. It looks a little like a programming data structure because it started as one, but JSON itself is just text; any language can read and write it, which is why it's become the default format for moving data between a server and a browser, between two services, or into a downloaded file.

You don't need to write code to run into JSON. It shows up when you export your data from an app (a "download my data" button often produces a .json file), when a website's settings or config live in a .json file you're asked to edit, when a browser's developer tools show you what a web page sent or received, or when a spreadsheet tool imports data from an online API. Understanding the shape of it is enough to read, edit, or troubleshoot it confidently — you don't need to be a programmer.

The six value types

Everything in JSON is built from exactly six kinds of value. There's no seventh type and no way to define a custom one — which is part of why JSON parses unambiguously in any language.

• String — text, always wrapped in double quotes: "Alice".
• Number — written plainly, no quotes: 30 or 19.99. JSON has no separate "integer" and "decimal" type the way some programming languages do — it's just "number."
• Boolean — exactly two possible values, lower-case and unquoted: true or false.
• Null — a deliberate "no value," written null, unquoted. Different from an empty string "" or the number 0 — it means the field is intentionally empty, not that it holds an empty-looking value.
• Object — an unordered set of named values in curly braces: {"name": "Alice", "age": 30}. Each name (called a "key") is always a string, followed by a colon, then its value.
• Array — an ordered list of values in square brackets: ["red", "green", "blue"]. Items don't need to share a type, though in practice they usually do.

Objects and arrays are the two "container" types, and they're what make JSON structured rather than flat: either one can hold any of the six types as a value, including another object or array, which is how real JSON ends up nested several layers deep.

A small, realistic example

Formatting {"user":{"name":"Alice","age":30},"active":true} produces:

{
  "user": {
    "name": "Alice",
    "age": 30
  },
  "active": true
}

Every value type but array and null happens to appear here: "user" is a key whose value is a nested object; "name" holds the string "Alice"; "age" holds the number 30; and "active" holds the boolean true. Extend it with an array of interests and a middle name left unset, and the same structure would read "interests": ["running", "chess"], "middleName": null — a list, and an explicit "nothing here."

Reading nested structure

The trick to reading deeply nested JSON without getting lost is to track one level of brace or bracket at a time and ignore everything inside it until you need to go deeper. In the example above, the outermost { } holds two keys — user and active — and that's the entire top level; you don't need to know what's inside user to see that. Only once you've located the key you care about do you step inside its braces and repeat the same process one level down. Indentation exists purely to make this visual: each level of nesting is indented one step further, so the eye can match an opening brace to its closing one by following the indent, the same way you'd track parentheses in a maths expression.

A path notation is the other tool worth knowing, because many tools (and error messages) describe a location in JSON this way: user.name means "the name key inside the user object," and interests[0] means "the first item in the interests array" — arrays count from zero, not one.

The syntax rules that trip people up

JSON's grammar is deliberately small, defined precisely in RFC 8259, and it is stricter than the JavaScript syntax it's named after — a document can look perfectly reasonable to a person and still fail to parse. The same handful of mistakes account for nearly every "invalid JSON" error:

• Only double quotes. "name" is valid; 'name' is not. Single quotes are legal in JavaScript object literals but never in JSON, which is the single most common source of confusion since the two look almost identical.
• No trailing commas. {"a": 1, "b": 2,} is invalid — that last comma after 2 has nothing following it, and JSON doesn't allow one. Easy to leave behind after deleting the last item in a list by hand.
• Keys must be quoted strings. {name: "Alice"} is invalid; it must be {"name": "Alice"}. Unlike JavaScript, JSON never allows a bare, unquoted key.
• No comments. JSON has no comment syntax at all — neither // like this nor /* like this */ is legal, which surprises people coming from config formats that do allow comments (YAML, and JavaScript/JSONC variants).
• No undefined, NaN or Infinity. These are JavaScript concepts with no JSON equivalent. If a value is genuinely absent, use null or omit the key entirely.

Worked example — an invalid document and why

Try to parse {a: 1} and it fails validation. The key a has no surrounding quotes — valid JavaScript, invalid JSON — so a parser stops right there and reports an unexpected character where it expected the opening quote of a string key.

What a "valid JSON" error message is actually telling you

A JSON parser reads left to right and stops at the exact character where the document stops matching the grammar — it doesn't understand your intent, only the rule it just failed. Error messages like "Unexpected token" or "Unexpected end of JSON input" name the specific problem: the first usually points at a stray character (an unquoted key, a single quote, a trailing comma) at the position given; the second means the document was cut off before every open brace or bracket found its matching close — commonly a lost closing } or ], or a value that got truncated mid-copy-paste. The position or line number in the error is worth trusting literally: the fault is at or very near that point, not somewhere else in the document, because a parser has no way to detect a mistake before it actually reaches it.

JSON versus CSV and XML

These three formats solve overlapping but different problems, and picking the right one for a task is mostly about shape:

• CSV is flat rows and columns — ideal for a spreadsheet-shaped list of similar records, but it has no native way to represent nesting, lists-within-a-field, or a record with optional fields other rows don't have.
• XML can represent the same nested, tree-shaped data JSON can, with a stricter and more verbose syntax (opening and closing tags for everything, plus a schema layer if you want validation), and native support for attributes alongside content. It remains common in older enterprise systems and some document formats.
• JSON sits between the two: it nests like XML but with far less punctuation, and it maps directly onto data structures every modern programming language already has (objects/dictionaries and arrays/lists), which is the main reason it displaced XML as the default for web APIs.

None of the three is strictly "better" — a genuinely flat list of uniform records is often more readably stored as CSV, and a document with rich mixed content (think: an article with inline formatting) is often a more natural fit for XML. JSON wins by default mainly because most data web tools exchange is object-shaped, not row-shaped or document-shaped.

Frequently asked

Why does my JSON file open as one unreadable line?

Whitespace — the line breaks and indentation that make JSON readable — is optional and often stripped before sending it over a network, since a machine doesn't need it and removing it saves space. Formatting adds that whitespace back in for human reading; it changes nothing about the data itself. Try pasting it into our JSON formatter.

Does formatting or minifying change my data?

No. Both operations only add or remove whitespace between tokens — the keys, values and structure are byte-for-byte the same information before and after. Formatting {"a":1} and minifying the result returns exactly {"a":1} again.

Can JSON have comments?

No, never, in standard JSON. Some tools accept a relaxed superset (often called JSONC or JSON5) that allows comments and trailing commas, but that's a different, non-standard format — a strict JSON parser, including the one behind this guide's tool, will reject both.

Is a JSON array the same as a JSON object?

No. An array ([ ]) is an ordered list where position is what identifies an item — "the second one." An object ({ }) is a set of named key-value pairs where the name is what identifies a value, and order isn't meaningful. Choosing between them when writing JSON by hand comes down to whether you'd naturally refer to an item by its position or by its name.