Conversor JSON para CSV

O que é a Conversão de JSON para CSV?

A conversão de JSON para CSV transforma dados estruturados do formato JSON em valores separados por vírgula — um formato tabular que planilhas, bancos de dados e ferramentas de análise consomem nativamente. O JSON armazena dados como objetos e arrays aninhados sem esquema fixo. O CSV armazena dados em linhas e colunas, com uma linha de cabeçalho definindo os nomes dos campos. Essa conversão é o caminho pelo qual dados de API chegam às planilhas e bancos de dados.

O CSV (Comma-Separated Values) é definido pela RFC 4180. Cada linha é um registro, e os campos dentro de uma linha são separados por um caractere delimitador, mais comumente uma vírgula. Campos que contenham o delimitador, aspas duplas ou quebras de linha devem ser colocados entre aspas duplas, com as aspas internas escapadas duplicando-as. Esse escape é a principal fonte de bugs ao escrever um conversor de JSON para CSV manualmente.

A conversão é direta quando a entrada é um array plano de objetos com chaves consistentes. Cada objeto se torna uma linha, e cada chave única se torna um cabeçalho de coluna. Objetos aninhados e arrays exigem uma etapa de achatamento, e chaves inconsistentes entre os objetos requerem uma estratégia para tratar campos ausentes — normalmente deixando a célula vazia. Um conversor confiável lida com todos esses casos automaticamente.

Por que Converter JSON para CSV?

APIs retornam JSON, mas planilhas, bancos de dados SQL e ferramentas de BI esperam dados tabulares. Converter JSON para CSV permite mover dados entre esses sistemas sem escrever scripts de importação personalizados.

Casos de Uso: JSON para CSV

Referência de Delimitadores CSV

O caractere delimitador separa os campos dentro de cada linha. A vírgula é a mais comum, mas outros delimitadores são padrão em contextos específicos. Escolher o delimitador errado faz os campos se mesclar ou dividir incorretamente quando o arquivo é aberto.

Tratando JSON Aninhado no CSV

CSV é um formato plano sem maneira nativa de representar objetos ou arrays aninhados. Quando seu JSON contém estruturas aninhadas, o conversor deve achatá-las em colunas. Existem várias estratégias, e a escolha certa depende de como o CSV será consumido.

Exemplos de Código

Converter JSON para CSV programaticamente requer tratar a extração de cabeçalhos, aspas em campos e escape de delimitadores. A maioria das linguagens tem suporte nativo ou de biblioteca padrão para escrita de CSV.

const data = [
  { name: "Alice", age: 30, city: "Berlin" },
  { name: "Bob", age: 25, city: "Tokyo" },
]

// Extract headers from the first object
const headers = Object.keys(data[0])
const csv = [
  headers.join(","),
  ...data.map(row => headers.map(h => {
    const val = String(row[h] ?? "")
    // Quote fields that contain commas, quotes, or newlines
    return val.includes(",") || val.includes('"') || val.includes("\n")
      ? '"' + val.replace(/"/g, '""') + '"'
      : val
  }).join(","))
].join("\n")

console.log(csv)
// → name,age,city
// → Alice,30,Berlin
// → Bob,25,Tokyo

import json, csv, io

json_str = '[{"name":"Alice","age":30,"city":"Berlin"},{"name":"Bob","age":25,"city":"Tokyo"}]'
data = json.loads(json_str)

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

print(output.getvalue())
# → name,age,city
# → Alice,30,Berlin
# → Bob,25,Tokyo

# Using jq to convert JSON array to CSV
echo '[{"name":"Alice","age":30},{"name":"Bob","age":25}]' | \
  jq -r '(.[0] | keys_unsorted) as $k | $k, (.[] | [.[$k[]]] ) | @csv'
# → "name","age"
# → "Alice",30
# → "Bob",25

# Using Miller (mlr) for streaming conversion
echo '[{"name":"Alice","age":30}]' | mlr --json --ocsv cat
# → name,age
# → Alice,30

package main

import (
    "encoding/csv"
    "encoding/json"
    "fmt"
    "os"
)

func main() {
    jsonStr := `[{"name":"Alice","age":30},{"name":"Bob","age":25}]`
    var data []map[string]interface{}
    json.Unmarshal([]byte(jsonStr), &data)

    w := csv.NewWriter(os.Stdout)
    // Write header
    headers := []string{"name", "age"}
    w.Write(headers)
    // Write rows
    for _, row := range data {
        record := make([]string, len(headers))
        for i, h := range headers {
            record[i] = fmt.Sprintf("%v", row[h])
        }
        w.Write(record)
    }
    w.Flush()
    // → name,age
    // → Alice,30
    // → Bob,25
}

Perguntas Frequentes