Armadilhas dos números em JSON: inteiros acima de 2^53, NaN e Infinity, e decimais exatos

O que é

A gramática do JSON (RFC 8259, citada) admite números de qualquer tamanho e precisão, mas permite que as implementações definam limites. A RFC observa que um emissor pode, em geral, esperar software baseado em IEEE 754 binary64; que os inteiros no intervalo [-(2^53)+1, (2^53)-1] são interoperáveis, no sentido de que as implementações concordam exatamente sobre os seus valores; e que valores que a gramática não consegue expressar, como Infinity e NaN, não são permitidos. A I-JSON (RFC 7493, citada) transforma isso em regras para mensagens interoperáveis: não enviar mais magnitude nem precisão do que um double oferece e codificar como strings valores maiores ou exatos, por exemplo inteiros de 64 bits, porque o JavaScript não consegue tratar como exato um inteiro acima de 9007199254740991. A documentação do módulo json do Python (citada) afirma que allow_nan é verdadeiro por padrão, de modo que nan e inf são escritos como NaN e Infinity, o que a especificação não permite. A MDN (citada) afirma que JSON.stringify trata NaN e Infinity como null.

Por que importa

Um identificador de banco de dados de 64 bits acima de 2^53 sobrevive a uma ida e volta em Python, mas perde silenciosamente os dígitos menos significativos em um navegador. Um notebook que grava NaN em um arquivo JSON produz um documento que outros parsers rejeitam, enquanto o mesmo valor, ao passar por um navegador, vira null e parece um "ausente" intencional. Dinheiro lido para um double binário já não é o valor decimal que foi enviado, e cada operação aritmética sobre ele arredonda.

Como aplicar

• Documente o contrato numérico de cada campo: inteiro com um intervalo, decimal com uma escala, ou ponto flutuante; tudo o que puder ultrapassar 2^53 trafega como string.
• Serialize identificadores como strings desde a primeira versão; mudar depois é uma quebra de compatibilidade para todos os clientes.
• Serialize decimais exatos (dinheiro, leituras com escala fixa) como strings e converta-os para um tipo decimal; o artigo relacionado sobre Decimal explica por que o double é o recipiente errado.
• Rejeite valores não finitos na fronteira: em Python, passe allow_nan=False para que a serialização lance um erro em vez de emitir NaN; em JavaScript, verifique com Number.isFinite antes de serializar. Represente "ausente" de forma deliberada, como null ou como campo omitido.
• Valide com um esquema que fixe type, minimum e maximum, além de um padrão (pattern) para números codificados como string.

Armadilhas

-0 é um número JSON válido, mas JSON.stringify(-0) em JavaScript produz "0". A notação exponencial é permitida para inteiros (1e2), e alguns parsers passam então a tipar o valor como ponto flutuante. Valores BigInt do JavaScript lançam erro em JSON.stringify, a menos que um replacer ou um método toJSON os converta. A RFC 8259 deixa indefinido o comportamento com nomes de membros duplicados e a I-JSON os proíbe; os parsers costumam manter o último, o que faz do contrabando por chaves duplicadas (duplicate-key smuggling) uma preocupação de validação.