Canonical JSON

  This page is monitored by the OLPC team.

A "canonical JSON" format is provided in order to provide meaningful and repeatable hashes of JSON-encoded data. Canonical JSON is parsable with any full JSON parser, but security-conscious applications will want to verify that input is in canonical form before authenticating any hash or signature on that input.

The grammar for canonical JSON closely matches the grammar presented at json.org:

object:
    {}
    { members } 
 members:
   pair
   pair , members
pair:
   string : value
array:
   []
   [ elements ]
elements:
   value
   value , elements
value:
   string
   number
   object
   array
   true
   false
   null
string:
   ""
   " chars "
chars:
   char
   char chars
char:
   any byte except hex 22 (") or hex 5C (\)
   \\
   \"
number:
   int
int:
   digit
   digit1-9 digits
   - digit1-9
   - digit1-9 digits
digits:
   digit
   digit digits

Whitespace is not permitted between tokens. Leading and trailing whitespace is likewise disallowed. The members production in object must consist of keys in lexicographically sorted order. Strings are uninterpreted bytes, with only two escaped byte values. Because only two byte values are escaped, be aware that JSON-encoded data may contain embedded control characters and nulls. It is suggested that unicode strings be represented as the UTF-8 encoding of unicode Normalization Form D (UAX #15). However, arbitrary content may be represented as a string: it is not guaranteed that string contents can be meaningfully parsed as UTF-8.

Notes

• Floating point numbers are not allowed in canonical JSON. Neither are leading zeros or "minus 0" for integers.
• All map keys must be quoted, and must appear in sorted order.
• All whitespace is eliminated.
• Trailing commas in members and elements are not allowed.
• Only one 'escape' sequence is defined for strings, and its use is mandatory for quote and backslash.
  • A previous version of this specification required strings to be valid unicode, and relied on JSON's \u escape. This was abandoned as it doesn't allow representing arbitrary binary data in a string, and it doesn't preserve the identity of non-NFD-canonical unicode strings.