O que é NDJSON? Registros de streaming, Sintaxe e Casos de Uso

API de Raspagem Sem Raspa retorna JSON estruturado que uma pipeline a jusante pode estruturar como NDJSON quando registros independentes precisam de streaming ou armazenamento orientado a linhas.

O que é NDJSON?

NDJSON é um formato de texto para uma sequência de valores JSON separados por caracteres de nova linha. Cada linha física contém um texto JSON completo. Um consumidor lê uma linha, analisa essa linha como JSON, processa o valor resultante e passa para o próximo registro.

O especificação NDJSON exige que cada texto JSON esteja em conformidade com as regras JSON e seja seguido por uma nova linha. Especifica UTF-8, aceita LF e CRLF como delimitadores de linha para análise e recomenda application/x-ndjson com a .ndjson extensão.

NDJSON é uma convenção de estrutura em torno de JSON, não um novo modelo de objeto. Uma linha pode tecnicamente conter qualquer valor JSON, embora objeto-por-linha seja o padrão dominante para logs, ingestão em massa, exportações e pipelines de dados. A gramática JSON permanece a definida por RFC 8259.

Como é um arquivo NDJSON?

Um fluxo de observação de produto pode conter três registros independentes:

{"sku":"A-17","price":34.5,"currency":"USD"}
{"sku":"B-08","price":28,"currency":"USD"}
{"sku":"C-31","price":null,"currency":"EUR"}

Não há colchete de abertura de array, vírgula entre registros, ou colchete de fechamento. Cada linha pode ser analisada por conta própria. A linha final deve terminar com uma nova linha sob a regra de serialização NDJSON, embora visualizadores de texto nem sempre tornem o delimitador final visível.

JSON formatado não funciona como um registro NDJSON porque a indentação escreve um valor em várias linhas físicas. Os produtores devem serializar cada valor em forma compacta. Uma string que contém uma quebra de linha lógica permanece válida porque o JSON a escapa:

{"id":41,"message":"first line\nsecond line"}

Os dois caracteres barra invertida e n permanecem dentro da string JSON em uma linha física. Um analisador JSON reconstrói o caractere de quebra de linha após a estruturação do registro ter sido bem-sucedida.

NDJSON vs um Array JSON

Por que NDJSON funciona para streaming

JSON padrão não define um limite entre dois valores de nível superior adjacentes. A escrita {}{} deixa um analisador sem um separador padrão. O NDJSON atribui esse papel à nova linha. O leitor não precisa verificar por chaves balanceadas porque as chaves dentro de strings JSON são caracteres de string comuns e o limite de linha físico encerra o registro.

Um produtor pode enviar cada linha quando o registro estiver pronto. Um consumidor pode aplicar contrapressão através de sua interface de fluxo, analisar uma linha, validar o valor e liberar memória após o processamento. Isso mantém o uso de memória vinculado ao maior registro e buffers de pipeline em vez de todo o conjunto de dados.

NDJSON não é o único formato de sequência JSON. RFC 7464 define sequências de texto JSON usando um caractere de separador de registro ASCII antes de cada texto JSON. Essa estrutura pode tolerar valores impressos porque os limites de registro não dependem exclusivamente de quebras de linha. Produtores e consumidores devem concordar sobre qual formato de sequência estão usando.

Design de Registro NDJSON

Um fluxo NDJSON forte dá a cada linha contexto suficiente para ser processada de forma independente. Inclua um tipo de registro ou versão de esquema estável quando várias formas de eventos compartilharem um fluxo. Inclua um identificador que suporte desduplicação quando o transporte puder entregar o mesmo registro lógico mais de uma vez. Adicione tempos de evento e observação apenas com formatos documentados e semânticas de fuso horário.

Mantenha conteúdo binário grande fora do JSON orientado a linhas, a menos que o contrato exija explicitamente bytes codificados. Base64 aumenta o tamanho e cria registros muito longos. Um evento melhor pode carregar uma referência de objeto controlada mais metadados de integridade, sujeita a autorização no momento da recuperação.

A ordenação deve ser explícita. O NDJSON preserva a ordem de linha física, mas produtores distribuídos, partições e consumidores paralelos podem alterar a ordem de processamento observada. Se a ordem importa dentro de uma entidade, inclua uma sequência ou versão e defina como lacunas e registros fora de ordem são tratados.

Validação de Esquema

JSON válido não é necessariamente um registro comercial válido. Uma linha pode ser analisada com sucesso enquanto falta um identificador obrigatório ou armazena um número onde o contrato espera uma string. Valide cada valor analisado contra um esquema de registro antes de usá-lo.

Fluxos com múltiplos tipos de registro podem escolher um esquema com base em um discriminator estável. O dispatcher deve rejeitar tipos desconhecidos ou encaminhá-los para um caminho de quarentena controlada. As versões de esquema devem definir compatibilidade para que os consumidores possam continuar quando campos opcionais forem adicionados.

