BONJSON: Binary Object Notation for JSON

BONJSON is a hardened, lightning-fast and efficient, 1:1 compatible binary drop-in replacement for JSON.

It's much faster to process than JSON due to the format being designed to take advantage of parallelizable instructions present in modern day processors.

It's also far safer than JSON:

• Safe against key collision attacks
• Safe against injection attacks
• Safe against truncation attacks
• Safe against numeric range attacks

Why use binary?

Efficiency

Text formats are great for humans to read, but they're slow and wasteful for computers.

Computers should speak to humans in text (such as JSON), and to each other in binary.

Why use BONJSON?

It's Small

• The BONJSON specification is only 750 lines long (including the formal grammar).
• The C reference implementation is less than 500 LOC each for the encoder and decoder.

It's Simple

• It doesn't use tricks like histograms or references or lookups. Leave those to real compression algorithms.
• It uses existing, CPU-native data encodings as much as possible.
• It keeps tricky sub-byte data to a minimum.

It's Safe

• Safe against key collision attacks
• Safe against injection attacks
• Safe against truncation attacks
• Safe against numeric range attacks

It's Speedy

• Data encoding and decoding can be done using branchless algorithms (example).
• The most common data types and ranges are encoded in fewer bytes.
• The C reference implementation is 35 times faster than jq.

Benchmarking the C Reference Implementation vs jq on a Core i3-1315U (using this test data):

10MB:

~/ksbonjson/benchmark$ ./benchmark.sh 10mb

Benchmarking BONJSON (decode+encode) with 9052k file 10mb.boj

real    0m0.021s
user    0m0.009s
sys     0m0.016s

Benchmarking BONJSON (decode only) with 9052k file 10mb.boj

real    0m0.011s
user    0m0.003s
sys     0m0.012s

Benchmarking JSON (decode+encode) with 10256k file 10mb.json

real    0m0.340s
user    0m0.322s
sys     0m0.024s

BONJSON processed 35.8x faster.

100MB:

~/ksbonjson/benchmark$ ./benchmark.sh 100mb

Benchmarking BONJSON (decode+encode) with 90508k file 100mb.boj

real    0m0.183s
user    0m0.085s
sys     0m0.121s

Benchmarking BONJSON (decode only) with 90508k file 100mb.boj

real    0m0.080s
user    0m0.030s
sys     0m0.071s

Benchmarking JSON (decode+encode) with 102560k file 100mb.json

real    0m3.227s
user    0m3.039s
sys     0m0.232s

BONJSON processed 35.8x faster.

1000MB:

~/ksbonjson/benchmark$ ./benchmark.sh 1000mb

Benchmarking BONJSON (decode+encode) with 905076k file 1000mb.boj

real    0m1.762s
user    0m0.846s
sys     0m1.124s

Benchmarking BONJSON (decode only) with 905076k file 1000mb.boj

real    0m0.746s
user    0m0.300s
sys     0m0.645s

Benchmarking JSON (decode+encode) with 1025564k file 1000mb.json

real    0m31.522s
user    0m29.737s
sys     0m2.307s

BONJSON processed 35.2x faster.

What about the other binary JSON-like formats?

None of them are 1:1 compatible. None of them are safe. Most of them are overcomplicated.

• Type Parity: No extra data types that aren't present in JSON
• Value Parity: Allows only the same value ranges as JSON (for example: infinities and NaN are disallowed)
• Feature Parity: Supports the same features as JSON (for example: progressive document construction)
• Safety: Guards against common attack vectors (key collisions, truncation, range)
• Endianness: Big endian formats are slower to process on modern hardware

Wherever there's a compatibility mismatch, breakage will eventually occur - it's only a matter of time before your complex data pipelines trigger it.

Having confidence in your data plumbing is paramount.

---

📚 Specifications and Code

Specification

• 📖 BONJSON Specification

Formal Grammar

• 🔡 Dogma grammar for BONJSON

Implementations

• ⚙️ C Implementation
• ⚙️ Go Implementation
• ⚙️ Rust Implementation
• ⚙️ Swift Implementation

Tools

• 🛠️ Bonbon: Cmdline tool to convert between JSON and BONJSON

Validating Implementations

This repository includes a universal test suite for validating BONJSON implementations across any language or platform.

To validate a new implementation:

1. Build a test runner that can parse the test specification format
2. Validate your test runner against tests/test-runner-validation/ - if these fail, your conformance results cannot be trusted
3. Validate your codec against tests/conformance/

See the test suite documentation for details.

---

JSON Standards

Any discussions about JSON are done within the context of the ECMA and RFC specifications for JSON, and the json.org website:

• ECMA-404
• RFC 8259
• json.org

License

Copyright (c) 2024 Karl Stenerud. All rights reserved.

Distributed under the Creative Commons Attribution License (license deed.