JSON has won. It's the data format of the web — used by every API, every config file, every NoSQL database. But JSON has limitations that have spawned two popular variants: JSON5 (designed for humans) and JSONC (JSON with Comments). This guide explains the syntax differences, when to use each, and which parsers support them.
What Is JSON?
JSON (JavaScript Object Notation) is defined by RFC 8259. It's a minimal data format with strict rules: double-quoted strings, no trailing commas, no comments, no single quotes. The strictness is intentional — JSON is meant for machine-to-machine communication where predictable parsing matters more than human convenience.
A valid JSON document:
{
"name": "ToolmetryAI",
"toolCount": 120,
"free": true,
"categories": ["seo", "dev", "utility"]
}
What Is JSON5?
JSON5 is a superset of JSON designed for human-authored configuration files. It relaxes JSON's strictest rules to make hand-writing JSON less error-prone. The "5" is a reference to ECMAScript 5 — JSON5's syntax is closer to JavaScript's ES5 object literal syntax than to strict JSON.
JSON5 adds the following on top of JSON:
- Single-quoted strings:
'value'as well as"value" - Trailing commas:
{ "a": 1, }and[1, 2, 3,]are valid - Comments: both
// line commentsand/* block comments */ - Unquoted object keys:
{ name: "value" }(with restrictions) - Hexadecimal numbers:
0xFF - Infinity, -Infinity, NaN: as bare identifiers
- Multi-line strings: using backslash continuations
JSON5 is used by: package.json (npm allows JSON5 syntax in some fields), tsconfig.json (TypeScript config files accept JSON5), .babelrc (Babel config), and many build tool configs.
What Is JSONC?
JSONC is "JSON with Comments" — a minimal extension that adds only comments to standard JSON. It doesn't change any other JSON rules. JSONC is what Visual Studio Code, TypeScript (tsconfig.json), ESLint (.eslintrc.json), and other Microsoft-originated tooling use for configuration files that benefit from inline documentation.
JSONC is a strict subset of JSON5 — every valid JSONC file is also valid JSON5, but not vice versa. If you need just comments and want maximum parser compatibility, use JSONC. If you need the full ergonomic improvements (single quotes, trailing commas, unquoted keys), use JSON5.
Side-by-Side Comparison
| Feature | JSON | JSONC | JSON5 |
|---|---|---|---|
| Double-quoted strings | Yes | Yes | Yes |
| Single-quoted strings | No | No | Yes |
| Line comments (//) | No | Yes | Yes |
| Block comments (/* */) | No | Yes | Yes |
| Trailing commas | No | No | Yes |
| Unquoted object keys | No | No | Yes |
| Hex numbers (0xFF) | No | No | Yes |
| Infinity / NaN | No | No | Yes |
| Multi-line strings | No | No | Yes |
Which Format to Use When
Use JSON when:
- Sending API responses. JSON is the standard for REST APIs — clients expect strict JSON.
- Storing data in databases (MongoDB, PostgreSQL JSON columns).
- Machine-to-machine communication of any kind.
- Files that will be parsed by many different tools in many different languages.
Use JSONC when:
- Configuration files that benefit from inline documentation (tsconfig.json, .vscode/settings.json).
- Files edited primarily in VS Code, which has first-class JSONC support.
- Configs that need comments but don't need other JSON5 features.
Use JSON5 when:
- Complex configuration files where trailing commas and unquoted keys reduce noise.
- Files authored by humans frequently and parsed by tools that support JSON5 (Babel, tsconfig in some setups).
- Migration path from JavaScript object literals to a more standard format.
Common JSON Parse Errors (and How to Fix Them)
"Unexpected token" errors — The most common JSON error. Causes: single quotes instead of double quotes, trailing commas, comments in JSON. Fix: use a JSON validator that pinpoints the error location, or switch to JSON5/JSONC if your parser supports it. Use our JSON Formatter to validate JSON with exact error positions.
"Unexpected end of JSON input" — The JSON string was truncated — usually because an HTTP response was cut off mid-payload. Fix: check your fetch/response handling for truncation.
"Unexpected token < in JSON" — Your fetch returned HTML (usually a 404 or 500 error page) instead of JSON. The parser hit the < of <html> and failed. Fix: check the response status code and Content-Type before calling response.json().
Parsing JSON5 and JSONC in Code
Standard library JSON.parse() in JavaScript only handles strict JSON. For JSON5 and JSONC, use a dedicated parser:
// JSON5
import JSON5 from 'json5';
const data = JSON5.parse(json5String);
// JSONC — use jsonc-parser (used by VS Code)
import { parse as parseJSONC } from 'jsonc-parser';
const data = parseJSONC(jsoncString);
// Or strip comments and parse as JSON
import { stripJsonComments } from 'strip-json-comments';
const data = JSON.parse(stripJsonComments(jsoncString));
Summary
- JSON — strict, machine-to-machine, the API standard. Use for API responses and database storage.
- JSONC — JSON + comments. Use for config files that need inline documentation (tsconfig, VS Code settings).
- JSON5 — JSON + comments + trailing commas + single quotes + unquoted keys. Use for human-authored config files where ergonomics matter.
Tools for working with JSON:
- JSON Formatter & Validator — pretty-print, validate, find syntax errors
- JSON Validator — quick validation without formatting
- JSON to CSV Converter — for spreadsheet analysis
- CSV to JSON Converter — reverse direction