Cómo diagnosticar errores JSON paso a paso

JSON parece sencillo porque el formato tiene pocos tipos y una puntuación familiar. Precisamente por eso un error pequeño suele llegar a una herramienta como un mensaje poco útil: una coma inesperada, una posición o un texto como “token no válido”. El objetivo no es adivinar hasta que el documento deje de fallar. Es reducir el caso, localizar la posición indicada, aplicar una corrección compatible con la gramática y comprobar que el dato sigue significando lo mismo.

RFC 8259 define JSON como un intercambio de datos basado en objetos, arrays, números, cadenas, valores booleanos y null. Las claves de un objeto son cadenas entre comillas dobles. Las cadenas no pueden contener un salto de línea literal. Las comas separan elementos, no cierran una lista con un elemento adicional. Estas reglas son deliberadamente estrictas para que dos programas lleguen al mismo resultado.

Un parser detecta sintaxis, no intención. Puede decir dónde dejó de reconocer el documento, pero no sabe si dos campos llamados de forma distinta representan el mismo precio, si un identificador perdió ceros iniciales o si una fecha usa la zona horaria correcta. Por eso conviene distinguir el error que impide leer el JSON de un problema semántico que seguirá presente después de formatearlo.

El ejemplo completo

Parte siempre de una copia pequeña que no contenga secretos reales. Este documento reúne cuatro problemas frecuentes. El orden importa: un parser normalmente informa del primer obstáculo y los siguientes quedan ocultos hasta corregirlo.

{
  "customer": "Ada",
  "items": ["notebook", "pen",],
  "note": "Deliver before
Friday",
  'orderId': "007",
  "total": 24.90,
  "amount": 24.90
}

La coma después de "pen" es una coma final. El salto entre before y Friday aparece dentro de una cadena sin escapar. orderId usa comillas simples, que pertenecen a JavaScript pero no a JSON. Por último, total y amount son sintácticamente válidos; el parser los acepta, aunque pueden describir la misma cantidad dos veces. Esa última observación requiere una decisión de quien conoce el contrato de la API.

Qué significa una posición del parser

Los errores de JSON.parse() suelen mencionar una posición, una línea y una columna según el motor y el navegador. Cuenta desde el comienzo de la entrada que realmente se entregó al parser, incluidos espacios y saltos. No supongas que la posición marca la causa exacta: con frecuencia señala el carácter donde la gramática ya no puede continuar. Una coma final puede manifestarse al encontrar ]; una cadena sin escapar puede manifestarse al alcanzar el salto de línea.

Trabaja con un editor que muestre líneas y columnas. Copia el contenido sin convertir comillas tipográficas y evita que una aplicación de mensajería agregue espacios o saltos. Si la herramienta muestra una posición absoluta, toma un fragmento de veinte caracteres antes y después. Si muestra una línea, revisa también la línea anterior: muchos delimitadores se abren antes de que aparezca el síntoma.

El problema práctico es separar una carga ilegible de una carga que es válida pero equivocada para el negocio. Un formateador solo puede actuar cuando la gramática es correcta. Si el documento proviene de un log, una variable de entorno o una respuesta HTTP, conserva primero la copia original y registra de qué sistema procede. No sustituyas valores a ciegas: un cambio para eliminar un error puede alterar una firma, una suma o un identificador. Reduce el ejemplo hasta el bloque que reproduce el fallo y elimina datos personales antes de compartirlo.

Diagnostica el ejemplo en cuatro pasadas. Primera: ve a la línea de items; la coma inmediatamente antes de ] no separa otro valor y debe eliminarse. Segunda: busca la línea indicada dentro de note; JSON necesita representar el salto como dos caracteres, barra invertida y n, no como un salto físico. Tercera: reemplaza las comillas simples de la clave por comillas dobles. Cuarta: pregunta al productor del dato si total y amount son conceptos distintos. Si son el mismo importe, conserva uno con el nombre establecido y documenta la migración.

{
  "customer": "Ada",
  "items": ["notebook", "pen"],
  "note": "Deliver before\nFriday",
  "orderId": "007",
  "total": 24.90
}

El JSON corregido se puede analizar, conserva orderId como cadena para no perder los ceros y expresa el salto de línea de forma portable. No conviertas "007" a número solo porque parece numérico: los códigos y referencias tienen reglas distintas de las cantidades.

