Hjson, a user interface for JSON

Status

This project is now entirely community-supported. If you would like to help or want to report an issue, please see our GitHub.

npmnugetgomavenpackagistPyPI versionC++cratecrategemLuaRocksRaku
AceAtomIntelliJNotepad++Sublime TextTextMate & CoVimVisualStudioVS Code

Intro

JSON is easy for humans to read and write... in theory. In practice JSON gives us plenty of opportunities to make mistakes without even realizing it.

Hjson is a syntax extension to JSON. It's NOT a proposal to replace JSON or to incorporate it into the JSON spec itself. It's intended to be used like a user interface for humans, to read and edit before passing the JSON data to the machine.

{
  # TL;DR
  human:   Hjson
  machine: JSON
}

How does Hjson help?

Commas!

Never see a syntax error because of a missing or trailing comma again (unless you try really hard).

A good practice is to put each value onto a new line, in this case commas are optional and should be omitted.

{
  first: 1
  second: 2
}

Comments

You are allowed to use comments! Encouraged, even!

Comments allow you to document your data inline. You can also use them to comment out values when testing.

{
  # hash style comments
  # (because it's just one character)

  // line style comments
  // (because it's like C/JavaScript/...)

  /* block style comments because
     it allows you to comment out a block */

  # Everything you do in comments,
  # stays in comments ;-}
}

Object Names (Keys)

Object names can be specified without quotes.

This makes them easier to read.

{
  # specify rate in requests/second
  rate: 1000
}

Quoteless Strings

You can specify strings without quotes.

In this case only one value per line and no commas are allowed.

{
  JSON: "a string"

  Hjson: a string

  # notice, no escape necessary:
  RegEx: \s+
}

Multiline

Write multiline strings with proper whitespace handling.

A simple syntax and easy to read.

{
  md:
    '''
    First line.
    Second line.
      This line is indented by two spaces.
    '''
}

Punctuators, Spaces and Escapes

JSON and Hjson use the characters {}[],: as punctuators to define the structure of the data.

Punctuators and whitespace can't be used in an unquoted key or as the first character of a quoteless string. In this (rather uncommon) case you need to use quotes.

The backslash is only used as an escape character in a quoted string.

{
  "key name": "{ sample }"
  "{}": " spaces at the start/end "
  this: is OK though: {}[],:
}

Hjson

"So this is Hjson."

If you like it please go ahead and add a star!

Star

Are you a user? Then ask the developer of your favorite application to add Hjson support!

Interested in details? Take a look at the syntax.

Questions? See the FAQ.

{
  // use #, // or /**/ comments,
  // omit quotes for keys
  key: 1
  // omit quotes for strings
  contains: everything on this line
  // omit commas at the end of a line
  cool: {
    foo: 1
    bar: 2
  }
  // allow trailing commas
  list: [
    1,
    2,
  ]
  // and use multiline strings
  realist:
    '''
    My half empty glass,
    I will fill your empty half.
    Now you are half full.
    '''
}
Users Developers Syntax Try FAQ Feedback History