Cómo convertir JSON a CSV cuando tus datos están anidados

Un array JSON de objetos se convierte en CSV tomando como columna cada clave que aparezca en cualquier punto del array y escribiendo una fila por objeto, así que [{"id":1,"name":"Ada"}] sale como una línea de cabecera id,name y una fila 1,Ada. Pega el array en el conversor de esta página y ese es el archivo que recibes, entrecomillado como pide el RFC 4180. Lo incómodo es todo lo que JSON puede expresar y un rectángulo no: objetos anidados, arrays, tipos y la diferencia entre null y un string vacío.

Cómo es en realidad el archivo convertido

Toma un array con un objeto anidado y un array dentro, como la mayoría de las respuestas de una API:

[
  { "id": 1, "name": "Ada Lovelace", "address": { "city": "London" }, "tags": ["maths"] },
  { "id": 2, "name": "Hopper, Grace", "address": { "city": "New York" }, "tags": [] }
]

El CSV es este:

id,name,address.city,tags
1,Ada Lovelace,London,"[""maths""]"
2,"Hopper, Grace",New York,[]

Ahí pasaron tres cosas. El objeto anidado address se convirtió en una columna con punto. El array tags se quedó como texto JSON en una sola celda. Y el nombre que lleva una coma terminó entre comillas, porque si no se habría partido en dos columnas y habría desplazado todo lo que tenía a la derecha.

Las columnas son la unión de todas las claves de todos los objetos, en el orden en que cada una aparece por primera vez. A una fila a la que le falta una clave le toca una celda vacía en lugar de una fila corta, así que los datos irregulares siguen alineados en vez de irse de lado a mitad del archivo.

¿Tu JSON tiene filas dentro?

Un array de objetos es el caso para el que esto funciona. Un objeto suelto también se convierte y te da una fila. Un array de valores simples se vuelve una tabla de una sola columna.

Mucho JSON no tiene ninguna fila dentro, y forzarlo a una hoja de cálculo te da algo válido e inútil. Un archivo de configuración, un árbol de preferencias o el payload decodificado de un token se convierten cada uno en una fila ancha de columnas con puntos. Los claims que hay dentro de un JWT se leen mucho mejor como JSON que como cuarenta columnas por las que te desplazas de lado.

Si el texto es una sola línea larga minificada y no distingues qué forma tiene, pásalo antes por un formateador de JSON. Señala los dos problemas que se parsean sin error y aun así hacen daño: claves duplicadas, donde gana la última en silencio, y enteros demasiado grandes para que JavaScript los guarde exactos. El conversor no menciona ninguno de los dos. Leer JSON minificado cubre el resto de eso.

Qué pasa con los objetos y los arrays anidados

Esta es la parte que no se puede hacer bien, solo decidir. Tres casos, tres concesiones.

Objetos anidados: columnas con puntos

{"address":{"city":"London"}} se convierte en una columna llamada address.city, y los puntos siguen bajando tan hondo como bajen tus datos. Un objeto sin nada dentro no tiene claves que prestar, así que {"address":{}} sale como una columna llamada address con el texto {} dentro. Desactiva el aplanado y cada objeto cae entero en una celda de esa forma: más fácil de leer cuando el archivo lo va a abrir una persona, inútil cuando lo tiene que parsear un programa.

Arrays de valores: una celda, como JSON

["maths","notes"] se queda como ese texto en una sola celda. La alternativa es una columna por posición, y entonces una sola fila con cuarenta tags ensancha el archivo para todas las demás, la mayoría de ellas en blanco. Si prefieres maths; notes en la celda, une el array en el JSON antes de convertir.

Arrays de objetos: elige de qué manera equivocarte

Pedidos con líneas de artículos, publicaciones con comentarios. El uno a muchos no tiene forma plana que lo conserve todo. Deja el array hijo como JSON en su celda y la hoja de cálculo no podrá hacer nada con él. Repite los campos del padre una vez por cada hijo y el archivo se lee bien hasta que alguien suma una columna, momento en el que cada total de pedido se cuenta tantas veces como artículos tenga. Si necesitas lo segundo, separa el JSON en una tabla padre y una tabla hija que compartan un id, y conviértelas por separado.

Por qué algunos campos salen entre comillas

Esas comillas no son parte de tus datos. Son la única forma que tiene el CSV de decir que una coma o un salto de línea dentro de un campo es contenido y no un separador, y el siguiente parser las quita al entrar. Borrarlas a mano es lo que hace que un archivo que funciona deje de funcionar.

Un campo se entrecomilla cuando contiene el delimitador, una comilla doble o un salto de línea. Una comilla dentro de un campo entrecomillado se duplica en vez de escaparse con barra invertida, así que Alan "Turing" se escribe "Alan ""Turing"""; las barras invertidas son otra convención y la mayoría de los importadores no las van a entender. Los campos con espacios al principio o al final también se entrecomillan aquí, algo que las reglas no exigen pero que te salva de los parsers que recortan en silencio los espacios sin comillas.

