JSON Array vs CSV vs Lista de Linhas: Qual Formato Você Deve Usar?

Entendendo os Três Formatos

Um JSON array é uma coleção ordenada de valores delimitada por colchetes. Pode conter strings, números, booleanos, objetos e arrays aninhados. CSV (valores separados por vírgula) representa dados tabulares como linhas de campos separados por vírgulas, geralmente com uma linha de cabeçalho opcional. Uma lista de linhas é a forma mais simples: um valor por linha, sem delimitadores, sem estrutura de colunas.

• JSON arrays lidam com dados heterogêneos e objetos aninhados.
• CSV é o padrão para exportações de planilhas e bancos de dados.
• Listas de linhas são melhores para coleções simples e ordenadas, como endereços de e-mail ou nomes de arquivos.

["apple", "banana", "cherry"]

fruit,quantity
apple,3
banana,5
cherry,2

apple
banana
cherry

Trabalhando com JSON Arrays

JSON arrays são amplamente utilizados em APIs web e arquivos de configuração porque suportam estruturas aninhadas. Um array pode conter objetos com múltiplas propriedades, facilitando a representação de entidades do mundo real. O formato é rigoroso: vírgulas finais, chaves sem aspas ou colchetes desiguais causarão erros de análise.

Para listas simples, JSON é mais verboso que uma lista de linhas, mas sua legibilidade por máquina e suporte a diversos tipos de dados geralmente compensam a sobrecarga. O escape é feito com barras invertidas dentro das strings: aspas duplas tornam-se \", barras invertidas tornam-se \\, e novas linhas tornam-se \n.

• Prós: suporta aninhamento complexo, independente de linguagem, autodescritivo.
• Contras: mais verboso, requer validação, menos editável por humanos para grandes conjuntos de dados.

[
  {"name": "Alice", "email": "[email protected]"},
  {"name": "Bob", "email": "[email protected]"}
]

["line1\nline2", "path\\to\\file", "She said \"hello\""]

Trabalhando com CSV

Arquivos CSV são o padrão de fato para troca de dados entre planilhas e bancos de dados. Cada linha representa um registro, e os campos são separados por um delimitador — tipicamente uma vírgula, embora ponto e vírgula sejam usados em regiões onde a vírgula é o separador decimal. Seguindo a RFC 4180, campos que contenham delimitador, aspas duplas ou nova linha devem ser delimitados por aspas duplas.

Os dados no CSV são sempre representados como strings; números, datas e booleanos podem ser interpretados de forma diferente por diferentes programas. Cabeçalhos são comuns, mas não obrigatórios. O maior desafio com CSV é lidar com delimitadores específicos de localidade e codificação (UTF-8, UTF-8 BOM ou ISO-8859-1).

• Prós: nativo para planilhas, fácil de visualizar em forma de tabela, compacto.
• Contras: tipos de dados limitados (apenas strings), sem estruturas aninhadas, escape de aspas pode ser confuso.

"Name","Comment"
"Smith, John","He said ""hello"""

Trabalhando com Listas de Linhas

Uma lista de linhas é o formato de dados baseado em texto mais simples: um valor por linha, sem delimitadores, sem regras de aspas. É ideal para coleções de itens onde cada item é uma única string sem novas linhas, como endereços de e-mail, nomes de domínio, nomes de arquivos ou códigos de produto. O formato é extremamente amigável para humanos e funciona bem com ferramentas de linha de comando como grep, sort e uniq.

Como não há escape, listas de linhas não podem conter valores multilinha. Se um item puder incluir uma nova linha, você deve usar um formato diferente ou codificar a nova linha como uma barra invertida + n literal (ou outro espaço reservado) por convenção. Muitos editores e sistemas de controle de versão lidam com listas de linhas de forma limpa porque cada alteração é visível linha por linha.

• Prós: legível para humanos, fácil de ordenar e deduplicar, sem escape para valores típicos.
• Contras: adequado apenas para dados de campo único, sem suporte para itens multilinha sem convenções.

[email protected]
[email protected]
[email protected]

Escape e Aspas nos Três Formatos

Cada formato lida com caracteres especiais de forma diferente. Em JSON, qualquer string pode conter sequências de escape com barra invertida: \" para aspas duplas, \\ para barra invertida, \n para nova linha, \t para tabulação. O interpretador sempre processa essas sequências, o que torna JSON inequívoco, mas mais difícil de escrever manualmente.

CSV depende de aspas duplas externas para proteger campos que contêm caracteres especiais. Se um campo contém aspas duplas, elas são duplicadas ("" torna-se uma aspa simples literal). Listas de linhas não têm mecanismo de escape; se o dado contiver uma nova linha, a estrutura quebra. Entender essas diferenças é crítico ao converter entre formatos.