Empieza ejecutando el parser en el mismo entorno que falló, si es posible. Anota el mensaje y la posición sin reescribir el texto. Después valida una copia con un formateador; si el mensaje cambia, revisa si la entrada fue normalizada. Corrige un único error sintáctico, vuelve a analizar y repite. Cuando el resultado sea válido, compara las claves, tipos, longitudes y valores significativos con una muestra conocida. Para una API, contrasta además el documento con su esquema o contrato. Un esquema puede exigir campos y formatos, pero tampoco decide por sí solo qué importe es el correcto.

Al automatizar, captura el texto de error y el contexto cercano, no toda la carga sensible. En JavaScript, envuelve JSON.parse() en un manejo de excepción y devuelve un diagnóstico que no exponga tokens. En una integración, almacena el identificador de solicitud, la versión del contrato y una muestra anonimizada. Esta disciplina permite reproducir el error sin convertir los registros de depuración en otra fuga de datos.

Las comillas dobles, las barras invertidas y las comas forman parte de la sintaxis, no de un estilo opcional. Dentro de una cadena, \n representa un salto, \" representa una comilla y \\ representa una barra. Una cadena abierta puede hacer que el parser culpe a un carácter posterior. Del mismo modo, una llave o corchete faltante puede reportarse al final del documento, porque solo allí se sabe que no llegó el cierre esperado.

Las claves duplicadas exactas son un caso especialmente peligroso: muchos parsers conservan la última, pero RFC 8259 advierte que el comportamiento cuando los nombres no son únicos es impredecible entre implementaciones. Los duplicados semánticos, como total y amount, son aún más difíciles: ambos pueden sobrevivir y producir dos interpretaciones. Define un nombre canónico, rechaza la combinación ambigua en el productor y añade una prueba que cubra la migración.

Evita “arregladores” que transforman cualquier texto parecido a JavaScript en JSON sin informar de sus cambios. Añadir comillas, eliminar comas o convertir valores puede ocultar una incompatibilidad del productor. Tampoco uses expresiones regulares para validar JSON completo: las cadenas escapadas y la anidación hacen que el enfoque sea frágil. El parser es la autoridad para sintaxis; pruebas de contrato y validación de esquema cubren los requisitos posteriores.

Otro fallo habitual es confundir JSON válido con una respuesta correcta. {"enabled":"false"} es válido, pero el tipo quizá deba ser booleano. 9007199254740993 puede perder precisión al convertirse a un número JavaScript. Una fecha como 03/04/2026 no explica su orden. Verifica tipo, unidades, zona horaria, rango y reglas de negocio antes de pasar el valor a otra capa.

Usa datos sintéticos para aprender el flujo y confirma dónde procesa la herramienta el contenido antes de pegar información interna. Para cargas grandes, divide el problema: valida el encabezado, un elemento del array y la estructura de cierre; no recortes en mitad de una cadena o de una secuencia UTF-8. Conserva la codificación UTF-8 y evita pegar desde procesadores de texto que sustituyen comillas rectas por comillas curvas.

Los mensajes de error varían entre navegadores y versiones. El número de posición es una pista reproducible solo para la misma entrada exacta. Incluye en un informe la versión del cliente, el mensaje literal, un fragmento saneado y los pasos para reproducirlo. No publiques una carga completa como “ejemplo” si contiene correos, rutas internas, sesiones o números de cuenta.

Esta guía no certifica que una carga sea segura, autorizada o adecuada para una decisión profesional. JSON no cifra, firma ni valida permisos. Un documento bien formado puede contener una instrucción maliciosa, datos desactualizados o cifras manipuladas. La validación de sintaxis tampoco sustituye controles de autenticación, autorización, límites de tamaño, registros seguros ni revisión humana cuando el contexto lo exige.

Las herramientas del navegador pueden ayudar a inspeccionar texto, pero no deben ser el único control de una integración crítica. Para pagos, salud, seguridad, obligaciones legales o datos regulados, sigue el contrato, los procedimientos y los entornos aprobados por la organización responsable. Si no sabes qué significa un campo duplicado, detén la importación y consulta al propietario del dato.

Antes de dar por resuelto un error JSON, conserva una copia protegida de la entrada y crea un ejemplo mínimo sin secretos. Lee el primer mensaje del parser y sitúa la posición dentro de la entrada exacta. Corrige una sola regla sintáctica por vez: comas, comillas, escapes y cierres. Analiza de nuevo después de cada cambio. Cuando pase, compara claves, tipos, identificadores, números, fechas y campos equivalentes con el contrato. Confirma que no hay nombres duplicados ni significados superpuestos. Finalmente prueba el consumidor real con datos controlados, registra la causa y corrige el productor para que el mismo documento no vuelva a emitirse.