Cómo aplanar JSON a CSV: qué hace realmente esa opción (Guía 2026)

Por qué JSON se resiste a lo plano: árboles contra cuadrículas

Un CSV es una cuadrícula: filas y columnas, cada celda con un solo valor plano. JSON es un árbol: objetos dentro de objetos, listas dentro de objetos, objetos dentro de listas. Aplanar es la traducción entre esas dos formas, y es la única parte de la conversión de JSON a CSV donde el convertidor tiene que tomar decisiones de juicio por ti — porque no existe una única respuesta \"correcta\".

Toma el registro anidado más simple: { \"id\": 1, \"customer\": { \"name\": \"Ana\", \"city\": \"Madrid\" } }. Una cuadrícula no tiene forma de contener un \"customer\" que incluye dos cosas. Así que el convertidor debe elegir: darle a customer su propia columna y meter el objeto como texto, o explotar el objeto en columnas customer.name y customer.city. Cada convertidor toma esta decisión con el mismo puñado de reglas — y una vez que las conoces, puedes predecir tu CSV antes de pulsar convertir.

El ejemplo que usaremos para aplanar

Todo lo que sigue se demuestra con un solo archivo: tres pedidos con tres niveles de anidación, una lista de valores simples, una lista vacía, un objeto vacío, un null y una lista de objetos. Pasamos este archivo exacto por el motor de conversión real de este sitio (el mismo JavaScript que se ejecuta cuando pulsas Convertir), y cada salida mostrada es lo que el motor realmente produjo:

orders-nested.json

[
  { "orderId": "A-101", "customer": { "name": "Ana Ruiz", "contact": { "email": "ana@example.com", "city": "Madrid" } }, "items": ["book", "pen"], "tags": [], "meta": {} },
  { "orderId": "A-102", "customer": { "name": "Ken Sato", "contact": { "email": "ken@example.com", "city": "Osaka" } }, "items": ["lamp"], "tracking": [{ "code": "TX-1", "status": "shipped" }, { "code": "TX-2", "status": "pending" }] },
  { "orderId": "A-103", "customer": { "name": "Lina Noor", "contact": { "email": null, "city": "Berlin" } }, "items": ["mug", null, "plate"] }
]

Regla 1: los objetos anidados se convierten en columnas con notación de puntos

La primera y más importante regla: cada nivel de anidación de objetos se convierte en un nombre de columna con los niveles unidos por puntos. customer.contact.email no son tres columnas: es una columna cuyo nombre es la ruta completa hacia abajo en el árbol. Aquí está la salida real del motor con el aplanado activado:

CSV output — flattening ON (verified against the real engine)

orderId,customer.name,customer.contact.email,customer.contact.city,items,tags,meta,tracking
A-101,Ana Ruiz,ana@example.com,Madrid,book; pen,,{},
A-102,Ken Sato,ken@example.com,Osaka,lamp,,,"[{""code"":""TX-1"",""status"":""shipped""},{""code"":""TX-2"",""status"":""pending""}]"
A-103,Lina Noor,,Berlin,mug; ; plate,,,

La profundidad de anidación no tiene límite práctico en la regla en sí: también probamos un objeto de cuatro niveles ({ a: { b: { c: { d: \"deep\" } } } }) y el motor produjo una sola columna llamada a.b.c.d con el valor deep. Los nombres con puntos se ordenan y filtran normalmente en una hoja de cálculo; después puedes renombrar los encabezados de una sola pasada si customer.contact.city te parece demasiado largo.

Regla 2: las listas de valores simples se unen en una celda

Cuando una lista contiene solo valores simples — cadenas, números, booleanos, nulos — la lista completa se colapsa en una sola celda con los valores unidos por \"; \" (punto y coma-espacio). Mira la columna items de arriba: [\"book\", \"pen\"] se convirtió en la celda única book; pen, y [\"mug\", null, \"plate\"] se convirtió en mug; ; plate — el null se volvió un segmento vacío, no uno omitido.

Dos consecuencias prácticas. Primera: si después eliges el punto y coma como delimitador del CSV, esa celda unida se pone entre comillas automáticamente (\"book; pen\") para que el separador dentro de la celda no la divida — el motor aplica las reglas de comillas del CSV por celda, verificado en la prueba de arriba. Segunda: al unir se pierde la información de los límites: después de aplanar, book; pen es texto, no una lista. Si necesitas dividir los elementos de nuevo en filas, consulta la Regla 3.

Regla 3: las listas de objetos se colapsan en una celda de texto JSON

Esta es la regla que sorprende a la gente. Cuando una lista contiene objetos — como el array tracking con sus entradas { code, status } — no puede convertirse en columnas (los objetos tienen estructura, no solo valores) ni unirse como valores simples. Así que el motor guarda la lista completa como una celda de texto JSON entre comillas. Arriba, la columna tracking de A-102 contiene el array JSON completo como texto, escapado según las reglas del CSV.

¿Es eso una limitación? Honestamente: sí, para esta forma. Este convertidor no tiene opción de expansión de filas — nunca crea una fila CSV por elemento de la lista. Si realmente necesitas una fila por evento de tracking, reestructura antes de convertir: extrae el array interno (convierte [{ \"code\": \"TX-1\", \"status\": \"shipped\" }, ...] por separado) y obtendrás filas limpias de code/status. Una columna de texto JSON es la alternativa honesta a inventar silenciosamente filas que no pediste.

Regla 4: los vacíos y los nulls siguen reglas exactas

Los nulos y los vacíos son donde empieza la mayor parte de la confusión del tipo \"por qué mi CSV se ve raro\", así que aquí están los comportamientos verificados, sin adivinanzas:

Un valor null se convierte en una celda vacía. El email: null de Lina Noor produjo una celda vacía bajo customer.contact.email — sin texto \"null\", sin comillas.
Una lista vacía se convierte en una celda vacía. El tags: [] de A-101 dejó la celda en blanco. (Nota: este es el comportamiento con el aplanado ACTIVADO; con el aplanado desactivado la misma lista aparece como el texto literal [].)
Un objeto vacío se convierte en el texto {}. El meta: {} de A-101 produjo una celda con {} — el motor no tiene nada que expandir, así que escribe la forma literal del objeto.
Un null dentro de una lista se convierte en un segmento unido vacío — mug; ; plate de arriba — en lugar de omitirse o escribirse como \"null\".

Estas son decisiones de diseño, no una ley universal, pero son consistentes: null significa \"aquí no hay nada\", y el CSV no dice nada.

Aplanado ACTIVADO frente a DESACTIVADO, byte por byte

Mismo archivo, aplanado desactivado. Cada clave de nivel superior conserva su propia columna y las estructuras anidadas se guardan como texto JSON entre comillas:

CSV output — flattening OFF (verified against the real engine)

orderId,customer,items,tags,meta,tracking
A-101,"{""name"":""Ana Ruiz"",""contact"":{""email"":""ana@example.com"",""city"":""Madrid""}}","[""book"",""pen""]",[],{},
A-102,"{""name"":""Ken Sato"",""contact"":{""email"":""ken@example.com"",""city"":""Osaka""}}","[""lamp""]",,,"[{""code"":""TX-1"",""status"":""shipped""},{""code"":""TX-2"",""status"":""pending""}]"
A-103,"{""name"":""Lina Noor"",""contact"":{""email"":null,""city"":""Berlin""}}","[""mug"",null,""plate""]",,,

Fíjate en los detalles del modo desactivado: las columnas se reducen a las claves de nivel superior (customer, items, tags, meta, tracking), cada valor anidado se convierte en JSON sin procesar con duplicación de comillas según el CSV, y la lista vacía y el objeto vacío aparecen como texto literal [] y {}. Desactivado es la representación honesta pero fea — correcta cuando necesitas preservar la estructura anidada exacta (por ejemplo, antes de devolver las filas a un sistema que espera campos con forma de JSON). Para el análisis — filtros, tablas dinámicas, gráficos — el aplanado activado es la opción correcta, y por eso es el valor por defecto.

De dónde salen las filas: arrays, envoltorios de API y JSON Lines

Aplanar decide las columnas; algo más decide las filas. El motor mira tu valor de nivel superior y sigue tres casos:

Caso uno: tu nivel superior es un array de objetos — cada objeto se convierte en una fila. Este es el ejemplo de los pedidos de arriba: tres objetos, tres filas. Caso dos: tu nivel superior es un solo objeto — obtienes una fila. El caso tres es el más útil: tu nivel superior es un objeto que envuelve un array, como hacen las respuestas de API — { \"data\": [ ... ], \"total\": 2 }. El motor detecta el array interno (revisa claves de envoltorio comunes como data, results, users, items) y convierte cada elemento en una fila, descartando los campos del envoltorio. Lo verificamos: { \"data\": [{ \"a\": 1, \"b\": 2 }, { \"a\": 3, \"b\": 4 }], \"total\": 2 } produjo exactamente las dos filas de datos con columnas a y b — total desapareció.

Otra forma de entrada que vale la pena conocer: el motor también acepta JSON Lines (NDJSON) — un objeto JSON por línea. Si tu exportación son diez mil líneas en lugar de un array grande, pégalo tal cual; se convierte de la misma manera.

Datos irregulares: las claves faltantes solo dejan celdas vacías

Las exportaciones reales son irregulares: el pedido A-102 tiene tracking pero no meta, A-101 tiene meta pero no tracking, A-103 no tiene ninguno. El motor construye la lista de columnas como la unión de cada clave encontrada en cada fila, en orden — por eso la fila de encabezados de arriba tiene las ocho columnas — y cualquier fila a la que le falte una clave simplemente obtiene una celda vacía debajo.

Por eso los encabezados salen en orden de inserción (orderId primero, luego las claves anidadas vistas primero) en lugar de orden alfabético: las columnas siguen la forma de tus datos a medida que el motor los recorre. Si una fila posterior introduce una ruta anidada completamente nueva, la columna aparece de todos modos — nada se descarta en silencio.

Tres casos límite que muerden

Primero: claves que ya contienen puntos. Si tu JSON tiene tanto una clave literal \"user.name\" como un objeto anidado user: { name: ... }, ambos quieren la misma columna. Lo probamos: el valor anidado gana y el valor de la clave literal se pierde ([{ \"user.name\": \"x\", user: { name: \"y\" } }] produjo una columna user.name con el valor y). Renombra las claves con puntos antes de convertir si ambos valores te importan.

Segundo: listas de tipos mixtos. Una lista como [1, \"a\", { \"b\": 2 }] no es \"todo primitivas\", así que el motor la trata como una lista de objetos y convierte el todo en una celda de texto JSON — aunque la mayor parte fuera simple. Mantén las listas homogéneas si quieres el comportamiento de unión con \"; \".

Tercero: la anidación profunda está bien, pero vigila los nombres de las columnas. Diez niveles de anidación te dan un nombre de columna de diez partes con puntos, que es técnicamente correcto y prácticamente ilegible. Aplana todo y luego renombra las tres columnas que de verdad te importan.

La lista de verificación de 30 segundos para aplanar

Si no recuerdas nada más: deja el aplanado activado para el análisis, desactívalo solo para preservar la estructura; espera columnas con notación de puntos y listas unidas con \"; \"; extrae las listas de objetos y conviértelas por separado cuando necesites una fila por elemento; y trata las celdas vacías como la representación honesta de los nulos — no como errores. La opción es un clic, pero ahora sabes exactamente qué hace ese clic.

Guías relacionadas

Preguntas frecuentes

¿Qué significa aplanar JSON a CSV?

Aplanar es el paso que convierte JSON anidado en una cuadrícula plana de hoja de cálculo: los objetos anidados se vuelven columnas con notación de puntos (customer.contact.city), las listas de valores simples se unen en una celda con \"; \" y las listas de objetos se colapsan en una sola celda de texto JSON. Sin aplanar, los valores anidados se guardan como texto JSON sin procesar entre comillas, una columna por cada uno.

¿Cómo convierto objetos JSON anidados en columnas CSV?

Usa un convertidor con opción de aplanado y déjala activada — los objetos anidados se expanden automáticamente a columnas con notación de puntos, a cualquier profundidad (customer.contact.email, o incluso a.b.c.d). En el convertidor de este sitio el aplanado viene activado por defecto: pega o sube tu JSON, convierte, y cada ruta anidada se convierte en su propia columna ordenable y filtrable.

¿Qué pasa con los arrays al aplanar JSON a CSV?

Depende de lo que contenga el array. Las listas de valores simples (cadenas, números) se unen en una sola celda con \"; \" — [\"book\", \"pen\"] se vuelve book; pen. Las listas de objetos se guardan como una celda de texto JSON entre comillas, porque los objetos no pueden volverse valores planos. Las listas vacías se convierten en celdas vacías. Las listas mixtas se convierten en texto completo, así que mantén las listas homogéneas para resultados predecibles.

¿Por qué mi CSV aplanado tiene tantas celdas vacías?

Las celdas vacías son normales y honestas: un valor null se convierte en una celda vacía, una lista vacía se convierte en una celda vacía, y cuando las filas tienen claves distintas (datos irregulares) las claves faltantes dejan espacios en blanco. Revisa si los vacíos coinciden con los nulos de tu JSON fuente — si es así, la conversión es correcta.

¿Debo activar o desactivar el aplanado al convertir JSON a CSV?

Déjalo activado para el análisis — las columnas con notación de puntos son lo que necesitan las tablas dinámicas, los filtros y los gráficos. Desactívalo solo cuando debas preservar la estructura anidada exacta, por ejemplo antes de devolver las filas a un sistema que espera campos con forma de JSON. El modo desactivado guarda cada valor anidado como texto JSON sin procesar entre comillas, lo cual es correcto pero inservible para hojas de cálculo.

¿Puedo obtener una fila CSV por elemento en un array anidado de objetos?

Este convertidor no expande las listas de objetos en filas — las guarda como una celda de texto JSON. La solución confiable: extrae el array interno y conviértelo por separado (por ejemplo convierte solo [{\"code\":\"TX-1\"},{\"code\":\"TX-2\"}]) para obtener una salida limpia de una fila por elemento. Haz la extracción antes de convertir, no después.

¿Hay una herramienta gratuita que aplane JSON a CSV en línea?

Sí — el convertidor de este sitio es gratuito, no pide registro y aplana JSON anidado por defecto (columnas con notación de puntos, listas unidas con \"; \") por completo en tu navegador, así que tus datos nunca salen de tu dispositivo. Sube un archivo o pega JSON, deja el aplanado activado, elige tu delimitador y descarga el CSV.