Validación con JSON Schema Explicada

JSON Schema es un vocabulario que permite anotar y validar datos JSON. Define la estructura, tipos y restricciones de tus datos para que las APIs, archivos de configuración e inputs de usuario puedan verificarse automáticamente para correción.

¿Qué es JSON Schema?

Un JSON Schema es en sí mismo un documento JSON que describe la forma esperada de otro documento JSON. Especifica qué campos deben existir, qué tipos deberían ser, qué valores son aceptables y cómo deberían verse las estructuras anidadas.

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

Este esquema dice: los datos deben ser un objeto con un name requerido (cadena), un age opcional (entero no negativo) y un email requerido (cadena en formato de email).

¿Por qué usar JSON Schema?

Sin validación, tu aplicación acepta cualquier dato silenciosamente y falla de manera impredecible en tiempo de ejecución. JSON Schema captura errores temprano — en el límite de la API, durante la carga de configuración o antes de las escrituras en base de datos.

• Contratos de API — Asegura que los cuerpos de solicitud y respuesta coincidan con el formato esperado.
• Validación de configuración — Captura errores tipográficos y campos faltantes en archivos de configuración.
• Validación de formularios — Valida la entrada del usuario tanto en cliente como en servidor usando el mismo esquema.
• Documentación — Un esquema bien escrito sirve como documentación viva de tu modelo de datos.

Palabras clave principales

Las más importantes son: type especifica el tipo de dato esperado. Para strings: minLength, maxLength, pattern (regex), format. Para números: minimum, maximum. Para arrays: items, minItems, maxItems. Para objetos: properties, required, additionalProperties.

Composición con allOf, anyOf, oneOf

Los esquemas del mundo real frecuentemente combinan múltiples restricciones. JSON Schema proporciona palabras clave de composición: allOf requiere que todos los esquemas coincidan, anyOf requiere que al menos uno coincida, oneOf requiere que exactamente uno coincida, y not invierte un esquema.

Depurando JSON inválido

Cuando la validación falla, necesitas mensajes de error claros. La mayoría de validadores JSON Schema producen salida detallada con la ruta al campo inválido, la restricción que falló y el valor actual. La herramienta JSON Formatter puede ayudarte a formatear e inspeccionar tu JSON antes de validarlo.

Mejores prácticas

• Usa $ref — Evita duplicar esquemas. Define esquemas reutilizables y refiérelos con $ref.
• Sé específico — Usa enum para conjuntos fijos de valores, pattern para formatos de cadena.
• Versiona tus esquemas — Usa $schema y $id para rastrear versiones.
• Valida en los límites — Verifica los datos lo antes posible.

Pruébalo

Usa una herramienta local para validar tus datos JSON contra un esquema — todo se ejecuta en tu navegador, ningún dato sale de tu máquina.