Ferramentas para desenvolvedores · Formatador e validador JSON
Por que um arquivo de linhas JSON falha na validação na linha 2, coluna 1
· Como funciona
JSON fluxo de trabalho do desenvolvedor validação
Um arquivo .jsonl contém muitos documentos JSON, não um, portanto, um validador estrito para exatamente onde o segundo começa. Esta postagem explica as convenções JSON Lines e NDJSON e como validá-las um registro por vez.
Válido em todas as linhas, inválido como arquivo
Válido em todas as linhas, inválido como arquivo — a exportação que toda ferramenta downstream lê com satisfação, mas um validador rejeita na segunda linha. Um remetente de log pode consumir cada nova linha como um limite de registro, mas um analisador JSON estrito vê o arquivo inteiro como uma entrada. O primeiro objeto está completo JSON; a próxima chave de abertura é um segundo valor de raiz ilegal.
ToolAcre valida um texto JSON, não JSON linhas. Depois que o scanner conclui o primeiro valor raiz, qualquer caractere posterior que não seja espaço em branco será relatado como inesperado após o final do valor JSON. Ele não oferece validação ou conversão NDJSON por linha como um substituto oculto. Essa distinção evita que um resultado verde implique que todos os registros em um fluxo orientado a linha foram verificados.
Um texto, um valor — o que RFC 8259 define como um texto JSON e por que dois valores de nível superior consecutivos são um erro gramatical
Um texto, um valor — o que RFC 8259 define como um texto JSON e por que dois valores de nível superior seguidos são um erro gramatical. Um texto JSON é um valor serializado, portanto, um objeto, array, string, número, booleano ou nulo pode estar na raiz. Espaços em branco podem cercar esse valor, mas não podem separar várias raízes em um documento válido maior.
Por exemplo, `{"ok":true} {"ok":false}` contém dois objetos individualmente válidos, mas não é um texto JSON. A análise do primeiro objeto consome um valor completo; analisar a string inteira deve então rejeitar o segundo `{`. Para representar ambos os valores em JSON comum, coloque-os dentro de um array e adicione a vírgula necessária entre os elementos do array.
JSON Linhas e NDJSON
JSON Linhas e NDJSON — as convenções delimitadas por nova linha, por que existem para streaming e logs e como diferem de uma matriz JSON. Cada linha física carrega um valor JSON completo, normalmente um objeto, e a nova linha atua como um enquadramento fora da gramática JSON. Os produtores podem anexar registros e os consumidores podem processá-los de forma incremental sem carregar uma coleção completa.
Em vez disso, uma matriz possui um colchete de abertura, elementos separados por vírgula e um colchete de fechamento, tornando o arquivo inteiro um único valor JSON. É conveniente para APIs que retornam uma coleção limitada, mas estranho para um fluxo de eventos em crescimento indefinido. Um arquivo de linhas JSON truncado pode preservar todos os registros anteriores completos; uma matriz truncada geralmente deixa o valor envolvente inacabado.
Por que o erro está sempre na linha 2, coluna 1
Por que o erro está sempre na linha 2, coluna 1 — o analisador termina o primeiro valor, espera o fim da entrada e atende o primeiro caractere do segundo registro. A nova linha em si é um espaço em branco legal, portanto não aciona a falha. A chave de abertura do próximo registro é o primeiro token que contradiz o estado do documento concluído.
Essa localização é uma evidência diagnóstica e não uma afirmação de que o segundo objeto está malformado. Se o relatório apontar consistentemente para o primeiro caractere que não seja um espaço em branco após uma raiz válida, inspecione o formato do arquivo antes de editar a pontuação. Excluir a chave corromperia o registro; escolher um leitor com reconhecimento de linha ou converter os registros em uma matriz resolve a incompatibilidade real de enquadramento.
Exemplo resolvido: validando três registros de log
Exemplo resolvido: validação de três registros de log – verificando cada linha por conta própria em vez de agrupá-las em uma matriz com vírgulas. Suponha que as linhas contenham `{"level":"info"}`, `{"level":"warn"}` e `{"level":"error"}`. Um validador orientado a linhas analisa três entradas separadas e pode identificar o registro exato se houver uma aspa faltando ou uma vírgula final.
Para uma verificação rigorosa de todo o documento, transforme a amostra em `[{"level":"info"},{"level":"warn"},{"level":"error"}]`. Os colchetes estabelecem uma raiz e as vírgulas delimitam seus elementos. Não substitua apenas novas linhas por vírgulas: isso produz três raízes separadas por pontuação, a menos que a matriz circundante seja adicionada, e pode manipular incorretamente linhas em branco que a convenção de origem pode proibir ou ignorar.
Convertendo entre as duas formas
Convertendo entre as duas formas — quando uma matriz de empacotamento é apropriada e quando ela anularia o ponto de saída delimitado por linha. Uma exportação finita destinada a uma solicitação API, editor ou validador estrito pode muitas vezes se tornar um array. A conversão deve analisar cada registro primeiro, porque a concatenação textual não pode contabilizar com segurança caracteres de escape incorporados ou linhas inválidas.
Mantenha linhas JSON quando os registros chegarem continuamente, os arquivos forem anexados ou os consumidores precisarem de memória limitada e recuperação em nível de registro. A conversão de um fluxo de eventos de vários gigabytes em um array requer a retenção do estado do contêiner e atrasa uma análise completa até que o colchete de fechamento chegue. Na outra direção, serialize cada elemento da matriz de forma compacta em uma linha e defina se linhas vazias ou novas linhas finais são permitidas.
O que isso não cobre
O que isso não cobre - JSON concatenado sem novas linhas e enquadramento separador de registros (RFC 7464), que precisa de analisadores dedicados. Valores colocados diretamente juntos não podem ser divididos com segurança com uma simples operação de linha, especialmente quando as raízes podem ser números ou strings. RFC 7464 usa um caractere separador de registros ASCII para enquadrar sequências de texto JSON em vez de depender apenas de novas linhas visíveis.
Também não valida regras de aplicação compartilhadas por registros. A análise de cada linha não pode provar que os carimbos de data e hora estão ordenados, os identificadores são exclusivos ou todos os objetos usam o mesmo esquema. Essas verificações ocorrem após o enquadramento do registro e a análise de sintaxe. Da mesma forma, uma nova linha incorporada como a sequência de escape ` `dentro de uma string estão dados, não um limite físico, e um leitor de linha compatível deve preservar essa distinção.
Conclusão: saiba qual forma você está segurando
Conclusão: saiba qual forma você está segurando - e como a posição do validador informa instantaneamente que um arquivo é delimitado por linhas. Uma falha no primeiro token da linha dois após um valor completo da linha um indica fortemente vários registros em quadros, e não uma sintaxe quebrada no primeiro registro. Verifique a extensão, a documentação do produtor e o consumidor esperado antes de alterar os dados.
Use um analisador JSON Lines ou NDJSON para validar registros de forma independente quando a nova linha for intencional. Use uma matriz quando o destino exigir uma coleção JSON completa. ToolAcre rejeita corretamente o arquivo multi-root porque seu contrato é uma validação estrita de texto único; a rejeição protege esse contrato em vez de mostrar que JSON delimitado por nova linha é inerentemente defeituoso. Combine o validador com o formato do enquadramento.