Validador de JSON Schema

¿Qué es una herramienta de JSON Schema?#

Un valor JSON por sí solo te dice qué son los datos: una cadena aquí, un número allí. No te dice qué deberían ser los datos: si age debe ser un entero no negativo, si email es obligatorio, si se permite que tags esté vacío. JSON Schema es el vocabulario para decir esas cosas. Escribes un esquema —un pequeño documento JSON que describe una forma— y un validador comprueba si un dato encaja con esa forma, campo a campo.

Esta página hace dos trabajos con un mismo motor de esquemas. Validar toma un esquema y un documento de datos y te dice exactamente qué campos violan qué reglas, cada uno anclado a su ruta en el documento. Inferir va en la otra dirección: dale un valor JSON de muestra y te escribe un esquema de estilo Draft-07 para ti, recorriendo la estructura y registrando el tipo de cada campo. Ambos componen de forma natural: infieres un esquema a partir de una muestra representativa y luego validas cada documento futuro contra él.

La validación se ejecuta con el mismo motor Ajv que usa el código de producción, con tres borradores seleccionables (Draft-07, 2019-09, 2020-12) y la protección de modo estricto relajada, de modo que un esquema ligeramente no estricto se tolera en vez de rechazarse de plano.

Cómo usarlo#

1. Elige un modo en el conmutador de la barra de herramientas:
   • Validar (por defecto): pega tu esquema a la izquierda, tus datos a la derecha.
   • Inferir: pega un valor JSON de muestra a la izquierda, lee el esquema generado a la derecha.
2. En modo Validar, elige el Draft contra el que está escrito el esquema. Draft-07 cubre a la gran mayoría de los esquemas que circulan; elige 2019-09 o 2020-12 solo si tu esquema usa características introducidas en esos borradores.
3. Elige una Sangría para la salida: 2 o 4 espacios. En modo Inferir controla el formato del esquema generado.
4. El panel derecho muestra el documento de datos (Validar) o el esquema inferido (Inferir). Las etiquetas de los paneles cambian según el modo.
5. En modo Validar, el panel Violaciones bajo los paneles enumera cada incumplimiento como ruta — motivo. La raíz del documento se muestra como (root); un campo anidado aparece como su JSON Pointer, como /age.
6. Pulsa Copiar en el panel derecho para llevarte el esquema inferido o los datos, o Ejemplo / Limpiar para cargar o reiniciar.

Los resultados se calculan en cuanto ambas entradas se analizan. Un error de sintaxis en el esquema o en los datos se reporta con su fila y columna exactas, etiquetado como problema de esquema, de datos o de compilación para que sepas dónde mirar.

Características principales#

• Dos modos, un motor. Valida documentos o genera un esquema a partir de una muestra, con el mismo validador de confianza por debajo.
• Tres borradores. Draft-07, 2019-09 y 2020-12 cargan cada uno solo su propio validador compilado, así siempre validas contra el borrador que realmente destinas.
• Todos los errores, no solo el primero. Cada violación se recopila, así un documento con cinco problemas muestra cinco problemas en vez de obligarte a cinco rondas.
• Violaciones ancladas a su ruta. Cada incumplimiento apunta a su ubicación en el documento: (root) para problemas de todo el documento, o un puntero preciso como /user/address/zip.
• Modo estricto relajado. Un esquema con una palabra clave desconocida o sin un tipo de nivel superior se tolera y se ejecuta, no se rechaza al compilar: el comportamiento correcto para una herramienta cuyo trabajo es comprobar, no dar lecciones.
• Solo local. Los esquemas y los datos se procesan en tu navegador. No se sube nada.

Ejemplo detallado#

Un objeto user debe tener un name, y age debe ser un entero no negativo. Pega este esquema a la izquierda en modo Validar:

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer", "minimum": 0 }
  },
  "required": ["name"]
}

Ahora prueba un documento que rompe ambas reglas —sin name, y con un age negativo:

{
  "age": -3
}

El panel de Violaciones reporta dos incumplimientos, cada uno anclado a dónde ocurrió:

(root) — must have required property 'name'
/age   — must be >= 0

La ruta (root) te indica que la propiedad obligatoria ausente es un problema de nivel de documento; /age señala directamente al campo infractor. Corrige los datos a {"name":"ada","age":36} y el estado pasa a válido con una lista de violaciones vacía. El texto del motivo es la propia redacción de palabra clave de Ajv, conservado literal para que coincida con lo que registrarán tus logs de producción.

Preguntas frecuentes#

Draft-07, 2019-09 o 2020-12, ¿cuál elijo?#

Draft-07 es el valor por defecto pragmático: la inmensa mayoría de los esquemas en tutoriales, librerías y especificaciones OpenAPI lo tienen como objetivo, y todo lo que probablemente necesites (type, properties, required, minimum, format, $ref) funciona ahí. Pasa a 2019-09 o 2020-12 solo cuando tu esquema use explícitamente características que esos borradores añadieron, como unevaluatedProperties o el comportamiento revisado de $ref. Elegir el borrador equivocado suele seguir funcionando, pero la opción segura es el borrado que el autor del esquema pretendía.

¿Por qué los mensajes de violación están en inglés?#

Son los propios textos de motivo de Ajv para cada palabra clave (must have required property, must be >= 0, etc.), pasados sin cambios. La idea es la consistencia: son las cadenas exactas que registrará tu validación del lado del servidor, así que emparejarlas aquí hace que un desajuste sea trivialmente rastreable con grep en producción.

¿Qué significa «modo estricto relajado»?#

El modo estricto de Ajv rechaza los esquemas que considera descuidados: una palabra clave desconocida, un $ref que no puede resolver, un type ausente. Eso es útil en un pipeline de build, pero incorrecto para una herramienta validadora, cuyo trabajo es comprobar datos contra el esquema que le entreguen. Esta página desactiva el modo estricto, así que un esquema no estricto compila y se ejecuta en lugar de lanzar un error.

¿Puedo inferir un esquema y luego validarlo contra él?#

Sí, es el viaje de ida y vuelta previsto. Pega una muestra representativa en modo Inferir, copia el esquema generado, cambia a Validar y pega el esquema de vuelta a la izquierda. El esquema inferido vuelve a validar la muestra original sin problemas, y a partir de ahí puedes comprobar cada documento nuevo contra él.