Cómo Convertir JSON a CSV sin Perder Datos

Convertir JSON a CSV consiste en tomar un array de objetos y transformarlo en una tabla de filas y columnas separadas por comas. El punto donde casi todos los conversores fallan no es la conversión en sí, sino el escapado: qué pasa cuando un valor de texto contiene, precisamente, una coma o unas comillas. Si esa regla se aplica mal, el CSV resultante se desalinea y cada columna termina en el lugar equivocado sin que el error sea evidente a simple vista.

Por qué CSV sigue siendo necesario

JSON es el formato natural para APIs y para pasar datos entre programas, pero en cuanto esos datos tienen que llegar a una hoja de cálculo, CSV sigue siendo el idioma universal. Excel, Google Sheets, Airtable, la mayoría de los pipelines de ETL y casi cualquier sistema de importación masiva de datos aceptan CSV como formato de entrada estándar, mientras que muy pocos aceptan JSON anidado directamente. Un array JSON con cien registros que llega de una API se convierte en CSV para que alguien del equipo de negocio lo abra, lo filtre o lo pegue en un reporte sin tocar código.

El ejemplo completo, fila por fila

Este es el JSON de entrada, un catálogo pequeño de productos con cuatro claves por objeto:

[
  { "sku": "A100", "product": "Wireless Mouse, Black", "price": 19.99, "in_stock": true },
  { "sku": "A101", "product": "17\" Laptop Stand", "price": 42.5, "in_stock": false },
  { "sku": "A102", "product": "USB-C Cable", "price": 8.99, "in_stock": true }
]

Y este es el CSV que produce:

sku,product,price,in_stock
A100,"Wireless Mouse, Black",19.99,true
A101,"17"" Laptop Stand",42.5,false
A102,USB-C Cable,8.99,true

Los encabezados salen de la unión de todas las claves que aparecen en el array, en el orden en que se ven por primera vez: sku, product, price, in_stock. Esto importa porque un conversor mal hecho a veces solo mira las claves del primer objeto y descarta en silencio cualquier campo que aparezca únicamente en objetos posteriores. Este conversor recorre el array completo antes de fijar las columnas, así que ningún campo se pierde por estar “escondido” en el segundo o tercer objeto.

Ahora el detalle fila por fila:

Fila 1. El valor Wireless Mouse, Black contiene una coma. Como esa coma es parte del texto y no un separador de columna, todo el valor se envuelve entre comillas dobles: "Wireless Mouse, Black". Sin esa envoltura, el CSV leería “Wireless Mouse” como una columna y “Black” como la siguiente, desplazando el resto de la fila.

Fila 2. El valor 17" Laptop Stand tiene una comilla doble literal (la marca de pulgadas). Aquí se aplican dos reglas a la vez: cada comilla interna se duplica (" se convierte en "") y, además, el valor completo se envuelve en un par de comillas exteriores. El resultado es "17"" Laptop Stand". Es la regla de escapado de comillas de RFC 4180, el estándar de facto para CSV, y es la parte que más confunde a quien escribe un parser de CSV a mano por primera vez.

Fila 3. El valor USB-C Cable no tiene coma, comilla ni salto de línea, así que pasa sin ninguna modificación. La mayoría de las celdas de un CSV real son así de simples, lo cual es justamente lo que hace que las que sí necesitan escapado sean fáciles de pasar por alto al programarlo uno mismo.

La misma lógica se aplica a un valor con un salto de línea dentro: si un campo de texto largo contiene un \n, también se envuelve en comillas, porque de otro modo ese salto de línea partiría la fila en dos dentro del archivo CSV.

Claves que faltan: cómo se comporta la unión de encabezados

Cuando un objeto no tiene una clave que otro sí tiene, la celda correspondiente queda vacía en lugar de romper la conversión. Por ejemplo:

[
  { "name": "Ana", "city": "Madrid" },
  { "name": "Luis", "city": "Bogotá", "country": "Colombia" }
]

