Hjson Syntax

TL;DR here

Character means any UNICODE character except the control characters.

Details

Commas

You can separate your values/members either with a comma or a new line.

Unlike JSON, trailing commas are ignored and do not produce a syntax error.

For example:

{
  one: 1
  two: 2,
  more: [3,4,5]
  trailing: 6,
}

You should omit optional commas to make your data more readable.

{
  one: 1
  two: 2
}

Whitespace & Comments

Whitespace and comments can be inserted between any pair of tokens.

Whitespace is defined as in the JSON specification (space, linefeed, carriage return, or horizontal tab).

Hash # or C style // comments start a single line comment.

The style is just a matter of preference. # may be easier on the eyes but // is sometimes used in existing JSON configs.

/* starts a multiline comment that ends with */. You can use it to comment out part of the data.

Keys

You only need to add quotes if the key name includes whitespace or any of the punctuators ({}[],:).

For example:

• foo
• "test case"
• "{option}"

Quoteless Strings

A quoteless string cannot start with any of the punctuators ({}[],:) or quotation marks ('") used in Hjson syntax. It is also not possible for a quoteless string to start with a start of comment sequence (#, //, /*).

Unlike a quoted string it automatically ends at the end of the current line. Do not add commas or comments as they would become part of the string. If you wish to add comments place them on the previous or next line.

Preceding and trailing whitespace is ignored. Escapes are only supported in quoted strings.

The Hjson parser will only parse data as a quoteless string if any other interpretation fails, and therefore it will still detect values (number, true, false or null) and parse them correctly. For example

• 3 is the number 3
• true is the boolean true
• 7 # minutes is the number 7 followed by a comment
• 5#comment is the number 5 followed by a comment

Examples that cannot be interpreted as anything else than single quoteless strings:

• 5 times is the string "5 times"
• 5 times, 6 times is the string "5 times, 6 times"
• X # not a comment is the string "X # not a comment"
• \s#([0-9a-fA-F]{3}) is the string "\\s#([0-9a-fA-F]{3})"

Special note regarding hex values in an object: Due to oversight different implementations might handle this in different ways, but anything that starts with # will be treated as a comment. In hjson-js this input will be parsed as an object only containing the key one with the value two: #00FF00 (when the parser detects a comment it assumes that the value starts at the beginning of the next line):

{
  one: #FF00AA
  two: #00FF00
}

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.

For example

haiku:
  '''
  My half empty glass,
  I will fill your empty half.
  Now you are half full.
  '''

Is the string "My half empty glass,\nI will fill your empty half.\nNow you are half full."

Strings

Quoted strings can be written with 'single' or "double" quotes.

Note: single quotes are new (2017/7) and may not yet be supported on all platforms.

Root Braces

Hjson allows you to omit {} for the root object so that a config file can contain nothing but keys and values, similar to YAML.

Note: This feature was previously marked as deprecated but is now officially supported again. If you need maximum portability with your Hjson files, then we recommend you keep the root braces in case a third party implementation doesn't support it.

File extension

.hjson

Encoding

.hjson files must be encoded in UTF-8 (without a BOM).

Header

Hjson does not have a header but if you want to indicate the file type you can use #hjson on the first line.

RFC

View the RFC draft (pending updates/root braces/single quotes)