I spent last weekend building a JSON toolkit in Rust under one rule: no third-party dependencies. Not "few". None. The [dependencies] table in Cargo.toml is present and empty, and Cargo.lock holds exactly one package — the project itself. No serde, No serde_json, No clap, No itoa, No ryu.
That constraint is the premise of the Zero Dependency hackathon,
and it is a good premise, because it forces you to find out what the standard library actually promises. Here is the thing I did not expect to find:
About 10% of the JSON documents that RFC 8259 says a parser must reject are accepted by Rust's own number parser.
Not a subtle 10%. NaN, Infinity, .5, 5., +1 and 012 are all invalid JSON, and
f64::from_str and i64::from_str take every one of them. If you write a JSON parser the obvious way — scan to the end of the number token, hand the slice to from_str — you ship a parser that is silently non-conformant, with no warning anywhere.
I have the number because I counted it against a real corpus before writing the parser. The rest of this post is what that measurement did to the design, and what generalizes to languages that are not Rust.
What I built
jaq-lite is a hand-rolled RFC 8259 parser, a serializer, and a jq-style query CLI with rustc-style caret diagnostics — 4,670 lines under src/ and 4,432 lines of tests, standard library only.
$ echo '{"users":[{"name":"ada","age":36},{"name":"linus","age":54}]}' | jaq-lite '.users[] | .name'
"ada"
"linus"
It supports identity, field access, quoted fields, indexes, iteration, pipes, commas, parentheses, the optional operator ?, and eleven builtins (length, keys, keys_unsorted, type, to_entries, from_entries, flatten, first, last, reverse, not). Exit codes follow jq: 2 for a bad flag, 3 for a filter that does not compile, 5 for input that is not JSON, 0 otherwise.
The measurement
JSONTestSuite is the standard conformance corpus:
318 files in test_parsing/, named by what a parser is supposed to do with them. 95 y_ files must parse, 188 n_ files must be rejected, and 35 i_ files are cases the standard leaves to the implementation. I vendored it at a pinned commit before writing a line of parser code.
51 of those files are n_number_*. Four contain invalid UTF-8, leaving 47 that are a single well-formed literal. I tested each one against Rust's documented from_str grammars — the float grammar being Sign? (inf | infinity | nan | Number), case insensitive, and the integer grammar being Sign? Digit+ with leading zeros permitted.
19 of the 47 are accepted. Fifteen by f64::from_str:
.123 -.123 .2e-3 <- float grammar allows Digit* '.' Digit+
1. -2. 0.e1 <- and Digit+ '.' Digit*
2.e3 2.e+3 2.e-3
Inf +Inf Infinity <- the inf / infinity keywords, case-insensitive
-Infinity NaN -NaN <- and nan, with or without a sign
And four more by i64::from_str, which permits a leading + and leading zeros: +1, 012, -01, -012.
Nineteen fixtures is about a tenth of the entire must-reject set. Delegating validation to from_str fails all nineteen with no error message, no warning, and no test failure anywhere except a conformance harness you had to build first in order to notice.
This is not a bug in Rust, and that is the part worth internalizing. from_str is a conversion, and its contract is Rust's literal syntax, not JSON's. It is permissive about exactly the forms Rust's own grammar permits, which is why it takes inf and +1.
Nothing in its signature or its name claims to be a validator. I reached for it because it was the obvious tool, and the obvious tool answers a different question.
So the number grammar is hand-written: a small state machine over bytes that enforces RFC 8259's actual production — optional minus, an integer part that is either 0 alone or a nonzero digit followed by digits, an optional fraction that must have at least one digit after the dot, an optional exponent that must have at least one digit after e and its optional sign — and then, critically, checks the terminator. 1 000.0 is in the corpus precisely because a grammar that stops at the space and does not ask what follows will accept 1 and then either choke or silently succeed.
The state machine is a few dozen lines. It was the highest-value few dozen lines in the project, and I only knew that because I had counted the fixtures first.
This is not a Rust problem
Before publishing that finding I checked whether it was a quirk of one standard library. It is not. Every language ships a lenient string-to-number conversion, because a conversion's job is to be generous about its own literal forms. Paste these and watch:
>>> float("Infinity"), float("NaN"), float(".5"), float("5."), float("+1"), float("012")
(inf, nan, 0.5, 5.0, 1.0, 12.0)
>>> float("1_0"), float("1_0.5") # digit separators, since 3.6
(10.0, 10.5)
>>> float(" 12 ") # surrounding whitespace is stripped
12.0
Python goes one better, and this one genuinely surprised me — the standard library's JSON module itself is non-conformant by design:
>>> import json
>>> json.loads("NaN"), json.loads("Infinity"), json.loads("-Infinity")
(nan, inf, -inf)
That is documented behaviour, not a bug, and it is why a payload written by Python's json.dumps can be rejected by a strict reader in another language. If you exchange JSON with a Python service, allow_nan=False is worth knowing about.
JavaScript's Number() is looser still, because it accepts every numeric literal form the language has, including bases JSON does not have at all:
Number(".5") // 0.5 Number("0x1") // 1
Number("5.") // 5 Number("0b11") // 3
Number("+1") // 1 Number("0o7") // 7
Number("012") // 12 Number(" 12 ") // 12
Number("Infinity") // Infinity Number("") // 0 <- the empty string is zero
JSON.parse is strict about all of them, which is the point: V8 ships a separate grammar for JSON rather than reusing Number(). Somebody there had this same realization and paid for the second implementation.
The transferable rule is small enough to remember: if a function's job is to convert, it is not your validator. When a wire format specifies a grammar, implement the grammar. The convenience helper will agree with it most of the time, and the disagreements are exactly the inputs an attacker or a buggy producer will send you.
The same trap, three more times
Once you are looking for it, the pattern is everywhere in a parser. Three more instances I hit in the same weekend, all from the same root cause — a helper whose contract is nearly the one you want:
char::is_whitespace() follows Unicode White_Space, which is about a dozen characters including the no-break space U+00A0 and the vertical tab. JSON's whitespace is exactly four bytes: space, tab, line feed, carriage return. A lexer that skips is_whitespace() accepts documents it must reject.
char::is_numeric() accepts １, U+FF11 FULLWIDTH DIGIT ONE — which is in the corpus as a must-reject fixture. The funny part is that from_str gets this one right, because Rust's integer parser only takes ASCII digits. So a lexer that uses is_numeric() to find where a number token ends fails the fixture even with a perfectly correct grammar behind it. The answer is is_ascii_digit(), and the general answer is that "is this a digit" is a different question from "is this one of the ten characters my grammar permits".
read_to_string() panics on 25 of the 318 fixtures, because they are not valid UTF-8 — 12 of those are must-reject cases, which means the naive harness dies before it can print a score for the very inputs it exists to check. The parser therefore takes &[u8] and gates UTF-8 explicitly with Utf8Error::valid_up_to(), so "not valid UTF-8 after 3 bytes" is a diagnostic rather than a panic. The conformance harness uses fs::read, never read_to_string.
And two fixtures nest 100,000 levels deep. Recursive descent on those is a stack overflow, which is a crash and not a rejection — the corpus scores it as a failure either way, but your users experience the difference. Both recursive descents carry an explicit u32 counter and refuse before recursing: 128 levels for a document, 64 for filter parentheses. Both limits are readable back out of the error variant that reports them, rather than being buried in an English message, because a number in prose is not available to a caller.
Diagnostics are worth the afternoon
The one feature I would keep if I had to cut everything else is the error format. This is rustc's shape, and it takes maybe two hours to implement:
$ jaq-lite . bad.json
jaq-lite: bad.json: line 1, column 2: expected a string as the object key
|
1 | {1:2}
| ^
[exit 5]
The renderer works on raw bytes rather than on a str, for the reason above: input that is not valid UTF-8 is one of the failures it has to draw a caret under. A position is stored as a byte offset and lines are only counted when a message is actually printed, so nothing pays for a line table it never uses.
The 35 files where the standard declines to decide
The i_ fixtures are the interesting third of the corpus: lone surrogates, a UTF-8 BOM before an empty object, integers that exceed 64 bits, duplicate keys. RFC 8259 permits a parser to accept or reject each of these, so a score against them means nothing — you can claim any number you like by changing your mind.
What I did instead was write four policies before looking at the files, and derive all 35 decisions from them. Policy 1 is the UTF-8 gate and settles 14 of the cases. The other three handle the numeric range, duplicate keys, and structural edge cases, covering 10, 10 and 1 respectively, with no residue: 10 accepted, 25 rejected, every one traceable to a rule rather than to a judgement call made at 2am.
That is the transferable move for implementation-defined behaviour anywhere: publish the policy, not the tally. A reader can disagree with a policy. A tally offers nothing to disagree with.
A number is the bytes it was written with
The design decision I am happiest about started as a compatibility question. jq does not round-trip numbers through a float: give it 1.0 and you get 1.0 back, -0.0 stays -0.0, and a 30-digit integer comes back intact. It only canonicalizes exponent form,
turning 1e2 into 1E+2.
So a number here is not an f64. It is:
pub struct Number {
raw: Box<str>, // the exact span the RFC 8259 grammar validated
val: f64, // for comparisons and arithmetic-free semantics
}
Construction is crate-private, which makes "raw was validated" a structural invariant rather than a comment. Three things fall out of it. Round-tripping becomes byte-exact over all 95 documents that must parse, rather than merely semantically equal. -0.0 != 0.0 comes free from comparing the text, while PartialEq on val still gives jq's 1.0 == 1. And it deletes code from the serializer: no appending .0 to integral floats, no scientific-notation threshold, no non-finite branch, because a literal the grammar accepted can never be inf or NaN.
The cost is real and I state it rather than hiding it: roughly 16 bytes plus the digits against 8 for a bare f64, which a number-dense document pays for.
Numbers the tool synthesizes — length, indices — are the only remaining place text gets generated, and they go through core::fmt::NumBuffer with format_into. That is also the itoa replacement, and it is measurably faster than the format! most people would reach for: 1.68 times, measured. One consequence is a named divergence from jq, in the README rather than in a footnote: 1e2 stays 1e2 here.
Compatibility is compared, not remembered
"jq-compatible" is the kind of claim that rots quietly. So CI runs 62 comparisons against a real jq 1.8.1 binary on every push: eight identity cases, six path expressions, 29 builtins over the corpus, and 19 over shapes the script writes into its own temporary directory. It reads its builtin roster out of the code's own match arms and fails if a builtin exists that no comparison reaches, which is a different and much more useful failure than a disagreement — it catches the feature you added and forgot to compare.
An external binary is not a dependency: nothing about jq ships in the artifact, and the comparison exists so that "jq-compatible" is a measurement rather than an adjective.
One trap worth passing on. jq's Windows build writes CRLF, because its stdout is in text mode; Rust writes LF. A naive byte diff therefore fails on every single line for a reason that has nothing to do with correctness, and Git Bash does not save you. The differential runs under WSL, which is also where the reproducibility check lives.
Then I made my documents fail the build
This is the practice I would take to any codebase, and it came out of being burned. A README number goes stale in the commit after the one that wrote it, and prose does not fail a build, so nothing tells you. In this repo, 14 of the 191 tests do nothing but read documents and compare them to the code:
- every hash recorded in
BUILD_LOG.mdmust agree with the others that describe the same build - the README must quote the reproducible-build script's assertion phrases verbatim, and
the CI job the README names by name must exist in
ci.yml - the README must contain no 64-hex-character token, so the decision not to publish a digest as if it were a constant cannot quietly reverse
- the test count stated in
CLAIMS.mdis grepped out ofsrc/andtests/rather than typed, because it had already gone stale twice - every limit the code enforces must be stated in the README, and every builtin the code has must be named there
The one that convinced me was a row in the claims ledger that said thirteen while the file it described held fourteen tests. Every gate passed while it was false, because no program was reading it. Now one is. A rewording fails in the commit that reworded it.
The general shape: for each claim in your docs, ask what file would contradict it, then read both in a test. It costs about twenty lines each and it converts documentation from a liability into an asset that CI defends.
A digest is evidence about a tree, not about a project
The build is byte-for-byte reproducible, and the mechanism is three lines in Cargo.toml:
codegen-units = 1 removes parallel-codegen nondeterminism, and debug = 0 with strip = "symbols" removes the absolute paths and symbol tables that otherwise record where the build happened.
Two details make the check honest. The script builds in two directories of different lengths, because equal-length paths give a false pass — a path baked into the binary would still compare equal. And it runs a control build with debug info left in, which yields a different digest every time; that is the sensitivity check that proves the comparison can fail at all. A test that cannot fail is not evidence.
The published digests are dated samples tied to the commit that produced them, not constants.
The binary was 468,704 bytes at commit 34 and 490,336 at commit 65, because 31 commits of source landed in between. Publish the recipe; date the digest.
Reporting speed without lying
The README prints 26.5 MiB/s for parsing and 197.9 for serializing, over a 1,196,671-byte document the test generates for itself. Then it spends a paragraph explaining why you should not trust that figure: five runs of one unchanged binary, across two boots of the same laptop, span 17.7 to 41.8 MiB/s. A factor of 2.4, from source that did not change.
So the suite asserts a floor and never the figure — 5 MiB/s release, 1 debug, raisable through an environment variable and lowerable by nothing. A regression that changes the shape of the algorithm fails a test; an unlucky sample on a busy machine does not. And what gets printed is the mean over the timing window rather than the fastest round in it, because interference only ever slows a round down, which makes the fastest round the flattering one to report and not the one a caller experiences.
What it does not do
No arithmetic, no variables, no user-defined functions. JQ_COLORS is not parsed. There is no --max-depth for either nesting limit. 1e2 does not become 1E+2. All of that is in the README, and one of those 14 tests fails the build if the code enforces a limit the README does not state — which is the only reason I trust the list to still be complete.
Try it
git clone https://github.com/pal-123456789/jaq-lite
cd jaq-lite
cargo test --release
191 tests, no network access after the clone, and one package in the lockfile.
Repository: pal-123456789/jaq-lite ·
v0.1.0 release ·
five-minute walkthrough
If you take one thing from this: the corpus came first, and it is the reason I know a number instead of an opinion. Whatever format you are parsing, find the conformance suite before you write the parser. Nineteen files is not a lot to fix on day one, and it is a very unpleasant thing to discover in production.
