Validar la sintaxis de un JSON

¿Para qué sirve un validador JSON?

Un validador JSON tiene un papel más modesto, pero más preciso, que un formateador: no reescribe nada. Toma una cadena y responde a una pregunta binaria: ¿es este texto JSON conforme a la RFC 8259? Si es así, la herramienta devuelve el control. Si no, indica exactamente la línea, la columna y un extracto del JSON en torno al problema, para ayudar al desarrollador a corregir de inmediato.

En la práctica, es la herramienta que se utiliza en cuanto un parser en algún sitio devuelve un mensaje de error críptico del tipo SyntaxError: Unexpected token } in JSON at position 217. En lugar de contar los caracteres a mano en un editor, se pega la cadena completa, se lee la posición y se ve el extracto erróneo.

Validación, formateo: dos operaciones distintas

Se confunden a menudo. Nuestro formateador JSON toma JSON válido y lo reescribe con una indentación legible. El validador, por su parte, se contenta con un veredicto sintáctico. No realiza una validación semántica: no sabe si el valor de un campo email parece un email, ni si la estructura se ajusta a un esquema JSON Schema. Para eso, se utilizan herramientas dedicadas (ajv en Node, justinrainbow/json-schema en PHP).

El encadenamiento clásico al depurar es: validar primero (la herramienta indica el error de sintaxis), formatear después (el payload ahora válido se vuelve legible), comparar por último con otro payload de referencia mediante nuestro comparador JSON.

Los errores JSON más frecuentes

• Coma final (trailing comma): {"a": 1, "b": 2,}. Tolerada por JavaScript, ECMAScript y JSON5; rechazada por JSON puro. Es el error n.º 1 al copiar y pegar desde un editor de código.
• Apóstrofes en lugar de comillas dobles: {'a': 1} no es válido. JSON solo acepta comillas dobles, alrededor de las claves y de los valores de cadena.
• Claves sin entrecomillar: {a: 1}, sintaxis JavaScript válida pero JSON no válida.
• Caracteres de control no escapados dentro de una cadena: un salto de línea en bruto, una tabulación. JSON exige \n, \t, \r.
• Comentarios: // commentaire o /* */. Aceptados en JSONC (config VS Code) o JSON5, rechazados en JSON puro.
• Codificación incorrecta: un BOM UTF-8 al inicio del fichero, contenido en latin-1 mal convertido. El validador devuelve a menudo un mensaje genérico para estos casos.
• Estructura sin terminar: un { o [ sin cierre, frecuente cuando se trunca un payload al copiar y pegar.

Cómo localiza el error el validador

La herramienta utiliza json_decode() de PHP con la bandera JSON_THROW_ON_ERROR. PHP devuelve un mensaje que contiene una posición en octetos (position 217), que convertimos en par línea/columna contando los saltos de línea antes del offset. A continuación, se recorta un extracto de unos 80 caracteres en torno a la posición para dar contexto. Suele ser suficiente para detectar el error: una comilla mal colocada, una coma de más, un corchete que falta.

Atención: la posición que reporta PHP no siempre es exactamente el carácter erróneo. A menudo está después del error, en el momento en que el parser ha renunciado. Si el extracto muestra "name": "Alice", }, el error real es la coma, no la llave.

Casos de uso típicos

• Configuración corrupta: composer.json, package.json, tsconfig.json que impiden que arranque un build. Se pega, se ve la línea, se corrige.
• Respuesta de API truncada: un proxy ha cortado el payload. La estructura no está terminada, el validador lo indica.
• Payload de webhook: un servicio de terceros envía JSON mal formado. El validador permite constatar el problema en el lado del emisor sin meterse en el código de la aplicación.
• JSON construido por concatenación: práctica a evitar pero habitual, sobre todo en bash o en SQL. El validador revela las comillas dobles no escapadas.

Límites de la herramienta

El validador no efectúa validación contra un esquema. No dice que falte el campo email, que el valor no es un entero o que la tabla esperada no tiene la longitud adecuada. Para esas comprobaciones estructurales, se utiliza JSON Schema. El validador tampoco corrige el JSON: no intenta añadir una llave que falte ni retirar una coma de más. Es una decisión: la corrección automática enmascara demasiado a menudo errores reales.

Preguntas frecuentes

Ejemplo de solicitud

curl -X POST https://cdrn.fr/api/v1/tools/json-validator/execute \
  -H "Content-Type: application/json" \
  -d '{"input":"..."}'

Esquema de entrada

Puntos de acceso

• GET https://cdrn.fr/api/v1/tools - lista todas las herramientas disponibles
• GET https://cdrn.fr/api/v1/tools/json-validator - recupera el esquema de esta herramienta
• POST https://cdrn.fr/api/v1/tools/json-validator/execute - ejecuta esta herramienta con un payload JSON