El encabezado final es name,city,country, porque country aparece por primera vez en el segundo objeto y se agrega a la lista de columnas. La fila de Ana, que no tiene country, queda como Ana,Madrid, con la última celda vacía en vez de generar un error o desalinear la fila.

Errores comunes

Objetos anidados se convierten en el texto [object Object]. Si un valor es a su vez un objeto, por ejemplo { "name": "Ana", "address": { "city": "Madrid", "zip": "28001" } }, el conversor no sabe cómo aplanarlo automáticamente y termina escribiendo literalmente la cadena [object Object] en esa celda, perdiendo toda la información de dentro. La solución es aplanar el objeto antes de convertir, moviendo cada campo anidado a su propia clave de primer nivel: address_city y address_zip en lugar de un único address que contiene un objeto.

Los arrays se aplanan en una sola celda separada por comas, no en columnas separadas. Un valor como "tags": ["red", "blue"] no genera dos columnas ni una lista con corchetes. Se convierte en la cadena de texto red,blue (sin corchetes), y como esa cadena ahora contiene una coma, el escapado la envuelve en comillas: la celda final queda como "red,blue". Es un comportamiento correcto y predecible, pero sorprende a quien espera que cada elemento del array termine en su propia columna.

El separador de lista de Excel en español no siempre es la coma. Muchas instalaciones de Excel configuradas en español o portugués usan la coma como separador decimal, así que por defecto esperan que el separador de lista de un CSV sea el punto y coma, no la coma. Al abrir un CSV separado por comas con esa configuración regional, Excel puede volcar la fila entera dentro de la columna A en lugar de repartirla en columnas. La solución no está en el archivo sino en Excel: usar “Datos > Texto en columnas” y elegir la coma como delimitador, o cambiar el separador de lista en la configuración regional del sistema operativo.

Un solo objeto suelto no es un array válido. La herramienta espera un array de objetos, es decir algo que empiece con [ y termine con ]. Si tienes un único registro como { "sku": "A100", "price": 19.99 }, hay que envolverlo entre corchetes, [{ "sku": "A100", "price": 19.99 }], antes de pegarlo. Sin los corchetes, no es un array y la conversión no puede continuar.

Convierte tu JSON aquí

Pega tu array JSON abajo y obtén el CSV al instante. Todo el procesamiento ocurre en tu navegador, ningún dato se envía a un servidor.

Preguntas frecuentes

¿Qué formato de entrada acepta el conversor? Un array JSON de objetos planos, como [{"sku": "A100", "price": 19.99}]. Un objeto suelto sin corchetes o un JSON que no sea un array muestra un error en pantalla en lugar de intentar convertir algo inválido.

¿Qué pasa si un objeto del array tiene claves que los demás no tienen? No es un error. Las columnas del CSV son la unión de todas las claves vistas en el array completo, en el orden en que aparecen por primera vez. Si un objeto concreto no tiene un valor para alguna de esas columnas, la celda correspondiente queda vacía.

¿Por qué mi columna con {"city": "Madrid"} sale como [object Object] en el CSV? Porque el conversor no aplana objetos anidados automáticamente. Antes de convertir, transforma ese campo anidado en claves de primer nivel, por ejemplo address_city y address_zip, y el problema desaparece.

¿Por qué Excel me mete toda la fila en una sola columna al abrir el CSV? Es casi siempre el separador de lista regional. Si Excel está configurado en español o portugués, puede esperar punto y coma en vez de coma como separador. Usa “Datos > Texto en columnas” eligiendo la coma como delimitador, o cambia el separador de lista en la configuración regional de tu sistema operativo.

¿Se envían mis datos a algún servidor al usar esta herramienta? No. La conversión de JSON a CSV ocurre enteramente en el navegador con JavaScript del lado del cliente. El JSON que pegas nunca sale de tu equipo.