JSON number pitfalls: integers beyond 2^53, NaN and Infinity, and exact decimals

What it is

The JSON grammar (RFC 8259, cited) allows numbers of any size and precision but lets implementations set limits; it notes that IEEE 754 binary64 software is what a sender can generally expect, that integers within [-(2^53)+1, (2^53)-1] are interoperable in the sense that implementations agree exactly on their values, and that values the grammar cannot express, such as Infinity and NaN, are not permitted. I-JSON (RFC 7493, cited) turns this into rules for interoperable messages: do not send more magnitude or precision than a double provides, and encode larger or exact values, 64-bit integers for example, as strings, because JavaScript cannot treat an integer beyond 9007199254740991 as exact. The Python json documentation (cited) states that allow_nan defaults to true, so nan and inf are written as NaN and Infinity, which the specification does not allow. MDN (cited) states that JSON.stringify treats NaN and Infinity as null.

Why it matters

A 64-bit database identifier above 2^53 survives a Python round trip and silently loses its low digits in a browser. A notebook that writes NaN into a JSON file produces a document other parsers reject, while the same value passed through a browser becomes null and looks like a deliberate "missing". Money parsed into a binary double is no longer the decimal amount that was sent, and every arithmetic step on it rounds.

How to apply

• Document the numeric contract per field: integer with a range, decimal with a scale, or floating point; anything that may exceed 2^53 travels as a string.
• Serialise identifiers as strings from the first release; switching later is a breaking change for every client.
• Serialise exact decimals (money, readings with a fixed scale) as strings and parse them into a decimal type; the related article on Decimal explains why doubles are the wrong container.
• Reject non-finite values at the boundary: in Python pass allow_nan=False so serialisation raises instead of emitting NaN; in JavaScript check Number.isFinite before stringifying. Represent "missing" as null or an absent field deliberately.
• Validate with a schema that pins type, minimum and maximum, and a pattern for string-encoded numbers.

Pitfalls

-0 is a valid JSON number, but JavaScript's JSON.stringify(-0) yields "0". Exponent notation is legal for integers (1e2) and some parsers then type the value as floating point. JavaScript BigInt values throw in JSON.stringify unless a replacer or toJSON method converts them. RFC 8259 leaves duplicate member names undefined and I-JSON forbids them; parsers commonly keep the last one, which makes duplicate-key smuggling a validation concern.