Cómo convertir JSON a CSV: aplanar arreglos de objetos en filas y columnas

Por qué importa la forma de tu JSON

El CSV es un formato plano y bidimensional: filas y columnas, nada más. El JSON es un árbol que puede anidar objetos dentro de objetos y arreglos dentro de arreglos. El caso limpio para la conversión es un arreglo de objetos de nivel superior, donde cada objeto es una fila y cada clave una columna. Todo lo más profundo debe reestructurarse antes de caber en una cuadrícula.

Como distintos objetos pueden llevar claves distintas, la fila de encabezado debe ser la unión de todas las claves vistas, no solo las del primer objeto. Si solo lees el primer registro, las columnas posteriores desaparecen sin aviso y el archivo queda desalineado.

Aplanar objetos y arreglos anidados

El truco estándar es la notación de punto. Un objeto como {"address":{"city":"Lagos"}} se convierte en una columna llamada address.city con el valor Lagos. El anidamiento puede ser tan profundo como quieras: user.address.city es perfectamente válido. Los arreglos se indexan por posición, así que tags con ["api","web"] se vuelve dos columnas, tags.0 y tags.1.

El aplanado funciona bien cuando los arreglos son cortos y de longitud fija. Cuando un arreglo puede crecer, las columnas indexadas explotan: un registro con cincuenta etiquetas produce cincuenta columnas. En ese caso suele ser más limpio conservar el arreglo como una sola cadena unida, como "api;web;csv", o dividir los datos en una segunda tabla relacionada.

Casos límite que rompen los convertidores ingenuos

El fallo más común son las comillas. Si un valor contiene el delimitador (normalmente una coma), una comilla doble o un salto de línea, debe ir entre comillas dobles, y cualquier comilla doble interna debe duplicarse. Así el valor She said "hi" se convierte en "She said ""hi""". Omitirlo corrompe todas las filas siguientes.

Otras trampas: null frente a cadena vacía (ambos suelen mostrarse como celda vacía), booleanos y números que una hoja de cálculo puede reinterpretar (un código con cero inicial como 007 puede perder sus ceros), y la codificación. Escribe siempre en UTF-8 y considera una marca de orden de bytes inicial si el archivo debe abrirse limpio en hojas de cálculo antiguas.

Preguntas frecuentes

¿Y si mi JSON es un único objeto, no un arreglo?

Envuélvelo en un arreglo para obtener un CSV de una fila. Si prefieres cada clave en su propia línea, transpónelo a dos columnas clave,valor.

¿Qué delimitador debo usar, coma o punto y coma?

La coma es el valor por defecto del estándar CSV. Algunas configuraciones regionales de hojas de cálculo esperan un punto y coma; si tus valores ya contienen comas, un punto y coma o una tabulación reduce el escapado.

¿Cómo evito que desaparezcan los ceros iniciales?

Los ceros están en el archivo CSV; la hoja de cálculo los elimina al tratar la columna como número. Importa la columna como texto, o la hoja la reformateará al abrir.

¿Puedo volver a convertir el CSV en JSON?

En parte. Las columnas planas se reconvierten limpio, pero las claves con notación de punto necesitan re-anidarse y el CSV pierde los tipos, así que números y booleanos vuelven como cadenas si no los reanalizas.