Mastering RFC 8259: The 10 Most Common JSON Syntax Errors and Edge Cases in Distributed Systems

1. The Philosophy of RFC 8259 Strictness

Why does JSON reject single quotes, comments, and trailing commas when JavaScript object literals allow all three?

The author of JSON, Douglas Crockford, intentionally designed JSON as a minimal, immutable data interchange standard. By eliminating syntactic variations (such as multiple quote styles or optional commas), JSON ensured that any two compliant software engines on Earth—whether written in C, Cobol, Python, or WebAssembly—would parse identical payloads without dialect ambiguities.

2. The 10 Most Common Syntax Errors

1. Trailing Commas in Objects and Arrays ```json // ❌ INVALID { "name": "Lintify", "active": true, }

// ✅ VALID { "name": "Lintify", "active": true }

2. Single Quotes Instead of Double Quotes ```json // ❌ INVALID { 'status': 'ok' }

// ✅ VALID { "status": "ok" }

3. Unquoted Object Keys ```json // ❌ INVALID (Valid JS, Invalid JSON) { user_id: 104 }

// ✅ VALID { "user_id": 104 }

4. Literal Unescaped Line Breaks in Strings ```json // ❌ INVALID { "note": "First line Second line" }

// ✅ VALID { "note": "First line\nSecond line" }

5. Inline or Block Comments ```json // ❌ INVALID { // User authorization tier "tier": "pro" }

// ✅ VALID (Use schema description or dedicated key) { "_comment": "User authorization tier", "tier": "pro" }

6. Special Numeric Values (NaN, Infinity, -Infinity) JSON does not support IEEE 754 non-finite numbers: ```json // ❌ INVALID { "score": NaN, "latency": Infinity }

// ✅ VALID { "score": null, "latency": "Infinity" }

7. Leading Decimal Points and Octal Numbers ```json // ❌ INVALID { "discount": .50, "code": 0123 }

// ✅ VALID { "discount": 0.50, "code": 123 }

8. Backslash Escape Failures in File Paths / Windows Paths ```json // ❌ INVALID { "path": "C:\Users\admin\config.json" }

// ✅ VALID { "path": "C:\\Users\\admin\\config.json" }

9. Top-level Multiple Documents Without Array Wrapping ```json // ❌ INVALID (Standard JSON expects a single root value) { "id": 1 } { "id": 2 }

// ✅ VALID [ { "id": 1 }, { "id": 2 } ]

10. Unescaped Tab / Control Characters Characters from `U+0000` through `U+001F` must be escaped (`\t`, `\r`, `\n`, `\u0000`).

3. Numeric Precision & 64-bit Integer Traps

JavaScript numbers are double-precision floats (IEEE 754), which only safely represent integers up to $2^{53} - 1$ (9,007,199,254,740,991).

If your backend generates 64-bit integer IDs (e.g. Twitter Snowflake IDs or PostgreSQL BIGINT 18446744073709551615): `json // ⚠️ DANGEROUS: Browser will parse this as 1709482948204928000 (truncated!) { "transaction_id": 1709482948204928392 }

// ✅ SAFE: Represent large numbers as strings { "transaction_id": "1709482948204928392" }

4. The ISO 8601 Date Serialization Standard

Because JSON lacks a native Date type, always use UTC ISO 8601 / RFC 3339 formatted strings: `json { "created_at": "2026-05-20T14:32:00.000Z", "expires_at": "2026-06-01T00:00:00.000Z" }

5. Automated Pre-commit Linting Pipelines

Prevent broken JSON from entering your git repositories with pre-commit hooks:

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.6.0
    hooks:
      - id: check-json
      - id: pretty-format-json
        args: ['--autofix', '--indent', '2', '--no-ensure-ascii']