2026-09-05 · 8 min read
- json
- numbers
- api-design
JSON numbers use a finite decimal grammar. They do not include NaN, positive Infinity, or negative Infinity even though JavaScript, Python, Java, databases, scientific tools, and telemetry systems may represent one or more of those values in memory.
A serializer may reject the value, emit non-standard text, replace it with null, or stringify it. If producers and consumers make different choices, valid-looking payloads can lose the distinction between unavailable data, invalid calculations, overflow, and an intentionally unbounded range.
Detect non-finite values at the domain boundary
Validate calculation results before constructing the transport object. Trace division by zero, overflow, failed numeric conversion, empty aggregates, invalid sensor readings, and database-specific special values back to a domain outcome.
- Use finite-number checks rather than comparisons with NaN.
- Validate every numeric member inside arrays and nested objects.
- Keep negative zero behavior explicit where it affects the domain.
- Apply bounds separately from the finite-number requirement.
Choose a portable representation
For an optional measurement, null may be appropriate if the schema defines its meaning. For calculations with several failure states, pair the value with a status enum or use a tagged object. Omission can represent not supplied when that differs from explicitly unavailable.
Strings such as NaN and Infinity are safe JSON strings but only become useful when the contract enumerates them and consumers never coerce arbitrary strings into numbers. Avoid magic finite sentinels that can collide with legitimate values.
- Document one representation for every non-finite domain state.
- Reject undocumented strings and implicit coercion.
- Preserve the distinction between null and a missing member.
- Version the schema when changing an established representation.
Control serialization and storage
Configure serializers for strict JSON and fail close to the calculation that created an unsupported value. Validate the actual serialized document, because an in-memory schema check may run before a library transforms non-finite numbers.
Check database drivers, caches, queues, analytics SDKs, and logs. A store that accepts NaN does not guarantee that its JSON export, query language, ordering, or downstream connector preserves the same semantics.
Build cross-language fixtures
Use Flashman's JSON formatter to inspect standards-compliant wire documents, diff to compare serialized outputs, number base converter for bounded integer fixtures, case converter for status-field naming, and units converter for explicit measurement limits.
Test NaN, both infinities, negative zero, underflow and overflow, null, missing fields, tagged errors, mixed arrays, schema generation, database round trips, logging, and every supported producer and consumer runtime.