Validador de OpenAPI JSON

Errores comunes de JSON que hacen fallar la comprobación

JSON es más estricto que YAML, así que la mayoría de los fallos en un archivo editado a mano vienen de la sintaxis y no del diseño de la API. Las causas habituales son una coma sobrante tras la última propiedad, comillas simples en lugar de dobles, un comentario (JSON no los admite) o una llave de cierre que falta tras un objeto paths largo. Un archivo roto suele terminar con el mensaje “No se pudo analizar como JSON ni como YAML”, o con errores de campos ausentes porque no se leyó nada utilizable.

Si solo ves un error de análisis, busca primero el fallo de sintaxis. Las comprobaciones estructurales se ejecutan cuando el documento se lee como objeto.

Un ejemplo práctico

Toma este documento pequeño:

{
  "openapi": "3.0.3",
  "info": { "title": "Orders API" },
  "paths": {
    "orders": { "get": { "summary": "List orders" } }
  }
}

Se parsea, y el campo openapi y el objeto paths están presentes. El informe seguiría mostrando:

Como hay un error, el documento no se considera válido. Añade "version": "1.0.0" a info y renombra la clave a /orders. Una segunda ejecución elimina los dos hallazgos.

Qué significa un resultado correcto y qué no

Un informe limpio significa que la estructura básica está bien. No sigue los enlaces $ref, no comprueba los esquemas ni confirma que cada operación tenga respuestas. Tómalo como una puerta rápida antes de confirmar el archivo y luego ejecuta un linter completo para las reglas más profundas.

Un flujo práctico para especificaciones JSON

Guarda la especificación en control de versiones y pégala aquí antes de cada commit que toque paths. Como la comprobación es rápida, funciona como paso de cordura tras combinar cambios de varias personas, cuando es más probable que haya claves duplicadas o una llave mal colocada. Si tu JSON lo genera un script de compilación, pega la salida generada y no la plantilla, para probar lo que realmente recibirán los lectores. Cuando el informe esté limpio, comparte el archivo o pásalo a un generador de documentación con más confianza en que la estructura de nivel superior es sólida.