Hjson vs JSON5: Syntax, Compatibility, and Use Cases Compared

When working with configuration files, data mocks, or any scenario where humans need to write structured data, standard JSON often feels too rigid. Missing commas, forgotten quotes, and the inability to add comments lead to frequent syntax errors. Both hjson and json5 solve this by offering relaxed parsers, but they take very different philosophical approaches to what "relaxed" means. Let's dive into how they handle syntax, compatibility, and real-world usage.

📝 Syntax Philosophy: Minimalist vs. JavaScript-Like

The core difference lies in how much they deviate from standard JSON.

hjson prioritizes human typing speed and visual clarity. It removes as much punctuation as possible. You don't need quotes for keys or string values (unless they contain special characters), you can skip colons, and you can omit braces for the root object. It looks more like a properties file or YAML.

// hjson example
{
  # Comments use hash or slash
  name: John Doe
  age: 30
  skills: [
    javascript
    rust
  ]
  # No quotes needed for simple strings
  role: admin
}

json5 aims to be a valid ECMAScript 5 object literal. It keeps the structure of JSON intact (braces, colons, commas are still expected) but relaxes the rules around them. You can add comments, use trailing commas, and drop quotes on keys if they are valid identifiers. It feels like writing a JavaScript object.

// json5 example
{
  // Comments use slash
  name: 'John Doe',
  age: 30,
  skills: [
    'javascript',
    'rust',
  ], // Trailing comma allowed
  role: 'admin', // Single or double quotes
}

🔌 Compatibility with Standard JSON

This is often the deciding factor for architectural decisions.

json5 is a strict superset of JSON. Any valid JSON file is also valid JSON5. This means you can incrementally adopt it; you can start with a standard JSON file and slowly add comments or trailing commas without breaking the parser. If you strip the comments and trailing commas, you are back to standard JSON.

// Valid JSON is also valid JSON5
{
  "key": "value",
  "number": 123
}
// JSON5 parser accepts this without changes

hjson is NOT a superset of JSON in practice because its default output and parsing expectations differ. While it can parse standard JSON, its canonical format omits characters that standard JSON parsers require. If you save an hjson file in its natural style (no quotes, no colons), a standard JSON.parse() will fail immediately. You must always use the hjson parser to read it, or compile it down to standard JSON before passing it to other systems.

// Valid hjson, but INVALID standard JSON
{
  key: value
}
// Standard JSON.parse() throws an error here

💬 Comments and Trailing Commas

Both libraries solve the two biggest pain points of standard JSON: comments and trailing commas.

hjson supports comments using # (hash) or // (double slash). This makes it very friendly for shell-script users or those who prefer hash comments. It naturally handles trailing commas since the list syntax is flexible.

# hjson comment style
items: [
  one
  two # last item, no comma needed
]

json5 supports only // and /* */ comments, matching JavaScript style. It explicitly allows trailing commas in arrays and objects, which is a huge win for version control diffs (adding a new item doesn't change the previous line).

// json5 comment style
items: [
  'one',
  'two', // Trailing comma is safe
]

🛠️ Real-World Usage Scenarios

Scenario 1: User-Editable Configuration Files

If you are building a CLI tool or an application where users manually edit config files, hjson often provides a better experience. Users don't have to worry about syntax errors from missing quotes or commas.

# config.hjson
# User edits this directly
port: 8080
debug: true
allowedHosts: [
  localhost
  example.com
]

Scenario 2: Build Tool Configurations

For build tools, bundlers, or project settings where the file might be touched by both humans and automated scripts, json5 is usually safer. Many modern tools (like Babel, ESLint, and Webpack) support JSON5 or similar JS-based configs because the structure remains predictable.

// .eslintrc.json5
{
  env: {
    browser: true,
    es2021: true,
  },
  extends: ['eslint:recommended'],
  // Easy to add new rules without fixing commas
  rules: {
    'no-console': 'warn',
  },
}

Scenario 3: Data Exchange Between Services

If you need to pass data between microservices where one service might use a standard library, neither is ideal without a compilation step. However, if you must choose, json5 is easier to sanitize back to standard JSON programmatically since the structure is already there. With hjson, you rely entirely on the hjson.stringify() method to produce valid JSON for transmission.

// Converting hjson to standard JSON for API transmission
const Hjson = require('hjson');
const fs = require('fs');

const raw = fs.readFileSync('config.hjson', 'utf8');
const obj = Hjson.parse(raw);
const standardJson = JSON.stringify(obj); // Now safe to send

⚠️ When to Avoid These Libraries

While these tools are powerful, they introduce a dependency and a parsing step.

• Avoid hjson if you are working in an environment where installing extra packages is difficult or if the config needs to be read by languages with robust JSON parsers but no Hjson ports (though many exist, JSON is universal).
• Avoid json5 if you need the absolute highest performance for parsing massive datasets. The relaxed parsing logic is slightly slower than native JSON.parse(). For huge data files, stick to standard JSON or binary formats like MessagePack.
• Do not use either for untrusted input without validation. Relaxed parsers can sometimes be more prone to injection attacks if not carefully sandboxed, although both libraries are generally mature. Always validate the resulting object schema.

📌 Summary Table

💡 The Big Picture

hjson is like writing a note to a friend — it skips the formalities to get the point across quickly. It's perfect for configuration files where a human is the primary writer and reader. The lack of punctuation noise makes it incredibly fast to edit.

json5 is like writing formal code — it keeps the structure strict but allows modern conveniences. It's the right choice when you want the benefits of comments and trailing commas but still want the file to look and behave like a standard JSON object, ensuring smoother integration with existing JSON-based toolchains.

Final Thought: If your config is strictly for humans and simplicity is king, go with hjson. If your config lives in a developer ecosystem where tools might also read it, json5 offers the safer, more compatible path.