JSON anidado a CSV

Los objetos anidados se vuelven columnas con puntos

La conversión baja hasta cada valor hoja y nombra la columna según el camino recorrido. Un city dentro de addr dentro de user se convierte en una columna llamada user.addr.city. No hay límite de profundidad, así que el número de columnas crece con la forma de tus datos, no con la cantidad de claves del nivel superior.

Esta parte se comporta bien y en principio es reversible: los puntos registran la estructura de la que partiste.

[
  { "id": 1, "user": { "name": "Ada", "addr": { "city": "London" } } },
  { "id": 2, "user": { "name": "Alan", "addr": { "city": "Wilmslow" } } }
]

id,user.name,user.addr.city
1,Ada,London
2,Alan,Wilmslow

Los arrays son la parte difícil

Un array no tiene nombres para sus miembros, solo posiciones, así que no hay un nombre de columna honesto que derivar. El conversor trata los dos casos de forma distinta, y conviene conocer la diferencia antes de confiar en la salida.

Un array de valores simples se colapsa en una sola celda, unido con punto y coma más espacio:

[
  { "id": 1, "tags": ["a", "b"] },
  { "id": 2, "tags": ["c"] }
]

id,tags
1,a; b
2,c

Los arrays de objetos generan columnas indexadas

Cuando el array contiene objetos, cada posición recibe su propio conjunto de columnas, numeradas por índice. Es fiel — no se fusiona nada — pero el número de columnas lo fija la fila más larga de todo el conjunto de datos.

Mira la fila 2: tiene un solo item, así que cuatro de sus celdas quedan vacías. Con un pedido de 50 líneas en un archivo de 10.000 pedidos, cada otra fila arrastra 49 grupos de columnas en blanco.

[
  { "id": 1, "items": [{ "sku": "x", "qty": 2 }, { "sku": "y", "qty": 1 }] },
  { "id": 2, "items": [{ "sku": "z", "qty": 5 }] }
]

id,items[0].sku,items[0].qty,items[1].sku,items[1].qty
1,x,2,y,1
2,z,5,,

Las claves faltantes se alinean, no desplazan

En datos reales rara vez todos los registros llevan las mismas claves. La cabecera es la unión de todas las claves vistas, en orden de primera aparición, y al registro que le falte una le corresponde una celda vacía en lugar de una fila desplazada.

Este es el comportamiento que quieres, y vale la pena comprobarlo en cualquier conversor: la implementación ingenua toma las claves del primer registro como cabecera y descarta en silencio todo campo que aparezca más adelante.

[
  { "id": 1, "name": "Ada" },
  { "id": 2, "email": "a@b.c" }
]

id,name,email
1,Ada,
2,,a@b.c

Respuestas envueltas, y cuándo se detiene el desenvuelto

Las respuestas de API suelen poner las filas dentro de un sobre. Cuando exactamente una propiedad del objeto de nivel superior es un array, ese array se toma como las filas, así que puedes pegar una respuesta sin reformarla antes.

{ "items": [{ "a": 1 }, { "a": 2 }] }

a
1
2

Con dos arrays no se adivina

Con dos arrays no hay forma de saber cuál contiene las filas, así que el conversor deja de adivinar y aplana el objeto entero como un único registro. El resultado es una fila muy ancha, que casi con seguridad no es lo que querías — y eso es el punto: está visiblemente mal en lugar de silenciosamente medio bien.

Si ves una sola fila de columnas indexadas, elige el array que querías y convierte ese.

{ "items": [{ "a": 1 }], "other": [{ "b": 2 }] }

items[0].a,other[0].b
1,2

Comillas y el problema de las fórmulas

Una celda se entrecomilla cuando contiene el delimitador, una comilla o un salto de línea — las reglas estándar de CSV, con las comillas internas duplicadas.

Una adición que conviene conocer: una celda que empieza por =, +, - o @ también se entrecomilla. Esos caracteres hacen que Excel y Google Sheets traten la celda como una fórmula, que es cómo una exportación CSV acaba ejecutando código en la máquina de otra persona. Entrecomillar es la mitad barata de la solución.

[{ "formula": "=1+1", "note": "a,b", "q": "say \"hi\"" }]

formula,note,q
"=1+1","a,b","say ""hi"""

Lo que no puedes recuperar

Convertir de vuelta produce claves planas, no el anidamiento del que partiste. Los puntos sobreviven como caracteres literales en el nombre de la clave: nada los vuelve a montar como objetos, porque un lector CSV corriente no tiene forma de saber si user.name era un campo anidado o una columna que de verdad llevaba un punto en el nombre.

• —Los tipos se vuelven a adivinar en el regreso. Un 01234 en una celda CSV se parsea como el número 1234, igual que en YAML sin comillas. Los códigos postales y los identificadores de cuenta son las víctimas habituales.
• —`null` y la cadena vacía se vuelven lo mismo. Ambos son una celda vacía, y una celda vacía se relee como cadena vacía.
• —Los arrays no vuelven. Una celda a; b es una cadena con un punto y coma, no una lista.

id,user.name
1,Ada

[
  {
    "id": 1,
    "user.name": "Ada"
  }
]

Consejo práctico

Trata CSV como formato de exportación, no de almacenamiento. Es la respuesta correcta cuando el destino es una hoja de cálculo, una herramienta de BI o una persona; es la respuesta equivocada cuando piensas releer los datos como JSON más adelante.

• —Convierte el array del que realmente quieres filas, no el sobre que lo envuelve.
• —Si los arrays dentro de tus registros varían de longitud, dale la vuelta a la forma: una fila por elemento, repitiendo los campos del padre.
• —Revisa la fila de cabecera antes de confiar en un archivo: te dice exactamente qué hojas encontró el aplanado.
• —Conserva el JSON original. Es la única copia que todavía conoce los tipos y la estructura.