JSON Schema Validator

¿Qué es JSON Schema y por qué es importante?

JSON (JavaScript Object Notation) es la lengua franca de las APIs web, los archivos de configuración y el intercambio de datos. Pero el JSON sin procesar no tiene un sistema de tipos integrado: un campo puede ser una cadena un día y un número al siguiente, y la única forma de descubrir la discrepancia es un error en tiempo de ejecución o un error de datos sutil. JSON Schema llena ese vacío: es un vocabulario declarativo para describir la estructura esperada y las restricciones de un documento JSON, validado frente a datos reales en tiempo de ejecución.

Los equipos utilizan JSON Schema para validar las cargas útiles de las solicitudes de API antes de procesarlas, para hacer cumplir la forma de los archivos de configuración cargados al inicio, para generar automáticamente documentación y formularios de UI desde una única fuente de verdad, y para mantener la consistencia de contratos entre microservicios. OpenAPI — el estándar para la documentación de APIs REST — está construido directamente sobre JSON Schema, convirtiéndolo en el estándar de validación de datos más ampliamente desplegado en la web.

Versiones del borrador de JSON Schema: Draft-07, Draft 2019-09 y Draft 2020-12

JSON Schema ha pasado por varios borradores de especificación. Draft-07, lanzado en 2018, sigue siendo el más ampliamente soportado en todas las principales bibliotecas de validadores y es el dialecto utilizado por OpenAPI 3.0. Introdujo las poderosas palabras clave de validación condicional if/then/else, las anotaciones de propiedad readOnly/writeOnly y las palabras clave de codificación de contenido. Si estás escribiendo esquemas hoy y no necesitas las últimas funciones, Draft-07 es la elección más segura para la máxima compatibilidad con el ecosistema.

Draft 2020-12 es la especificación estable actual e introduce varios cambios significativos: la palabra clave items es reemplazada por prefixItems para la validación de tuplas, las referencias dinámicas usan $dynamicRef en lugar de $recursiveRef, y las nuevas palabras clave unevaluatedProperties y unevaluatedItems proporcionan un control más preciso sobre el contenido adicional. Usa Draft 2020-12 solo si estás en OpenAPI 3.1 o necesitas esas características específicas.

Palabras clave clave de JSON Schema explicadas

La palabra clave type impone un tipo de dato: string, number, integer, boolean, array, object o null. required enumera las propiedades que deben estar presentes en un objeto. properties mapea cada nombre de propiedad a su propio subesquema. pattern aplica una expresión regular a un valor de cadena. minimum, maximum, minLength y maxLength restringen rangos numéricos y de cadena. enum restringe un valor a un conjunto fijo de valores permitidos; const lo restringe a un único valor.

Las palabras clave de composición te permiten construir reglas complejas a partir de bloques de construcción simples: allOf actúa como AND lógico, anyOf como OR y oneOf como XOR. La palabra clave not invierte un esquema. Las palabras clave if/then/else habilitan la validación condicional. Juntas, te permiten expresar casi cualquier regla de validación sin escribir código imperativo personalizado.

JSON Schema en producción: contratos de API y pipelines de CI

En sistemas de producción, la validación de JSON Schema se ejecuta del lado del servidor o en pipelines de CI usando bibliotecas como Ajv (JavaScript/Node.js), jsonschema (Python) o Newtonsoft.Json (C#). Los esquemas se confirman en el control de versiones junto con el código de la aplicación para que los cambios de contrato sean revisados y rastreados como cualquier otro cambio. Los cambios disruptivos — eliminar un campo requerido, reducir un tipo — se detectan en la revisión de código antes de llegar a producción.

Esta herramienta basada en el navegador es ideal para diseñar y depurar esquemas de forma iterativa antes de confirmarlos. Pega tus datos, escribe tu esquema, haz clic en Validar, lee los mensajes de error detallados y refina — sin servidor, sin npm install, sin viajes de ida y vuelta. El validador también formatea tu JSON en cada ejecución de validación, convirtiéndolo en un cómodo formateador de JSON combinado y tester de esquemas.

Ejemplo práctico: Validando una respuesta de API

Supongamos que tu API devuelve un objeto de usuario. Un JSON Schema que lo valida podría requerir un id entero, un nombre de cadena no vacío, un email de cadena que coincida con un patrón de email y un rol de cadena opcional de un enum de 'admin', 'editor' y 'viewer'. Establecer additionalProperties en false asegura que tu API nunca devuelva silenciosamente campos no documentados de los que los consumidores posteriores podrían depender inadvertidamente.

La función if/then/else habilita reglas condicionales — por ejemplo, si el rol es 'admin' entonces se requiere un array de permisos, de lo contrario está prohibido. Estas reglas composicionales permiten que un solo esquema cubra múltiples formas válidas de un objeto sin duplicar definiciones de propiedades. Escribe y prueba ese esquema aquí antes de incrustarlo en tu base de código para ahorrar tiempo de depuración significativo en producción.

Cómo se compara UtiloKit con otros validadores de JSON Schema

La mayoría de las herramientas de validación de JSON Schema online caen en dos categorías: constructores visuales de esquemas y validadores de API del lado del servidor. jsonschema.net te obliga a través de una interfaz de apuntar y hacer clic para construir esquemas — es útil para principiantes que aprenden la estructura del esquema, pero lento para desarrolladores que ya saben qué palabras clave necesitan y solo quieren probar un esquema que han escrito.

jsonschemavalidator.net, construido sobre la biblioteca Newtonsoft.Json de Microsoft, informa errores usando rutas de propiedades .NET y códigos de error que parecen poco familiares para los desarrolladores de JavaScript. Herramientas como Stoplight y SwaggerHub validan esquemas como parte de un documento OpenAPI completo y requieren configuración del proyecto y cuenta.

El validador de UtiloKit funciona con el mismo motor Ajv que impulsa la mayoría de las aplicaciones Node.js, Express y Fastify. Los mensajes de error, las rutas de puntero JSON y el comportamiento de palabras clave coinciden exactamente con tu entorno de producción — y se ejecuta gratis en tu navegador sin cuenta, sin carga, sin límite de tamaño de archivo y sin límite de uso diario.