Hjson, the Human JSON

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

Intro

"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? */ } Quotes "Why do I have to place key names in quotes?" Glad you asked. Actually you don't need to do that! { key: "value" } Commas "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] } Quoteless "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). } 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 like in JSON inside quotes escape: "\\

\t \"" } Multiline "Multiline strings are kind of hard to read." "I wonder

why you

say 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!" 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. */ JSON "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. */ YAML "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 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

add # , // or /**/ comments,

, or comments, omit "" for keys,

for keys, omit "" for strings,

for strings, omit , at the end of a line and

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

or space, use quotes if your string starts with { or [ , use quotes

or , use quotes remember that quoteless strings include everything up to the end of the line.

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

.

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.

Platforms

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

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

Editor Syntax

Name Source Package Atom GitHub package Sublime Text / TextMate GitHub packagecontrol.io Notepad++ GitHub see source

Integrated with

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