Understanding JSON: A Complete Developer Guide

What Is JSON?

JSON — JavaScript Object Notation — was formalised by Douglas Crockford in the early 2000s as a lightweight, human-readable alternative to XML for data interchange. Today it is standardised as RFC 8259 and ECMA-404, and is effectively the default wire format for REST APIs, GraphQL responses, configuration files, and app-to-app data exchange the world over.

Despite being derived from JavaScript object literal syntax, JSON is language-independent. Every major programming language has a parser and serialiser in its standard library or a popular third-party package.

The Six Value Types

A JSON document can contain exactly six types of value:

string — text in double quotes: "hello"
number — integer or floating-point: 42, 3.14, -0.5
boolean — true or false
null — the explicit absence of a value
object — an unordered set of key/value pairs: { "key": "value" }
array — an ordered list of values: [1, "two", true]

Any of these can be nested arbitrarily. An object value can itself be an array of objects, and so on.

Why JSON Is Stricter Than It Looks

Developers who come from JavaScript often run into issues because JSON looks so similar to a JS object but has tighter rules:

Keys must be double-quoted strings. { name: "Alice" } is valid JavaScript but invalid JSON — the key needs to be "name".
Strings use double quotes only. Single-quoted strings are not allowed.
No trailing commas. [1, 2, 3,] fails JSON.parse in every runtime.
No comments. JSON has no syntax for comments, by design.
No undefined. JavaScript's undefined has no JSON equivalent. Properties set to undefined are simply omitted during serialisation.
No functions. Functions cannot be serialised to JSON.

These restrictions exist intentionally: a simpler grammar means faster, more consistent parsers across languages.

How Parsers Report Errors

When JSON.parse() encounters invalid input it throws a SyntaxError with a character position. For example:

SyntaxError: Expected ',' or '}' after property value in JSON at position 42

The character index points to the exact location of the problem. A JSON formatter highlights that location and, in some cases, can suggest the fix (missing comma, unmatched bracket, stray trailing comma).

Common Use Cases

Debugging API responses. When a server returns a minified single-line payload, it is impossible to read without formatting. Pasting into a formatter reveals the nesting structure and makes it easy to find the field that came back wrong.

Config files. Many tools use JSON for configuration: package.json, tsconfig.json, VS Code settings. Keeping these readable and correctly formatted is basic hygiene.

Serialising state for storage. Saving application state to localStorage or a database often involves JSON.stringify. Understanding the format helps debug serialisation bugs.

API request bodies. REST API calls frequently use JSON request bodies. Minifying them before sending reduces payload size.

The Formatter Workflow

A good JSON formatter does three things:

Validates — runs JSON.parse and reports any syntax error with position
Beautifies — serialises back with configurable indentation (2 spaces or 4 spaces)
Minifies — strips all optional whitespace to produce the most compact representation

Everything happens locally in the browser. No data is sent to a server — important when pasting API responses that may contain authentication tokens or sensitive payload data.

Gotchas to Watch Out For

Large numbers lose precision. JavaScript's Number type is a 64-bit float, so integers larger than 2^53 - 1 cannot be represented exactly. If your API returns large IDs as numbers, they may be corrupted by the parser. Use strings for large IDs.

Duplicate keys. JSON does not forbid duplicate keys, but behaviour is undefined. Most parsers take the last value; some throw an error. Avoid duplicates.

Unicode escapes. JSON supports \uXXXX escape sequences. Make sure your formatter handles multi-byte Unicode (emoji, CJK) correctly.

Try It

The JSON Formatter on Syntaxly handles all of the above. Paste your JSON, pick Beautify or Minify, and any syntax error is reported immediately with the character position highlighted — all client-side, nothing uploaded.