Converter YAML para NDJSON

NDJSON é JSON com uma regra sobre quebras de linha: um valor completo por linha, sem vírgulas, sem colchetes envolvendo. Para produzir isso, algo precisa decidir onde um registro termina e o próximo começa, e a única coisa num arquivo YAML que diz isso é uma sequência no nível superior. Um documento que começa com uma lista de traços converte para uma linha por traço.

Tudo mais é uma linha só. Um mapeamento na raiz é um valor único não importa quanto esteja aninhado dentro dele, então um manifesto Kubernetes, um arquivo compose ou uma configuração de aplicação sai como uma linha de vários kilobytes. Isso não é uma falha, e geralmente não é o que a pessoa convertendo queria, motivo pelo qual é a primeira coisa nesta página em vez de uma nota de rodapé.

Se os registros que você quer estão aninhados sob uma chave — uma chave users guardando uma lista, uma chave events guardando uma lista —, a conversão não vai entrar e encontrá-los. Ela olha só para a raiz. A correção é elevar essa lista para o topo do documento antes de converter, o que num editor é apagar a primeira linha e desindentar o resto.

A alternativa é converter para JSON em vez disso e usar jq tanto para selecionar quanto para transformar em fluxo: extrair o array e emiti-lo um elemento por linha é uma expressão só. É a rota melhor quando a extração vai se repetir, porque é scriptável, e este conversor é a rota melhor quando acontece uma vez.

Âncoras YAML permitem que um bloco seja definido uma vez e referenciado várias vezes, e o analisador resolve todo alias numa cópia completa antes de qualquer coisa ser escrita. O NDJSON, portanto, fica maior que o YAML, às vezes consideravelmente.

Para um fluxo, isso não é um custo, é a exigência. Um consumidor de NDJSON lê uma linha por vez e pode nunca ter visto as outras — esse é o ponto inteiro do formato, e é o que permite a um carregador dividir um arquivo entre workers ou retomar depois de uma falha. Uma linha que se referisse a uma definição numa linha anterior quebraria exatamente nas condições para as quais o formato existe para sobreviver. Qualquer coisa que reduza a duplicação precisa acontecer depois da carga, não no arquivo.

Um fluxo YAML separado por marcadores --- é, conceitualmente, já NDJSON: um documento por registro, em ordem. É a correspondência estrutural mais próxima em toda essa família de formatos, e é a única entrada que esta conversão recusa, porque o analisador lê um documento único e para quando encontra um segundo.

O contorno é uma edição de texto, não uma ferramenta. Substitua cada --- por um marcador de item de lista de primeiro nível e indente os documentos abaixo dele, e o arquivo converte exatamente no fluxo esperado. Num arquivo grande, um sed de uma linha resolve; numa dúzia de documentos, um editor também resolve. Vale dizer claramente que isso é o pipeline sem um recurso, não uma limitação de nenhum dos dois formatos.

NDJSON é o formato de intercâmbio para ferramentas orientadas a linha desde cerca de 2013, e os destinos querem coisas ligeiramente diferentes. BigQuery e Snowflake aceitam JSON delimitado por linha diretamente como formato de carga. jq lê sem nenhuma flag e escreve de volta com a opção compacta. pandas lê com um argumento lines. Qualquer um desses consome esta saída sem alteração.

Elasticsearch é a exceção em que as pessoas tropeçam. Sua API bulk tem formato NDJSON mas espera uma linha de ação antes de cada documento, então um arquivo de registros simples é recusado. Intercalar as linhas de ação é uma passada de jq ou awk sobre a saída, e propositalmente não é feito aqui, porque a linha de ação nomeia um índice e uma operação que só você conhece.

Cada linha é JSON compacto: sem indentação, sem espaço depois de dois-pontos, chaves na ordem que o YAML tinha. O arquivo é UTF-8 e termina com uma quebra de linha, que a maioria dos carregadores exige e alguns toleram em silêncio.

Os tipos vêm do analisador YAML, não do escritor. Sob YAML 1.2 uma data sem aspas continua string, então um campo de data chega como texto em vez de algo que um carregador reconheça como carimbo de tempo sem uma dica de esquema. Inteiros grandes são o perigo silencioso: um identificador escrito 9223372036854775807 sai como 9223372036854776000, porque números JSON são doubles IEEE. Coloque esses entre aspas no YAML antes de converter, e chegam como strings, que é o que um identificador deveria ter sido de qualquer jeito.

Uma lista cujos itens não compartilham as mesmas chaves converte sem reclamar, e cada linha carrega só as chaves que seu registro tinha. É uma vantagem real sobre converter o mesmo dado para CSV, onde as colunas precisam ser a união de todo registro e as células ausentes precisam ser preenchidas com alguma coisa.

Se o destino é igualmente tolerante é outra questão. Um repositório de esquema na leitura aceita linhas irregulares de bom grado; um carregador de tabela com esquema fixo vai recusar ou nulificar os campos inesperados. A conversão preserva o que o YAML dizia, e vale escanear as primeiras e últimas linhas de uma saída grande para ver o quanto o formato deriva ao longo do arquivo.

Comentários YAML são descartados, e NDJSON não tem onde colocá-los: é JSON por linha, e JSON não tem sintaxe de comentário. Também não há linha de cabeçalho, declaração de esquema nem bloco de metadados, então o arquivo carrega registros e nada mais.

Essa ausência é proposital no formato e vale respeitar no pipeline. Se a carga precisa saber uma origem, um identificador de lote ou uma versão de esquema, isso pertence a um campo em cada registro ou ao nome do arquivo, não a um preâmbulo — qualquer coisa no topo de um arquivo NDJSON é um registro, e um carregador vai tentar lê-lo como um.

Se o YAML é configuração em vez de dado, esta conversão não tem nada a oferecer. Uma linha só de JSON minificado é pior que o YAML em todo sentido que uma pessoa se importa, e nenhum consumidor de fluxo queria um arquivo de configuração. Converta para JSON se precisa que seja legível por máquina, e deixe o YAML em paz se não precisa.

O par vale a pena quando o arquivo é genuinamente uma lista — registros exportados, fixtures, um log de eventos que alguém escreveu à mão, um conjunto de dados semente — e o destino lê linhas. Nesse caso a conversão é instantânea, roda inteiramente no seu navegador, e a única coisa que sobra para checar é a primeira linha e a última.