What Is JSON, Really?
JSON (JavaScript Object Notation) is a text-based data format defined in RFC 8259. Despite the name, it has nothing to do with running JavaScript — it's just a way to represent structured data as plain text. Every major programming language can read and write it.
The format was formalized by Douglas Crockford around 2001, but it took off because it's simpler than XML while being human-readable enough to debug by eye. Today it's the default wire format for REST APIs, configuration files (package.json, tsconfig.json), and document databases like MongoDB.
One thing that surprises people: JSON is a strict subset of YAML 1.2. Any valid JSON file is also valid YAML. The reverse isn't true — YAML allows comments, multi-line strings, and anchors that JSON doesn't support.
JSON Syntax Rules (The Ones That Actually Matter)
JSON has exactly 6 data types: string, number, boolean (true/false), null, object (key-value pairs), and array (ordered list). That's it. No dates, no undefined, no functions.
Strings must use double quotes. Single quotes are invalid. This is the #1 reason people get "unexpected token" errors when pasting JavaScript objects into a JSON file.
Numbers cannot have leading zeros (01 is invalid), cannot use hex notation (0xFF is invalid), and cannot be NaN or Infinity. If you need those values, encode them as strings.
Objects use curly braces {} with key-value pairs separated by colons. Keys must be double-quoted strings. Trailing commas after the last item are illegal — this is the most common syntax error in hand-edited JSON.
// ❌ INVALID — these mistakes are everywhere
{
name: "Alice", // keys must be quoted
'age': 30, // single quotes not allowed
"scores": [1, 2, 3,], // trailing comma
"id": 0x1F, // hex numbers not allowed
}
// ✅ VALID JSON
{
"name": "Alice",
"age": 30,
"scores": [1, 2, 3],
"id": 31
}The 5 Most Common JSON Errors (And How to Fix Them)
1. Trailing comma: Remove the comma after the last item in an object or array. Most formatters highlight this instantly. If you want trailing commas, use JSONC (JSON with Comments) in VS Code settings.
2. Unexpected token at position 0: Usually means the response isn't JSON at all — it might be an HTML error page (starts with <) or an empty string. Check your API endpoint and Content-Type header.
3. Unquoted keys: Copy-pasting from JavaScript console output gives you {name: "value"} instead of {"name": "value"}. Run it through a formatter to add quotes automatically.
4. Single-quoted strings: Python's json.dumps() always produces double quotes, but if you're hand-writing JSON or copying from a Python repr(), you might have single quotes. Find-and-replace won't work if strings contain apostrophes — use a proper formatter.
5. BOM (Byte Order Mark): Some Windows editors prepend an invisible \uFEFF character. JSON parsers choke on this. Open the file in a hex editor — if it starts with EF BB BF, that's your BOM. Save as UTF-8 without BOM.
JSON vs JSONC vs JSON5 vs YAML: When to Use What
Standard JSON (RFC 8259): Use for API payloads, data interchange, and anything that needs maximum compatibility. Every parser in every language supports it.
JSONC (JSON with Comments): Use for configuration files you edit by hand — VS Code settings, tsconfig.json, etc. Allows // and /* */ comments plus trailing commas. Not supported by standard JSON.parse().
JSON5: Extends JSON with unquoted keys, single-quoted strings, hex numbers, trailing commas, and comments. Good for human-edited config files. Requires the json5 npm package to parse.
YAML: Use when you need comments, multi-line strings, or anchors/aliases for DRY config. Common in DevOps (Docker Compose, Kubernetes, GitHub Actions). Beware: indentation errors are silent and deadly. The "Norway problem" (NO gets parsed as false) has bitten many teams.
Our recommendation: Use standard JSON for anything machines read. Use JSONC or YAML for anything humans edit regularly. Don't use JSON5 unless your team already depends on it.
Working with Large JSON Files
Browser-based tools (including ours) can handle files up to about 50 MB before the tab starts lagging. For larger files, use command-line tools: jq for querying, python -m json.tool for formatting, or fx for interactive exploration.
If you're dealing with JSON files over 100 MB regularly, consider whether JSON is the right format. NDJSON (newline-delimited JSON, one object per line) is streamable and doesn't require loading the entire file into memory. Tools like jq can process NDJSON line by line.
For API responses, pagination is your friend. If an endpoint returns 10,000 objects in one response, that's an API design problem, not a JSON problem. Request smaller pages and process them incrementally.
Performance tip: JSON.parse() in V8 is actually faster than a JavaScript object literal for large objects (counterintuitive but true since 2019). If you have a large static dataset in your frontend code, wrapping it in JSON.parse('...') can improve startup time.
JSON Security Considerations
Never use eval() to parse JSON. This was common in the early 2000s before JSON.parse() existed, but it executes arbitrary code. Always use JSON.parse() or your language's equivalent.
Watch out for prototype pollution in JavaScript. If you parse {"__proto__": {"isAdmin": true}} and merge it into an object, you might accidentally modify Object.prototype. Libraries like lodash.merge had this vulnerability. Use Object.create(null) for parsed data you don't control.
JSON doesn't support circular references. If you try to JSON.stringify() an object that references itself, you'll get a TypeError. Use a replacer function or a library like flatted to handle circular structures.
Size limits matter for APIs. A 10 MB JSON payload can be a denial-of-service vector. Set Content-Length limits on your server (Express: express.json({limit: "1mb"}), nginx: client_max_body_size).
Validating JSON in Different Contexts
For quick validation: Paste into our JSON Formatter tool. It shows the exact line and character position of syntax errors, handles files up to 50 MB, and works offline.
For schema validation: Use JSON Schema (draft 2020-12) to define the structure your JSON should follow. Tools like ajv (JavaScript) or jsonschema (Python) validate data against a schema at runtime. This catches "valid JSON but wrong structure" errors that syntax checking misses.
For CI/CD pipelines: Add a JSON lint step. The simplest approach: python -m json.tool < file.json > /dev/null. For stricter checking with schema validation, use ajv-cli or check-jsonc-syntax.
For config files: Most frameworks validate their own config format. Running next build catches next.config.js issues, tsc --noEmit catches tsconfig.json issues. Don't reinvent validation that your toolchain already provides.