How to Flatten the JSON Data: explotar, unir o dejar anidado (Guía 2026)

Qué significa aplanar los datos JSON

CSV es plano: filas y columnas, nada más. JSON es un árbol: objetos dentro de objetos, listas dentro de objetos, objetos dentro de listas. Aprender how to flatten the JSON data es convertir ese árbol en una tabla sin perder la información que realmente necesitas. Cada herramienta de aplanado hace los mismos tres movimientos, y cuando puedes nombrarlos, cada herramienta se vuelve predecible.

Los tres movimientos son: los objetos anidados se convierten en columnas con notación de puntos (customer se convierte en customer.name y customer.city); las listas de valores simples se convierten en una celda unida (items se convierte en book; pen); y las listas que necesitas analizar se convierten en una fila por elemento, lo que se llama explotar. Qué movimiento se aplica a cada lista es toda la habilidad, y es una decisión, no un valor por defecto.

Una distinción importa antes que cualquier otra. Nuestra guía anterior sobre cómo aplanar JSON a CSV documenta exactamente lo que hace el interruptor de aplanado del convertidor de este sitio, celda por celda, incluidos sus casos límite. Esta guía trata sobre el trabajo en sí: tienes datos JSON anidados, quieres una tabla plana y puedes elegir cómo se aplana cada parte, en cualquier herramienta, incluidas las que no tienen ningún interruptor.

El ejemplo práctico: tres pedidos anidados

Cada ejemplo de esta guía usa el mismo ejemplo pequeño, tres pedidos con un objeto customer anidado, una lista items y una lista vacía en el tercer pedido. Lo bastante pequeño para comprobarlo a mano, lo bastante anidado para mostrar cada decisión.

orders.json, el ejemplo práctico

[
  { "orderId": "A-101", "customer": { "name": "Ana", "city": "Madrid" }, "items": ["book", "pen"], "total": 19.99 },
  { "orderId": "A-102", "customer": { "name": "Ken", "city": "Osaka" }, "items": ["lamp"], "total": 42.50 },
  { "orderId": "A-103", "customer": { "name": "Lina", "city": "Berlin" }, "items": [], "total": 7.25 }
]

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

Un objeto anidado tiene campos con nombre, así que aplanarlo es mecánico: baja por el árbol y une los nombres de las claves con puntos. customer.name guarda Ana, customer.city guarda Madrid, y el anidado original desaparece pero no se pierde nada, porque el nombre con puntos registra la ruta completa de vuelta a la fuente.

Este es el movimiento en el que todas las herramientas coinciden. El convertidor en línea lo hace, json_normalize de pandas lo hace, jq lo hace cuando nombras las rutas de forma explícita. La profundidad es el único criterio a decidir: uno o dos niveles de puntos siguen siendo legibles, cuatro niveles (a.b.c.d) suelen significar que estás aplanando una estructura que nunca fue pensada como fila de tabla, y ese es el tema de la sección sobre profundidad más abajo.

Paso 1 aplicado: objetos con puntos, listas unidas

orderId,customer.name,customer.city,items,total
A-101,Ana,Madrid,book; pen,19.99
A-102,Ken,Osaka,lamp,42.50
A-103,Lina,Berlin,,7.25

Paso 2: las listas cortas se convierten en una sola celda unida

Una lista de valores simples, textos o números sin anidado propio, se aplana en una sola celda uniendo los valores con un separador. El convertidor de este sitio une con punto y coma seguido de un espacio (book; pen). El punto y coma es una elección deliberada: las comas chocarían con el delimitador del CSV, mientras que un punto y coma dentro de una celda no crea ambigüedad y sobrevive a un viaje de ida y vuelta por Excel.

Unir mantiene una fila por registro, que es lo que quieres cuando la lista es contexto, no el tema. Etiquetas en un artículo, habilidades en un perfil, categorías en un producto: las leerás, quizá filtrarás por ellas, pero no sumarás ni contarás los valores individuales. Une esas listas.

Listas unidas: una fila por pedido, listas en una celda

orderId,items
A-101,book; pen
A-102,lamp
A-103,

Paso 3: explotar una lista en una fila por elemento

Explotar es el movimiento que la mayoría de la gente pasa por alto, porque la mayoría de los convertidores nunca lo ofrecen. En lugar de comprimir una lista en una celda, creas una fila por elemento y repites los campos del padre en cada fila. El pedido A-101, con dos elementos, se convierte en dos filas: una para book, otra para pen, cada una con Ana, Madrid y 19.99. Tres pedidos se convierten en cuatro filas, porque la lista vacía de A-103 todavía produce una fila con un elemento vacío, así que el pedido en sí nunca se descarta en silencio.

