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 y comentarios son legales, porque el motor analiza ese código como cualquier otro. JSON es una gramática mucho más pequeña y estricta (RFC 8259), y JSON.parse() aplica cada una de sus reglas sin alternativa. El parser lee de izquierda a derecha y se detiene en el primer token que no encaja con la gramática en esa posición.

Los diseñadores lo eligieron a propósito. Un parser de JSON indulgente aceptaría documentos ligeramente distintos en cada implementación, justo el problema de interoperabilidad que JSON quería evitar. El coste: los mensajes de error son breves y solo indican posiciones. 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 aparecen todo el tiempo cuando alguien escribe JSON a mano o lo copia 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 se informa de otra forma: el V8 moderno sabe que esperaba un nombre de propiedad e informa `Expected property name or '}' in JSON at position 2` sin nombrar el identificador suelto. La corrección es mecánica en ambos casos: 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

JSON prohíbe 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. Escápalo como `\n`, `\t`, etc. El problema aparece sobre todo cuando el código construye JSON concatenando un valor multilínea (un mensaje de log, un fragmento de código, un comentario de usuario) en un literal de cadena sin escaparlo.

{
  "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 y no solo un token. Escapa el carácter en lugar de dejarlo en bruto: `"line one\nline two"`.

Claves duplicadas, NaN/Infinity/undefined y caracteres BOM

Tres modos de fallo más silenciosos merecen nombre propio. Primero, las claves duplicadas en un objeto JSON no causan ningún error de análisis. `{ "id": 1, "id": 2 }` se analiza sin problema, y JSON.parse conserva la última aparición (`id: 2`) y descarta la primera sin avisar. RFC 8259 dice que los nombres 'deberían' ser únicos pero no exige que los parsers rechacen duplicados, así que tu parser cumple la especificación, y quien revisa el código pasa el bug por alto con facilidad.

Segundo, `NaN`, `Infinity` y `undefined` son válidos en JavaScript pero no son tokens JSON. JSON tiene `number` sin los valores especiales de IEEE-754, y no tiene `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). `JSON.stringify` convierte `NaN`/`Infinity` a `null` y descarta los valores `undefined`, así que este error suele significar que alguien escribió el JSON a mano o que una fuente no-JS asumió semántica de JS.

Tercero, una marca de orden de bytes UTF-8 (U+FEFF) al principio de un archivo rompe `JSON.parse` cuando lees el archivo como cadena en bruto, y produce `Unexpected token '\ufeff'... is not valid JSON` en la posición 0. Los editores de Windows y algunas herramientas de Java/.NET la añaden al guardar UTF-8. El problema es propio de `JSON.parse` sobre una cadena: `Response.json()` de la Fetch API decodifica texto UTF-8 y elimina un BOM inicial al decodificar, así que los mismos bytes pueden comportarse distinto por HTTP y al leerlos del disco con `fs.readFileSync(path, 'utf8')`.

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 que pasaste, no un número de línea. Node (v20+) añade también un `(line X column Y)`, pero los runtimes antiguos y los navegadores solo dan el desplazamiento en bruto. Dos cosas confunden a la gente. La posición marca dónde el parser notó la gramática rota, y con una coma final o un corchete faltante suele quedar un token después de tu error. Y si embelleciste el JSON para leerlo mientras depuras 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, corrígelo a mano en cuanto localices la posición. Pégalo en un validador que resalte el carácter en lugar de contar desplazamientos. Para un archivo grande con varios errores sin relación, JSON salido de una herramienta con bugs aguas arriba, o JSON estropeado por varias rondas de copiar y pegar, la reparación manual cuesta demasiado tiempo. Entonces toca automatizar. El JSON Validator de JsonForge localiza cada infracción de esquema con una ruta precisa en cuanto el documento se analiza, y JSON Repair corrige errores estructurales comunes (comillas faltantes, comas finales, llaves desparejadas) cuando la entrada está demasiado dañada para arreglar un error cada vez.