Convert JSON to CSV: Complete Guide With Examples

Quando Você Precisa de Conversão de JSON para CSV

JSON é o formato padrão para APIs e aplicações web, mas no momento em que os dados precisam sair do ecossistema de desenvolvedores — para uma planilha, uma ferramenta de inteligência de negócios, uma importação de banco de dados ou um relatório enviado por e-mail a um interessado — o CSV é geralmente o formato esperado.

Cenários comuns onde a conversão de JSON para CSV é necessária:

• Exportando dados da API — puxando registros de uma API REST e carregando-os no Excel ou Google Sheets para análise.
• Importações de banco de dados — muitos bancos de dados (PostgreSQL, MySQL, SQLite) suportam importações CSV de forma nativa, mas não JSON.
• Relatórios — interessados não técnicos precisam de dados em um formato que possam abrir em uma planilha, e não em um visualizador de JSON.
• Pipelines de dados — sistemas ETL legados frequentemente esperam CSV como um formato de intercâmbio entre estágios.

Experimente você mesmo: Cole um array JSON em nosso JSON para CSV conversor para um download instantâneo de um arquivo CSV pronto.

Passo a Passo para Conversão Simples

O caso mais simples: você tem um array JSON de objetos planos onde cada objeto tem as mesmas chaves. Isso se mapeia diretamente para uma tabela CSV.

JSON de Entrada:

[
  { "name": "Alice", "age": 30, "city": "Portland" },
  { "name": "Bob", "age": 25, "city": "Seattle" },
  { "name": "Carol", "age": 35, "city": "Denver" }
]

CSV de Saída:

name,age,city
Alice,30,Portland
Bob,25,Seattle
Carol,35,Denver

As chaves dos objetos se tornam cabeçalhos de coluna, e cada objeto se torna uma linha. Este é o caminho feliz — e funciona perfeitamente para a maioria das respostas de API que retornam arrays de registros.

A complexidade surge quando seu JSON não é plano. Objetos aninhados, arrays dentro de objetos, chaves ausentes e tipos mistos exigem decisões sobre como representar dados hierárquicos em uma tabela plana.

Lidando com JSON Aninhado

JSON do mundo real raramente é plano. Uma resposta de API para um usuário pode incluir um objeto de endereço aninhado, um array de funções e campos opcionais que não aparecem em todos os registros. O CSV não tem conceito de aninhamento, então você precisa de uma estratégia de achatamento.

Estratégia 1: Notação de Ponto

A abordagem mais comum. As chaves aninhadas são concatenadas com pontos para formar um único nome de coluna.

Entrada:

[
  {
    "name": "Alice",
    "address": {
      "city": "Portland",
      "state": "OR"
    }
  }
]

Saída:

name,address.city,address.state
Alice,Portland,OR

A notação de ponto preserva a relação estrutural no nome da coluna. Funciona bem para um ou dois níveis de aninhamento, mas se torna difícil para dados profundamente aninhados (user.profile.settings.notifications.email).

Estratégia 2: Colunas Separadas por Valor Folha

Semelhante à notação de ponto, mas com nomes de coluna personalizados que eliminam a hierarquia de aninhamento. Por exemplo, address.city se torna apenas city. Isso produz cabeçalhos mais limpos, mas requer mapeamento manual de colunas e corre o risco de colisões de nomes se diferentes objetos aninhados tiverem chaves com o mesmo nome.

Estratégia 3: Serializar Objetos Aninhados

Para estruturas aninhadas complexas que não se mapeiam bem para colunas planas, serialize o valor aninhado como uma string JSON dentro da célula CSV.

Saída:

name,address
Alice,"{""city"":""Portland"",""state"":""OR""}"
Bob,"{""city"":""Seattle"",""state"":""WA""}"

Isso preserva todos os dados, mas as células CSV contêm JSON bruto — não ideal para usuários de planilhas. Funciona quando o CSV é um formato intermediário que será analisado novamente por código.

Comparando Abordagens de Achatamento

Abordagem	Legibilidade	Perda de dados	Aninhamento profundo	Melhor para
Notação de ponto	Boa	Nenhuma	Fica verboso	1-2 níveis de aninhamento
Nomes de coluna personalizados	Melhor	Colisões possíveis	Esforço manual	Esquemas conhecidos e estáveis
Serializar	Ruim para humanos	Nenhuma	Lida com qualquer profundidade	Pipelines máquina-a-máquina

Lidando com Arrays Dentro de Objetos

Arrays apresentam um desafio diferente. Considere um usuário com várias funções:

{
  "name": "Alice",
  "roles": ["admin", "editor", "viewer"]
}

Você tem várias opções para representar isso em CSV:

• Juntar como string delimitada: admin;editor;viewer em uma única célula. Simples, mas requer análise posterior.
• Colunas separadas: roles.0, roles.1, roles.2. Funciona quando o comprimento máximo do array é conhecido e pequeno.
• Linhas separadas: Uma linha por função, com os outros dados do usuário repetidos. Isso desnormaliza os dados, mas evita células de múltiplos valores.
• Serializar: ["admin","editor","viewer"] como JSON bruto na célula. Preserva a estrutura para processamento posterior.

A escolha certa depende de quem consome o CSV. Para usuários de planilhas, a abordagem de string delimitada é geralmente a mais prática. Para pipelines de dados, serializar preserva a maior parte da informação.

Casos Limite

Toda conversão de JSON para CSV eventualmente encontra esses casos. Conhecer sobre eles antecipadamente economiza tempo de depuração.

Valores Nulos

