TOON vs JSON5 and HJSON: Human-Friendly Meets Token-Friendly

JSON5 and HJSON make JSON easier for humans to write — adding comments, optional quotes, and multi-line strings. TOON makes JSON cheaper for LLMs to read — removing per-row structural overhead. They solve opposite problems: use JSON5 or HJSON for config files humans maintain; use TOON for data you feed into a model's context window.

What Are JSON5 and HJSON, and Why Do They Exist?

Standard JSON is strict by design: no comments, no trailing commas, all keys must be double-quoted, no special numeric values. That strictness makes it predictable for machines but painful for humans writing configuration files by hand.

JSON5 ("JSON for Humans") addresses that pain with a set of ECMAScript 5-inspired extensions: single-line (//) and block (/* */) comments, trailing commas after the last array or object member, unquoted identifier keys (host: "localhost" instead of "host": "localhost"), single-quoted strings, hexadecimal numbers, and the special values Infinity, -Infinity, and NaN.

HJSON ("Human JSON") goes further and explicitly describes itself as a "user interface for JSON" — a format you write before a machine parses the result. It supports #, //, and /* */ comments, optional quotes around string values that contain no ambiguous characters, newline-separated array items without commas, and triple-quoted multi-line strings. The assumption is that a tool will normalize HJSON back to standard JSON before passing it to any downstream consumer.

Both are excellent at what they do. The problem is that those ergonomic features — comments, extra whitespace, decorative quoting — directly translate to additional tokens when the data ends up in an LLM context window.

The Token Cost of Human-Friendly Features

LLMs use Byte Pair Encoding (BPE) tokenization. Every character in a prompt has a cost. JSON5 and HJSON features that improve human authoring add tokens that carry no semantic payload for the model:

• Comments (// this setting controls X) can run 5–20 tokens each and convey information the model could infer from field names and values.
• Decorative whitespace and indentation used for readability adds tokens proportional to nesting depth.
• Repeated keys — a problem inherited from JSON itself — appear once per object on every row in an array, paying the key-name token tax N times for N objects.

TOON takes the opposite approach. Instead of enriching the syntax, it strips it. The official toonformat.dev benchmarks — 5,016 LLM calls across 209 questions, six formats, and four models — measured TOON at 39.9% fewer tokens than JSON on average, and up to 58.8% fewer tokens on flat, uniform tables (67,778 vs 164,452 tokens). The mechanism is simple: field names are declared once in the header line and never repeated.

The Same Config in JSON5, HJSON, and TOON

Consider a small API client configuration with three servers. Here is the same data expressed in all three formats:

// JSON5 — human-friendly config, ~55 tokens
{
  // Primary API cluster
  servers: [
    { host: 'api-1.example.com', port: 443, region: 'us-east' },
    { host: 'api-2.example.com', port: 443, region: 'eu-west' },
    { host: 'api-3.example.com', port: 443, region: 'ap-south' },
  ],
}

# HJSON — same data, similar token cost, ~50 tokens
{
  // Primary API cluster
  servers:
  [
    { host: api-1.example.com, port: 443, region: us-east }
    { host: api-2.example.com, port: 443, region: eu-west }
    { host: api-3.example.com, port: 443, region: ap-south }
  ]
}

# TOON — optimized for LLM context windows, ~22 tokens for data rows
servers[3]{host,port,region}:
  api-1.example.com, 443, us-east
  api-2.example.com, 443, eu-west
  api-3.example.com, 443, ap-south

The TOON block eliminates the repeated keys (host, port, region appear once, not three times), all punctuation per row, and any comments. On three rows the absolute saving is modest. At 200 rows the structural overhead in JSON5/HJSON would dwarf TOON's header cost. You can convert between formats instantly using the free converter.

Note that TOON intentionally has no comment syntax. For a config file a human will edit, that is a deal-breaker. For data fed to a model, comments are noise.

JSON5 vs HJSON vs TOON: Feature Comparison

For a broader look at how TOON measures up against JSON, YAML, CSV, and more, see the TOON format comparison guide.

When Should I Use JSON5 or HJSON Instead of TOON?

The answer is straightforward: use JSON5 or HJSON whenever a human will directly read or write the file. The canonical examples are application config files (tsconfig.json, .eslintrc, Webpack configs), game data files edited by non-developers, and any place where inline comments explain the why behind a value.

TOON has no comment syntax and its tabular rows (value1, value2, value3) are not self-documenting without the header. A developer editing a TOON file manually would need to cross-reference the header on every line. That is an acceptable trade-off when an LLM is the consumer; it is a bad trade-off when a human is.

A practical pipeline in many teams: store configuration as HJSON (authored and version-controlled by humans), parse it to JSON at build time, then convert that JSON to TOON at runtime before constructing an LLM prompt. The converter handles the JSON-to-TOON step. For a detailed breakdown of what TOON is and how it works, see What is TOON?

Does TOON Beat JSON5 and HJSON on Every LLM Task?

No — and the caveats are important. The accuracy advantage TOON holds over JSON-family formats (76.4% vs JSON's 75.0% in the official benchmark) applies to comprehension and retrieval tasks on large, uniform arrays. It does not extend uniformly to every task type or every model.

The official benchmark breaks down TOON accuracy by question type: field retrieval sits at 99.6%, but structural validation drops to 70.0%, aggregation to 61.9%, and filtering to 56.8%. If your primary task is filtering or counting rows inside the LLM, consider running that computation outside the model and passing the result. See Validating TOON Data for programmatic approaches.

Model variance is also significant. The same TOON data produced 96.7% accuracy on Gemini 3 Flash and only 58.4% on Grok 4.1. Always benchmark your specific model-format combination before committing to either format in a production prompt pipeline.

A 2026 arXiv study (arXiv 2603.03306) adds another nuance: for generation tasks — where the model must produce structured output — plain JSON outperformed TOON. TOON's edge is in reading and retrieving from data, not in producing it. The JSON vs TOON deep-dive covers this split in detail.

The Practical Decision Rule

Three questions resolve almost every format choice:

• Will a human edit this directly? Yes → JSON5 or HJSON. No → continue.
• Is this going into an LLM context window? Yes → TOON (for uniform arrays) or JSON (for small or non-uniform data). No → standard JSON.
• Do you need schema validation, streaming, or a query API on top of token savings? Yes → consider TONL, which delivers 32–50% token savings plus those features. No → TOON is sufficient.

JSON5 and TOON are not competitors. They serve different stages of the same pipeline: JSON5/HJSON for the human authoring stage, TOON for the LLM inference stage. Understanding that distinction is more useful than asking which is "better."

For a comparison of TOON against other LLM-oriented formats rather than human-oriented ones, see the YAML vs TOON comparison.

Frequently Asked Questions