¿Qué es JSON? Una guía en lenguaje claro (y cómo arreglar errores comunes)

JSON está por todas partes en el software moderno — archivos de configuración, respuestas de API, bases de datos y ajustes dependen de él. Sin embargo, una sola coma extraviada puede romper un archivo entero y dejarte mirando un críptico error «Unexpected token». Esta guía explica qué es JSON en lenguaje claro, cómo funciona realmente su sintaxis y cómo diagnosticar y arreglar los errores que encontrarás con más frecuencia.

Qué es JSON

JSON significa JavaScript Object Notation. Es un formato ligero, basado en texto, para almacenar e intercambiar datos estructurados. A pesar del nombre, no está atado a JavaScript — prácticamente todo lenguaje de programación puede leerlo y escribirlo, que es exactamente por lo que se convirtió en el idioma por defecto de las API web.

Todo el sentido de JSON es ser legible tanto por humanos como por máquinas. Representa los datos como una combinación de unos pocos bloques simples:

• Objetos — colecciones de pares clave/valor entre llaves { }.
• Arreglos (arrays) — listas ordenadas entre corchetes [ ].
• Valores — una cadena, un número, true, false, null, un objeto o un arreglo.

Aquí un ejemplo pequeño pero completo:

{
  "name": "Ada Lovelace",
  "active": true,
  "age": 36,
  "skills": ["math", "logic"],
  "address": {
    "city": "London",
    "postcode": null
  }
}

Las reglas que hacen tropezar

JSON se parece mucho a un objeto de JavaScript, y esa semejanza es la fuente de la mayoría de los errores — JSON es más estricto. Ten presentes estas reglas y evitarás la gran mayoría de los errores:

1. Las claves y las cadenas necesitan comillas dobles

Toda clave debe ser una cadena entre comillas dobles, y todo valor de texto debe usar comillas dobles también. Las comillas simples no son JSON válido, aunque en JavaScript estén bien.

// Inválido
{ 'name': 'Ada' }

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

2. Sin comas finales

No puedes dejar una coma después del último elemento de un objeto o arreglo. Este es el error de JSON más común, porque muchos editores y lenguajes lo permiten sin problema en otros sitios.

// Inválido — coma después del último valor
{ "a": 1, "b": 2, }

// Válido
{ "a": 1, "b": 2 }

3. Sin comentarios

El JSON estándar no tiene sintaxis de comentarios. Las líneas que empiezan por // o los bloques entre /* */ provocan un error de análisis. Si necesitas comentarios, formatos como JSON5 o YAML los permiten — mira nuestro formateador de YAML si eso encaja mejor con tu caso.

4. Los números son simples

Los números se escriben sin comillas y sin ceros a la izquierda ni puntos decimales al final. 01, 1. y .5 son todos inválidos; escribe 1, 1.0 y 0.5.

Errores comunes y cómo arreglarlos

Cuando un analizador rechaza tu JSON, suele informar de una línea y una columna. Ese lugar apunta a donde el analizador se rindió, que a menudo está justo después del error real. Estos son los mensajes que verás más y lo que significan de verdad:

• "Unexpected token } in JSON" — casi siempre una coma final antes de la llave o el corchete de cierre. Quita la coma de más.
• "Unexpected string" / "Expected comma" — te falta una coma entre dos valores, o usaste un salto de línea donde debería ir una coma.
• "Unexpected token ' in JSON" — comillas simples. Reemplázalas por comillas dobles.
• "Unexpected end of JSON input" — un corchete o una llave nunca se cerró. Cuenta tus { y }; cada apertura necesita un cierre que le corresponda.
• "Unexpected token o in JSON" — una señal clásica de que intentaste analizar algo que ya era un objeto, no una cadena JSON. Llama al analizador solo sobre texto.

La forma más rápida de localizar el punto exacto es pasar el texto por un formateador que valida sobre la marcha. Nuestro formateador y validador de JSON resalta la línea y columna precisas del primer error y, una vez que el JSON es válido, lo imprime con formato para que los problemas estructurales (un corchete mal puesto, un valor anidado un nivel de más) se vean de un vistazo. Todo se ejecuta en tu navegador, así que puedes revisar con seguridad datos privados o sensibles.

Formatear vs. minificar

Dos operaciones surgen constantemente al trabajar con JSON. Formatear (también llamado embellecer o pretty-print) añade indentación y saltos de línea para hacer legible un bloque denso — ideal mientras depuras. Minificar elimina todo espacio y salto de línea innecesario para producir la salida más pequeña posible — ideal para enviar por la red o incrustar en código, donde el tamaño importa. Los datos son idénticos en ambos casos; solo cambia el espacio en blanco.

Lista rápida

Antes de entregar JSON a un programa, verifica:

• Todas las claves y valores de texto usan comillas dobles.
• No hay comas finales.
• No hay comentarios.
• Cada corchete y llave está equilibrado.
• Pasa un validador sin errores.

Acierta con esos cinco y JSON se vuelve lo que fue diseñado para ser: un formato aburrido, predecible y que simplemente funciona. Cuando algo sí se escape, pégalo en el formateador de JSON y deja que te señale el problema directamente.