DEV Community: Mark Lenhardt

Shortest Round-Trip: Implementing IEEE 754 to Decimal Conversion in Go

Mark Lenhardt — Sat, 28 Feb 2026 05:42:33 +0000

Every programmer has seen this:

0.1 + 0.2 = 0.30000000000000004

The joke is that floating-point arithmetic is broken. It isn't. IEEE 754 is doing exactly what it specifies. The problem surfaces when you need to serialize these values to text — and when two different systems need to produce exactly the same text for the same value.

This is what RFC 8785 (JSON Canonicalization Scheme) requires: byte-deterministic JSON output. And the hardest part of that requirement is number formatting. You need the shortest decimal string that, when parsed back, recovers the original IEEE 754 bits. You need to agree on tie-breaking when two representations are equally short. And you need to match the exact output format specified by ECMA-262 Number serialization, because that's what RFC 8785 mandates.

Go's strconv.FormatFloat is a high-quality shortest-round-trip formatter, but it is not an ECMA-262 conformance contract. So I implemented the Burger-Dybvig algorithm from scratch in 490 lines of Go, validated against 286,362 oracle test vectors. This article walks through the entire implementation.

IEEE 754 Anatomy: 64 Bits of Structure

Before generating digits, you need to understand the raw material. An IEEE 754 double-precision float is 64 bits:

[1 bit: sign] [11 bits: biased exponent] [52 bits: mantissa]

The value it represents (for normal numbers) is:

(-1)^sign × 1.mantissa × 2^(exponent - 1023)

The 1.mantissa is key — normal numbers have an implicit leading 1 bit, giving you 53 bits of precision total. Subnormal numbers (biased exponent = 0) lose the implicit bit, giving 0.mantissa × 2^(-1022).

Here's how the implementation extracts these parts:

func decodeFloatParts(f float64) floatParts {
    bits := math.Float64bits(f)
    mantissa := bits & ((uint64(1) << 52) - 1)
    expBits := exponentBits(bits)
    biasedExp := int(expBits)

    fMant := mantissa
    fExp := 1 - 1023 - 52
    if biasedExp != 0 {
        fMant = (uint64(1) << 52) | mantissa
        fExp = biasedExp - 1023 - 52
    }

    lowerBoundary := biasedExp > 1 && mantissa == 0

    return floatParts{
        mantissa:      mantissa,
        biasedExp:     biasedExp,
        fMant:         fMant,
        fExp:          fExp,
        lowerBoundary: lowerBoundary,
        isEven:        fMant%2 == 0,
    }
}

Two things to note here. First, the subnormal branch: when biasedExp == 0, there's no implicit leading 1, and the effective exponent is fixed at 2^(-1074) (the smallest representable power). Second, the lowerBoundary flag: when the mantissa is zero and the exponent is above the minimum normal range, the float sits at a power-of-two boundary where the gap to the lower adjacent representable is half the gap to the upper adjacent. This asymmetry matters for the algorithm.

The exponent extraction itself works on the raw bit pattern:

func exponentBits(bits uint64) uint16 {
    hi := byte((bits >> 56) & 0xFF)
    lo := byte((bits >> 48) & 0xFF)
    return (uint16(hi&0x7F) << 4) | uint16(lo>>4)
}

This reconstructs the 11-bit biased exponent by extracting the relevant bytes and masking away the sign bit.

The Core Insight: Why You Need Multiprecision Arithmetic

The Burger-Dybvig algorithm answers this question: what is the shortest decimal string d such that parse(d) == f for our original float f?

To answer it, you need to compute exact boundaries. Every float f has two adjacent representable values. The "shortest round-trip" string must map back to f and not to either neighbor. This means computing the midpoints between f and its neighbors with exact arithmetic — not floating-point arithmetic, which would introduce the very imprecision you're trying to eliminate.

The algorithm represents the value and its boundaries as ratios of big integers. For a float with fractional mantissa fMant and exponent fExp, the value is fMant × 2^fExp. The boundaries M- and M+ define the interval within which any decimal representation will round back to f.

State Initialization: R, S, M+, M-

The algorithm works with four multiprecision integers:

R (remainder): represents the current value, scaled into the digit-extraction space
S (scale): the denominator; digits are extracted by dividing R by S
M+ (upper margin): how far R can grow before rounding to the next float
M- (lower margin): how far R can shrink before rounding to the previous float

Initialization depends on the exponent sign:

func initScaledPositiveExp(state *digitState, parts floatParts) {
    if !parts.lowerBoundary {
        state.r.SetUint64(parts.fMant)
        lshByInt(state.r, parts.fExp+1)  // r = fMant × 2^(fExp+1)
        state.s.SetInt64(2)               // s = 2
        state.mPlus.SetInt64(1)
        lshByInt(state.mPlus, parts.fExp) // m+ = 2^fExp
        state.mMinus.Set(state.mPlus)     // m- = m+
        return
    }

    // Lower boundary: asymmetric margins
    state.r.SetUint64(parts.fMant)
    lshByInt(state.r, parts.fExp+2)       // r = fMant × 2^(fExp+2)
    state.s.SetInt64(4)                    // s = 4
    state.mPlus.SetInt64(1)
    lshByInt(state.mPlus, parts.fExp+1)   // m+ = 2^(fExp+1)
    state.mMinus.SetInt64(1)
    lshByInt(state.mMinus, parts.fExp)    // m- = 2^fExp (half of m+)
}

The lowerBoundary case (mantissa is zero, exponent above minimum) requires special handling. At a power-of-two boundary, the float sits at the top of one binade and the bottom of the next. The gap to the lower neighbor is half the gap to the upper neighbor. The algorithm accounts for this by doubling all values (multiplying R and S by 2) and setting m+ = 2 × m-.

For negative exponents, the roles are similar but the scaling direction reverses — instead of left-shifting R, we left-shift S:

func initScaledNegativeExp(state *digitState, parts floatParts) {
    if !parts.lowerBoundary {
        state.r.SetUint64(parts.fMant)
        lshByInt(state.r, 1)               // r = fMant × 2
        state.s.SetInt64(1)
        lshByInt(state.s, -parts.fExp+1)   // s = 2^(-fExp+1)
        state.mPlus.SetInt64(1)            // m+ = 1
        state.mMinus.SetInt64(1)           // m- = 1
        return
    }

    state.r.SetUint64(parts.fMant)
    lshByInt(state.r, 2)                   // r = fMant × 4
    state.s.SetInt64(1)
    lshByInt(state.s, -parts.fExp+2)       // s = 2^(-fExp+2)
    state.mPlus.SetInt64(2)                // m+ = 2
    state.mMinus.SetInt64(1)               // m- = 1
}

