# 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](https://tools.ietf.org/html/rfc7159) 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 follows [gibson's Canonical JSON spec](https://github.com/gibson042/canonicaljson-spec).
## Usage
Add this to your ``Cargo.toml``:
```toml
[dependencies]
canonical_json = "0.5.0"
```
## Examples
```rust,no_run
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](https://github.com/mozilla-services/python-canonicaljson-rs/): Python bindings for this crate
* [CanonicalJSON.jsm](https://searchfox.org/mozilla-central/rev/358cef5d1a87172f23b15e1a705d6f278db4cdad/toolkit/modules/CanonicalJSON.jsm) in Gecko
* [Original python implementation](https://github.com/Kinto/kinto-signer/blob/6.1.0/kinto_signer/canonicaljson.py) in Remote Settings
* https://github.com/matrix-org/python-canonicaljson/ (encodes unicode with ``\xDD`` instead of ``\uDDDD``)
## License
Licensed under MIT