Errores comunes al escribir JSON

Respuesta breve

Muchos errores de JSON se reducen a unos pocos patrones: un separador que falta o sobra, una cadena mal delimitada, una extensión tomada de JavaScript o una estructura que quedó incompleta. Reconocer el patrón permite corregir la causa sin reescribir todo el documento.

Esta página es una referencia para comparar entradas incorrectas con su forma válida. Si necesitas conocer el primer diagnóstico, la línea y el contexto de tu propio texto, utiliza el validador JSON. Si aún no sabes cómo interpretar esa ubicación, consulta el procedimiento para validar un JSON y localizar el error.

Referencia rápida

Los analizadores no tienen por qué redactar igual sus mensajes. La pista puede señalar el carácter donde el análisis ya no puede continuar, aunque la causa esté justo antes.

Separadores: comas y dos puntos

Los dos puntos separan el nombre de una propiedad de su valor. Las comas separan miembros de un objeto o elementos de un array. No son intercambiables y una coma nunca cierra una lista.

Una coma justo antes del cierre

Esta lista tiene una coma después de su último elemento:

{"roles":["editor","lector",]}

JSON no admite comas finales. La versión válida termina el último valor y cierra el array directamente:

{
  "roles": ["editor", "lector"]
}

La misma regla se aplica a los objetos: tampoco puede quedar una coma antes de }.

Falta una coma entre propiedades

Aquí empieza "puerto" sin haber separado el miembro anterior:

{"host":"localhost" "puerto":8080}

La corrección está entre "localhost" y la propiedad siguiente:

{
  "host": "localhost",
  "puerto": 8080
}

El analizador puede señalar el comienzo de "puerto" porque ese es el punto donde descubre que no puede continuar. El carácter que falta está justo antes.

Faltan los dos puntos

En un objeto, el nombre debe ir seguido de dos puntos antes del valor:

{"modo" "seguro"}

La forma correcta es:

{
  "modo": "seguro"
}

Una regla breve ayuda a diferenciarlos: : une un nombre con su valor; , separa ese par del siguiente.

Propiedades, comillas y cadenas

JSON se parece a la notación de objetos de JavaScript, pero no acepta todas sus formas abreviadas. Tanto los nombres de propiedades como las cadenas se delimitan con comillas dobles.

El nombre de una propiedad no tiene comillas

Este nombre podría funcionar como identificador en JavaScript, pero no es una cadena JSON:

{modo:"seguro"}

Debe escribirse entre comillas dobles:

{
  "modo": "seguro"
}

La regla también se aplica a nombres numéricos o con guiones: dentro de un objeto JSON, todo nombre de propiedad es una cadena.

Se han utilizado comillas simples

Las comillas simples no delimitan cadenas ni propiedades en JSON:

{'activo':true}

La versión válida usa comillas dobles:

{
  "activo": true
}

No conviene sustituir todas las comillas simples de forma automática. Un apóstrofo puede formar parte del texto y no necesita convertirse:

{
  "mensaje": "L'entrada está abierta"
}

Una barra inversa inicia un escape no válido

En una cadena, la barra inversa \ inicia una secuencia de escape. Por eso esta ruta contiene \d y \e, que no son escapes JSON:

{"ruta":"C:\datos\entrada"}

Para representar una barra inversa literal hay que escribir dos:

{
  "ruta": "C:\\datos\\entrada"
}

Después de analizar el JSON, cada \\ representa una sola barra en el valor. JSON también admite escapes cortos como \n, \t, \r, \b y \f, además de \" para una comilla interior y \uXXXX para una unidad Unicode.

Un salto de línea o tabulador literal dentro de una cadena es un carácter de control y debe escribirse mediante su escape. Fuera de las cadenas, los espacios, tabuladores y saltos de línea sí pueden funcionar como espacio en blanco.

Formas de JavaScript que JSON no admite

Un archivo puede parecer JSON y, en realidad, utilizar extensiones propias de JavaScript, JSON5, JSONC o alguna herramienta de configuración. Un analizador permisivo puede aceptarlas, pero eso no las convierte en JSON interoperable.

Comentarios

JSON no define comentarios de línea ni de bloque:

{
  "puerto": 8080, // puerto HTTP
  "seguro": false
}

Si el comentario solo documenta el archivo, la corrección es retirarlo:

