Verificar seu JSON

O que o JSON realmente proíbe

A gramática do JSON é propositalmente mínima, e quase toda falha de validação é uma das poucas coisas que as pessoas trazem do JavaScript e que o JSON nunca adotou. Uma vírgula final depois do último elemento. Aspas simples em vez de duplas. Chaves sem aspas. Comentários — o JSON não tem, e nunca teve. NaN e Infinity, que são números válidos em JavaScript e não são JSON válido. E uma marca de ordem de bytes (BOM) no início, invisível em qualquer editor, que algumas ferramentas do Windows acrescentam ao salvar em UTF-8 e que faz um documento perfeitamente bom falhar no primeiro caractere.

Duas coisas são permitidas e ainda assim vão lhe dar trabalho, e é por isso que “válido” não é o mesmo que “correto”. Chaves duplicadas não são proibidas pela especificação — e cada parser as resolve de um jeito, a maioria ficando com a última, então um documento com uma chave repetida é validado aqui e significa coisas diferentes em linguagens diferentes. E os números não têm limite de precisão definido no JSON, enquanto a maioria dos parsers os lê como ponto flutuante: um inteiro acima de uns nove quatrilhões é arredondado sem aviso, e é por isso que identificadores grandes tantas vezes são transmitidos como strings.

O que você recebe é a linha, a coluna e o caractere exatos em que a interpretação parou, o que costuma ser mais útil do que a própria mensagem. Um parser informa o ponto em que o documento deixou de fazer sentido, não onde o erro foi cometido — uma chave de fechamento faltando é apontada no fim do arquivo, e uma vírgula faltando é apontada no token seguinte. Olhar logo antes da posição informada é o hábito que mais economiza tempo.

Bem formado não é o mesmo que correto, e a distinção importa. Isto confirma que a sintaxe é interpretada. Se o documento tem os campos que a sua API exige, se um valor está dentro do intervalo, se uma data é realmente uma data — nada disso é uma questão de JSON. Isso é validação de schema, exige um schema, e um documento pode estar impecável aqui e ser rejeitado imediatamente pelo serviço para o qual você o envia.

Quando você precisa de outra coisa

Para verificar documentos em relação a um schema em vez de uma gramática, o JSON Schema é o padrão e o ajv é a implementação mais rápida dele — ele informa que um campo obrigatório está faltando ou que um valor está fora do intervalo, que geralmente é a pergunta que você realmente tem. O check-jsonschema faz as mesmas verificações na linha de comando e em CI.

Para qualquer coisa na linha de comando, o jq é a ferramenta a ter: jq empty file.json valida e não imprime nada em caso de sucesso, exatamente o certo para um script, e jq . formata. Para arquivos grandes demais para caber na memória, jq --stream e o ijson do Python interpretam de forma incremental, o que nenhuma página que carrega o documento inteiro consegue fazer.