Arrays y objetos JSON: estructura y anidamiento para principiantes
En resumen: JSON solo tiene dos contenedores: el objeto para campos nombrados, el array para listas ordenadas. Aprende a combinarlos, a elegir el correcto y a corregir los tres errores más frecuentes: falsos arrays con claves numéricas, coma final y apóstrofos.

JSON solo te da dos contenedores: el objeto lleva campos nombrados, el array lleva listas ordenadas — y casi todo payload roto se explica por comillas, comas, o una lista escrita como un falso objeto.
Uno: JSON solo tiene dos contenedores
Por compleja que sea una respuesta de API, todo se reduce a dos contenedores y seis tipos de valor. Un objeto es una colección de pares clave/valor envuelta en llaves {}; un array es una lista ordenada de valores envuelta en corchetes []. Un valor puede ser una cadena, un número, true, false, null — u otra vez un objeto o un array. Objetos dentro de arrays, arrays dentro de objetos: esa recursión es toda la potencia expresiva de JSON.
{
"user": { "name": "Ada", "active": true },
"roles": ["admin", "editor"],
"lastLogin": null,
"loginCount": 42
}
De ahí una consecuencia práctica: ante un payload confuso, no lo leas carácter por carácter. Comprueba primero si el carácter más externo es { o [. Si es un objeto, léelo como campos nombrados; si es un array, léelo como lista y luego baja nivel por nivel. El diagrama de sintaxis de json.org cabe en una sola página precisamente porque dos estructuras más recursión cubren todo.
Dos: escribir objetos, cuatro reglas duras
Los objetos son donde los principiantes más fallan, pero las reglas se reducen a cuatro:
- Las claves deben ser cadenas entre comillas dobles.
{name: "Ada"}y{'name': 'Ada'}son ambos inválidos; hay que escribir{"name": "Ada"}. Los literales de objeto de JavaScript permiten claves desnudas y apóstrofos, JSON no — esa es la confusión más común entre ambos. - Separa los pares con comas y nunca dejes coma después del último.
{"a": 1, "b": 2,}falla conUnexpected token }en la llave de cierre. - Las claves deben ser únicas. RFC 8259 lo formula como SHOULD, no MUST: las claves duplicadas no provocan error, pero conservar el primer o el último valor depende de la implementación, y los lenguajes difieren. Nunca confíes en eso.
- El orden de las claves no tiene significado.
{"a":1,"b":2}y{"b":2,"a":1}son el mismo objeto; las herramientas de diff y las funciones de comparación ignoran el orden de las claves. Si el orden importa, los datos pertenecen a un array.
Tres: escribir arrays, el orden es un dato
Los arrays guardan valores por posición, y la indexación empieza en 0: en ["admin", "editor"], la cadena "editor" es el [1]. Ese orden es significativo — es la diferencia esencial entre arrays y objetos. Resultados de búsqueda ordenados por relevancia, entradas de log ordenadas por fecha: esa información solo vive en la secuencia, y convertirla en objeto la destruye.
Dos recomendaciones prácticas. Primero, mantén los elementos homogéneos: [{"id":1},{"id":2}] es mucho más fácil de consumir que [1, "text", true], que es legal pero obliga a cada consumidor a comprobar tipos en cada paso. Segundo, un array vacío [] es un valor perfectamente válido — cuando un campo de lista aún no tiene contenido, emite [] en lugar de null, para que el consumidor no tenga que comprobar existencia y luego vacío.
[
{ "city": "Tokyo", "population": 13960000 },
{ "city": "Delhi", "population": 16780000 }
]
Cuatro: el anidamiento, las cuatro formas de los payloads reales
Los datos reales son solo estos dos contenedores anidados uno dentro del otro, y los patrones se reducen a cuatro formas:
| Forma | Cómo se ve | Uso típico |
|---|---|---|
| Objeto que contiene un array | {"tags": ["a","b"]} |
Campo de lista de una entidad |
| Array de objetos | [{"id":1},{"id":2}] |
Listas de registros, resultados paginados |
| Objeto que contiene un objeto | {"db": {"host": "..."}} |
Configuración agrupada, bloques de dirección |
| Array de arrays | [[1,2],[3,4]] |
Matrices, filas de tabla |
Una respuesta típica de API usa un objeto como envoltorio y un array como contenido:
{
"code": 0,
"data": {
"items": [
{ "id": 1, "title": "first" },
{ "id": 2, "title": "second" }
],
"page": 1,
"total": 2
}
}
No anides por anidar. Más allá de tres o cuatro niveles, las rutas de acceso se vuelven ilegibles y el código consumidor crece en paralelo. Los campos que siempre viajan juntos pertenecen a un subobjeto: sustituye addrCity y addrZip por address: {city, zip}.
Cinco: ¿objeto o array?, una tabla de decisión
| Pregunta | Respuesta | Por qué |
|---|---|---|
| ¿Cada valor tiene un nombre? | Objeto | Acceso por clave; añadir o quitar campos no rompe nada |
| ¿Es una lista de registros parecidos? | Array | El orden importa; se puede mapear y filtrar |
| ¿Necesitas búsqueda rápida por clave? | Objeto indexado por identificador | Acceso O(1) en vez de un recorrido |
| ¿Varios atributos de una misma entidad? | Objeto | Los atributos no tienen orden propio |
| ¿Colección creciente de elementos parecidos? | Array | La longitud se estira libremente |
Un antipatrón merece mención especial: imitar un array con un objeto cuyas claves son "0", "1", "2". Se parsea sin error, pero pierdes la semántica de longitud y las herramientas de iteración de un array verdadero, y los consumidores tienen que ordenar Object.keys antes de leer nada. Si las claves son números secuenciales, escribe un array de verdad. También vale el inverso: una lista de pares clave/valor como [{"key":"theme","value":"dark"}] es inferior al objeto {"theme": "dark"} — salvo que las claves sean realmente dinámicas y no se puedan declarar por adelantado.
Seis: tres errores frecuentes y sus mensajes
| Forma errónea | Error típico | Corrección |
|---|---|---|
Coma final {"a":1,} |
Unexpected token } |
Quitar la última coma |
Apóstrofos / claves desnudas {name:'Ada'} |
Unexpected token ' / Expected property name |
Comillas dobles para claves y cadenas, siempre |
Literales de Python True / None |
Unexpected token T |
Sustituir por true / null |
| Falso array con claves numéricas | Sin error, semántica errónea | Reescribir como array verdadero |
Dos hábitos de depuración: los parsers suelen señalar una posición después del carácter culpable, así que cuando ves position 42, mira uno o dos caracteres atrás; y un JSON enorme en una sola línea debe formatearse primero — los números de línea y columna ganan a los offsets de caracteres siempre. El catálogo completo de errores está en la tabla de búsqueda de errores JSON, y el flujo de triaje paso a paso en cómo corregir errores de parseo de JSON.
Siete: después de escribir, valida la estructura
Un JSON escrito a mano debe pasar siempre por un parser antes de entregarse. La comprobación más ligera cabe en una línea de comandos:
python3 -m json.tool config.json > /dev/null && echo OK
jq empty config.json && echo OK
En línea, pega el contenido en la página de formateo y validación de JSON — los errores de sintaxis vuelven con línea y columna. Cambia a la vista de árbol para ver el tipo de cada nivel de un vistazo: si un número se interpretó como cadena, si las longitudes de los arrays coinciden. Y cuando la audiencia no es técnica, un payload de array-de-objetos se puede desplegar en filas y columnas en la página de JSON a tabla, lo que de paso verifica que tus datos forman de verdad una lista regular de registros.
Las preguntas sobre el campo que debería haber sido un array, o sobre rehacer un anidamiento demasiado profundo, pertenecen al modelado de tipos — la siguiente lectura es seis tipos, precisión numérica y trampas de codificación.
¿Se pueden convertir arrays y objetos JSON uno en otro?
Sí, pero no sin pérdidas. Convertir un objeto en array suele significar transformar las claves en valores y perder el acceso por clave; convertir un array en objeto exige inventar una clave para cada elemento, y el origen de esas claves es un nuevo problema de diseño. Decide por cómo lee los datos el consumidor, no por comodidad sintáctica.
¿Pueden duplicarse las claves de un objeto?
Sintácticamente sí — RFC 8259 solo dice que las claves DEBERÍAN ser únicas. Pero JavaScript conserva el último valor mientras algunas bibliotecas de la familia C conservan el primero: el comportamiento difiere entre parsers. En firmas, diffs o hashes, las claves duplicadas causan discrepancias directas. Evítalas en el lado productor y trata los duplicados de una fuente desconocida como riesgo en el lado consumidor.
¿Puede un array contener valores de tipos distintos?
Sintácticamente sí: [1, "a", true] es un JSON válido. Pero los arrays heterogéneos obligan a comprobaciones de tipo en cada posición del código consumidor, y son difíciles de expresar en un schema. Salvo en matrices y tuplas, donde la posición es la semántica, mantén los arrays homogéneos.
¿Por qué {name:'json'} falla la validación?
Porque JSON exige comillas dobles alrededor de cada clave y de cada valor cadena. {name:'json'} es un literal de objeto de JavaScript, no JSON. Sustitúyelo por {"name": "json"} y la validación pasa. Los apóstrofos, las claves desnudas y los comentarios pertenecen a dialectos como JSON5/JSONC, que requieren parsers propios en lugar del JSON.parse estándar.