{
  "puerto": 8080,
  "seguro": false
}

Si la nota debe formar parte de los datos, podría modelarse como una propiedad solo cuando el sistema receptor la permita. Añadir una propiedad "comentario" por cuenta propia puede incumplir el contrato de una API.

undefined, NaN e Infinity

Estos valores existen en JavaScript, pero no forman parte de la gramática JSON:

{"resultado":NaN,"opcional":undefined}

JSON admite objetos, arrays, cadenas, números y únicamente los literales true, false y null. Una representación posible sería:

{
  "resultado": null,
  "opcional": null
}

null no es una sustitución automática. Según el significado de los datos, puede ser correcto usar null, omitir la propiedad o representar el estado de otra forma. La decisión pertenece al contrato del sistema que recibirá el documento.

Números que no cumplen la gramática

Los números JSON se escriben en base diez. Pueden incluir un signo negativo, una fracción y un exponente, pero no admiten ceros iniciales salvo que el número completo sea cero.

Este valor no es válido como número:

{"intentos":03}

Si representa una cantidad, se elimina el cero:

{
  "intentos": 3
}

Si 03 es un código y el cero tiene significado, debe conservarse como texto:

{
  "intentos": "03"
}

Una fracción necesita al menos un dígito después del punto y un exponente necesita dígitos después de e o E. Por eso 1. y 2e tampoco son números JSON completos. El signo + inicial no está admitido.

Documento incompleto o con más de una raíz

El texto JSON completo contiene un único valor raíz. Ese valor debe estar terminado antes de que acabe el documento y no puede ir seguido de un segundo valor independiente.

El documento termina antes de completar el valor

Aquí se abre un array, pero no se añade ningún elemento ni se cierra la estructura:

{"items":[

Si la intención era representar una lista vacía, la corrección mínima es:

{
  "items": []
}

Un final inesperado también puede indicar una cadena sin cerrar, un valor que falta después de : o el cierre pendiente de un objeto. Completa la estructura según los datos reales; no añadas cierres al azar hasta que el analizador deje de mostrar un error.

Hay dos valores raíz consecutivos

Estos son dos objetos separados sin ningún contenedor común:

{"ok":true}{"ok":false}

Si ambos pertenecen al mismo documento, pueden agruparse en un array:

[
  {
    "ok": true
  },
  {
    "ok": false
  }
]

Otra solución puede ser conservar solo uno o procesar cada documento por separado. Agruparlos es correcto únicamente si el receptor espera una lista.

Tres casos que no son errores de sintaxis

Evitar estos falsos positivos es tan importante como reconocer una coma o una comilla incorrecta.

Un valor raíz puede ser primitivo

"texto", 42, true y null son documentos JSON válidos. Una API puede exigir que la raíz sea un objeto o un array, pero esa es una regla de su contrato, no de la sintaxis general de JSON.

El espacio en blanco permitido es válido

Los espacios, tabuladores, retornos de carro y saltos de línea pueden aparecer fuera de las cadenas en los puntos permitidos por la gramática. Formatear un documento cambia su presentación, no su validez.

Los nombres duplicados son un problema distinto

Este texto cumple la gramática, aunque repite el mismo nombre:

{
  "estado": "pendiente",
  "estado": "enviado"
}

RFC 8259 recomienda que los nombres de un objeto sean únicos porque distintos receptores pueden conservar el primer valor, el último, todos o incluso rechazar el documento. El validador nativo puede aceptarlo, mientras que los conversores de Tools in a Tab rechazan nombres duplicados para no producir un resultado ambiguo.

Comprueba la corrección

Después de reconocer un patrón, cambia únicamente la causa identificada y vuelve a comprobar el documento completo. El validador JSON conserva tu entrada y muestra el primer problema con línea, columna y contexto directamente en esta pestaña.

Cuando el resultado ya sea válido, puedes usar el formateador JSON para mejorar la legibilidad o generar una versión compacta. La sintaxis válida no garantiza que una API acepte los datos: propiedades obligatorias, tipos, formatos y reglas de negocio deben revisarse en su documentación o JSON Schema.

Referencia técnica

La gramática y las recomendaciones de interoperabilidad utilizadas en esta guía están definidas en RFC 8259. Los ejemplos incorrectos se han comprobado contra el validador de Tools in a Tab y las correcciones contra el analizador JSON nativo.