Convert JSON to CSV: Complete Guide With Examples

Cuándo Necesitas Conversión de JSON a CSV

JSON es el formato predeterminado para APIs y aplicaciones web, pero en el momento en que los datos necesitan salir del ecosistema de desarrolladores — hacia una hoja de cálculo, una herramienta de inteligencia empresarial, una importación a base de datos o un informe enviado por correo a un interesado — CSV suele ser el formato esperado.

Escenarios comunes donde surge la conversión de JSON a CSV:

• Exportación de datos de API — extrayendo registros de una API REST y cargándolos en Excel o Google Sheets para análisis.
• Importaciones a bases de datos — muchas bases de datos (PostgreSQL, MySQL, SQLite) admiten importaciones CSV de forma nativa, pero no JSON.
• Informes — los interesados no técnicos necesitan datos en un formato que puedan abrir en una hoja de cálculo, no en un visor de JSON.
• Pipelines de datos — los sistemas ETL heredados a menudo esperan CSV como un formato de intercambio entre etapas.

Prueba tú mismo: Pega un array JSON en nuestro JSON a CSV convertidor para obtener un archivo CSV listo para descargar al instante.

Guía de Conversión Simple

El caso sencillo: tienes un array JSON de objetos planos donde cada objeto tiene las mismas claves. Esto se mapea directamente a una tabla CSV.

JSON de entrada:

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

CSV de salida:

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

Las claves del objeto se convierten en encabezados de columna, y cada objeto se convierte en una fila. Este es el camino feliz — y funciona perfectamente para la mayoría de las respuestas de API que devuelven arrays de registros.

La complejidad surge cuando tu JSON no es plano. Objetos anidados, arrays dentro de objetos, claves faltantes y tipos mixtos requieren decisiones sobre cómo representar datos jerárquicos en una tabla plana.

Manejo de JSON Anidado

El JSON del mundo real rara vez es plano. Una respuesta de API para un usuario podría incluir un objeto de dirección anidado, un array de roles y campos opcionales que no aparecen en cada registro. CSV no tiene concepto de anidamiento, así que necesitas una estrategia de aplanamiento.

Estrategia 1: Notación de Punto

El enfoque más común. Las claves anidadas se concatenan con puntos para formar un solo nombre de columna.

Entrada:

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

Salida:

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

La notación de punto preserva la relación estructural en el nombre de la columna. Funciona bien para uno o dos niveles de anidamiento, pero se vuelve engorrosa para datos profundamente anidados (user.profile.settings.notifications.email).

Estrategia 2: Columnas Separadas por Valor Hoja

Similar a la notación de punto, pero con nombres de columna personalizados que eliminan la jerarquía de anidamiento. Por ejemplo, address.city se convierte simplemente en city. Esto produce encabezados más limpios pero requiere un mapeo manual de columnas y corre el riesgo de colisiones de nombres si diferentes objetos anidados tienen claves con el mismo nombre.

Estrategia 3: Convertir Objetos Anidados a Cadena

Para estructuras anidadas complejas que no se mapean bien a columnas planas, serializa el valor anidado como una cadena JSON dentro de la celda CSV.

Salida:

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

Esto preserva todos los datos, pero las celdas CSV contienen JSON en bruto — no es ideal para usuarios de hojas de cálculo. Funciona cuando el CSV es un formato intermedio que será analizado nuevamente por código.

Comparando Enfoques de Aplanamiento

Enfoque	Legibilidad	Pérdida de datos	Anidamiento profundo	Mejor para
Notación de punto	Buena	Ninguna	Se vuelve verboso	1-2 niveles de anidamiento
Nombres de columna personalizados	Mejor	Colisiones posibles	Esfuerzo manual	Esquemas conocidos y estables
Convertir a cadena	Pobre para humanos	Ninguna	Maneja cualquier profundidad	Pipelines máquina a máquina

Manejo de Arrays Dentro de Objetos

Los arrays presentan un desafío diferente. Considera un usuario con múltiples roles:

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

Tienes varias opciones para representar esto en CSV:

• Unir como cadena delimitada: admin;editor;viewer en una sola celda. Simple pero requiere análisis posterior.
• Columnas separadas: roles.0, roles.1, roles.2. Funciona cuando la longitud máxima del array es conocida y pequeña.
• Filas separadas: Una fila por rol, con los otros datos del usuario repetidos. Esto desnormaliza los datos pero evita celdas de múltiples valores.
• Convertir a cadena: ["admin","editor","viewer"] como JSON en bruto en la celda. Preserva la estructura para un procesamiento posterior.

La elección correcta depende de quién consume el CSV. Para los usuarios de hojas de cálculo, el enfoque de cadena delimitada es generalmente el más práctico. Para pipelines de datos, convertir a cadena preserva la mayor cantidad de información.

