Cómo validar un JSON y entender sus errores más habituales

Validar un JSON consiste en comprobar que el texto cumple la gramática definida en el RFC 8259: objetos entre llaves con claves entre comillas dobles, arrays entre corchetes, valores separados por comas sin coma final, y sin comentarios. Casi todos los errores de parseo se deben a cinco causas: comas finales, comillas simples, comentarios, claves sin comillas y valores no permitidos como undefined o NaN. Puedes validarlo en segundos con una herramienta online, con jq en la terminal o con JSON.parse en Node.js.

Este artículo repasa las reglas, muestra cómo interpretar los mensajes de error y compara las formas de validar según el contexto.

Las reglas de JSON en seis líneas

1. Un documento JSON es un valor: objeto, array, cadena, número, true, false o null.
2. Los objetos van entre {} y contienen pares "clave": valor separados por comas.
3. Los arrays van entre [] y contienen valores separados por comas.
4. Las cadenas van siempre entre comillas dobles; dentro, los caracteres especiales se escapan con \ (\", \\, \n, \uXXXX).
5. Los números no llevan comillas, ni ceros a la izquierda, ni formas como .5 o +1; 1e3 sí es válido.
6. No existen comentarios, comas finales, undefined, NaN, Infinity ni fechas como tipo propio (se escriben como cadenas).

Un ejemplo válido:

{
  "nombre": "AIMRAN Tools",
  "version": 2,
  "activo": true,
  "etiquetas": ["imágenes", "json", "texto"],
  "autor": { "nombre": "Aimran", "web": "https://aimran.es" },
  "fechaPublicacion": "2026-10-06"
}

Los cinco errores más habituales

1. Coma final

{ "a": 1, "b": 2, }

Válido en JavaScript, inválido en JSON. Node.js 22 lo rechaza con Expected double-quoted property name in JSON at position 18 (line 1 column 19): tras la coma espera otra clave y encuentra }.

2. Comillas simples

{ 'a': 1 }

JSON solo admite comillas dobles. Node.js 22 devuelve Expected property name or '}' in JSON at position 2 (line 1 column 3): el parser llega a la comilla simple y no la reconoce como inicio de una clave. Es el error típico al copiar un objeto desde código Python o JavaScript.

3. Comentarios

{
  // configuración
  "debug": true
}

Ni // ni /* */ existen en JSON. Algunos formatos derivados (JSONC, JSON5) los admiten, y por eso archivos como tsconfig.json o settings.json de VS Code los toleran, pero un parser estricto los rechaza.

4. Claves sin comillas

{ nombre: "Aimran" }

En JavaScript es un literal de objeto válido; en JSON, la clave debe ir entre comillas dobles. Node.js devuelve el mismo mensaje que con las comillas simples (Expected property name or '}'), porque en ambos casos lo que falta es la comilla doble.

5. Valores que no existen en JSON

{ "total": NaN, "fecha": undefined }

NaN, Infinity y undefined no son valores JSON. Al serializar con JSON.stringify en JavaScript, las propiedades undefined desaparecen y NaN se convierte en null, lo que a veces oculta el problema hasta que otro sistema lee el archivo.

Otros errores menos frecuentes: comillas tipográficas (“ y ”) pegadas desde un procesador de texto, un carácter BOM al inicio del archivo, o un número con cero a la izquierda (007).

Cómo leer un mensaje de error

Los parsers indican la posición (índice de carácter) o la línea y columna donde dejaron de entender el texto. Ese punto es donde el parser se rindió, que no siempre coincide con el error real: una llave sin cerrar en la línea 3 puede reportarse al final del archivo. Si el mensaje no te lleva directo al problema, busca hacia atrás desde la posición indicada el último elemento que sí era válido.

Python 3.13, por ejemplo, es más descriptivo con la coma final: Illegal trailing comma before end of object: line 1 column 17 (char 16). Versiones anteriores daban el mensaje genérico Expecting property name enclosed in double quotes.

Formas de validar un JSON

Contexto	Herramienta	Comando o uso
Rápido, sin instalar nada	Validador online	Pega el texto en el formateador de JSON de AIMRAN Tools: señala la línea del error y formatea el resultado sin enviar los datos a ningún servidor.
Terminal (Linux, macOS, WSL)	jq	jq . archivo.json imprime el JSON formateado o el error con la línea. jq empty archivo.json solo valida.
Terminal, sin instalar nada	Python	python3 -m json.tool archivo.json
Proyecto JavaScript	Node.js	node -e "JSON.parse(require('fs').readFileSync('archivo.json','utf8'))"
Editor	VS Code, Zed, etc.	Marcan los errores de sintaxis al vuelo; asegúrate de que el archivo esté en modo JSON y no JSONC.
Validar estructura, no solo sintaxis	JSON Schema	Define qué claves y tipos se esperan y valida con una librería como Ajv (JavaScript) o jsonschema (Python).

Para datos sensibles (configuraciones con claves, exportaciones de usuarios), prefiere herramientas que trabajen en local o en el navegador sin subir el contenido.

Validar sintaxis no es validar contenido

Un JSON sintácticamente correcto puede seguir siendo inútil para tu aplicación: una clave mal escrita, un número donde esperabas una cadena, un campo obligatorio ausente. Eso lo resuelve JSON Schema, un estándar para describir la forma esperada de un documento. Si consumes JSON de terceros o expones una API, merece la pena definir un esquema y validarlo en la frontera de tu sistema.

Conclusión

JSON es un formato pequeño con reglas estrictas, y la mayoría de errores vienen de tratarlo como si fuera JavaScript: comas finales, comillas simples, comentarios y claves sin comillas. Para encontrar el fallo, usa un validador que indique la posición (online, jq, json.tool o JSON.parse) y recuerda que el punto señalado es donde el parser se detuvo, no necesariamente donde empezó el problema. Y si el JSON forma parte de un contrato entre sistemas, añade JSON Schema para validar también el contenido.