JSON null pode ser mapeado para uma célula vazia, a string literal null, ou um espaço reservado personalizado. A maioria das ferramentas usa uma célula vazia, o que é correto para planilhas, mas perde a distinção entre "null" (explicitamente sem valor) e "chave ausente" (campo não presente). Se essa distinção for importante, use null como uma string literal.

Tipos Mistos

Um campo JSON pode ser uma string em um registro e um número em outro. Colunas CSV não têm tipos — tudo é uma string — então isso geralmente funciona bem no nível do CSV. O problema surge ao importar para sistemas tipados (bancos de dados, dataframes tipados). Valide os tipos após a conversão.

Chaves Ausentes

Quando objetos em um array JSON não têm todas as mesmas chaves, o conversor precisa construir uma união de todas as chaves em todos os objetos. Isso produz uma linha de cabeçalho com todas as possíveis colunas, e objetos que faltam uma chave recebem uma célula vazia para essa coluna.

[
  { "name": "Alice", "age": 30 },
  { "name": "Bob", "city": "Seattle" }
]

Saída:

name,age,city
Alice,30,
Bob,,Seattle

Caracteres Especiais em Valores

Valores CSV que contêm vírgulas, aspas duplas ou quebras de linha devem ser envoltos em aspas duplas. Se o valor em si contém aspas duplas, elas são escapadas duplicando-as. A maioria das bibliotecas de conversão lida com isso automaticamente, mas se você estiver construindo seu próprio conversor, é a fonte mais comum de bugs.

name,bio
Alice,"Ama ""JSON"" e programação"
Bob,"Portland, OR"

Conversão Programática

JavaScript / Node.js

Para dados simples e planos, você pode converter JSON para CSV em algumas linhas sem dependências:

const jsonToCsv = (data: Record<string, unknown>[]) => {
  if (data.length === 0) return "";

  const headers = Object.keys(data[0]);
  const rows = data.map((row) =>
    headers
      .map((header) => {
        const value = row[header] ?? "";
        const str = String(value);
        return str.includes(",") || str.includes('"') || str.includes("\\n")
          ? `"\${str.replace(/"/g, '""')}"` 
          : str;
      })
      .join(",")
  );

  return [headers.join(","), ...rows].join("\\n");
};

Para uso em produção com dados aninhados, bibliotecas como json2csv (do pacote @json2csv/plainjs) lidam com achatamento, transformações personalizadas e casos limites:

import { Parser } from "@json2csv/plainjs";
import { flatten } from "@json2csv/transforms";

const parser = new Parser({
  transforms: [flatten({ separator: "." })],
});

const csv = parser.parse(data);

Python

A biblioteca padrão do Python tem tudo que você precisa para conversões básicas:

import csv
import json
import io

def json_to_csv(data: list[dict]) -> str:
    if not data:
        return ""

    output = io.StringIO()
    writer = csv.DictWriter(output, fieldnames=data[0].keys())
    writer.writeheader()
    writer.writerows(data)
    return output.getvalue()

Para JSON aninhado, a biblioteca pandas achata e converte em uma única chamada:

import pandas as pd

df = pd.json_normalize(data, sep=".")
df.to_csv("output.csv", index=False)

json_normalize lida automaticamente com objetos aninhados usando notação de ponto para nomes de colunas. É a maneira mais rápida de ir de uma resposta de API aninhada para um arquivo CSV limpo.

Considerações para Arquivos Grandes

Quando seu arquivo JSON tem centenas de megabytes ou mais, a abordagem de conversão precisa mudar. Carregar o arquivo inteiro na memória, analisá-lo e construir uma string CSV na memória pode facilmente exceder sua RAM disponível.

Analisadores em streaming são a solução. Em vez de carregar o arquivo inteiro, eles o processam incrementalmente:

• Node.js: Use JSONStream ou stream-json para analisar o array JSON um objeto de cada vez, converter cada um em uma linha CSV e escrevê-lo em um fluxo de saída. A memória permanece constante, independentemente do tamanho do arquivo.
• Python: A biblioteca ijson fornece análise JSON iterativa. Combine-a com csv.writer escrevendo em um manipulador de arquivo para conversão com memória constante.
• CLI: jq processa JSON de forma nativa em um modo de streaming. Para JSON para CSV especificamente, ferramentas como miller (mlr) e csvkit são projetadas para conversão de formato em grande escala.

Uma regra prática: se seu arquivo JSON tiver menos de 50 MB, a conversão na memória está bem. Acima disso, mude para uma abordagem de streaming. Acima de 1 GB, use uma ferramenta CLI como miller ou um framework de processamento de dados dedicado.

Escolhendo a Abordagem Certa

Cenário	Abordagem recomendada
Conversão rápida e única	Ferramenta online ou conversor de navegador
JSON plano, arquivos pequenos	Biblioteca de linguagem embutida (módulo csv, função JS simples)
JSON aninhado, esquema complexo	pandas.json_normalize ou @json2csv com transformação de achatamento
Arquivos grandes (>50 MB)	Analisador em streaming (ijson, stream-json) ou CLI (miller)
Pipeline recorrente	Script com uma biblioteca, integrado ao CI/ETL

Para a maioria dos desenvolvedores, o caminho de conversão rápida é tudo o que eles precisam. Cole JSON, obtenha CSV, siga em frente. A complexidade só importa quando os dados estão aninhados, os arquivos são grandes ou a conversão é executada sem supervisão em um pipeline.

Experimente você mesmo: Cole seus dados JSON em nosso JSON para CSV conversor para obter um arquivo CSV limpo em segundos. Precisa ir na outra direção? Use nossa ferramenta CSV para JSON.