Los errores de JSON que causan la mayoría de fallos al analizar y cómo corregirlos

La mayoría de los errores al analizar JSON se deben a una lista corta de fallos: una coma final, una cadena entre comillas simples, un comentario, una clave sin comillas, un valor como NaN o undefined, o comillas tipográficas copiadas de un documento. JSON es más estricto que el JavaScript al que se parece, así que código que a una persona le parece correcto puede ser rechazado por un analizador. El mensaje de error indica una línea y una columna, y la solución suele estar en esa posición o justo antes.

Formatear JSONEl JSON no se analizaÚsalo gratis

Las reglas que impone JSON

Un documento JSON es un único valor: un objeto entre llaves, un array entre corchetes, una cadena, un número, true, false o null. Dentro de esos valores:

• Cada clave y cada cadena usa comillas dobles rectas, como "name".
• Las comas separan los elementos, y no debe haber coma después del último elemento de un objeto o de un array.
• Los números no pueden llevar un signo más al principio, y NaN, Infinity y undefined no son números ni valores válidos.
• Los comentarios no están permitidos en absoluto.
• Las claves deben ser cadenas, así que una clave sin comillas como name: no es válida.

Algunos analizadores aceptan algunas de estas cosas por defecto, y algunas herramientas admiten JSON con comentarios por comodidad. Esa tolerancia oculta el problema hasta que el archivo llega a un lector más estricto, así que escribe la forma estricta.

Leer el mensaje de error

Los analizadores informan del primer punto en el que no pudieron continuar. El mensaje describe el problema y da una posición, normalmente una línea y una columna. Este es un archivo pequeño con una coma final en un array y otra después de la última propiedad:

{
  "name": "Ada",
  "tags": ["a", "b",],
}

Python informa de esto como "Illegal trailing comma before end of array: line 3 column 20". La redacción varía según la herramienta, y algunos analizadores antiguos solo dicen "Unexpected token" con un desplazamiento de caracteres. Ve a la posición indicada y mira el carácter que está justo antes. El error real suele ser una coma, una comilla o una llave uno o dos caracteres antes del punto señalado.

Algunos mensajes más del analizador de Python y lo que suelen significar:

• "Expecting property name enclosed in double quotes" para '{'a': 1}' indica una clave entre comillas simples o sin comillas.
• "Expecting value" en una posición donde esperabas un número o una cadena suele indicar una comilla tipográfica, porque el analizador la interpreta como un carácter desconocido.
• "Expecting ',' delimiter" suele indicar una coma que falta entre dos elementos, o un comentario en medio de los datos.

Comillas tipográficas y texto copiado

Las comillas tipográficas son el caso más confuso, porque se parecen casi igual a las rectas. Un archivo JSON copiado de un procesador de texto, una página web o un mensaje de chat puede contener comillas dobles curvas. El archivo te parece bien y no se analiza, porque el analizador ve “x” como un carácter desconocido en lugar de como delimitador de una cadena.

Los caracteres ocultos provocan el mismo tipo de fallo. Un espacio de no separación entre dos valores no es un espacio en blanco para el analizador. Elimina los caracteres ocultos antes de intentar reparar la estructura a mano, y después corrige las comillas. La guía sobre comillas tipográficas explica cómo enderezarlas sin riesgo.

Comillas simples, comentarios y claves sin comillas

Muchos desarrolladores escriben datos parecidos a JSON en un lenguaje que permite más cosas:

• Las comillas simples son válidas en los literales de JavaScript y Python, pero JSON exige comillas dobles. Sustituye {'a': 1} por {"a": 1}.
• Los comentarios como // o /* */ deben eliminarse. Si necesitas notas, ponlas en un campo aparte, o usa un formato pensado para archivos de configuración.
• Las claves sin comillas son habituales en los objetos literales de JavaScript. Añade las comillas.
• NaN y undefined no existen en JSON. Usa null para un valor que falta, o una cadena si el valor es texto.

Ten cuidado con un reemplazo general. Cambiar todas las comillas simples por dobles rompe cualquier cadena que contenga un apóstrofo, como "Ada's notes". Revisa cada coincidencia en buscar y reemplazar antes de hacerlo, para ver qué comillas cambiarían.

Corregir la estructura paso a paso

1. Pega el archivo en el formateador de JSON. Formatearlo hace visible la estructura, y el error muestra su línea y su columna. Después pulsa Reparar, que elimina los comentarios y las comas finales. No cambia las comillas simples ni las tipográficas, así que corrígelas tú.
2. Corrige solo el primer error y vuelve a comprobar. Un solo fallo puede provocar varios errores más abajo.
3. Comprueba que cada llave o corchete de apertura tenga su cierre, y que la anidación sea la que pretendes.
4. Valida el archivo final con el analizador que usa tu aplicación, no solo con una herramienta web. Los analizadores difieren un poco.

Un archivo que se analiza no es necesariamente el que querías. Compruébalo con un JSON Schema para detectar un campo que falta o un valor de tipo incorrecto, o compara dos documentos JSON para ver qué cambió entre versiones.

Casos límite

• Comas finales en archivos generados. Algunas herramientas las escriben. Si generas JSON construyendo cadenas a mano, usa el serializador de tu lenguaje, que produce una salida válida.
• Claves duplicadas. JSON las permite, pero la mayoría de los analizadores conservan solo el último valor. Las claves duplicadas son un error esperando a suceder.
• Números grandes. Los enteros muy grandes pueden perder precisión en algunos analizadores, así que guarda los identificadores como cadenas si son más largos de lo que el analizador puede representar con exactitud. La guía de CSV a JSON hace la misma advertencia sobre los ID.

Respuestas rápidas

¿Por qué falla mi JSON si parece correcto?

Las causas habituales son una coma final, comillas simples, un comentario o comillas tipográficas copiadas de un documento. Revisa la posición indicada en el mensaje de error y el carácter que está justo antes.

¿JSON puede tener comentarios?

No. El estándar de JSON no permite comentarios. Elimínalos, o mueve las notas a un campo propio. El botón Reparar del formateador los elimina por ti.

¿Qué uso en lugar de undefined en JSON?

Usa null cuando un valor falte a propósito, o elimina la clave por completo. undefined es un valor de JavaScript y no tiene representación en JSON.