A validação em nível de registro permite que um lote relate falhas específicas sem perder a localização de registros aceitáveis. Armazene o número da linha física, o deslocamento de bytes quando disponível, o erro de esquema e um identificador de registro redigido com segurança. Não copie segredos ou cargas úteis sensíveis para logs de erro.

Casos de Uso Comuns de NDJSON

NDJSON, CSV e Parquet

NDJSON preserva estruturas JSON aninhadas e permite registros com campos opcionais. CSV é mais compacto e acessível quando cada registro é uma linha de tabela plana. Parquet adiciona armazenamento coluna tipada para análises repetidas em muitos registros.

Um pipeline comum coleta ou recebe JSON, escreve NDJSON cru para rastreabilidade amigável a anexos, valida e normaliza registros e, em seguida, publica Parquet para consultas analíticas. CSV permanece útil para exportações planas selecionadas para usuários de planilhas. Cada estágio tem um consumidor diferente e, portanto, um formato melhor diferente.

Compressão e Divisão

Registros de texto geralmente compressam bem porque padrões de chaves e valores se repetem. A compressão de arquivo inteiro reduz o tamanho de armazenamento e transferência, mas alguns codecs dificultam o início da leitura a partir do meio de um fluxo comprimido. Compressão dividível ou pedaços comprimidos independentemente podem ser melhores para processamento paralelo.

Divida apenas em limites de registro completos. Um corte de intervalo de bytes através do meio de uma string JSON cria fragmentos inválidos. Sistemas que precisam de acesso paralelo podem manter índices de bloco, dividir o fluxo em vários objetos ou usar formatos de armazenamento construídos para leituras seletivas.

Concatenar arquivos NDJSON válidos geralmente preserva a estrutura de linha válida quando cada entrada termina com uma nova linha. Se um arquivo faltar o delimitador final, seu último registro pode se misturar com o primeiro registro do próximo arquivo. Os escritores devem sempre terminar registros serializados, incluindo o final.

Limites de Segurança e Operacionais

Aplique limites ao total de bytes, comprimento de linha, profundidade de aninhamento, comprimento de string, magnitude numérica e contagem de propriedades permitidas. Uma única linha NDJSON pode ser arbitrariamente grande, a menos que a aplicação imponha um limite. Leia com um buffer limitado ou estratégia de streaming que relate um registro excessivo sem esgotar a memória.

Não execute campos como comandos ou templates. Escape valores quando entrarem em HTML, SQL, shell ou contextos de log. Proteja contra forjamento de log quando registros NDJSON forem posteriormente convertidos em texto simples. Mantenha a autorização em nível de fluxo e registro quando um arquivo puder conter dados para vários locatários.

Como Processar NDJSON de Forma Confiável

1. Abra o fluxo como UTF-8. Defina como sequências de bytes inválidas são relatadas; substituição silenciosa pode mudar identificadores.
2. Leia uma linha física limitada. Aceite as quebras de linha acordadas e imponha um tamanho máximo de registro.
3. Lide com linhas vazias conforme o contrato. Decida se elas são ignoradas ou rejeitadas, e aplique a regra de forma consistente.
4. Analise um valor JSON. Rejeite conteúdo não vazio no final dessa linha e defina o comportamento de membros duplicados.
5. Valide o esquema do registro. Verifique tipo, propriedades obrigatórias, limites de valor e versões suportadas.
6. Processar de forma idempotente quando possível. Identificadores de registro estáveis ajudam a prevenir efeitos colaterais duplicados quando um registro aparece mais de uma vez.
7. Registre o progresso com segurança. Os pontos de verificação devem identificar um registro durável ou limite de byte sem afirmar que uma linha incompleta foi processada.

Quando Não Usar NDJSON

Use um documento JSON normal quando a carga útil for pequena, precisar carregar metadados de nível superior ou se beneficiar da impressão formatada. Use CSV quando os dados forem uma tabela plana para consumidores de planilhas. Use Parquet quando motores analíticos precisarem de poda de colunas, armazenamento tipado e compressão em grandes conjuntos de dados.

NDJSON também é uma má escolha quando valores individuais devem conter formatação de linha física não escapada para edição humana. Uma sequência JSON baseada em separadores de registro ou um protocolo binário estruturado pode atender melhor a esse requisito.

Conclusão

NDJSON adiciona uma regra prática ao intercâmbio de JSON: cada linha é um valor JSON completo. Essa regra suporta arquivos amigáveis para anexação, analisadores em streaming, validação em nível de registro e memória limitada. Não define o esquema empresarial, garantias de ordenação, política de segurança ou semântica de entrega. Um fluxo de trabalho NDJSON confiável usa registros compactos em UTF-8, esquemas explícitos, limites de tamanho, identificadores estáveis, comportamento claro de linhas vazias e pontos de verificação cientes de linha.