Casos Especiales

Cada conversión de JSON a CSV eventualmente se encuentra con estos casos. Conocerlos de antemano ahorra tiempo de depuración.

Valores Nulos

JSON null puede mapearse a una celda vacía, la cadena literal null, o un marcador de posición personalizado. La mayoría de las herramientas utilizan una celda vacía, lo cual es correcto para hojas de cálculo pero pierde la distinción entre "null" (sin valor explícito) y "clave faltante" (campo no presente). Si esa distinción importa, usa null como una cadena literal.

Tipos Mixtos

Un campo JSON podría ser una cadena en un registro y un número en otro. Las columnas CSV no tienen tipos — todo es una cadena — así que esto generalmente funciona bien a nivel CSV. El problema surge al importar en sistemas tipados (bases de datos, dataframes tipados). Valida los tipos después de la conversión.

Claves Faltantes

Cuando los objetos en un array JSON no tienen todas las mismas claves, el convertidor necesita construir una unión de todas las claves a través de todos los objetos. Esto produce una fila de encabezado con cada posible columna, y los objetos que faltan una clave obtienen una celda vacía para esa columna.

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

Salida:

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

Caracteres Especiales en Valores

Los valores CSV que contienen comas, comillas dobles o saltos de línea deben estar envueltos en comillas dobles. Si el valor en sí contiene comillas dobles, se escapan duplicándolas. La mayoría de las bibliotecas de conversión manejan esto automáticamente, pero si estás construyendo tu propio convertidor, es la fuente más común de errores.

name,bio
Alice,"Le encanta ""JSON"" y programar"
Bob,"Portland, OR"

Conversión Programática

JavaScript / Node.js

Para datos planos simples, puedes convertir JSON a CSV en unas pocas líneas sin ninguna dependencia:

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 en producción con datos anidados, bibliotecas como json2csv (del paquete @json2csv/plainjs) manejan el aplanamiento, transformaciones personalizadas y casos especiales:

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

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

const csv = parser.parse(data);

Python

La biblioteca estándar de Python tiene todo lo que necesitas para conversiones 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 anidado, la biblioteca pandas aplana y convierte en una sola llamada:

import pandas as pd

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

json_normalize maneja objetos anidados automáticamente usando notación de punto para los nombres de columna. Es la forma más rápida de pasar de una respuesta de API anidada a un archivo CSV limpio.

Consideraciones para Archivos Grandes

Cuando tu archivo JSON tiene cientos de megabytes o más, el enfoque de conversión necesita cambiar. Cargar todo el archivo en memoria, analizarlo y construir una cadena CSV en memoria puede exceder fácilmente tu RAM disponible.

Los analizadores de streaming son la solución. En lugar de cargar todo el archivo, procesan de manera incremental:

• Node.js: Usa JSONStream o stream-json para analizar el array JSON un objeto a la vez, convertir cada uno en una fila CSV y escribirlo en un flujo de salida. La memoria se mantiene constante independientemente del tamaño del archivo.
• Python: La biblioteca ijson proporciona análisis JSON iterativo. Combínala con csv.writer escribiendo en un manejador de archivos para una conversión de memoria constante.
• CLI: jq procesa JSON de forma nativa en un modo de streaming. Para JSON a CSV específicamente, herramientas como miller (mlr) y csvkit están diseñadas para conversiones de formato a gran escala.

Una regla práctica: si tu archivo JSON es menor de 50 MB, la conversión en memoria está bien. Por encima de eso, cambia a un enfoque de streaming. Por encima de 1 GB, usa una herramienta CLI como miller o un marco de procesamiento de datos dedicado.

Elegir el Enfoque Correcto

Escenario	Enfoque recomendado
Conversión rápida y única	Herramienta en línea o convertidor de navegador
JSON plano, archivos pequeños	Biblioteca del lenguaje incorporada (módulo csv, función JS simple)
JSON anidado, esquema complejo	pandas.json_normalize o @json2csv con transformación de aplanamiento
Archivos grandes (>50 MB)	Analizador de streaming (ijson, stream-json) o CLI (miller)
Pipeline recurrente	Script con una biblioteca, integrado en CI/ETL

Para la mayoría de los desarrolladores, el camino de conversión rápida es todo lo que necesitan. Pega JSON, obtén CSV, sigue adelante. La complejidad solo importa cuando los datos están anidados, los archivos son grandes, o la conversión se ejecuta sin supervisión en un pipeline.

Prueba tú mismo: Pega tus datos JSON en nuestro JSON a CSV convertidor para obtener un archivo CSV limpio en segundos. ¿Necesitas ir en la otra dirección? Usa nuestra herramienta CSV a JSON.