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

{
  # This is Hjson

  /*

  Why?

  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 Hjson",

  but: commas and quotes are optional!
  and: those are allowed: // /**/ #
  so:  less mistakes, more comments ;-)
}

For details see hjson.org.

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.

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

• 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 */.

• 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.

Platform	Source	Download
JavaScript, Node.js & Browser	GitHub
Python	GitHub
C#, .Net	GitHub

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

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);

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.

• 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