Comparisons••7 min read

Hjson Explained: Human JSON for Config Files

Hjson — what it is, how it compares to JSON5, JSONC, and YAML, and the contexts where it works better than any of them.

By JSONEditor.net Team

What Hjson is

Hjson is "Human JSON" — a config-file format designed for humans to write and edit, with JSON as the output. It was created by Christian Zangl in 2014 as a reaction to YAML's whitespace sensitivity and JSON's punctuation noise. The spec is small and stable.

Like JSON5 and JSONC, every Hjson document represents the same data structure as some JSON document, and every valid JSON document is also valid Hjson. But unlike JSON5, which keeps JavaScript object-literal syntax, Hjson deliberately changes the surface syntax — particularly around quoting and commas — to be even more forgiving.

The syntax

{
  # comments use # or // or /* */
  name: Christian Zangl       // values do not need quotes for simple strings
  age: 42                     // commas are optional between members
  active: true
  skills: [
    json
    config
    formats
  ]
  address: {
    city: Berlin
    zip: 10115
  }
}

The defining choice: unquoted strings are the default. A bare token like Christian Zangl is a string by default, not an identifier reference. Quotes are only needed when the value contains special characters or you want to be explicit. Commas are optional everywhere. Newlines separate members.

This makes Hjson read like an indented form with English-language values — the bytes that win for human reading are not the quotes and commas, but the field names and values themselves.

Multiline strings

Hjson's killer feature for config: triple-quoted multiline strings that preserve literal content without escape juggling.

{
  prompt:
    '''
    Hello,
    This is a multiline message.
    No "escape" needed for quotes.
    '''
}

The triple-quoted block strips the common leading whitespace from every line (similar to Python's textwrap.dedent). For files that embed SQL queries, email templates, or shell scripts as config values, this is genuinely useful — JSON forces you to \n-escape every newline and double-escape every quote.

Hjson vs JSON5 vs JSONC vs YAML

Four formats, all trying to be "JSON but friendlier." Their differences:

JSONC adds only comments and trailing commas. Closest to JSON. Used by VS Code's settings.

JSON5 adds JavaScript-object-literal features: unquoted identifier keys, single quotes, hex numbers, trailing commas, comments. Used by Babel and Bun.

Hjson goes further: unquoted string values, optional commas, multiline strings with auto-dedent. Used by smaller projects and as a config format in tools like the scoop package manager.

YAML is the maximalist alternative: indentation-sensitive, anchors and aliases, document streams, type tags. More features than the JSON family combined but with a famously surprising spec (the Norway problem, octal autoconversion, time-bomb date parsing).

The trade-off is the same across all four: the more "friendly" the syntax, the more ambiguity at the edges. Hjson's optional quotes mean true as a value is the boolean and "true" as a value is the string — usually what you want, occasionally a foot-gun.

Tooling

Hjson has bindings for JavaScript, Python, Go, Java, C#, Rust, and a few others. The reference repo is hjson/hjson-js and there is a CLI hjson that converts between Hjson and JSON in both directions.

# Convert Hjson to JSON
hjson -j config.hjson > config.json

# Round-trip JSON through Hjson (for human review)
hjson config.json > config.hjson

The smaller ecosystem is the honest downside. Where JSON5 has 2,000+ npm dependents, Hjson has a fraction of that. If you adopt Hjson, you commit to converting to JSON at every boundary — your CI pipeline, your build outputs, your deployments all consume the converted JSON, not the source.

The verdict

Hjson wins for one specific case: a config file you edit by hand frequently, with multiline string values, where the build pipeline can convert it to JSON before deployment. The multiline string handling alone justifies it for any config with embedded SQL, regex, or templates.

For configs without multiline strings, JSON5 or JSONC are easier picks because they have wider tooling support. For configs that are read by many tools without conversion, stick to strict JSON or use YAML if you want hierarchy without curly braces.

If you have an existing JSON config and want to see what it looks like in Hjson before committing to anything, paste it into the formatter, copy the output, and feed it to the Hjson CLI's reverse conversion. The data round-trips losslessly — only the syntax changes.

JSONCSVConvertersData