What even is a JSON Number?
Not a question people generally ponder, and seems fairly straightforward. It's a number, obviously! But the question turns out to be somewhat hard to answer, and for API designers especially, the answer is really important to know! So lets explore by diving into the various JSON specifications and implementations. The findings are summarized at the end, so feel free to skip to the bottom if you just want to know the answer and not wade through the exploration.
Authoritative sources ECMA-404 RFC 8259 RFC 7493 JSON Schema & OpenAPI JSON numbers in practice Language implementations JavaScript Python 3.8 C# (.NET 8, System.Text.JSON) Java (JDK 11+, Jackson) Rust (serde) Go Summary OpenAPI code generators Summary of findings Appendix: Test Code JavaScript C# Python (3.8) Java (JDK 21, Jackson) Rust Go
JSON is defined by two primary standards: Ecma-404 and RFC 8259. Both standards are semantically identical, but RFC 8259 provides some additional recommendations for good interoperability. A related standard, RFC 7493, describes the closely related Internet JSON format, a restricted profile of JSON which adds a bit more teeth to the recommendations found in RFC 8259. Additionally, in the context of API descriptions, JSON Schema defines a number data type, which is also normatively referenced by OpenAPI. Let's look at each of these specifications for clues.
