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!
Tools - Cheat Sheet


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

  // prefer c-style comments?
  /* feeling old fashioned? */


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

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

  key: "value"


"Now I forgot the comma at the end."

So you did. But lucky for you, in Hjson they are only required if two or more values are on the same line.

  one: 1
  two: 2
  # only multiple values on
  # the same line need them:
  array: [1,2,3]


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

You are right. Let's make quotes for strings optional as well.

  text: look ma, no quotes!
  # quoteless strings include everything
  # up to the end of the line (so no comma).


"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 like in JSON inside quotes
  escape: "\\ \n \t \""


"Multiline strings are kind of hard to read."

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

    JSON I love you.
    But strangled is my data.
    This, so much better.


"OMG, you broke JavaScript!"

JSON is not JavaScript, it's a data interchange format that can be used in many languages.

 * Hjson, like JSON, is not limited
 * to JavaScript.


"OK but OMG, now you broke JSON!"

JSON is a great data format that can be edited by hand but it has a very strict syntax.

A more forgiving format makes it easier for Humans to write, it reduces unnecessary mistakes and is also nicer to read.

 * Hjson does not replace JSON.
 * Use it for configuration files
 * and things like debug dumps.
 * For protocols and anything
 * else use JSON.


"OK but still, do we need another YAML/HOCON/etc.?"

YAML expresses structure through whitespace. Significant whitespace is a common source of mistakes that we shouldn't have to deal with.

Both HOCON and YAML make the mistake of implementing too many features (like anchors, sustitutions or concatenation).

 * A data format for Humans
 * should be lean and simple.

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.rt.parse(text);

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

// stringify with comments
text = Hjson.rt.stringify(data);


The Hjson syntax is a superset of JSON (see but allows you to

You are also allowed to omit the root {} braces for objects.

Cheat Sheet

Simple rules to remember:



Platform Source Package
JavaScript, Node.js & Browser GitHub NPM version
Java GitHub Maven Central
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 Package
Atom GitHub package
Sublime Text / TextMate GitHub
Notepad++ GitHub see source

Integrated with

Name Link Details
any-json: convert (almost) anything to JSON NPM version see readme
gulp: the streaming build system NPM version see readme
grunt: the JavaScript task runner NPM version see readme
hjsonify: a browserify transform to require Hjson files NPM version see readme
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
rc: non-configurable configuration loader for lazy people. NPM version var conf=require('rc')('appname', {/*defaults*/},
null, require('hjson').parse);


All versions work on Linux, OS X & Windows and allow you to convert Hjson from/to JSON.


Install with npm i hjson -g

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


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.