Explota cuando la lista es la unidad de análisis: líneas de pedido que vas a sumar, eventos que vas a contar, transacciones que vas a filtrar. Si unes esas listas en su lugar, los números por elemento quedan atrapados dentro de una celda de texto, y ninguna fórmula de hoja de cálculo los recupera de forma limpia. La regla práctica: si alguna vez vas a filtrar, contar o sumar sobre valores individuales dentro de la lista, explótala. Si la lista solo se lee como un todo, únela.

Explotado, el ejemplo práctico se convierte en cinco líneas incluida la cabecera: A-101 dos veces (book, luego pen), A-102 una vez (lamp), A-103 una vez con un elemento vacío. Los campos del pedido se repiten en cada fila, lo que parece redundante y es exactamente la idea: cada fila es ahora un hecho analizable.

¿Explotar o unir? Decide según lo que significa la lista

La decisión entre explotar o unir es el único punto donde el aplanado sale mal en silencio, porque ambas salidas parecen CSV válido. Una lista unida de líneas de pedido se abre bien en Excel, y nada te avisa de que los precios por elemento ahora son texto irrecuperable. Haz una pregunta por lista antes de aplanarla, y la elección se hace sola.

¿Voy a filtrar, contar o sumar sobre valores individuales dentro de esta lista? Si la respuesta es sí, explótala. Las líneas de pedido, los eventos, las transacciones y las mediciones pertenecen aquí.
¿La lista solo se lee como un todo? Si la respuesta es sí, únela. Las etiquetas, las categorías, las habilidades y los rótulos pertenecen aquí.
¿No estás seguro? Explota. Una tabla explotada siempre se puede agrupar de nuevo en celdas unidas, pero una celda unida no se puede dividir de forma fiable en filas, porque el separador también puede aparecer dentro de un valor.
¿La lista contiene objetos, no valores simples? Entonces ningún movimiento se aplica directamente: una lista de objetos se colapsa a una celda de texto JSON al unirla, o necesita que sus campos se conviertan en puntos antes de explotar. Consulta la sección sobre profundidad para ese caso.

¿Hasta qué profundidad debes aplanar?

Aplanar hasta las hojas parece exhaustivo, y produce las peores tablas: decenas de columnas con nombres de puntos de cuatro niveles, la mayoría vacías, ninguna legible. Aplana hasta la profundidad que realmente vas a usar. Si vas a filtrar u ordenar por un campo, dale una columna. Si solo lo vas a leer en contexto, deja ese subárbol como una celda de texto JSON.

Una regla práctica para detenerse: aplana dos o tres niveles de profundidad, y conserva cualquier cosa más profunda como texto JSON. Una lista de seguimiento con objetos de envío, por ejemplo, son datos reales, pero rara vez pertenecen a columnas: una celda de seguimiento con el texto JSON mantiene la tabla legible, y el archivo JSON original conserva el detalle completo. El CSV aplanado es una vista derivada de tus datos, no un reemplazo, así que conserva el archivo JSON original.

Datos irregulares: claves faltantes, listas vacías y nulos

El JSON real es irregular: un registro tiene un campo que el siguiente no tiene, una lista está vacía, un valor es nulo. El aplanado maneja los tres con la misma regla aburrida, y aburrido es lo que quieres: la fila de cabecera es la unión de cada clave encontrada en cualquier parte de los datos, y cualquier registro al que le falte una clave recibe una celda vacía ahí. Sin error, sin fila descartada, solo una celda vacía que puedes ver.

Las listas vacías y los nulos siguen la misma regla en ambos movimientos. Unida, una lista vacía se convierte en una celda vacía. Explotada, una lista vacía todavía produce una fila con un elemento vacío, así que el registro padre sobrevive. Un nulo dentro de una lista se convierte en un segmento vacío entre los separadores: una lista de mug, nulo y plate se une como mug; ; plate, con el hueco visible exactamente donde estaba el nulo.

Nulos y segmentos vacíos, verificados con el motor real

orderId,items
A-101,book; pen
A-103,mug; ; plate

Receta 1: Python, json_normalize más explode

Python con pandas es la ruta más flexible, porque json_normalize aplana los objetos y explode maneja las listas en dos líneas legibles. Al ejecutarlo sobre el ejemplo de tres pedidos, json_normalize produjo las columnas orderId, items, total, customer.name y customer.city, y explode sobre items convirtió 3 filas en 4, con la lista vacía dejando una fila con un elemento vacío. Esa es la misma salida que describe la sección de explotar, y puedes comprobarla fila por fila: A-101 aparece dos veces, A-102 una vez, A-103 una vez con el elemento vacío. Cuando el aplanado no es algo de una sola vez, esta receta es la que conviene guardar, porque el mismo guion cubre ambas decisiones con un cambio mínimo.