Power-of-10 Scaling

After initialization, R, S, M+, and M- are all in base-2 space. To extract decimal digits, we need to scale them so that the first digit comes from floor(R/S). This requires estimating k ≈ ceil(log10(f)) and scaling accordingly:

func scaleByPower10(state *digitState, k int) {
    switch {
    case k > 0:
        p := pow10Big(k)
        state.s.Mul(state.s, p)           // Scale denominator up
    case k < 0:
        p := pow10Big(-k)
        state.r.Mul(state.r, p)           // Scale numerator up
        state.mPlus.Mul(state.mPlus, p)   // Scale margins too
        state.mMinus.Mul(state.mMinus, p)
    }
}

The k estimate uses floating-point logarithms and is allowed to be off by one. Two fixup passes correct any estimation error:

func applyHighFixup(state *digitState, isEven bool, n int) int {
    high := new(big.Int).Add(state.r, state.mPlus)
    if cmpHigh(high, state.s, isEven) {
        state.s.Mul(state.s, bigTen)
        return n + 1
    }
    return n
}

If R + M+ already exceeds S after initial scaling, we need one more decimal position — multiply S by 10 and increment the exponent count. The low fixup works in the opposite direction, looping while 10R and 10(R + M+) are both less than S.

Computing pow10Big efficiently matters because these are big integer multiplications. The implementation pre-computes 700 powers of 10 at init time:

var pow10Cache [700]*big.Int

func init() {
    pow10Cache[0] = big.NewInt(1)
    for i := 1; i < len(pow10Cache); i++ {
        pow10Cache[i] = new(big.Int).Mul(pow10Cache[i-1], bigTen)
    }
}

func pow10Big(n int) *big.Int {
    if n >= 0 && n < len(pow10Cache) {
        return new(big.Int).Set(pow10Cache[n])  // Defensive copy
    }
    return new(big.Int).Exp(bigTen, big.NewInt(int64(n)), nil)
}

The defensive copy on line 487 is critical — without it, callers that mutate the returned *big.Int would corrupt the cache. IEEE 754 binary64 ranges from approximately 10^-324 to 10^308, so the 700-entry cache covers all practical k values.

Digit Generation: The Main Loop

With scaling complete, digit extraction is a simple loop. Multiply R, M+, and M- by 10, then divide R by S to get one decimal digit. Repeat until termination:

func extractDigits(state *digitState, isEven bool, n int) (string, int) {
    var digitBuf [30]byte
    dIdx := 0
    quot := new(big.Int)
    rem := new(big.Int)

    for {
        scaleDigitState(state)                              // R, M+, M- *= 10
        d := divideAndRemainder(state, quot, rem)           // d = R / S; R = R mod S

        tc1, tc2 := terminationConditions(state, isEven)
        if !tc1 && !tc2 {
            digitBuf[dIdx] = byte('0' + d)
            dIdx++
            continue
        }

        digitBuf[dIdx] = finalDigit(d, tc1, tc2, state.r, state.s)
        dIdx++
        break
    }

    n = normalizeDigitBuffer(digitBuf[:], dIdx, &dIdx, n)
    return string(digitBuf[:dIdx]), n
}

The 30-byte buffer is generous — IEEE 754 binary64 produces at most 17 significant digits in shortest form, with carry propagation adding at most one more.

The two termination conditions test whether we've reached a boundary:

func terminationConditions(state *digitState, isEven bool) (bool, bool) {
    tc1 := cmpRoundDown(state.r, state.mMinus, isEven)
    high := new(big.Int).Add(state.r, state.mPlus)
    tc2 := cmpHigh(high, state.s, isEven)
    return tc1, tc2
}

tc1 (round down): the remainder R is small enough that rounding down to digit d would still land in the correct interval
tc2 (round up): the remainder R plus the upper margin M+ meets or exceeds S, meaning rounding up to d+1 is within range

When neither condition fires, we aren't yet at the shortest representation — emit the digit and continue. When at least one fires, this is the last digit.

Even-Digit Tie-Breaking

