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

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 are right. Let's make quotes for strings optional as well.

{
  text: look ma, no quotes!
  # quoteless strings end with
  # the new-line.
}

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?

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 JavaScript's 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.

YAML

"OK but still, do we need another YAML?"

No matter if people are messy in their editor or if they like to copy/paste from a webpage. Incorrect indentation or tabs should not affect your data.

YAML claims to be human-friendly yet its specs fill 69 pages.

Hjson is no YAML.

We treat whitespace as, er,
white space!

Hjson is easier as it has
less rules to remember.

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
data.foo = "text";

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

Syntax

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

Cheat Sheet

Simple rules to remember:

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
Atom GitHub package
Sublime Text / TextMate GitHub packagecontrol.io
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);

Tools

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

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