Canonical JSON library

Canonical JSON is a variant of JSON in which each value has a single, unambiguous serialized form. This provides meaningful and repeatable hashes of encoded data.

Canonical JSON can be parsed by regular JSON parsers. The most notable differences compared to usual JSON format (RFC 7159 or serde_json::to_string()) are:

• Object keys must appear in lexiographical order and must not be repeated
• No inter-token whitespace
• Unicode characters and escaped characters are escaped

This library is used for content signatures verification in Remote-Settings, and its definition precedes other Canonical JSON specs like this one. The main difference is about float representation:

   5. MUST represent all non-integer numbers in exponential notation
      1. including a nonzero single-digit significand integer part, and
      2. including a nonempty significand fractional part, and
      3. including no trailing zeroes in the significand fractional part (other than as part of a ".0" required to satisfy the preceding point), and
-     4. including a capital "E", and
-     5. including no plus sign in the exponent, and
+     4. including a lowercase "e", and
+     5. including a plus sign in the exponent, and
      6. including no insignificant leading zeroes in the exponent

Usage

Add this to your Cargo.toml:

[dependencies]
canonical_json = "0.1.0"

Examples

   use serde_json::json;
   use canonical_json::ser::to_string;

   fn main() {
     to_string(&json!(null)); // returns "null"
 
     to_string(&json!("we ❤ Rust")); // returns "we \u2764 Rust""
 
     to_string(&json!(10.0_f64.powf(21.0))); // returns "1e+21"
 
     to_string(&json!({
         "a": "a",
         "id": "1",
         "b": "b"
     })); // returns "{"a":"a","b":"b","id":"1"}"; (orders object keys)
 
     to_string(&json!(vec!["one", "two", "three"])); // returns "["one","two","three"]"
   } 

Test suite

Run the projet test suite:

$ cargo test

Run @gibson042's Canonical JSON test suite:

$ git clone git@github.com:gibson042/canonicaljson-spec.git
$ cd canonicaljson-spec/
$ ./test.sh ../canonicaljson-rs/demo/target/debug/demo

Some known errors:

• lone leading surrogate in hex escape
• number out of range
• Non-token input after 896 characters: "\u6} surrogate pair\u2014U+1D306

See also

• python-canonicaljson-rs: Python bindings for this crate
• CanonicalJSON.jsm in Gecko
• Original python implementation in Remote Settings
• https://github.com/matrix-org/python-canonicaljson/ (encodes unicode with \xDD instead of \uDDDD)

License

Licensed under Mozilla Public License, Version 2.0 (https://www.mozilla.org/en-US/MPL/2.0/)