flatten.py, json_normalize más explode (verificado)

import json
import pandas as pd

rows = json.load(open('orders.json'))
df = pd.json_normalize(rows)
flat = df.explode('items')
flat.to_csv('orders-flat.csv', index=False)

Si quieres el movimiento de unir en lugar de explotar, omite la línea de explode: json_normalize deja la lista como lista, y una línea de unión la convierte en la celda separada por punto y coma. El mismo guion cubre por tanto ambas decisiones, y por eso es la receta a la que recurrir cuando el aplanado no es algo de una sola vez.

Receta 2: jq, explotar en un solo comando

jq explota una lista en un solo comando, sin archivo de guion y sin dependencias más allá del propio jq. La receta de abajo asocia cada pedido a una variable, comprueba si su lista items está vacía, y emite una fila con un elemento vacío o una fila por elemento. Al ejecutarla sobre el ejemplo práctico produjo exactamente la salida de cinco líneas descrita en la sección de explotar: A-101 dos veces, A-102 una vez, A-103 una vez con un elemento vacío. Es la opción más rápida cuando ya trabajas en la terminal y no quieres instalar nada más, y el resultado es fácil de redirigir a un archivo CSV.

jq: explotar items en una fila por elemento (verificado)

jq -r '. as $rows | (["orderId","name","city","item","total"] | @csv), ($rows[] | . as $o | if (.items | length) == 0 then [$o.orderId, $o.customer.name, $o.customer.city, "", $o.total] | @csv else (.items[] | [$o.orderId, $o.customer.name, $o.customer.city, ., $o.total] | @csv) end)' orders.json

La rama para listas vacías es la parte que la mayoría de las recetas de explotar con jq en línea omiten, y es la parte que pierde datos: sin ella, los pedidos sin elementos desaparecen de la salida por completo. Consérvala, incluso cuando tus datos actuales no tengan listas vacías, porque el siguiente archivo sí las tendrá.

Receta 3: Excel Power Query, sin código

Si tu destino es Excel de todos modos, Power Query aplana JSON sin ningún código. Importa con Datos, luego Obtener datos, luego Desde un archivo, luego Desde JSON, y Power Query muestra cada registro como una fila con las columnas anidadas todavía plegadas. Las dos operaciones de expandir se corresponden exactamente con los dos movimientos de lista de esta guía, y elegir la equivocada es el mismo error que en cualquier herramienta. Cuando termines de expandir, revisa que cada columna tenga el tipo correcto y que ninguna fila haya desaparecido por una lista vacía, porque Power Query puede ocultar ese caso si no miras con atención.

Expande una columna de registro (customer) con la flecha de expandir, luego marca los campos que quieres: name y city se convierten en columnas normales. Esto es el Paso 1.
Expande una columna de lista (items) con la flecha de expandir y elige Expandir a filas nuevas para explotarla: una fila por elemento, campos del padre repetidos. Esto es el Paso 3.
Expande una columna de lista y elige Extraer valores, con un separador de punto y coma y espacio, para unirla en una celda. Esto es el Paso 2.
Repite para cada columna anidada hasta que la tabla quede plana a la profundidad que necesitas, luego Cerrar y cargar.

Receta 4: el convertidor en línea, une pero nunca explota

El convertidor gratuito de este sitio aplana con su interruptor de aplanado activado: los objetos anidados se convierten en columnas con notación de puntos y las listas se unen en celdas separadas por punto y coma, exactamente los Pasos 1 y 2. Si desactivas el interruptor, los valores anidados quedan como texto JSON dentro de sus celdas, que es la opción de dejar anidado del título. Lo que el convertidor no hace es explotar: no existe ninguna opción que convierta un pedido en una fila por elemento.

Esa es una limitación honesta, no un error. Explotar cambia el número de filas, que es una decisión de modelado de datos, y un convertidor de un clic no debería tomarla en silencio. Si tu lista necesita explotar, usa la receta de Python o jq de arriba, y usa el convertidor para los muchos archivos donde unir es la decisión correcta.

Abrir el convertidor gratuito de JSON a CSV

¿Puedes desaplanarlo y volver atrás?

Aplanar es fácil de revertir para los objetos y difícil de revertir con exactitud para las listas explotadas, así que planifícalo. Las columnas con puntos se dividen de nuevo en objetos anidados con un guion pequeño, y no se pierde nada, porque los puntos registraron la ruta completa. Las filas explotadas se agrupan de nuevo con un agrupar por sobre la clave del padre, recogiendo los elementos en una lista otra vez, pero el orden original de los elementos sobrevive solo si conservaste un índice de fila, y las listas vacías originales no se distinguen de las faltantes.

