Star on GitHub

Hjson, the Human JSON

A configuration file format that caters to humans and helps reduce the errors they make.

Get Hjson!Try It!

Intro

Comments, yay!

"What exactly is this value? A comment would help!"

Sure, comments allow you to document your data.

{
  # specify rate in requests/second
  "rate": 1000
  // maybe you prefer js style comments
  /* or if you feel old fashioned */
}

Quotes

"Why do I have to place key names in quotes?"

Glad you asked. Actually you don't need to do that!

{
  key: "value"
}

More Quotes

"Come to think of it, why do I have to place strings in quotes?"

You don't. Quotes for strings are optional as well!

{
  text: look ma, no quotes!
}

Escapes

"When there are no quotes, do I need escapes?"

No, escapes are gone from unquoted strings.

{
  # write a regex without escaping the escape
  regex: ^\d*\.{0,1}\d+$

  # quotes in the content need no escapes
  inject: <div class="important"></div>

  # escapes work inside quotes
  escape: "c:\\windows"
}

Commas

"Now I forgot the comma at the end."

So you did. But lucky for you, in Hjson they are optional.

{
  one: 1
  two: 2
}

More Commas

"So what if I added a trailing comma?"

Can't make up your mind or was that copy & paste?

Like JavaScript, Hjson totally respects your choice of trailing commas.

{
  one: 1,
  two: 2,
}

Multiline

"Multiline strings are kind of hard to read."

"I wonder\nwhy you\nsay that." Hjson will let you write them with proper whitespace handling.

{
  haiku:
    '''
    JSON I love you.
    But strangled is my data.
    This, so much better.
    '''
}

JavaScript

"OMG, you broke JavaScript!"

JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format. It shares some of JavaScripts syntax but it's not JavaScript.

JSON is not JavaScript.

JSON

"OK but OMG, now you broke JSON!"

JSON is a great tool that does its job very well. Maybe too well. JSON is a great hammer but not everything is a nail.

Configuration files are edited by end-users, not developers. Users should not have to worry about putting commas in the correct place. Software should empower the user not hinder him.

JSON is a great hammer but
not everything is a nail.

Hjson does not replace JSON.
Use it for configuration files
and things like debug dumps.

For anything else use JSON.

Round trip

"Can Hjson keep my comments when updating a config file?"

Yes, Hjson allows you to round-trip your data, including your comments.

var data = Hjson.parse(text, { keepWsc: true });

// use data like a normal object
data.foo = "text";

// stringify with comments
text = Hjson.stringify(data, { keepWsc: true });

Syntax

The Hjson syntax is a superset of JSON (see json.org) but allows you to

Details

Platforms

Platform Source Download
JavaScript, Node.js & Browser GitHub NPM version
Python GitHub PyPI version
C#, .Net GitHub nuget version

Please open an issue if you port Hjson to another platform/language.

Editor Syntax

Name Source Download
Sublime Text GitHub packagecontrol.io
Notepad++ GitHub see source

Integrated with

Name Details
node-config: node.js application configuration NPM version see wiki
nconf: hierarchical node.js configuration NPM version nconf.file({ file: 'file.hjson', format: require('hjson').rt });
(round trips your comments)
gulp: the streaming build system NPM version see readme
Grunt: the JavaScript task runner NPM version see readme

Conversion

All versions work on Linux, OS X & Windows.

node.js

Install with npm i hjson -g

hjson file.json will convert to Hjson.
hjson -j file.hjson will convert to JSON.

Python

Install with pip install hjson

python -m hjson.tool file.json will convert to Hjson.
python -m hjson.tool -j file.hjson will convert to JSON.

C# .Net & Mono

As Nuget does not install commandline tools

hjsonc file.json will convert to Hjson.
hjsonc -j file.hjson will convert to JSON.

History