Un campo que lleva un salto de línea hace que una fila de CSV ocupe dos líneas del archivo. Eso es válido, y rompe cualquier cosa que lea el archivo línea a línea, que es la mayoría de los scripts rápidos.

Las reglas vienen del RFC 4180, publicado en 2005 y marcado como informativo: documentó lo que la gente ya hacía en vez de decirle a nadie qué hacer, y por eso los importadores siguen sin ponerse de acuerdo entre ellos. Las filas terminan en CRLF, como pide el RFC y como prefiere Excel. Las herramientas Unix leen eso sin quejarse, salvo que algunas dejan el retorno de carro pegado al último campo de cada fila. Si un importador que no controlas se sigue negando a aceptar el archivo, entrecomillar todos los campos es verboso y nunca está mal.

Por qué todas las columnas caen en la celda A1

Porque tu hoja de cálculo espera otro delimitador. Excel sigue el separador de listas del sistema, que es el punto y coma en buena parte de Europa y de América Latina, donde la coma ya es el separador decimal. Abre ahí un archivo delimitado por comas y la fila entera cae en la celda A1. Cambiar el delimitador a punto y coma lo arregla. El tabulador hace el mismo trabajo con muchas menos comillas, porque los tabuladores casi nunca aparecen dentro de datos reales.

Por qué los acentos llegan hechos basura

Si José se abre como José, el archivo está bien y quien lo lee está mal. Excel en Windows todavía abre un .csv normal usando la página de códigos heredada del sistema en lugar de UTF-8. Una marca de orden de bytes —tres bytes al principio del archivo— le dice lo contrario, y por eso el conversor de aquí escribe una en la descarga por defecto.

Déjala puesta para Excel. Quítala cuando el archivo vaya a un script, a un cargador de base de datos o a un pipeline de Unix, donde esos tres bytes acaban pegados al principio del nombre de tu primera columna y producen un error desconcertante. El BOM va solo en el archivo descargado, nunca en el texto que copias.

Qué cambia una hoja de cálculo en cuanto la abres

El CSV puede ser perfecto y la hoja de cálculo lo va a editar igual al entrar, porque abrir un archivo con doble clic la deja adivinar en cada columna.

• Los ceros a la izquierda desaparecen. El código postal 01234 se vuelve 1234 y el código de producto 007 se vuelve 7.
• Los números largos pierden el final. Excel guarda 15 dígitos significativos, así que un número de tarjeta de 16 dígitos o una referencia de pedido de 19 vuelven redondeados, muchas veces en notación científica.
• Todo lo que tenga forma de fecha se vuelve una fecha. En el formato de la configuración regional, que no es necesariamente aquel en el que se escribieron tus datos.

El arreglo es dejar de hacer doble clic. En Excel, usa Datos y luego Desde texto/CSV, y marca como Texto las columnas problemáticas durante la importación. En Google Sheets, usa Archivo y luego Importar, y desactiva la opción que convierte el texto en números, fechas y fórmulas. Nada de esto es culpa del archivo; el daño ocurre del otro lado.

Por qué una celda que empieza con = es un problema de seguridad

Una celda cuyo texto empieza con =, +, @, un tabulador o un signo menos que no sea el principio de un número se evalúa como fórmula en vez de mostrarse. Cuando los datos vinieron de usuarios, esa fórmula se ejecuta en la máquina de quien abra la exportación. Tiene nombre —CSV injection— y es una vía de ataque real, no una curiosidad.

El conversor cuenta esos campos y te dice cuántos hay. No los neutraliza, y es a propósito: el arreglo habitual es anteponer un apóstrofo, lo que corrompe el valor para todo lector del archivo que no sea una hoja de cálculo. Que esa concesión valga la pena depende de adónde vaya el archivo.

Qué se pierde en la conversión

Los tipos. CSV no tiene ninguno. 42, "42" y true se vuelven todos texto plano, y lo que lea el archivo después tiene que adivinarlos de vuelta. Esa adivinanza es donde convertir un CSV de vuelta a JSON se tuerce, y por eso una ida y vuelta de JSON a CSV a JSON no devuelve lo que tenías al principio.

Null. null y un string vacío salen los dos como una celda vacía; el CSV no los puede distinguir.

Los enteros muy grandes. Pasado 9007199254740991, JavaScript ya no puede guardar exacto cualquier número entero, así que un ID así de largo puede haberse redondeado al parsear el JSON: antes de que el CSV existiera, y sin nada en el CSV que lo delate. Los ID de ese tamaño tienen que ser strings en el JSON.

El tamaño. No hay streaming. El texto, el valor parseado y el CSV terminado están todos en memoria a la vez, así que unos pocos megabytes funcionan bien y cien no. Pasado ese punto —o pasada la segunda vez que lo haces— mejor escribe el script.

Última actualización 19 de septiembre de 2026