JSON Explicado: Sintaxis, Errores Comunes y Mejores Prácticas

JSON está en todas partes. Impulsa las APIs REST, los archivos de configuración, las salidas de bases de datos, los payloads de webhooks y los agregadores de registros. Te lo encuentras docenas de veces al día tanto si estás construyendo un servicio backend como depurando una aplicación frontend o leyendo documentación. Entender JSON en profundidad —no solo cómo analizarlo, sino cómo leerlo, validarlo y solucionar sus problemas— es una de las habilidades de mayor apalancamiento que puede tener un desarrollador.

Esta guía cubre desde los fundamentos de la sintaxis JSON hasta la depuración de errores de análisis comunes, estrategias de formato y el trabajo con estructuras profundamente anidadas. Pega cualquier JSON en el Formateador JSON de BrowseryTools para validarlo e imprimirlo con formato al instante —gratis, sin registro, todo se queda en tu navegador.

Por Qué Ganó JSON (y Perdió XML)

Antes de que JSON se convirtiera en el formato de intercambio de datos por defecto, XML era el estándar. Las APIs SOAP, los feeds RSS y los archivos de configuración usaban XML. JSON surgió como una alternativa más simple y fue tomando el relevo progresivamente para la mayoría de los casos de uso. Las razones son sencillas:

• Menos verboso — JSON no requiere etiquetas de cierre. Los mismos datos se representan con un 30-50% menos de caracteres.
• Nativo de JavaScript — JSON son las siglas de JavaScript Object Notation. Se mapea directamente a los objetos y arrays de JavaScript, lo que hace que sea trivial analizarlo y serializarlo en el navegador.
• Legible por humanos — un payload JSON correctamente formateado es más fácil de leer que el XML equivalente con sus corchetes angulares y declaraciones de espacio de nombres.
• Ampliamente soportado — todos los lenguajes principales tienen un analizador JSON incorporado. No es necesario instalar una biblioteca solo para deserializar una respuesta de API.

XML todavía tiene casos de uso legítimos —formatos de documentos (DOCX, SVG), configuraciones que necesitan comentarios (que JSON no soporta) y protocolos como SOAP donde es obligatorio. Pero para la comunicación por API y el almacenamiento de datos, JSON es el ganador indiscutible.

Reglas de Sintaxis JSON

JSON tiene una sintaxis pequeña y estricta. Estas son las reglas que pillan desprevenidos a la mayoría de los desarrolladores:

• Las claves deben ser cadenas entre comillas dobles — {"name": "Alice"} es válido; {name: "Alice"} no lo es. A diferencia de los literales de objeto de JavaScript, JSON no permite claves sin comillas.
• Sin comas finales — [1, 2, 3,] no es JSON válido. La coma final después del último elemento es aceptada por JavaScript y muchos analizadores pero no es parte de la especificación JSON.
• Sin comentarios — JSON no tiene sintaxis de comentarios. Esto sorprende a los desarrolladores que quieren anotar los archivos de configuración. Si necesitas comentarios en un archivo de configuración, considera JSONC (JSON con Comentarios) o YAML en su lugar.
• Las cadenas usan solo comillas dobles — las cadenas con comillas simples como 'hello' no son JSON válido.
• Los números no pueden tener ceros iniciales — 007 no es válido; usa 7 en su lugar.
• Solo seis tipos de valores — cadenas, números, booleanos (true / false), null, objetos y arrays. Sin fechas, sin funciones, sin undefined.

Errores JSON Comunes y Lo Que Significan

Los errores de análisis JSON pueden ser crípticos. Aquí están los más comunes y cómo solucionarlos.

Token inesperado

// Error: Unexpected token ' in JSON at position 9
{ "name": 'Alice' }

Las comillas simples no son JSON válido. Reemplázalas con comillas dobles: {"name": "Alice"}.

Token } / ] inesperado

// Error: Unexpected token } in JSON at position 23
{
  "items": [1, 2, 3,]
}

Una coma final antes del corchete de cierre. Elimina la coma después del último elemento. Este es el error JSON más común para los desarrolladores que vienen de JavaScript, donde las comas finales son perfectamente válidas.

Fin inesperado de la entrada JSON

Esto significa que el JSON está truncado —la cadena termina antes de que todos los objetos y arrays abiertos estén cerrados. Cuenta tus llaves y corchetes de apertura y cierre. Deben coincidir.