La regla práctica se deduce de eso: nunca trates el CSV aplanado como tu única copia. Conserva el archivo JSON original, trata el CSV como una vista derivada construida para un análisis, y vuelve a aplanar desde el JSON cuando el análisis cambie. El almacenamiento es barato, y volver a derivar desde la fuente supera a depurar un CSV que ha perdido estructura en silencio.

Lista de verificación para aplanar

Antes de aplanar cualquier archivo JSON, repasa estas seis comprobaciones. Llevan un minuto, y detectan cada modo de fallo de esta guía.

Nombra primero la unidad de análisis: ¿una fila por pedido, por elemento o por evento? Esa respuesta elige explotar o unir para cada lista.
Aplana los objetos hasta la profundidad por la que vas a filtrar u ordenar, y deja los subárboles más profundos como texto JSON.
Revisa cada lista: los valores simples se unen o explotan sin problema, pero una lista de objetos necesita que sus campos se conviertan en puntos antes de que cualquier movimiento tenga sentido.
Espera datos irregulares: las claves faltantes se convierten en celdas vacías, las listas vacías se convierten en una fila o celda vacía, los nulos se convierten en segmentos vacíos.
Vigila los puntos dentro de los nombres de clave: una clave como version.2 choca con una ruta anidada del mismo nombre, y una de ellas gana en silencio.
Conserva el JSON original. El CSV aplanado es una vista derivada, no la fuente de verdad.

Guías relacionadas

Preguntas frecuentes

¿Qué significa aplanar datos JSON?

Significa convertir un árbol JSON anidado en una tabla plana de filas y columnas. Los objetos anidados se convierten en columnas con notación de puntos (customer.name), las listas de valores simples se unen en una celda (book; pen) o se explotan en una fila por elemento, y cualquier cosa que no aplanes queda como texto JSON en una celda.

¿Debo aplanar JSON anidado antes de convertirlo a CSV?

Sí, a menos que quieras texto JSON dentro de tus celdas CSV. CSV no tiene anidado, así que los datos anidados deben aplanarse, unirse o quedar como texto. Aplanar con el interruptor activado te da columnas reales que puedes filtrar y ordenar; dejarlo desactivado mantiene los valores anidados como texto JSON legible en celdas individuales.

¿Cómo aplanar un array JSON en filas, una por elemento?

Explótalo. En Python: pd.json_normalize(rows) y luego df.explode('items'). En jq: asocia cada registro a una variable y emite una fila por elemento, con una rama explícita para listas vacías para que los registros sin elementos no se descarten. Ambas recetas están en esta guía y se verificaron con el ejemplo práctico.

¿Cómo aplanar JSON en Python?

Usa pandas: carga el archivo con json.load, pd.json_normalize(rows) para aplanar objetos anidados en columnas con notación de puntos, luego une las columnas de lista con un separador o usa df.explode('items') para obtener una fila por elemento. Para objetos anidados sin pandas, una función recursiva pequeña que construye claves con puntos hace el mismo trabajo.

¿Cómo aplanar JSON en Excel?

Usa Power Query: Datos, Obtener datos, Desde un archivo, Desde JSON. Expande las columnas de registro para aplanar objetos anidados, y expande las columnas de lista con Expandir a filas nuevas para explotar o Extraer valores para unir. Repite por cada columna anidada, luego Cerrar y cargar.

¿Qué pasa con las listas vacías y los nulos al aplanar JSON?

Se convierten en celdas vacías o segmentos vacíos, nunca en errores. Una clave faltante da una celda vacía, una lista vacía se une en una celda vacía o se explota en una fila con un elemento vacío, un nulo se convierte en una celda vacía, y un nulo dentro de una lista se convierte en un segmento vacío entre separadores (mug; ; plate).

¿Puedo aplanar JSON en línea sin instalar nada?

Sí. Pega JSON o sube un archivo a un convertidor gratuito en línea con el aplanado activado: los objetos anidados se convierten en columnas con notación de puntos y las listas se unen en una celda. Si necesitas explotar una lista en una fila por elemento, usa en su lugar la receta de Python o jq de esta guía, porque los convertidores en línea unen las listas y no las explotan.

¿JSON anidado? Aplánalo en el navegador, gratis

Pega JSON o sube un archivo: los objetos anidados se aplanan a columnas con notación de puntos, las listas se unen en celdas limpias y la descarga es UTF-8 simple. Gratis, sin registro, se ejecuta por completo en tu navegador.

Abrir el convertidor de JSON a CSV

Todas las guías