JSON Lines ou array JSON: prepare registros para uma API sem perder dados

JSON Lines e array JSON não são o mesmo formato

JSON é um formato de texto para representar dados estruturados. JSON Lines, também chamado JSONL, organiza esses dados como registros: cada linha contém um valor JSON independente. A documentação de ajuda da Claris, por exemplo, descreve a exportação de registros para um arquivo de texto JSON Lines. Já um array JSON é uma única estrutura que contém uma sequência de valores entre colchetes. Essa diferença importa porque um arquivo pode ser válido como JSONL e não ser um único documento JSON válido para o consumidor que tenta lê-lo.

Considere estas duas linhas: «{"id":1,"nome":"Ana"}» e «{"id":2,"nome":"Luis"}». Juntas, elas representam dois registros no formato JSON Lines. O array equivalente é «[{"id":1,"nome":"Ana"},{"id":2,"nome":"Luis"}]». Os objetos e seus valores são os mesmos; o que muda é a estrutura que os agrupa. Não basta renomear a extensão nem colar as linhas uma após a outra: primeiro, é preciso identificar qual formato você tem e de qual precisa.

• JSON Lines: um valor JSON por linha; o arquivo pode conter vários registros independentes.
• Array JSON: um documento entre colchetes que contém zero ou mais valores separados por vírgulas.

Confirme a estrutura exigida pelo endpoint

Antes de transformar qualquer coisa, consulte a documentação do endpoint específico e, se houver, a especificação OpenAPI. Procure um exemplo do corpo da solicitação e confira se ele espera um array na raiz, um objeto com uma propriedade de registros, um único objeto ou dados enviados de outra forma. Não deduza a estrutura pelo nome do endpoint nem pelo fato de ele receber vários registros: é o contrato daquela operação que determina o formato aceito.

Anote também os requisitos do contrato para cada campo: nomes exatos, tipos de valor, propriedades obrigatórias e comportamento diante de campos adicionais, nulos ou vazios. Um registro com o campo «id» como número não é necessariamente equivalente a outro que o envia como texto. Se a documentação não esclarecer uma regra, procure um exemplo oficial ou confirme o que é esperado com a equipe responsável antes de preparar o lote completo. Mudar a estrutura externa do arquivo não corrige incompatibilidades entre os campos e o contrato.

• Identifique o endpoint e o exemplo de solicitação correspondentes à operação real.
• Registre a estrutura da raiz e os tipos esperados antes de modificar o arquivo.
• Separe as regras confirmadas das dúvidas que precisam ser esclarecidas.

Transforme uma amostra sem alterar os registros

Comece com uma cópia pequena que inclua registros representativos e, se houver, casos extremos. Se o endpoint exigir um array de objetos, a transformação conceitual consiste em inserir um colchete de abertura antes do primeiro objeto, separar os objetos com vírgulas e fechar o array depois do último. Não acrescente uma vírgula após o último elemento. O resultado de dois registros seria: «[{"id":1,"nome":"Ana"},{"id":2,"nome":"Luis"}]». Este é um exemplo de estrutura, não uma garantia de que aquele endpoint específico aceite esses campos.

Preserve cada nome de propriedade, valor e tipo exatamente, a menos que o contrato indique uma conversão necessária. Não transforme «0012» em 12, não mude um valor booleano para uma string e não remova propriedades porque parecem repetidas. Se automatizar a montagem, faça com que o processo leia cada linha como um valor JSON e crie uma lista de valores; evite manipular o texto com substituições improvisadas de quebras de linha ou vírgulas. Depois, compare a amostra de entrada e a de saída campo por campo.

• Guarde o original sem alterações e transforme uma cópia.
• Teste primeiro com poucos registros e preserve os tipos e valores originais.
• Gere a separação e os colchetes com uma ferramenta que entenda a estrutura, não com substituições às cegas.

Detecte erros de sintaxe e registros inesperados

Um erro frequente é concatenar objetos sem transformá-los em um array: «{"id":1}{"id":2}». Embora cada trecho pareça um objeto, essa sequência não tem a estrutura do array do exemplo. Também pode sobrar uma vírgula após o último elemento, faltar um colchete ou haver uma aspa sem escape dentro de uma string. Examine a mensagem do analisador e a localização indicada; se o erro apontar para uma linha ou posição, confira o registro correspondente e também o caractere imediatamente anterior.