• JSON usa escape com barra invertida dentro das strings.
• CSV usa aspas duplas para campos que contenham vírgulas, novas linhas ou aspas.
• Listas de linhas assumem que não há novas linhas nos dados; novas linhas incorporadas não são representáveis.

JSON: "He said \"hello\"\nand left."
CSV: "He said ""hello""
and left."

Integração com Planilhas e Importação/Exportação

CSV é o formato mais direto para usuários de planilhas. A maioria dos aplicativos de planilha (Microsoft Excel, Google Sheets, LibreOffice Calc) pode abrir um arquivo CSV diretamente, embora possam interpretar mal o delimitador ou a codificação. Para resultados consistentes, salve arquivos CSV em UTF-8 com BOM e use vírgulas (ou ponto e vírgula conforme exigido pela região).

JSON arrays podem ser importados para planilhas usando ferramentas integradas como Power Query (Excel) ou escrevendo um pequeno script. Listas de linhas são frequentemente coladas em uma única coluna; talvez você precise usar o recurso ‘Texto para Colunas’ se a lista contiver delimitadores. Para cada formato, cuidado com a conversão automática de dados: zeros à esquerda em números, strings de data ou números grandes que podem perder precisão.

1. Abra o Excel e escolha Arquivo > Abrir.
2. Selecione seu arquivo CSV. Se os dados aparecerem incorretamente, use o Assistente de Importação de Texto para especificar delimitador e codificação.
3. Para JSON, use Dados > Obter Dados > De Arquivo > De JSON.
4. Para uma lista de linhas, cole os dados em uma coluna, depois selecione a coluna e use Dados > Texto para Colunas se precisar dividir ainda mais.

• CSV: verifique o delimitador e a codificação de caracteres; UTF-8 com BOM pode melhorar a compatibilidade com algumas versões do Excel.
• JSON: valide a estrutura antes de importar para que erros de sintaxe sejam detectados precocemente.
• Lista de linhas: cole em uma coluna formatada como texto quando zeros à esquerda devem ser preservados.

Armadilhas Comuns de Conversão e Como Evitá-las

Converter entre esses formatos frequentemente causa perda de dados se você não tomar cuidado. Achatar um JSON array aninhado para CSV força você a escolher quais propriedades manter, descartando outras. Ao converter uma lista de linhas para CSV, cada linha se torna um campo único, mas se a linha contiver uma vírgula ou aspas duplas, ela deve ser devidamente entre aspas para permanecer uma única coluna.

A validação é fundamental. Arquivos JSON devem ser validados com um linter para detectar vírgulas finais ou chaves sem aspas. Arquivos CSV devem ser verificados quanto a comprimentos de linha consistentes e aspas corretas. Listas de linhas devem ter novas linhas finais e nenhuma linha em branco, a menos que pretendido. Usar uma ferramenta de conversão dedicada pode ajudar a evitar essas armadilhas.

1. 1. Identifique a estrutura do formato de origem (plana ou aninhada).
2. 2. Se convertendo de JSON, achate quaisquer objetos ou arrays aninhados.
3. 3. Para CSV, garanta que os cabeçalhos estejam presentes, se necessário, e que os campos estejam corretamente entre aspas.
4. 4. Para listas de linhas, confirme que os itens não contêm novas linhas; se contiverem, codifique-os ou mude de formato.
5. 5. Valide a saída com um teste de análise simples.

• Achatar objetos aninhados em JSON antes de converter para CSV.
• Sempre coloque entre aspas os campos em CSV se eles puderem conter vírgulas ou novas linhas.
• Valide JSON com um linter antes da conversão.
• Verifique se há linhas vazias ou espaços finais em listas de linhas.

Source JSON: [{"name": "Alice", "tags": ["dev", "admin"]}]
Flattened CSV: name,tags
Alice,"[""dev"",""admin""]"

"Name"
"Smith, John"

Escolhendo um Formato: Guia de Decisão

O melhor formato para seus dados depende de como eles serão criados, consumidos e mantidos. Use JSON arrays quando seus dados tiverem estruturas aninhadas, ou quando você estiver trocando dados entre aplicativos que já usam JSON. Escolha CSV quando seu público-alvo usar planilhas, ou quando você precisar de um formato tabular universalmente aceito. Opte por uma lista de linhas para coleções simples e planas que humanos editarão com um editor de texto básico.

• Para dados de API → JSON.
• Para importação de planilhas → CSV.
• Para listas simples (e-mails, códigos) → lista de linhas.
• Para máxima interoperabilidade → CSV (todos os aplicativos de planilha suportam).
• Para diffs amigáveis ao controle de versão → lista de linhas.