Validar JSON

Um parser de JSON para assim que encontra algo que não encaixa, e esse ponto costuma ficar bem depois do erro de verdade. Uma vírgula que falta na linha 12 só é descoberta na 13, quando aparece uma aspa onde deveria haver uma vírgula; a mensagem aponta a 13.

Por isso aqui não sai só um número, e sim o trecho com o ponto marcado. Ver o contexto é o que transforma «coluna 4» em «falta a vírgula da linha de cima», e essa é a diferença entre corrigir em dez segundos e ficar encarando um documento de duzentas linhas.

O mesmo documento quebrado produz mensagens diferentes no Chrome, no Firefox e no Safari, porque cada motor de JavaScript escreve as suas. Alguns dão a posição como um deslocamento em caracteres, outros não dão posição nenhuma.

Aqui a linha e a coluna são calculadas a partir do deslocamento em vez de confiar no texto da mensagem. Assim a resposta é a mesma em qualquer navegador, que é o mínimo que se pode pedir de uma ferramenta cuja única função é dizer onde olhar.

Uma vírgula a mais antes de uma chave ou de um colchete de fechamento; uma vírgula faltando entre dois elementos; aspas simples no lugar de aspas duplas; e uma chave sem aspas. Esses quatro respondem pela imensa maioria dos documentos recusados, e todos vêm de escrever JSON como se fosse JavaScript.

O quinto é mais traiçoeiro: um caractere invisível no começo do documento, quase sempre a marca de ordem de bytes que o Excel e alguns editores do Windows colocam na frente de tudo. O documento parece perfeito e o parser falha na coluna 1, que é exatamente o lugar em que ninguém olha.

Um documento ser JSON válido significa que a sintaxe está certa, e nada mais. Um campo que deveria ser número e chega como string, uma data num formato que o outro lado não espera ou um objeto ao qual falta metade das chaves passam por esta verificação sem problema.

Se uma API continua recusando um documento que aqui aparece como válido, o problema já não é de sintaxe: é de esquema. Isso quem confere é um validador de JSON Schema contra o esquema daquela API específica, e é outra pergunta, que começa exatamente onde esta página termina.

Contar colunas com tabulações no meio é ambíguo: uma tabulação é um caractere, mas na tela ocupa quatro ou oito conforme a configuração do editor. Um número de coluna calculado sobre caracteres não bate, então, com o que se vê.

Aqui são contados caracteres, que é o que o parser faz, e o trecho é mostrado com as tabulações expandidas para que o ponto marcado caia onde o olho espera. É um detalhe minúsculo e é a diferença entre uma marcação que ajuda e uma que confunde.

Quando o documento passa, aparece também a forma dele: se o nível de cima é um objeto ou um array, quantas chaves tem, quanto ele aninha e que tamanho ocupa. São os dados que a gente olha antes de decidir como processar.

A profundidade de aninhamento é a mais útil das quatro. Muitos parsers e muitas APIs têm um limite, e um documento gerado automaticamente pode passar dele sem que ninguém tenha previsto. É um número que nunca se olha, até o dia em que ele explica um erro que não fazia sentido.

Se o documento contém um inteiro grande demais para se manter exato, isso é dito, mesmo que o documento seja perfeitamente válido. Não é erro de sintaxe: é uma perda silenciosa que acontece na leitura, e acontece igual em qualquer sistema que use um parser de JavaScript.

Merece aviso próprio porque é a falha que pior se diagnostica. O documento entra bem, sai bem, e no meio um identificador mudou nos últimos dígitos — e o sistema que o recebe não encontra o registro, sem nenhuma pista de por quê.

Muito log e muita exportação vêm em JSON Lines: um documento completo por linha, sem vírgula entre eles e sem colchetes em volta. Isso não é um JSON válido como um todo, e colar o arquivo inteiro aqui produz um erro logo depois do fim da primeira linha.

O erro está certo e a resposta é validar uma linha de cada vez. Reconhecer o formato economiza a busca por um problema de sintaxe que não existe: se o erro aparece exatamente na fronteira entre duas linhas que parecem completas, você não tem um documento quebrado, tem vários documentos inteiros.

Um campo vazio não é JSON válido, e nem uma string vazia é: o menor documento válido é um valor, como `null` ou `0`. Isso surpreende quem esperava que «nada» passasse, e é a razão de uma resposta de API de corpo vazio quebrar um cliente que chama o parser sem olhar antes.

Um documento cortado na transmissão dá outro sintoma: o erro aparece no fim do texto, não no meio. Se a linha e a coluna apontam para o último caractere que existe, o problema não está na sintaxe e sim no que ficou faltando — um download interrompido, um campo de banco com limite de tamanho, um log truncado.

Esta página responde uma pergunta e não duas: onde está falhando. Ver o documento indentado é o que a página de formatar faz, e ela ainda tem o seletor de indentação e a ordenação de chaves, que aqui não pintam.

É a mesma decisão que separa codificar de decodificar no resto da seção. Quem chega aqui está com algo quebrado e quer o lugar; quem chega lá está com algo ilegível e quer enxergar. Juntar daria uma página com metade sobrando para cada um dos dois.

Um documento colado de um chat, de um e-mail ou do Word chega com frequência com aspas curvas no lugar das retas. Na tela a diferença é quase invisível; para o parser não existe dúvida nenhuma, porque só a aspa reta delimita uma string em JSON.

O sintoma é um erro logo no começo de uma chave, com a coluna apontando para a primeira aspa. A correção é desligar a substituição automática de aspas na ferramenta que gerou o texto, ou colar em um editor de código antes. Vale conferir também o hífen: o mesmo mecanismo troca hífen por travessão, e isso estraga um valor sem estragar a sintaxe.

O documento que alguma coisa está recusando quase sempre é o documento de produção: um pedido, um cadastro de cliente, o corpo de um webhook com nome e endereço. Como a verificação acontece na página, nada disso é compartilhado conosco nem fica em log de requisição nosso.

É exatamente o caso que uma política interna quer impedir — colar dado pessoal num serviço de terceiro para depurar — e aqui ele não acontece, porque não há serviço de terceiro recebendo nada. O painel de rede mostra isso enquanto você usa.