JSON Toolkit

NaN ou Infinity podem aparecer em JSON

Resumo: JSON tem apenas literais numéricos decimais. `JSON.stringify` transforma NaN e Infinity em null sem avisar, e é por isso que "o campo numérico às vezes é null" continua aparecendo em produção.

Iniciante~3 min de leituraPublicado em 2026-10-30Atualizado em 2026-10-30
O que realmente acontece com NaN e Infinity em JSON

Resumo da ópera: JSON não consegue representar NaN nem Infinity — JSON.stringify transforma ambos silenciosamente em null — então codifique o estado explicitamente com null mais um campo de motivo, ou um valor de string documentado.

JSON.stringify({ ratio: NaN, limit: Infinity });
// '{"ratio":null,"limit":null}'

Sem erro, sem aviso. Dois números viram null.

O que a gramática permite

number = [ minus ] int [ frac ] [ exp ]

Apenas decimais. NaN e Infinity são sentinelas IEEE 754, não literais. Escritos em JSON, são identificadores inválidos, e como a semântica de comparação deles difere entre linguagens, a especificação os exclui em vez de escolher uma representação.

O que cada linguagem faz em vez disso

Linguagem Comportamento
JSON.stringify do JavaScript Emite null silenciosamente
json.dumps do Python Emite NaN por padrão (não padrão); lança erro com allow_nan=False
encoding/json do Go Retorna unsupported value: NaN
Jackson do Java Emite a string "NaN" por padrão

Quatro comportamentos para um valor. Quando uma API entre linguagens mostra um campo numérico que é intermitentemente null, verifique esta camada primeiro.

O que fazer em vez disso

Strings documentadas. "NaN", "Infinity" com uma nota de tipo. Custa a todo consumidor uma verificação explícita.

null mais um campo de status. Melhor: {"avgLatency": null, "avgLatencyStatus": "no-sample"}. O motivo viaja junto com o valor.

Repense a unidade. A maioria dos resultados Infinity vem de dividir por zero amostras. Retornar null e renderizar "ainda sem dados" geralmente corresponde melhor à verdade do negócio do que um número infinito.

Armadilhas relacionadas

  • Bibliotecas de gráfico quebram a linha em null — confirme que é isso que você quer
  • JSON.stringify também descarta undefined, funções e símbolos por completo; essas chaves somem em vez de virar null
  • O allow_nan=True padrão do Python produz saída que JSON.parse rejeita

Leitura adicional