JSON Variants: JSON5, JSONC, and NDJSON Explained

Why Variants Exist

Standard JSON (as specified in RFC 8259 and ECMA-404) is deliberately minimal. It excludes comments, trailing commas, single-quoted strings, unquoted keys, and many other conveniences that developers find useful. Crockford's rationale: simplicity and interoperability. Every parser should produce identical results for any valid JSON input; there should be no ambiguity.

In practice, many developers find strict JSON frustrating for configuration files and other human-authored contexts. You cannot add a comment explaining why a timeout is set to 30 seconds. You cannot leave a trailing comma after the last element in an array without causing a parse error. These limitations are fine for machine-generated API payloads but annoying for hand-maintained files.

JSON variants emerged to fill these gaps — extending the format for human-authored contexts while typically remaining backward compatible with standard JSON for machine-generated content.

JSON5: JSON for Humans

JSON5 (json5.org) is a superset of JSON that adds several features from ECMAScript 5 syntax:

• Comments: Both single-line (// comment) and block (/* comment */) comments are supported
• Trailing commas: Arrays and objects can have a trailing comma after the last element
• Unquoted keys: Object keys that are valid identifiers do not need to be quoted
• Single-quoted strings: String values can be wrapped in single quotes instead of double quotes
• Multi-line strings: Strings can span multiple lines using a backslash continuation
• Hexadecimal numbers: 0xFF-style hex number literals are supported
• Leading and trailing decimal points: .5 and 5. are valid numbers
• Infinity and NaN: Infinity, -Infinity, and NaN are valid number values
• Additional whitespace: Unicode whitespace characters beyond the standard set are allowed

A JSON5 example:

{
  // Database configuration
  host: 'localhost',
  port: 5432,
  timeout: 30, // seconds
  options: {
    ssl: true,
    retries: 3,
  },
}

All standard JSON is valid JSON5 — the superset relationship is preserved. JSON5 parsers are available for JavaScript, Python, Java, Rust, and many other languages.

When to use JSON5: Configuration files that humans write and maintain directly. Not for API payloads or any data that crosses system boundaries where the receiving parser may not support JSON5.

JSONC: JSON with Comments

JSONC (JSON with Comments) is a lighter extension used notably by Visual Studio Code for its configuration files (tsconfig.json, settings.json, etc.) and by several other tools. It adds exactly one feature to standard JSON:

• Single-line comments (// comment)
• Block comments (/* comment */)

Everything else in JSONC is identical to standard JSON — quoted keys, double-quoted strings, no trailing commas, strict number format. The only difference is that comment lines are stripped before parsing.

JSONC is popular precisely because it adds one thing that configuration file authors genuinely need (comments) without adding anything else that might surprise a developer unfamiliar with the variant. It is conservative by design.

When to use JSONC: Configuration files where comments are needed but full JSON5 extensions are not required. Several major tools (VS Code, TypeScript's tsconfig, Jest configuration) use JSONC natively.

NDJSON: Newline-Delimited JSON

NDJSON (ndjson.org, also called "JSON Lines" or JSONL) is a completely different kind of variant — not about human readability but about streaming and batch processing. NDJSON is a format where each line is a complete, valid JSON value (typically a JSON object), and lines are separated by newlines.

A NDJSON file:

{"id":1,"name":"Alice","score":95}
{"id":2,"name":"Bob","score":87}
{"id":3,"name":"Carol","score":92}

Each line can be parsed independently. This has several advantages:

• Streaming: A client can begin processing records as they arrive, without waiting for the entire response to be received. Standard JSON requires the complete array to be received before parsing begins.
• Incremental processing: Large NDJSON files can be processed one line at a time with minimal memory footprint. Standard JSON arrays require loading the entire array into memory to parse.
• Easy appending: Adding records to an NDJSON file means appending lines. Adding records to a standard JSON array means modifying the file structure (removing the final ] and adding to it).
• Grep-ability: Each record is a single line, so standard Unix line tools (grep, awk, head, tail) can operate on NDJSON files without a JSON-aware parser.

When to use NDJSON: Log files, event streams, large data exports, streaming API responses, and any context where records are processed one at a time rather than as a batch. It is the standard format for many log ingestion systems and data pipeline tools.

Other Notable Variants

JSON Schema

JSON Schema is not a format extension but a separate specification for validating JSON. A JSON Schema document (which is itself valid JSON) describes the expected structure of JSON data — required properties, data types, format constraints, value ranges. Tools like AJV (JavaScript), Pydantic (Python), and JSON Schema Validator (Java) implement JSON Schema validation. JSON Schema has its own versioning (Draft-04, Draft-07, 2019-09, 2020-12) and is not formally standardised by IETF or ECMA.

HJSON

HJSON (Human JSON, hjson.github.io) is another human-focused superset that goes further than JSON5: it allows unquoted string values (not just keys), multi-line strings without escaping, and a simplified syntax that removes the need for quotes in many contexts. HJSON is less widely adopted than JSON5 but represents a more aggressive simplification for human authoring.

JSON-LD

JSON-LD (JSON Linked Data) is a W3C standard that adds semantic meaning to JSON by introducing a context document that maps JSON keys to URIs in linked data vocabularies. It is used for structured data markup on web pages (recognized by Google's search engine) and for semantic web applications. JSON-LD is standard JSON with specific keys (@context, @type, @id) that carry semantic meaning.

Format your JSON →