JSON Getting started with JSON Editing JSON by Hand

Example

JSON is a very strict format (see http://json.org). That makes it easy to parse and write for machines but surprises humans when an inconspicuous mistakes breaks the document.

Common Problems

Trailing Comma

Unlike most programming languages your are not allowed to add a trailing comma:

{
  a: 1,
  b: 2,
  c: 3
}

Adding a comma after 3 will produce a synax error.

The same issue exists for arrays:

[ 
  1,
  2
]

You must take extra care if you need to reorder the items.

Missing Comma

{
  a: 1,
  b: 2,
  c: 3
  d: 4
}

Since trailing commas are not allowed, it is easy to forget to append one before adding a new value (in this case after 3).

Comments

JSON does not allow comments as it is a data-interchange format. This is still a hot topic though with no clear answers other than not to use them.

There are several workarounds:

• Use C style comments, then strip them out before passing it to the parser
• Embed comments into the data

{
  "//": "comment",
  "data": 1
}

• Embed comments and overwrite them with data

{
  "data": "comment",
  "data": 1
}

The second data entry will overwrite the comment in most parsers.

Solutions

To make it easier to write JSON use an IDE that checks for syntax errors and provides syntax coloring. Plugins are available for most editors.

When you develop applications and tools, use JSON internally and as a protocol but try not to expose it in places where a human would likely be required to edit it by hand (except for debugging).

Evaluate other formats that are better suited for this use, like:

• Hjson, can be seamlessly converted to and from JSON
• TOML, similar to INI files
• YAML, more features but at the cost of added complexity