Cómo aplanar JSON anidado: reglas de claves combinadas

Contenido
Para llevar un objeto JSON muy anidado a Excel o CSV, primero tienes que convertir esa jerarquía de varios niveles en una estructura unidimensional de clave-valor que quepa en una sola tabla. A esa conversión se la llama aplanado (Flatten) de JSON y, al proceso inverso —devolver una estructura unidimensional al objeto anidado original—, desaplanado (Unflatten). Ambos son cálculos mecánicos que siguen reglas fijas, así que, si las conoces, puedes reproducirlos a mano incluso sin herramienta.
Resumen ① Las claves de un objeto anidado se combinan con la forma «clave padre + delimitador + clave hija» hasta formar una estructura unidimensional. ② Los arrays no son objetos, así que quedan fuera del aplanado y su valor se mantiene tal cual. ③ Si el carácter que eliges como delimitador ya aparece dentro de una clave original, al desaplanar esa clave se partirá en más trozos de lo que esperabas.
El problema de pasar un JSON anidado a una tabla
Las respuestas de una API o los archivos de configuración suelen tener objetos dentro de otros objetos. Por ejemplo, en {"user": {"name": "Kim Cheolsu", "address": {"city": "Seúl"}}} la información de dirección va envuelta una vez más dentro de la información del usuario.
Si pasas esa estructura tal cual a Excel o CSV, aparecen problemas. Una tabla solo admite un valor por celda, y si metes un elemento cuyo valor es un objeto completo, como address, las columnas no se crean bien o los valores se ven rotos.
Por eso hace falta una estructura unidimensional en la que la clave padre y la clave hija se unan en un solo nombre de columna, como address.city. El aplanado consiste precisamente en hacer esa conversión con reglas exactas, en lugar de rearmar todo a mano cada vez.
Las reglas para convertir a mano, sin herramientas
Flatten y Unflatten funcionan cada uno con una única regla recursiva. Si la sigues, puedes convertir a mano un JSON pequeño sin problema.
Regla de aplanado (Flatten)
Si el valor de una clave es un objeto puro (una forma {} que no es un array ni tampoco null), entras en él y subes cada clave hija al nivel superior con un nuevo nombre: «clave padre + delimitador + clave hija». Si el valor no es un objeto (arrays incluidos), lo escribes en el resultado con su clave original.
Supongamos que aplanamos el siguiente JSON usando el punto (.) como delimitador.
{"user": {"name": "Kim Cheolsu", "address": {"city": "Seúl"}}, "tags": ["a", "b"]}
user es un objeto, así que entramos en él. user.name es "Kim Cheolsu" y user.address vuelve a ser un objeto, así que entramos una vez más y user.address.city pasa a ser "Seúl". tags es un array, no un objeto, así que se mantiene tal cual.
{"user.name": "Kim Cheolsu", "user.address.city": "Seúl", "tags": ["a", "b"]}
Regla de desaplanado (Unflatten)
El sentido contrario consiste en dividir cada clave por el delimitador y luego recorrer esos fragmentos en orden para reconstruir el objeto anidado. Vas avanzando fragmento a fragmento, de izquierda a derecha, creando los niveles que no existan y colocando el valor original en el último fragmento.
Si desaplanamos los datos que acabamos de generar, user.address.city se divide en tres fragmentos —user, address y city—, se crea el objeto address dentro del objeto user y debajo se coloca city: "Seúl". user.name se une también bajo ese mismo objeto user, y la estructura anidada original queda restaurada exactamente igual.
Compruébalo con nuestra herramienta gratuita, Aplanador y Desanidador JSON.
El JSON que introduces no se envía a ningún servidor: el aplanado y la reestructuración se hacen solo dentro de tu navegador.

Los puntos que más confunden: arrays y elección del delimitador
Hay dos cosas que despistan con frecuencia. Una es que el resultado sale distinto de lo esperado cuando hay arrays, y la otra es que, por culpa del delimitador elegido, el resultado de Unflatten no coincide con el original.
Qué pasa cuando hay un array
Primero, los arrays. Aunque dentro de un array haya objetos, como en {"users": [{"name": "Kim Cheolsu"}, {"name": "Lee Younghee"}]}, el valor de users en sí es un array, así que queda excluido del aplanado. No se entra hasta el objeto {"name": "Kim Cheolsu"} que hay dentro del array para desplegarlo con índices del tipo users.0.name: bajo la clave users el array se mantiene completo, tal como estaba en el original.
| Forma del valor | Tratamiento al aplanar |
|---|---|
Objeto puro {} | Se entra de forma recursiva y las claves hijas se unen como clave padre + delimitador + clave hija |
Array [] (aunque contenga objetos) | No se recorre; el array original se conserva íntegro como valor |
| Cadena, número, booleano, null | Se conserva tal cual bajo su clave original |
Cuándo la elección del delimitador cambia el resultado
Ahora, el delimitador. El mismo carácter que se usa en Flatten para unir las claves se usa también en Unflatten para volver a dividirlas. Si ese carácter ya estaba presente en las claves de los datos originales, Unflatten cortará esas claves en más trozos de los que corresponde.
Por ejemplo, imagina que tienes datos planos con una clave que contiene un punto, como {"precio.won": 15000}. Si los desaplanas con el punto (.) como delimitador, se dividen en dos fragmentos, precio y won, y se crea un objeto anidado que no estaba en la intención original: {"precio": {"won": 15000}}.
Es lo que suele pasar cuando trabajas con claves que incluyen puntos, como números de versión (1.2.3), extensiones de archivo o nombres de dominio. En esos casos puedes evitar el problema eligiendo como delimitador un carácter que no aparezca en las claves originales, por ejemplo el guion bajo (_) o la barra (/).
En resumen
- El aplanado solo despliega de forma recursiva los objetos puros y crea claves nuevas con la forma «clave padre + delimitador + clave hija».
- Los arrays no son objetos, así que no se aplanan: aunque contengan objetos dentro, se conservan como valor tal cual estaban.
- El desaplanado es el proceso inverso: divide cada clave por el delimitador y reconstruye en orden los objetos anidados.
- Conviene elegir un delimitador que no aparezca en las claves originales para evitar separaciones no deseadas al hacer Unflatten.
- El texto con formato inválido se detecta en la etapa de JSON.parse y se muestra como error en lugar de convertirse.
El JSON que introduces no se envía a ningún servidor: el aplanado y la reestructuración se hacen solo dentro de tu navegador.
Preguntas frecuentes
¿También se aplanan los objetos que están dentro de un array?
No. Si el valor es un array, se considera que no es un objeto y queda excluido de la recursión. Aunque dentro del array haya objetos como {"name": "Kim Cheolsu"}, no se despliegan con índices del tipo users.0.name: el array se mantiene íntegro como valor.
¿Qué delimitador conviene elegir?
Puedes elegir entre el punto (.), la barra (/) y el guion bajo (_); el valor predeterminado es el punto. Si ese carácter ya aparece en los nombres de claves originales, al hacer Unflatten se pueden producir divisiones no deseadas, así que es más seguro escoger un carácter que no aparezca en las claves.
¿Qué pasa si el valor es null?
null no se considera un objeto puro, así que no entra en la recursión y se mantiene tal cual bajo su clave original. No se divide en claves hijas.
¿Qué pasa si introduzco un JSON inválido?
Si el formato hace fallar a JSON.parse (comillas faltantes, comas mal puestas, etc.), la conversión no se ejecuta, aparece un mensaje de error en rojo y el área de salida queda vacía. Conviene comprobar primero que el texto original sea un JSON válido.
Este artículo está adaptado de nuestro original en coreano. Leer el original en coreano