Inspecione as linhas vazias e os valores que não sejam objetos. Não conclua por intuição que uma linha vazia é um registro descartável: defina essa regra de acordo com a origem e o processo que recebe os dados e documente as exclusões. Da mesma forma, «null», uma string ou um array podem ser valores JSON, mas não são objetos de registro. Se o contrato espera objetos, identifique esses casos antes do envio, em vez de forçar sua aceitação ou removê-los silenciosamente.

• Confira colchetes, vírgulas, aspas e escapes quando não for possível interpretar o resultado.
• Conte e classifique as linhas vazias ou os valores que não sejam objetos.
• Não oculte erros descartando registros sem uma regra acordada.

Valide registros, caracteres e o resultado completo

Antes de enviar, compare o número de registros de origem com o número de elementos do array resultante. Se houver exceções documentadas, registre quantas linhas foram omitidas e por quê; se não houver, qualquer diferença precisa ser investigada. Confira o primeiro e o último registro e também revise uma amostra intermediária. Essas verificações ajudam a encontrar truncamentos no início ou no fim, além de erros que afetam apenas uma parte do arquivo.

Valide se o resultado pode ser interpretado como um único JSON e se a raiz tem o formato exigido. Confira nomes de campos, tipos, valores nulos, strings vazias e caracteres especiais em casos representativos: aspas, barras invertidas, quebras de linha ou caracteres acentuados. Confirme também a codificação esperada pela ferramenta ou pelo endpoint; não a altere sem verificar o requisito. Se a validação falhar, preserve o arquivo original, corrija a causa e execute novamente as verificações em todo o resultado.

• Compare as quantidades e explique qualquer diferença.
• Confira o primeiro registro, o último e amostras intermediárias.
• Valide a sintaxe, a raiz, os campos, os tipos, os caracteres e a codificação esperada.

Decida quando manter JSON Lines

Converter nem sempre é melhor. Se o consumidor aceitar JSON Lines e o fluxo for processado registro por registro, manter esse formato pode evitar a criação de um único array grande e permite trabalhar com a organização original por linhas. A decisão depende do que o processo receptor aceita e de como os erros serão tratados. Não presuma que um endpoint aceite JSONL só porque aceita JSON, nem que aceitar um array signifique aceitar registros independentes.

O array pode ser necessário quando o contrato exige uma única lista no corpo de uma solicitação. Nesse caso, avalie também o tamanho do lote e a estratégia para informar falhas parciais, se a documentação especificar uma. Se não estiver claro se é melhor enviar tudo junto ou em vários grupos, teste com uma amostra controlada e verifique a resposta antes de aumentar o volume. Mantenha separados os dados originais, os transformados e os resultados do teste.

• Mantenha JSON Lines se o consumidor aceitar esse formato e o processamento por registro for adequado.
• Use um array quando essa for a estrutura exigida pelo contrato.
• Confira o tamanho e o tratamento de erros antes de enviar um lote completo.

Lista de verificação e ferramentas

Antes de concluir a preparação, verifique se identificou o formato de origem, confirmou o contrato e preservou uma cópia intacta. Teste uma amostra com mais de um registro, valide a estrutura resultante e compare os campos e as quantidades. Anote como tratou linhas vazias, registros malformados e valores inesperados. Se a amostra passar, aplique o mesmo procedimento ao arquivo completo e repita a validação; não presuma que o lote final está correto só porque uma amostra pequena estava.

Se estiver avaliando um conversor, verifique separadamente seus formatos de entrada e saída, se ele distingue JSON Lines de JSON convencional, o que faz diante de linhas vazias e registros inválidos e como informa erros. Teste casos que incluam caracteres especiais e valores de tipos diferentes. A Apification oferece integração de Cloud e serviços por REST API, OpenAPI, webhooks, iframe e JavaScript, além de um assistente guiado para processar dados e outros arquivos. Essa descrição não confirma uma conversão específica de JSON Lines: verifique se o formato necessário é aceito antes de depender de uma função específica.

• Contrato confirmado e arquivo original preservado.
• Amostra validada e quantidades comparadas.
• Erros, linhas vazias e caracteres especiais revisados.
• Recursos específicos do conversor verificados antes do uso.

Perguntas frequentes