Hjson, the Human JSON

A configuration file format for humans. Relaxed syntax, less mistakes, more comments.

Intro

{
  # specify rate in requests/second (because comments are helpful!)
  rate: 1000

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

  # did you notice that rate doesn't need quotes?
  hey: look ma, no quotes for strings either!

  # best of all
  notice: []
  anything: ?

  # yes, commas are optional!

  # Obviously you can always use standard JSON syntax as well:
  favNumbers: [ 1, 2, 3, 6, 42 ]
}

For details see hjson.org.

Syntax

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

add #, // or /**/ comments,
omit "" for keys,
omit "" for strings,
omit , at the end of a line and
use multiline strings with proper whitespace handling.

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

Cheat Sheet

Simple rules to remember:

if your key includes a JSON control character like {}[],: or space, use quotes
if your string starts with { or [, use quotes
remember that quoteless strings include everything up to the end of the line, excluding trailing whitespace.

Details

Keys

You only need to add quotes if the key name includes whitespace or any of these characters: {}[],:.
Strings

When you omit quotes the string ends at the newline. Preceding and trailing whitespace is ignored as are escapes.

A value that is a number, true, false or null in JSON is parsed as a value. E.g. 3 is a valid number while 3 times is a string.

Naturally a quoteless string cannot start with { or [.

Use quotes to have your string handled like in JSON. This also allows you to specify a comment after the string.
Multiline Strings
- Start with triple quotes ''', whitespace on the first line is ignored
- ''' defines the head, on the following lines all whitespace up to this column is ignored
- all other whitespace is assumed to be part of the string.
- ends with triple quotes '''. The last newline is ignored to allow for better formatting.
A multiline string is OS and file independent. The line feed is always \n.
Commas

Commas are optional at the end of a line. You only need commas to specify multiple values on one line (e.g. [1,2,3]).

Trailing commas are ignored.
Comments

# and // start a single line comment.

/* starts a multiline comment that ends with */.
Root braces

Can be omitted for objects.
Mime Type

text/hjson (pending)
File extension

.hjson
Header

Hjson does not have a header but if you want to indicate the file type (in an rc file or in a database) you can use #hjson in the first line.

Get Hjson

Platform	Source	Package
JavaScript, Node.js & Browser	hjson-js
Java	hjson-java
Python	hjson-py
C#, .Net	hjson-cs
PHP	hjson-php

Partial implementations

Platform	Description	Source
Go	Parser and unmarshaller using a slightly different syntax	xson
C	jzon variant, based on Hjson	jzon-c

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

Editor Syntax

Name	Source	Package
Atom	language-hjson	package
Sublime Text / TextMate	sublime-hjson	packagecontrol.io
Notepad++	npp-hjson	see source

Integrated with

Name	Link	Details
any-json: convert (almost) anything to JSON		see readme
gulp: the streaming build system		see readme
grunt: the JavaScript task runner		see readme
hjsonify: a browserify transform to require Hjson files		see readme
node-config: node.js application configuration		see wiki
nconf: hierarchical node.js configuration		`nconf.file({ file: 'file.hjson',` `format: require('hjson').rt });` `// round trips your comments`
rc: non-configurable configuration loader for lazy people.		`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

please build from source
and add cli\bin\Release to your path.

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

History

2015-05-06: Allow root braces to be omitted.
2015-01-11: Simplified the syntax for quoteless keys. Previously only alphanumeric keys were allowed without quotes.
2015-01-11: Fixed multiline strings: OS/file independent (EOL is always \n). Also the last LF is removed to allow for better formatting.
2015-01-06: Simplified the syntax for quoteless strings. Previously unquoted strings starting with a number, true, false or null were not allowed.
2015-01-02: Added // and /**/ comment support
2014-12-02: Added mime type and file extension.
2014-05-09: Added multiline strings.
2014-03-19: First draft

smclements / hjson