Los nombres de propiedad deben ser cadenas

// Inválido — clave sin comillas
{ name: "Alice" }

// Válido
{ "name": "Alice" }

Impresión Bonita vs Minificación

El JSON puede representarse de dos formas: con impresión bonita (con sangría y saltos de línea) o minificado (sin ningún espacio en blanco). La elección depende del contexto.

Usa la impresión bonita cuando leas, depures, revises o almacenes JSON en el control de versiones. El JSON con sangría es inmediatamente legible y difunde limpiamente en Git porque cada valor está en su propia línea.

Minifica cuando transmitas JSON por una red. El espacio en blanco es sobrecarga pura en las respuestas HTTP. Un payload JSON de 100 KB con impresión bonita puede comprimirse a 60 KB cuando se minifica y luego a 15 KB con gzip. La mayoría de las APIs sirven JSON minificado a través de la red y dejan que el cliente lo imprima con formato según sea necesario.

En JavaScript: JSON.stringify(data, null, 2) imprime con formato con 2 espacios de sangría. JSON.stringify(data) minifica. El Formateador JSON de BrowseryTools hace ambas cosas —pega tu JSON y alterna entre vistas con formato y minificadas al instante.

Navegar por JSON Profundamente Anidado

Las respuestas de API del mundo real a menudo están profundamente anidadas. Un payload de webhook de Stripe, una respuesta de la API de GitHub o una configuración de Kubernetes puede tener objetos a cinco o seis niveles de profundidad. Aquí hay estrategias para trabajar con ellos:

Usa el encadenamiento opcional en JavaScript

// Without optional chaining — crashes if any level is undefined
const city = user.address.location.city;

// With optional chaining — returns undefined instead of throwing
const city = user?.address?.location?.city;

// With nullish coalescing for a default value
const city = user?.address?.location?.city ?? "Unknown";

Usa jq para consultas JSON en la línea de comandos

# Pretty-print the entire response
curl https://api.example.com/users | jq .

# Extract a specific field
curl https://api.example.com/users | jq '.[0].email'

# Filter an array
curl https://api.example.com/users | jq '.[] | select(.active == true) | .name'

JSON en APIs vs Archivos de Configuración

JSON sirve para dos roles muy diferentes según el contexto y las mejores prácticas difieren entre ellos.

En las respuestas de API, el JSON es generado por código y consumido por código. Rara vez lo escribes a mano. La prioridad es la corrección y la consistencia —usa una biblioteca de serialización y deja que maneje el escapado. Minifica para producción, incluye un encabezado Content-Type de application/json y versiona tu API para que los cambios en la estructura JSON no sean incompatibles.

En los archivos de configuración (package.json, tsconfig.json, .eslintrc.json), el JSON es escrito por humanos. Aquí la legibilidad importa más. Usa sangría de 2 espacios, mantén la estructura poco profunda donde sea posible y añade comentarios usando un analizador compatible con JSONC si tus herramientas lo soportan. Nunca minifiques los archivos de configuración que viven en el control de versiones.

Validación de JSON Schema

JSON Schema es una especificación para definir la estructura, los tipos y las restricciones de un documento JSON. Te permite validar que un payload JSON cumple con una forma esperada antes de intentar usarlo.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["id", "name", "email"],
  "properties": {
    "id":    { "type": "integer" },
    "name":  { "type": "string", "minLength": 1 },
    "email": { "type": "string", "format": "email" },
    "age":   { "type": "integer", "minimum": 0, "maximum": 150 }
  },
  "additionalProperties": false
}

Bibliotecas como ajv (JavaScript), jsonschema (Python) y JSON.NET Schema (.NET) pueden validar un documento JSON contra un esquema en tiempo de ejecución —detectando payloads malformados en el límite de la API antes de que causen errores inesperados más profundamente en la aplicación.

Resumen

La simplicidad de JSON es su mayor fortaleza. Seis tipos de valores, reglas estrictas de comillas, sin comentarios, sin comas finales —las restricciones son pequeñas y el formato es inequívoco. Cuando algo sale mal, casi siempre es uno de un puñado de errores de sintaxis predecibles. Pega tu JSON roto en el Formateador JSON de BrowseryTools y el error será inmediatamente visible con la posición exacta resaltada.