Errores comunes de análisis de JSON y cómo corregirlos

Por qué JSON.parse lanza errores en lugar de adivinar

Los literales de objeto de JavaScript son indulgentes: claves sin comillas, comas finales, cadenas con comillas simples e incluso comentarios son legales, porque el código fuente lo analiza el mismo motor que analiza todo lo demás. JSON no es JavaScript — es una gramática mucho más pequeña y estricta (RFC 8259), y JSON.parse() aplica cada regla de esa gramática sin alternativa. No existe el JSON 'casi correcto'; el parser lee de izquierda a derecha y se detiene en seco en el primer token que no encaja con la gramática en esa posición.

Es una decisión de diseño deliberada, no una limitación: un parser de JSON indulgente aceptaría silenciosamente documentos sutilmente distintos en distintas implementaciones, que es exactamente el problema de interoperabilidad que JSON se inventó para evitar. El coste es que los mensajes de error son breves y posicionales en lugar de semánticos — el parser te dice dónde se rompió la gramática, no qué querías escribir.

Comas finales

El error de JSON más común de todos es una coma final que queda al editar un literal de objeto de JavaScript (donde es legal) olvidando que no es legal en JSON.

{
  "name": "Alice",
  "roles": ["admin", "editor"],
}

V8 rechaza esto en la llave de cierre, no en la coma, porque la coma en sí es gramática válida justo hasta que el parser espera otra propiedad y encuentra `}` en su lugar. Según tu versión de Node/Chrome verás algo como `Unexpected token '}', "...editor"],\n}"... is not valid JSON` (V8 más reciente, con un fragmento) o el más antiguo y escueto `Unexpected token } in JSON at position 47`. En cualquier caso, la corrección es la misma: elimina la coma antes del corchete o llave de cierre.

Comillas simples y claves sin comillas

JSON exige comillas dobles para cada cadena y cada clave — sin excepciones. Las cadenas con comillas simples y las claves sin comillas son ambas extremadamente comunes cuando el JSON se escribe a mano o se copia y pega de código JavaScript.

{ 'name': 'Alice' }
{ name: "Alice" }

Una comilla simple al principio produce algo como `Unexpected token ''', "{ 'name'"... is not valid JSON`. Una clave sin comillas es sutilmente distinta: el V8 moderno reconoce que se esperaba un nombre de propiedad e informa `Expected property name or '}' in JSON at position 2`, en lugar de culpar directamente al identificador suelto. En cualquier caso, la corrección es mecánica — envuelve cada clave y cada valor de cadena entre comillas dobles.

Saltos de línea y caracteres de control sin escapar dentro de las cadenas

Un salto de línea en bruto, un tabulador u otro carácter de control (cualquier cosa por debajo de U+0020) dentro de una cadena JSON es ilegal — debe escaparse como `\n`, `\t`, etc. Esto muerde más a menudo cuando el JSON se genera concatenando ingenuamente un valor multilínea (un mensaje de log, un fragmento de código, un comentario de usuario) en un literal de cadena sin escaparlo primero.

{
  "message": "line one
line two"
}

Esto produce `SyntaxError: Bad control character in string literal in JSON at position 21` — uno de los pocos errores de JSON que nombran el problema real en lugar de solo un token. La corrección es escapar el carácter en lugar de dejarlo aparecer en bruto: `"line one\nline two"`.

Claves duplicadas, NaN/Infinity/undefined y caracteres BOM

Tres modos de fallo más silenciosos que conviene conocer por su nombre. Primero, las claves duplicadas en un objeto JSON no son en absoluto un error de análisis — `{ "id": 1, "id": 2 }` se analiza con éxito, y JSON.parse conserva silenciosamente la última aparición (`id: 2`) y descarta la primera. RFC 8259 dice que los nombres 'deberían' ser únicos pero no exige que los parsers rechacen los duplicados, así que esto es comportamiento conforme a la especificación y fácil de pasar por alto en revisión, no un bug de tu parser.

Segundo, `NaN`, `Infinity` y `undefined` son todos válidos en JavaScript pero ninguno es un token JSON válido — JSON solo tiene `number`, no los valores especiales de IEEE-754, y no tiene ningún concepto de `undefined` (solo `null`). `{ "value": NaN }` lanza `Unexpected token 'N', ..."value":NaN}"... is not valid JSON` (o `Unexpected token N in JSON at position 10` en motores antiguos). Si serializas desde JavaScript, `JSON.stringify` ya convierte `NaN`/`Infinity` a `null` y descarta los valores `undefined` por completo — el error suele significar que el JSON se escribió a mano o provino de una fuente no-JS que asumió semántica de JS.

Tercero, una marca de orden de bytes UTF-8 (U+FEFF) justo al principio de un archivo — añadida a menudo silenciosamente por editores de Windows o algunas herramientas de Java/.NET al guardar UTF-8 — rompe `JSON.parse` cuando el archivo se lee como cadena en bruto, produciendo `Unexpected token '\ufeff'... is not valid JSON` en la posición 0. Ten en cuenta que esto es específicamente un problema de `JSON.parse` sobre una cadena: `Response.json()` de la Fetch API decodifica texto UTF-8 y elimina un BOM inicial como parte de esa decodificación, así que los mismos bytes servidos por HTTP y leídos del disco con `fs.readFileSync(path, 'utf8')` pueden comportarse de forma distinta.

Leer la posición, y cuándo recurrir a una herramienta de reparación

La `position` en un error de JSON.parse es un desplazamiento de caracteres con índice cero dentro de la cadena exacta que pasaste, no un número de línea — Node (v20+) además calcula y añade un `(line X column Y)` por conveniencia, pero los runtimes antiguos y los navegadores solo dan el desplazamiento en bruto. Dos cosas confunden a la gente: la posición informada es donde el parser notó que la gramática se rompió, que para una coma final o un corchete faltante suele estar un token después de donde cometiste realmente el error; y si has embellecido el JSON para leerlo pero estás depurando la cadena minificada original, los desplazamientos no coincidirán con lo que ves en pantalla.

Para un desliz de sintaxis puntual en un documento corto, corregirlo a mano una vez localizada la posición es más rápido que cualquier herramienta — pégalo en un validador que resalte el carácter exacto en lugar de contar desplazamientos manualmente. Para un archivo grande con varios errores sin relación, JSON generado por una herramienta con bugs aguas arriba, o JSON que ha pasado por varias rondas de copiar-pegar con pérdida, la reparación manual deja de compensar el tiempo. Ese es el momento de recurrir a algo automático: el JSON Validator de JsonForge localiza cada infracción de esquema con una ruta precisa una vez el documento al menos se analiza, y JSON Repair intenta corregir errores estructurales comunes (comillas faltantes, comas finales, llaves desparejadas) automáticamente cuando la entrada está demasiado destrozada para corregir un error cada vez.