Converter NDJSON para JSON

Um documento JSON é um valor só. Um arquivo NDJSON é uma sequência deles com quebras de linha no meio, e nenhuma boa vontade transforma isso num documento — um interpretador lê o primeiro objeto, chega na chave do segundo e para com um erro de token inesperado. Isso não é bug do interpretador, e é o motivo desta página existir.

A consequência aparece em lugares comuns. Um validador de esquema recusa o arquivo. Uma chamada de rede que espera JSON lança erro. Um carregador de configuração reporta um erro de sintaxe na linha 2 de um arquivo cuja linha 2 é JSON perfeitamente válido. Em todo caso a correção é a mesma linha de estrutura: colchetes ao redor de tudo e vírgulas entre os registros.

Toda linha vira um elemento de um array de nível superior, na ordem do arquivo, e isso vale mesmo quando a origem tem uma linha só — um arquivo de um registro produz um array de um elemento em vez de um objeto solto. A saída é indentada com dois espaços por nível e termina com uma quebra de linha.

Poder prever a forma importa mais do que parece. Significa que um script consumindo o resultado pode indexar sem checar o que voltou, e que o comprimento do array é o número de linhas não vazias da origem. Se sua origem é um arquivo de um objeto só e você queria o objeto em vez de uma lista de um, esse desembrulhar é uma etapa separada que esta conversão não faz por você.

A maioria das APIs não aceita um array solto. Elas aceitam um objeto com os registros sob um nome — `records`, `data`, `items` — e frequentemente com uma contagem ao lado. A conversão produz o array e para ali, porque inventar um nome de chave seria chutar um contrato que ela não consegue ver.

Adicionar isso depois é trivial e vale fazer deliberadamente em vez de à mão num editor, onde uma chave faltando no fim de um arquivo grande é fácil de errar e chato de achar. Confira o nome do campo contra a documentação da API antes de enviar qualquer coisa, já que um lote rejeitado geralmente só reporta que o corpo era inválido.

Esta é a direção segura para sair do NDJSON, e vale dizer isso claramente porque os destinos vizinhos não são assim. Enviar o mesmo arquivo para CSV, TSV, XLSX ou Parquet achata todo objeto aninhado em colunas pontuadas e reconcilia os registros contra um conjunto único de colunas. Aqui nada disso acontece: um registro com um objeto de usuário três níveis de profundidade chega com esse objeto três níveis de profundidade.

Tipos sobrevivem pelo mesmo motivo. Um número continua número, `true` continua booleano, `null` continua nulo, e uma string numérica continua entre aspas. Nada é inferido, porque nada precisa ser — a origem já era JSON e o destino é JSON. A ordem das chaves dentro de cada registro também é preservada.

Se qualquer linha falhar ao ser interpretada, nada é escrito. A mensagem identifica a linha: algo como "este arquivo não pôde ser lido como NDJSON — a linha 3 não é JSON válido". Nenhum documento parcial é produzido e nenhum registro é silenciosamente pulado.

Para este destino esse comportamento vale mais do que valeria numa planilha. Uma última linha truncada — a causa comum, de um processo interrompido no meio da escrita — de outra forma produziria um documento que interpreta, valida, e está faltando um número desconhecido de registros. Linhas vazias no final não são problema: são ignoradas.

A saída é formatada com indentação de dois espaços, então um registro que ocupava uma linha densa na origem ocupa uma linha por valor folha mais suas chaves. Um arquivo de registros planos com uma dúzia de campos cada um cresce, portanto, por um fator de aproximadamente uma dúzia de linhas.

Nada disso é dado, e comprime a quase nada na transmissão. Se o destino é uma pessoa ou uma comparação, a indentação é o ponto. Se o destino é um campo de upload com limite de tamanho, gere a forma compacta com uma ferramenta de linha de comando, ou reconsidere se a entrada realmente precisava de um documento — muitas que parecem precisar aceitam o NDJSON de bom grado se pedido.

As duas metades desta conversão são operações de valor inteiro. As linhas são interpretadas num array antes de qualquer coisa ser escrita, e o array é serializado numa passagem só, então o custo máximo é a origem mais a estrutura interpretada mais a string de saída. Nada flui em transmissão contínua, e nada poderia — um array não está pronto até seu último elemento estar.

O teto gratuito é 100 MB por arquivo e o teto prático é a aba. Dezenas de megabytes é tranquilo; algumas centenas de megabytes de registros é onde um navegador começa a sofrer, e é exatamente o tamanho em que transformar um fluxo num documento único deixa de ser boa ideia de qualquer forma. O NDJSON se divide com segurança em qualquer fronteira de linha.

Converter o resultado de volta na outra direção devolve o que você começou com. Um array JSON de nível superior é escrito um elemento por linha, então os registros, suas chaves, sua ordem e seus tipos voltam inalterados. Não há etapa com perda em nenhuma direção para acumular.

Isso torna o par útil como uma manobra de trabalho em vez de uma migração. Converta para JSON, rode o validador, corrija o que ele reclamar num editor JSON de verdade com correspondência de chaves, converta de volta, e alimente o fluxo corrigido para o carregador que queria linhas desde o início.

Se o consumidor aceita entrada delimitada por linha, entregue isso. BigQuery, ClickHouse, DuckDB, cargas em massa do Elasticsearch e a maioria dos coletores de log nomeiam NDJSON como formato de entrada justamente porque um array único força o leitor a segurar tudo de uma vez. Converter para satisfazer uma preferência em vez de uma exigência deixa o arquivo maior e a carga mais lenta.

Guarde o original de qualquer forma. O array não tem vantagem que as linhas não tenham, exceto ser um valor só, e as linhas têm várias que o array não tem: acrescentam sem reescrever, filtram sem carregar tudo, e um byte corrompido danifica um registro em vez do documento inteiro.

A conversão é JavaScript puro na página. Nenhum motor é baixado, nenhuma requisição carrega o arquivo, não existe conta nem cota diária, e a guia de rede durante uma conversão é a checagem, não esta frase.

Isso importa aqui porque os arquivos que precisam desta conversão raramente são públicos. Uma exportação de eventos, um log de auditoria, um extrato de cliente a caminho de um validador de esquema — tudo isso é exatamente o material que uma organização proíbe colar num serviço web. Não há nada a proibir quando nada é enviado.