The most subtle part of the algorithm is what happens when both termination conditions fire simultaneously — the value sits at the exact midpoint between two representations. ECMA-262 Note 2 mandates even-digit tie-breaking (banker's rounding):

func finalDigit(d int, tc1, tc2 bool, r, s *big.Int) byte {
    switch {
    case tc1 && !tc2:
        return byte('0' + d)      // Only round-down applies: use d
    case !tc1 && tc2:
        return byte('0' + d + 1)  // Only round-up applies: use d+1
    default:
        return midpointDigit(d, r, s)  // Both apply: tie-break
    }
}

func midpointDigit(d int, r, s *big.Int) byte {
    twoR := new(big.Int).Lsh(r, 1)
    cmp := twoR.Cmp(s)
    if cmp < 0 {
        return byte('0' + d)      // Closer to lower: round down
    }
    if cmp > 0 {
        return byte('0' + d + 1)  // Closer to upper: round up
    }
    // Exactly at midpoint: even-digit tie-breaking
    if d%2 == 0 {
        return byte('0' + d)      // d is even: keep it
    }
    return byte('0' + d + 1)      // d is odd: round up to even
}

The midpoint test compares 2R against S. If 2R < S, the remainder is less than half the scale — round down. If 2R > S, round up. When 2R == S exactly, the algorithm breaks the tie by choosing the even digit.

This even-digit preference also influences the boundary comparisons themselves. The cmpRoundDown, cmpHigh, and cmpLow functions use different comparison operators depending on whether the mantissa is even or odd:

func cmpRoundDown(lhs, rhs *big.Int, isEven bool) bool {
    if isEven {
        return lhs.Cmp(rhs) <= 0   // Inclusive: allow rounding to even at boundary
    }
    return lhs.Cmp(rhs) < 0        // Strict: odd mantissa
}

func cmpHigh(lhs, rhs *big.Int, isEven bool) bool {
    if isEven {
        return lhs.Cmp(rhs) >= 0   // Inclusive
    }
    return lhs.Cmp(rhs) > 0        // Strict
}

This asymmetry is the difference between ECMA-262 compliance and "close enough." When the mantissa is even, the boundary comparisons are inclusive — they allow termination at exact boundary values, creating the conditions for even-digit tie-breaking. When odd, strict comparisons ensure the algorithm doesn't terminate prematurely.

Carry Propagation

When finalDigit returns d+1, it may produce a 10 (the character after '9'). This overflow must propagate:

func normalizeDigitBuffer(digitBuf []byte, dIdx int, dIdxPtr *int, n int) int {
    // Propagate carries
    for i := dIdx - 1; i > 0; i-- {
        if digitBuf[i] > '9' {
            digitBuf[i] = '0'
            digitBuf[i-1]++
        }
    }

    // Handle carry out of the first digit
    if dIdx > 0 && digitBuf[0] > '9' {
        copy(digitBuf[1:dIdx+1], digitBuf[0:dIdx])
        digitBuf[0] = '1'
        digitBuf[1] = '0'
        dIdx++
        n++    // One more integer digit
    }

    // Strip trailing zeros
    for dIdx > 1 && digitBuf[dIdx-1] == '0' {
        dIdx--
    }
    *dIdxPtr = dIdx
    return n
}

Consider a carry cascade: digits [9, 9, 10] become [9, 10, 0] then [10, 0, 0], and finally the carry-out case shifts everything right to produce [1, 0, 0, 0] with an incremented exponent. Trailing zeros are then stripped since the algorithm produces shortest representations.

ECMA-262 Output Formatting

The Burger-Dybvig algorithm produces a digit string and an exponent n. The ECMA-262 specification (§6.1.6.1.20) defines four formatting branches based on n:

func formatECMA(negative bool, digits string, n int) string {
    k := len(digits)

    var buf []byte
    if negative {
        buf = append(buf, '-')
    }

    switch {
    case k <= n && n <= 21:
        // Integer fixed: "12300" (digits + trailing zeros)
        buf = appendIntegerFixed(buf, digits, k, n)
    case 0 < n && n <= 21:
        // Fraction fixed: "12.345" (decimal point within digits)
        buf = appendFractionFixed(buf, digits, n)
    case -6 < n && n <= 0:
        // Small fraction: "0.00123" (leading zeros after decimal point)
        buf = appendSmallFraction(buf, digits, n)
    default:
        // Exponential: "1.23e+20" or "1e-7"
        buf = appendExponential(buf, digits, k, n)
    }

    return string(buf)
}

The boundary constants come directly from the ECMA-262 specification:

Branch	Condition	Example Input	Output
Integer fixed	`k ≤ n ≤ 21`	`1e20`	`100000000000000000000`
Fraction fixed	`0 < n ≤ 21, n < k`	`1.5`	`1.5`
Small fraction	`-6 < n ≤ 0`	`1e-6`	`0.000001`
Exponential	otherwise	`1e21`	`1e+21`

The boundaries are exact. A value of exactly 10^21 uses exponential notation (1e+21), while 999999999999999900000 (just below 10^21) uses integer fixed notation. A value of exactly 10^-6 uses small fraction notation (0.000001), while anything below that switches to exponential.

These boundary behaviors can be verified against specific bit patterns:

0x444b1ae4d6e2ef50 → "1e+21"                        (exponential)
0x444b1ae4d6e2ef4f → "999999999999999900000"         (integer fixed)
0x3eb0c6f7a0b5ed8d → "0.000001"                      (small fraction)
0x3eb0c6f7a0b5ed8c → "9.999999999999997e-7"          (exponential)

Why strconv.FormatFloat Is Insufficient

Go's strconv.FormatFloat is the standard library's number-to-string conversion. With format 'e', 'f', or 'g' and precision -1, it produces shortest-round-trip representations. The issue for JCS is not quality; the issue is contract mismatch. RFC 8785 requires ECMAScript-compatible rendering rules, and FormatFloat does not expose that contract.

The gaps are concrete.

Format-policy divergence. ECMA-262 and FormatFloat make different notation choices at key boundaries. Examples:

Value	ECMA-262 / RFC 8785 expected	`FormatFloat(v, 'g', -1, 64)`
`1e20`	`100000000000000000000`	`1e+20`
`1e-6`	`0.000001`	`1e-06`
`1000000`	`1000000`	`1e+06`

These are all valid shortest representations, but only one side matches the JCS contract (see RFC 8785's ECMAScript-compatible serialization examples in Appendix B).

These three examples are sufficient to establish the core point: ECMA-262 rendering switches policy across multiple exponent ranges, while any single FormatFloat mode has one fixed rendering policy. Once boundary cases disagree, conformance requires a dedicated ECMA-262 formatting layer.

Single-mode mismatch. ECMA-262 output policy spans multiple branches (fixed integer, fixed fraction, small fraction, exponential) with exact thresholds. No single FormatFloat mode ('e', 'f', or 'g') reproduces all branches across the full range.

Upstream algorithm drift risk. Go's shortest-mode internals are not static over time. As of Go 1.26.0 (February 2026), shortest mode in internal/strconv/ftoa.go explicitly says "Use the Dragonbox algorithm" and calls dboxFtoa; the Dragonbox implementation in ftoadbox.go states round-to-nearest, ties-to-even behavior. Older Go releases used different internals. That evolution is normal for a standard library, but it is exactly why canonicalization code should not outsource its normative behavior to implementation details of an external runtime.

Building from scratch eliminates these issues. The Burger-Dybvig path always uses exact multiprecision arithmetic, applies explicit midpoint handling, and formats according to ECMA-262 branch rules. The cost is performance, but for canonicalization, correctness is the constraint.

Special Values

Three special cases are handled before the algorithm runs:

func FormatDouble(f float64) (string, *jcserr.Error) {
    if math.IsNaN(f) {
        return "", jcserr.New(jcserr.InvalidGrammar, -1,
            "NaN is not representable in JSON")
    }
    if f == 0 {
        return "0", nil    // Both +0 and -0 produce "0"
    }
    if math.IsInf(f, 0) {
        return "", jcserr.New(jcserr.InvalidGrammar, -1,
            "Infinity is not representable in JSON")
    }
    // ... proceed with Burger-Dybvig
}

NaN and Infinity are errors — JSON has no representation for them. Negative zero is normalized to "0" because IEEE 754's -0 and +0 are mathematically equal, and canonical JSON should not distinguish them. (Note: lexical -0 in JSON input is a separate concern, rejected at parse time as a policy violation — the two requirements are independent.)

Validation: 286,362 Oracle Vectors

The implementation is validated against two pinned oracle datasets:

golden_vectors.csv: 54,445 test vectors covering boundary values, powers of 10, subnormals, and edge cases
golden_stress_vectors.csv: 231,917 stress test vectors targeting tie-breaking and carry propagation scenarios

Each CSV row contains a 16-character hex encoding of the IEEE 754 bits and the expected output string:

0000000000000000,0
0000000000000001,5e-324
3ff0000000000000,1
3eb0c6f7a0b5ed8d,0.000001

The test function validates three properties per dataset:

Semantic correctness: FormatDouble(bits) == expected for every row
Cardinality: The exact row count matches expectations (catches truncation)
Integrity: SHA-256 of the entire file matches a pinned hash (catches corruption)

func TestGoldenOracle(t *testing.T) {
    verifyOracle(t, "testdata/golden_vectors.csv", 54445,
        "593bdecbe0dccbc182bc3baf570b716887db25739fc61b7808764ecb966d5636")
}

func TestStressOracle(t *testing.T) {
    verifyOracle(t, "testdata/golden_stress_vectors.csv", 231917,
        "287d21ac87e5665550f1baf86038302a0afc67a74a020dffb872f1a93b26d410")
}

The SHA-256 checksums pin the test data against silent modification. If someone edits a single byte in either file, the test fails.

Round-Trip and Fuzz Testing

Beyond oracle vectors, the implementation uses two additional validation strategies.

Round-trip testing verifies the shortest representation property directly: format a value, parse it back with strconv.ParseFloat, and confirm the original bits are recovered:

cases := []float64{5e-324, 1e-7, 1e-6, 0.1, 0.2, 1.1, 1, 2, 1e20, 1e21, math.MaxFloat64}
for _, c := range cases {
    formatted, _ := jcsfloat.FormatDouble(c)
    parsed, _ := strconv.ParseFloat(formatted, 64)
    if parsed != c {
        t.Fatalf("round-trip failed for %.17g: formatted %q, parsed back as %.17g",
            c, formatted, parsed)
    }
}

Fuzz testing generates random 64-bit patterns, interprets them as IEEE 754 doubles, and verifies round-trip stability:

func FuzzFormatDoubleRoundTrip(f *testing.F) {
    f.Fuzz(func(t *testing.T, data []byte) {
        if len(data) < 8 { return }
        bits := binary.BigEndian.Uint64(data[:8])
        fval := math.Float64frombits(bits)

        if math.IsNaN(fval) || math.IsInf(fval, 0) {
            _, err := jcsfloat.FormatDouble(fval)
            if err == nil { t.Fatal("expected error for non-finite") }
            return
        }

        s, err := jcsfloat.FormatDouble(fval)
        if err != nil { t.Fatalf("unexpected error: %v", err) }

        parsed, _ := strconv.ParseFloat(s, 64)
        if fval == 0 {
            if parsed != 0 { t.Fatal("zero round-trip failed") }
            return
        }
        if math.Float64bits(parsed) != math.Float64bits(fval) {
            t.Fatalf("round-trip failed: bits=%016x → %q → bits=%016x",
                bits, s, math.Float64bits(parsed))
        }
    })
}

Note the special case for zero: IEEE 754 -0 formats as "0", which parses back as +0. The bit patterns differ (0x8000000000000000 vs 0x0000000000000000), but mathematically the values are equal, so the round-trip comparison uses == 0 instead of bit equality.

Idempotency testing verifies that format → parse → format produces the same string, which is a consequence of correct tie-breaking:

for i := uint64(1); i < 5000; i += 97 {
    v := math.Float64frombits(i * 0x9e3779b97f4a7c15)
    if math.IsNaN(v) || math.IsInf(v, 0) { continue }

    f1, _ := jcsfloat.FormatDouble(v)
    parsed, _ := strconv.ParseFloat(f1, 64)
    f2, _ := jcsfloat.FormatDouble(parsed)

    if f1 != f2 {
        t.Fatalf("idempotency failed for bits=%016x: %s != %s",
            math.Float64bits(v), f1, f2)
    }
}

If tie-breaking were inconsistent, formatting a value at the exact midpoint could oscillate between two representations. Even-digit tie-breaking prevents this by always choosing the same direction at midpoints.

The Complete Pipeline

Putting it all together, the conversion from IEEE 754 bits to canonical decimal string follows this path:

Decode the 64-bit pattern into mantissa, exponent, and boundary flags
Initialize R, S, M+, M- as big integers with appropriate scaling
Estimate the decimal exponent k using floating-point logarithms
Scale by 10^k using pre-computed powers from the 700-entry cache
Fix up the scaling if the estimate was off by one (high or low)
Extract digits one at a time by multiplying by 10 and dividing
Terminate when boundary conditions indicate the shortest representation
Tie-break using even-digit preference when at the exact midpoint
Propagate carries if rounding up causes overflow
Format using the appropriate ECMA-262 branch based on the exponent

The entire implementation is 490 lines of Go with zero external dependencies (only math, math/big, and the project's own error package). It is deterministic, locale-independent, and produces identical output regardless of platform or Go runtime version.

The implementation lives in the jcsfloat package of json-canon, an RFC 8785 JSON canonicalization library.

json-canon: A Strict RFC 8785 Implementation in Go for Deterministic JSON

Mark Lenhardt — Fri, 27 Feb 2026 12:28:01 +0000

JSON is not deterministic. Object key order, number formatting, and whitespace vary across serializers, languages, and runtime versions. For most applications this doesn’t matter. For systems that sign, hash, or compare JSON by its raw bytes, it is a correctness failure.

RFC 8785 — the JSON Canonicalization Scheme (JCS) — defines a canonical form that eliminates this nondeterminism. It specifies lexicographic key sorting, ECMAScript-compatible number serialization, and I-JSON constraints to produce byte-identical output for logically equivalent data.

json-canon is an infrastructure-grade RFC 8785 implementation in pure Go. v0.2.0 was released on February 27, 2026. This post explains why it was built, the engineering decisions behind it, and who it is for.

The problem in practice

Consider two services that independently serialize the same data structure. One produces {"amount":1e2} and the other produces {"amount":100}. Both are valid JSON representing the same value. If either system signs or hashes the serialized bytes, the signatures will not match.

This class of problem appears wherever JSON participates in cryptographic operations: digital signatures over API payloads, content-addressed storage, deduplication pipelines, audit trail verification, and determinism proofs in replay systems. The root cause is always the same — JSON serializers do not guarantee a single byte representation for a given logical value.

RFC 8785 solves this by defining a canonical form. But an RFC is a specification, not an implementation. The implementation details matter.

Why another implementation

Existing JCS implementations generally fall into one of two categories: thin wrappers around a language’s built-in JSON serializer, or lenient parsers that accept malformed input and normalize it into canonical form.

Both approaches create problems for infrastructure use. A wrapper inherits the serialization behavior of whatever JSON library version is installed — behavior that can change between releases. A lenient parser that silently accepts malformed JSON means two systems may canonicalize the same malformed input differently, producing different outputs with no error reported.

json-canon takes a different approach. It owns every byte of its output through a hand-written strict parser and an ECMA-262-compatible number formatter implemented from scratch. It has zero external dependencies in go.mod. This eliminates the risk of formatting drift from upstream library changes.

The parser rejects invalid input immediately and never produces partial output. If the input is not well-formed JSON, the operation fails with a classified error. This is a deliberate design choice: a canonicalizer that accepts invalid input is a normalizer, and normalizers do not provide the determinism guarantees that signing and hashing pipelines require.

Failure taxonomy

Every rejection is classified into one of eleven stable failure classes: INVALID_UTF8, INVALID_GRAMMAR, DUPLICATE_KEY, LONE_SURROGATE, NONCHARACTER, NUMBER_OVERFLOW, NUMBER_NEGZERO, NUMBER_UNDERFLOW, BOUND_EXCEEDED, NOT_CANONICAL, and CLI_USAGE. Each failure class maps to a documented exit code. Errors include the failure class, byte offset, and a diagnostic message.

This matters for pipeline integration. When a canonicalization step fails in a CI/CD pipeline or an audit system, operators need to know what failed and where — not just that something went wrong. Stable failure classes also allow downstream systems to branch on error type without parsing human-readable error messages.

Resource bounds

Seven configurable limits are enforced at parse time: nesting depth (default 1,000), input size (64 MiB), total values (1M), object members (250K), array elements (250K), string bytes (8 MiB), and number token length (4,096). All bound violations classify as BOUND_EXCEEDED.

These defaults are tuned for typical infrastructure workloads. They can be adjusted via the Go API. The purpose is DoS resilience — untrusted input should not be able to cause unbounded resource consumption in a canonicalization step.

Conformance evidence

Unit tests prove local behavior. json-canon goes further.

76 traced requirements map from RFC clauses to requirement IDs to implementation symbols to tests. The conformance harness validates bidirectional coverage: no requirement exists without a test, and no test exists without a requirement. This traceability is the mechanism for substantiating the claim that the implementation conforms to RFC 8785 — not as an assertion, but as auditable evidence.

Additionally, over 286,000 oracle vectors validate the ECMA-262 number formatting logic against an independent reference implementation. Number formatting is the most error-prone part of any JCS implementation because IEEE 754 double-precision semantics and the ECMAScript Number::toString algorithm have subtle edge cases around exponent boundaries, negative zero, and precision limits.

An offline cold-replay framework validates behavioral stability across Linux distributions, kernel versions, and CPU architectures (x86_64 and arm64). Evidence bundles bind source identity, binary checksums, and matrix/profile digests. Release gating requires validated evidence from both architectures before publication.

Stable CLI ABI

json-canon ships a CLI tool (jcs-canon) with a versioned ABI under SemVer. Commands, flags, exit codes, failure class semantics, and stream contracts are defined in a machine-readable manifest. Breaking changes require a major version bump.

This is relevant for teams that embed jcs-canon in shell scripts, CI pipelines, or Makefiles. A canonicalization tool that changes its exit code semantics or output format between minor releases breaks every downstream consumer.

# Canonicalize
echo '{"b":2,"a":1}' | jcs-canon canonicalize -
# {"a":1,"b":2}

# Verify canonical form
jcs-canon verify document.json
# exit 0 if canonical, exit 2 if not

Go library usage

import (
    "github.com/lattice-substrate/json-canon/jcs"
    "github.com/lattice-substrate/json-canon/jcstoken"
)

v, err := jcstoken.Parse([]byte(`{"b":2,"a":1}`))
if err != nil {
    log.Fatal(err) // classified error with stable failure class
}
out, _ := jcs.Serialize(v)
// {"a":1,"b":2}

Install: go get github.com/lattice-substrate/json-canon

Supply-chain integrity

Release binaries are static Linux builds (CGO_ENABLED=0). Artifacts include SHA-256 checksums and SLSA build provenance attestation via GitHub Actions. All CI and release workflow actions are pinned by commit SHA.

Who should use this

json-canon is designed for a specific set of use cases:

Signing or hashing JSON documents where signatures must verify across languages, services, and time.
Content-addressable storage where identical logical content must produce identical hashes.
Audit and replay pipelines where byte drift between runs is a correctness failure.
Pipeline validation gates where untrusted JSON input requires strict rejection with stable, machine-readable exit codes.

Who should not use this

If you need pretty-printing or human-readable formatting, use jq.
If you need lenient parsing of malformed JSON, this tool will reject it by design.
If you need macOS or Windows support, the supported runtime is Linux only.
If you need a general-purpose JSON transformation toolkit, this is a canonicalization primitive, not a query engine.

What Your JSON Parser Doesn’t Reject: Building a Strict RFC 8259 Parser in Go

Mark Lenhardt — Thu, 26 Feb 2026 00:00:00 +0000

Most JSON parsers are lenient by design. They accept input that RFC 8259 forbids, because lenient parsing is convenient and rarely causes visible problems. But when your downstream depends on deterministic processing (canonical signatures, content-addressed storage, reproducible builds), leniency is a defect. A value silently accepted by one parser and rejected by another breaks your contract.

I built a strict JSON parser in Go. It enforces every constraint in RFC 8259 and adds the RFC 7493 (I-JSON) restrictions that RFC 8785 requires. This article walks through the design and implementation, focusing on the parts where strictness requires real work: surrogate pairs, noncharacter detection, duplicate keys after escape decoding, and resource bounds.

The Gap: What Canonicalization Cannot Accept

Go’s encoding/json is a solid general-purpose parser. For canonicalization, some of its documented behaviors are intentionally too permissive. On Go 1.25.6, representative examples look like this:

Input	`encoding/json` result	Strict parser	Source	Why it matters
`"\uD800\u0041"`	Decodes as `"�A"` (invalid surrogate replaced)	Rejected: lone surrogate	RFC 7493 §2.1	I-JSON forbids surrogates
`"\uFDD0"`	Accepts noncharacter	Rejected: noncharacter	RFC 7493 §2.1	I-JSON forbids noncharacters
`{"a":1,"a":2}`	Later key wins (`a=2`)	Rejected: duplicate key	RFC 7493 §2.3	I-JSON requires unique names
raw bytes `22 ff 22`	Decodes as `"�"`	Rejected: invalid UTF-8	project policy	silent byte substitution changes meaning
`-0`	Accepts lexical `-0`	Rejected: negative zero token	project policy	lexical ambiguity at acceptance boundary
`1e-400`	Parses to `0` with `err == nil` (Go 1.25.6)	Rejected: underflow	project policy	non-zero token collapses to zero

Rows labeled RFC 7493 are normative I-JSON requirements. Rows labeled project policy are stricter acceptance rules chosen to keep canonicalization fail-closed and deterministic.

These are not bugs in encoding/json; they are compatibility choices. The Go package documentation for Unmarshal explicitly states that invalid UTF-8 / invalid UTF-16 surrogates are replaced by U+FFFD, and duplicate object keys are processed in order with later values replacing earlier ones.

Minimal reproduction (Go 1.25.6), with explicit error checks:

var v any
err := json.Unmarshal([]byte(`"\uD800\u0041"`), &v)
fmt.Printf("case surrogate err=%v v=%#v\n", err, v) // err=<nil>, v="�A"

err = json.Unmarshal([]byte(`{"a":1,"a":2}`), &v)
fmt.Printf("case dup-key err=%v v=%#v\n", err, v) // err=<nil>, later duplicate replaces earlier value

err = json.Unmarshal([]byte("1e-400"), &v)
fmt.Printf("case underflow err=%v v=%#v\n", err, v) // err=<nil>, v=0

For application code, replacement and merge behavior is pragmatic. A canonicalization engine has a different contract: reject ambiguous or lossy inputs so every accepted value has a single deterministic canonical form. If two parsers disagree on interpretation, canonical output is undefined. Rejection is the safe outcome.

Parser Architecture

The parser uses single-pass recursive descent with byte-level dispatch. The core structure is a parser struct that holds the input bytes, a cursor position, depth tracking, and configurable bounds:

type parser struct {
    data []byte
    pos int
    depth int
    valueCount int
    maxDepth int
    maxValues int
    maxObjectMembers int
    maxArrayElements int
    maxStringBytes int
    maxNumberChars int
}

Value dispatch is a single switch on the first byte:

func (p *parser) parseValue() (*Value, error) {
    p.valueCount++
    if p.valueCount > p.maxValues {
        return nil, p.newErrorf(jcserr.BoundExceeded,
            "value count %d exceeds maximum %d", p.valueCount, p.maxValues)
    }

    c, ok := p.peek()
    if !ok {
        return nil, p.newError("unexpected end of input")
    }

    switch c {
    case '{': return p.parseObject()
    case '[': return p.parseArray()
    case '"': return p.parseString()
    case 't', 'f': return p.parseBool()
    case 'n': return p.parseNull()
    default: return p.parseNumber()
    }
}

No lookahead beyond the first byte is needed for type discrimination. Every call to parseValue checks the bound counter first.

UTF-8 Validation: Upfront and Incremental

The parser validates UTF-8 twice, for different reasons.

Upfront bulk validation runs before any parsing begins:

if !utf8.Valid(data) {
    return nil, jcserr.New(jcserr.InvalidUTF8, firstInvalidUTF8Offset(data),
        "input is not valid UTF-8")
}

This catches structural UTF-8 violations: continuation bytes without start bytes, truncated multibyte sequences, overlong encodings, and raw UTF-8 encodings of surrogate code points. The firstInvalidUTF8Offset function locates the exact byte offset of the first violation by scanning rune-by-rune until utf8.DecodeRune returns a replacement character:

func firstInvalidUTF8Offset(data []byte) int {
    for i := 0; i < len(data); {
        _, size := utf8.DecodeRune(data[i:])
        if size == 1 && data[i] >= 0x80 {
            return i
        }
        i += size
    }
    return 0
}

Incremental validation happens during string parsing. After verifying the input is well-formed UTF-8, the string parser still decodes each rune individually to validate semantic constraints: noncharacter rejection and surrogate detection that apply to decoded values, not raw bytes.

Why both? The upfront check is fast (Go’s utf8.Valid is optimized) and gives clear error reporting for malformed input before the parser’s position tracking complicates offset calculation. The incremental check applies rules that operate on decoded code points, not byte patterns.

Number Grammar: Four Layers of Enforcement

RFC 8259 §6 defines a specific number grammar. The parser enforces it in four phases.

Leading Zero Rejection

func (p *parser) scanZeroIntegerPart() *jcserr.Error {
    p.pos++
    if p.pos < len(p.data) && isDigit(p.data[p.pos]) {
        return p.newError("leading zero in number")
    }
    return nil
}

01, 007, 00.5: all rejected. A zero integer part must be exactly 0, followed by a non-digit (or end of number). RFC 8259 §6 specifies: “Leading zeros are not allowed.”

Missing Fraction Digits

func (p *parser) scanFractionPart(numStart int) *jcserr.Error {
    if p.pos >= len(p.data) || p.data[p.pos] != '.' {
        return nil
    }
    p.pos++

    if p.pos >= len(p.data) || !isDigit(p.data[p.pos]) {
        return p.newError("expected digit after decimal point")
    }
    // ... scan remaining digits
}

1. and 1.e5 are rejected; the grammar requires at least one digit after the decimal point.

Lexical Negative Zero

This is a project policy enforcement, not a grammar rule. The value -0 is mathematically zero, but the lexical token -0 is ambiguous:

// PROF-NEGZ-001: lexical negative zero
if strings.HasPrefix(raw, "-") && tokenRepresentsZero(raw) {
    return nil, jcserr.New(jcserr.NumberNegZero, start,
        "negative zero token is not allowed")
}

This rejects -0, -0.0, -0e0, -0.0e+0, and every other way to spell negative zero in JSON number syntax. The tokenRepresentsZero function checks whether the mantissa portion of the number token contains any non-zero digit, ignoring the exponent entirely.

Note: this is a different requirement from serialization. At serialization time, the IEEE 754 bit pattern for -0 outputs as "0". At parse time, the lexical token -0 is rejected. The two requirements are independent: one governs input, the other governs output.

Overflow and Underflow

After grammar validation, the number string is parsed with strconv.ParseFloat:

f, err := strconv.ParseFloat(raw, 64)

// Overflow: value exceeds IEEE 754 range
if math.IsNaN(f) || math.IsInf(f, 0) {
    return nil, jcserr.New(jcserr.NumberOverflow, start,
        "number overflows IEEE 754 double")
}

// Underflow: non-zero token rounds to zero
if f == 0 && !tokenRepresentsZero(raw) {
    return nil, jcserr.New(jcserr.NumberUnderflow, start,
        "non-zero number underflows to IEEE 754 zero")
}

1e999999 overflows to infinity; rejected. 1e-400 is a non-zero number that underflows to zero in IEEE 754; also rejected. The underflow check uses the same tokenRepresentsZero function: if the token has non-zero digits but ParseFloat returns zero, the precision was lost.

String Parsing: Two Paths

The string parser is a linear scan with two code paths: escape sequences and raw UTF-8 bytes.

func (p *parser) parseString() (*Value, error) {
    if err := p.expect('"'); err != nil {
        return nil, err
    }

    var buf []byte
    for {
        if p.pos >= len(p.data) {
            return nil, p.newError("unterminated string")
        }
        b := p.data[p.pos]
        if b == '"' {
            p.pos++
            return &Value{Kind: KindString, Str: string(buf)}, nil
        }
        if b == '\\' {
            // Escape sequence path
            escapeStart := p.pos
            p.pos++
            r, err := p.parseEscape(escapeStart)
            if err != nil { return nil, err }
            if err := validateStringRune(r, escapeStart); err != nil { return nil, err }
            var tmp [4]byte
            n := utf8.EncodeRune(tmp[:], r)
            buf = append(buf, tmp[:n]...)
            continue
        }
        if b < 0x20 {
            // PARSE-GRAM-004: reject unescaped control characters
            return nil, p.newErrorf(jcserr.InvalidGrammar,
                "unescaped control character 0x%02X in string", b)
        }
        // Raw UTF-8 path
        sourceOffset := p.pos
        r, size := utf8.DecodeRune(p.data[p.pos:])
        if err := validateStringRune(r, sourceOffset); err != nil { return nil, err }
        buf = append(buf, p.data[p.pos:p.pos+size]...)
        p.pos += size
    }
}

Both paths call validateStringRune to check for noncharacters and surrogates. The escape path first decodes the escape to a rune, then validates the decoded value. The raw path decodes the rune from UTF-8 bytes, then validates. The decoded results are identical: \u0041 and A both produce rune 0x41. This is critical for duplicate key detection later.

The escape dispatch is a straightforward table:

func escapedRune(b byte) (rune, bool) {
    switch b {
    case '"': return '"', true
    case '\\': return '\\', true
    case '/': return '/', true
    case 'b': return '\b', true
    case 'f': return '\f', true
    case 'n': return '\n', true
    case 'r': return '\r', true
    case 't': return '\t', true
    default: return 0, false
    }
}

RFC 8259 §7 defines exactly these eight simple escapes plus \uXXXX. Anything else (\x41, \U0041, \a) is rejected with InvalidGrammar.

Control characters below U+0020 that appear unescaped are also rejected per §7: “All Unicode characters may be placed within the quotation marks, except for the characters that MUST be escaped: quotation mark, reverse solidus, and the control characters (U+0000 through U+001F).”

Surrogate Pairs: 2-Character Lookahead

UTF-16 surrogate pairs in JSON appear as \uD800\uDC00: two consecutive \uXXXX escapes where the first is a high surrogate (U+D800-U+DBFF) and the second is a low surrogate (U+DC00-U+DFFF). Together they encode a supplementary-plane character (U+10000 and above).

The parser must handle five cases:

Not a surrogate : Return the rune as-is
Lone low surrogate (U+DC00-U+DFFF appearing first): Error
High surrogate with no following \u : Error
High surrogate followed by non-low-surrogate : Error
Valid pair : Decode to supplementary-plane scalar

func (p *parser) parseUnicodeEscape(sourceOffset int) (rune, *jcserr.Error) {
    r1, err := p.readHex4(sourceOffset)
    if err != nil {
        return 0, err
    }

    if !utf16.IsSurrogate(r1) {
        return r1, nil // Case 1: not a surrogate
    }

    if r1 >= 0xDC00 {
        return 0, jcserr.New(jcserr.LoneSurrogate, // Case 2: lone low surrogate
            sourceOffset, fmt.Sprintf("lone low surrogate U+%04X", r1))
    }

    // Case 3: high surrogate must be followed by \uXXXX
    if p.pos+1 >= len(p.data) || p.data[p.pos] != '\\' || p.data[p.pos+1] != 'u' {
        return 0, jcserr.New(jcserr.LoneSurrogate, sourceOffset,
            fmt.Sprintf("lone high surrogate U+%04X (no following \\u)", r1))
    }
    secondEscapeOffset := p.pos
    p.pos += 2 // Skip past '\u'

    r2, err := p.readHex4(secondEscapeOffset)
    if err != nil {
        return 0, err
    }
    if r2 < 0xDC00 || r2 > 0xDFFF {
        return 0, jcserr.New(jcserr.LoneSurrogate, // Case 4: not a low surrogate
            secondEscapeOffset,
            fmt.Sprintf("high surrogate U+%04X followed by non-low-surrogate U+%04X", r1, r2))
    }

    // Case 5: valid pair
    decoded := utf16.DecodeRune(r1, r2)
    if decoded == unicode.ReplacementChar {
        return 0, jcserr.New(jcserr.LoneSurrogate, sourceOffset,
            fmt.Sprintf("invalid surrogate pair U+%04X U+%04X", r1, r2))
    }
    return decoded, nil
}

The 2-character lookahead checks for \u without consuming input. This is the only lookahead in the parser beyond single-byte dispatch. If the two bytes aren’t \u, the high surrogate is lone and the error points to the first escape’s offset. If the second escape exists but decodes to a non-low surrogate (like \uD800\u0041), the error points to the second escape’s offset, because that’s where the violation occurs.

Compare with encoding/json: it replaces lone surrogates with U+FFFD (documented behavior in the Unmarshal docs). This is convenient for display pipelines, but it silently changes semantic content. A canonicalization engine cannot do this. Changing input bytes means the canonical output no longer represents the original data.

Noncharacter Rejection: 66 Forbidden Code Points

RFC 7493 §2.1 forbids Unicode noncharacters in I-JSON text. There are exactly 66:

32 in the range U+FDD0 to U+FDEF
34 at U+xFFFE and U+xFFFF for each of the 17 Unicode planes (0-16)

The implementation uses a compact two-branch check:

func IsNoncharacter(r rune) bool {
    if r >= 0xFDD0 && r <= 0xFDEF {
        return true
    }
    if r&0xFFFE == 0xFFFE && r <= 0x10FFFF {
        return true
    }
    return false
}

The bitwise trick on the second branch is worth explaining. The mask r & 0xFFFE zeros the lowest bit, so both U+xFFFE and U+xFFFF match the pattern 0xFFFE. The bound r <= 0x10FFFF limits this to planes 0 through 16. This catches U+FFFE, U+FFFF, U+1FFFE, U+1FFFF, all the way up to U+10FFFE and U+10FFFF, for 2 per plane times 17 planes = 34 code points.

The validation runs on decoded runes, not raw bytes. This matters because supplementary-plane noncharacters like U+1FFFE can appear as either raw UTF-8 bytes or as surrogate pair escapes (\uD83F\uDFFE). Both paths decode to the same rune and hit the same check.

Duplicate Key Detection: After Escape Decoding

RFC 7493 §2.3 requires that JSON objects not contain duplicate member names. The subtle requirement is that "\u0061" and "a" are the same key; both decode to the string “a”.

The parser handles this by comparing decoded strings, not raw lexemes:

func (p *parser) parseObject() (*Value, error) {
    // ...
    v := &Value{Kind: KindObject}
    seen := make(map[string]int)

    for {
        keyStart := p.pos

        keyVal, err := p.parseString() // Decodes all escapes
        if err != nil { return nil, err }
        key := keyVal.Str // Decoded Unicode string

        if firstOff, exists := seen[key]; exists {
            return nil, jcserr.New(jcserr.DuplicateKey, keyStart,
                fmt.Sprintf("duplicate object key %q (first at byte %d)", key, firstOff))
        }
        seen[key] = keyStart

        // ... parse colon and value
    }
}

The seen map uses the decoded string as the key. When the parser encounters "\u0061", it decodes the escape to produce “a”, and the map lookup finds a match with a previously seen raw "a". The error message includes the byte offset of both occurrences, enabling precise diagnostics.

This is a design choice that some parsers skip entirely (encoding/json processes duplicate keys in input order, with later values replacing or merging earlier ones) or implement on raw bytes (which misses escape-decoded equivalence). For canonicalization, decoded comparison is the only correct approach, because canonical output normalizes escape sequences.

Resource Bounds: Seven Independent Limits

The parser enforces seven configurable bounds, each checked at a different point in the parse:

Bound	Default	Checked At
Input size	64 MB	Before parsing begins
Nesting depth	1,000	On each `{` or `[`
Total values	1,000,000	On each `parseValue` call
Object members	250,000	Before adding each member
Array elements	250,000	Before adding each element
String bytes	8 MB	During string decode (per-string)
Number chars	4,096	During number scan (per-token)

All bounds are fail-fast: the parser stops at the first violation rather than continuing to consume input. The number character bound is checked during digit scanning, not just after:

func (p *parser) scanNonZeroIntegerDigits(numStart int) *jcserr.Error {
    for p.pos < len(p.data) && isDigit(p.data[p.pos]) {
        p.pos++
        if p.pos-numStart > p.maxNumberChars {
            return jcserr.New(jcserr.BoundExceeded, numStart,
                fmt.Sprintf("number token length %d exceeds maximum %d",
                    p.pos-numStart, p.maxNumberChars))
        }
    }
    return nil
}

This prevents a 100 MB number token from being fully scanned before the bound check fires.

Every bound violation returns a BoundExceeded failure class, regardless of which bound was hit. This is a deliberate classification choice: the cause is “resource policy violation,” not “invalid grammar” or “I/O error.” Machines consuming the exit code can distinguish policy rejections from syntax errors.

Error Offset Tracking

Every parser error includes a byte offset pointing to the source position of the violation:

func (p *parser) newError(msg string) *jcserr.Error {
    return jcserr.New(jcserr.InvalidGrammar, p.pos, msg)
}

For most errors, the offset is the parser’s current position, the byte where parsing failed. But for escape sequences and surrogate pairs, the offset points to the start of the escape that caused the problem, not the byte where the violation was detected:

if b == '\\' {
    escapeStart := p.pos // Record position of the backslash
    p.pos++
    r, err := p.parseEscape(escapeStart) // Pass source position
    // ...
}

For a lone high surrogate in "\uD800", the offset is 1 (the backslash). For a high surrogate followed by a non-low surrogate in "\uD800\u0041", the offset is 7 (the second backslash). This matters for tooling: an editor or diagnostic tool can highlight the exact source token that caused the rejection.

The offset semantics are stable across the failure taxonomy. Parse errors always report byte positions in the original input. CLI errors use offset -1 (not applicable). Bound violations report the start of the bounded element (e.g., the first byte of a too-long number token).

What Strictness Buys You

A lenient parser makes these implicit decisions:

“Leading zeros are fine” → Different parsers may interpret 012 as octal 10 or decimal 12
“Lone surrogates get replaced” → The canonical output of \uD800 is undefined
“Duplicate keys use last value” → Or first value, depending on implementation
“Trailing content is ignored” → {"a":1}extra silently becomes {"a":1}

A strict parser converts these implicit decisions into explicit rejections. The downstream consumer never has to wonder whether the input was ambiguous. If it parsed, it has exactly one interpretation. If it didn’t parse, the failure class and byte offset tell the consumer exactly what went wrong and where.

For infrastructure that depends on deterministic processing, this is the difference between “it works in my tests” and “it works because ambiguous input is structurally excluded.”

Strictness as Error Budget

There’s a useful way to think about parser strictness: it’s an error budget. A lenient parser spends its error budget on user convenience, accepting malformed input so users don’t have to fix their data. A strict parser spends its error budget on correctness guarantees, ensuring every accepted input has exactly one interpretation.

Neither is wrong. They serve different purposes. But when you build infrastructure that sits between systems, processing input from one machine and producing output consumed by another, spending the error budget on convenience is spending it on the wrong consumer. The machine downstream doesn’t benefit from leniency. It benefits from guarantees.

The parser code in the jcstoken package exists to provide one guarantee: if the parser returns a value, that value has a single, unambiguous, deterministic canonical representation. Every rejection (leading zeros, lone surrogates, duplicate keys, noncharacters, overflow, underflow, negative zero) eliminates a case where two consumers might disagree.

The implementation lives in the jcstoken package of json-canon, an RFC 8785 JSON canonicalization library. For callers who want a single parse-and-serialize call, jcs.Canonicalize(input) wraps this parser with the RFC 8785 serializer.

Revision History

Date	Change
2026-03-04	Corrected leading-zero quote attribution (RFC 8259, not ECMA-404 phrasing); fixed -0 policy attribution (project policy, not RFC 7493); removed stale source line reference; corrected bounds check timing (before add, not after)
2026-03-03	Removed line-count claims; added `jcs.Canonicalize` API reference
2026-02-26	Initial publication