Objeto JSON vs array: diferencias y cuál debe ir en la raíz

Respuesta breve

Un objeto JSON agrupa pares de nombre y valor entre {}; un array conserva una secuencia ordenada de valores entre []. Ambos pueden ocupar la raíz de un documento JSON válido, pero no son intercambiables: la API o el proceso de destino decide cuál representa correctamente el contrato.

La diferencia estructural

Un objeto identifica cada dato mediante un nombre:

{
  "id": 42,
  "nombre": "Ada"
}

Un array identifica elementos por su posición:

[
  { "id": 42, "nombre": "Ada" },
  { "id": 43, "nombre": "Linus" }
]

Los nombres de un objeto deberían ser únicos. El orden visible de sus miembros no debe transportar significado. En cambio, el orden de los elementos de un array sí forma parte de la secuencia y un mismo valor puede repetirse.

Qué estructura debe ir en la raíz

Usa un objeto cuando el documento representa una entidad o una respuesta con campos nombrados. Usa un array cuando la raíz es directamente una colección ordenada de elementos equivalentes. Si una respuesta necesita la lista y metadatos adicionales, un objeto suele expresar mejor ambas cosas:

{
  "resultados": [{ "id": 42 }, { "id": 43 }],
  "total": 2,
  "siguiente": null
}

No envuelvas automáticamente un array en un objeto solo porque una biblioteca antigua lo exija, ni elimines ese envoltorio si el contrato documenta campos de paginación, versión o estado.

JSON válido no significa API válida

El validador JSON acepta tanto {} como [], e incluso otros valores JSON en la raíz. Una API puede rechazar un array porque esperaba un objeto con la propiedad resultados. Eso es un error de contrato, no de sintaxis.

Comprueba por separado:

1. que el texto se pueda analizar;
2. que el valor raíz sea del tipo esperado;
3. que existan las propiedades requeridas;
4. que cada elemento del array tenga la estructura acordada.

Consecuencias al convertir a CSV

Una tabla suele corresponder a un array de objetos con columnas comparables. El conversor JSON a CSV también admite un único objeto como una fila, pero no convierte de forma arbitraria arrays de números o mezclas de valores porque no existe una decisión universal sobre sus columnas.

Antes de convertir, identifica qué representa cada fila. Si unos objetos tienen campos distintos, decide si las columnas ausentes deben quedar vacías o si la entrada necesita normalización previa.

Errores frecuentes

• Acceder a datos.nombre cuando la raíz es un array.
• Recorrer un objeto como si el orden de sus propiedades fuera un contrato.
• Confundir un objeto vacío {} con una lista vacía [].
• Aceptar una raíz válida sin comprobar el esquema exigido por la API.
• Convertir un array heterogéneo en tabla y perder la relación entre valores.

RFC 8259 define un objeto como una colección de pares nombre/valor y un array como una secuencia ordenada. Elige la raíz por el significado de los datos, no solo por cuál de las dos formas pasa el analizador.