Standard JSON does not allow comments. It does not allow trailing commas. Many developers assume otherwise because "it works in VS Code." Then a config file that looks fine in the editor causes a fatal crash when sent as an HTTP payload.
Comments and trailing commas belong to specialized extensions: JSONC (JSON with Comments) and JSON5.
Your tsconfig.json allows comments because VS Code parses it as JSONC, not JSON. Your REST API rejects them because its parser follows RFC 8259. The differences matter.
The Standard: JSON (RFC 8259)
Standard JSON exists for one purpose: predictable, language-agnostic data exchange. It sacrifices human convenience for maximum parser compatibility.
- No Comments: Absolutely forbidden.
- No Trailing Commas: A comma after the last element throws an error.
- Strict Quotes: All keys and string values must be wrapped in double quotes (
"). Single quotes (') are illegal. - Strict Numbers: No leading zeros, no hexadecimals, no special values like
NaNorInfinity.
Primary Use Case: Network payloads (REST, gRPC), database storage, and strict distribution configs like package.json. If you need to validate standard JSON safely, always use a strict, client-side JSON Formatter.
JSONC: JSON with Comments
JSONC was popularized by VS Code and other editors to make configuration files human-readable and documentable.
- Comments Allowed: Supports both
// inlineand/* block */comments. - Trailing Commas: Technically allowed by some parsers, but generally discouraged by editor linters.
- Everything else: Maintains the strictness of standard JSON (double quotes only, strict numbers).
Primary Use Case: Editor and compiler configurations (tsconfig.json, VS Code settings.json, ESLint configs).
JSON5: The ES5 Superset
JSON5 extends JSON to align with ECMAScript 5 syntax. It is the most relaxed of the three formats, optimized for hand-written data.
- Comments Allowed: Both inline and block.
- Trailing Commas: Fully supported for both objects and arrays.
- Flexible Quotes: Keys can be unquoted (if they are valid JS identifiers), and strings can use single quotes (
'). - Advanced Numbers: Supports hexadecimal (
0x1A), explicit positive signs (+1), leading/trailing decimals (.5,5.), and special values (Infinity,NaN). - Multi-line Strings: Supported by escaping the newline character.
Primary Use Case: Build tool configurations, test suite declarations, and hand-authored data structures.
Feature Comparison Matrix
| Syntax Feature | JSON (RFC 8259) | JSONC | JSON5 |
|---|---|---|---|
Comments (//, /* */) | ❌ Forbidden | ✅ Allowed | ✅ Allowed |
| Trailing Commas | ❌ Forbidden | ⚠️ Parsable, but discouraged | ✅ Allowed |
| Object Key Quotes | ⚠️ Strict Double (") | ⚠️ Strict Double (") | ✅ Optional |
Single Quotes for Text (') | ❌ Forbidden | ❌ Forbidden | ✅ Allowed |
| Hex, Infinity, NaN | ❌ Forbidden | ❌ Forbidden | ✅ Allowed |
The Danger of Cross-Pollination
The single biggest source of frustration is treating these formats interchangeably.
Copy a block of JSON5 from a Webpack config (single quotes, comments included) and paste it into a fetch request payload headed for a Go or Node.js server. The server's RFC 8259 parser rejects it with invalid json or unexpected token.
Best Practice: Use JSON5 or JSONC for internal tooling configs where readability matters. The moment data crosses a network boundary or hits an external API, strip it to strict standard JSON.
Before shipping network payloads or investigating a crash, run your output through a 100% client-side JSON Formatter to catch leaked comments or trailing commas before they reach production.