Entendiendo JSON Schema: Valida tus datos como un profesional

¿Alguna vez tuviste un bug donde tu API devolvió "42" (un string) en vez de 42 (un número) y todo lo que venía después se rompió? ¿O alguien envió una petición sin un campo requerido y tu app crasheó en vez de devolver un error útil? JSON Schema existe precisamente para prevenir este tipo de problemas.

Piensa en él como un plano para tus datos JSON — describe qué forma deben tener los datos y atrapa cualquier cosa que no coincida.

Cómo se ve JSON Schema

JSON Schema se escribe en JSON (meta, ¿verdad?). Aquí tienes un schema simple para un objeto usuario:

Esto dice: "Espero un objeto con un name requerido (string no vacío) y un email (formato de email válido), más un age opcional (entero entre 0 y 150)." Si alguien envía {"name": "", "email": "not-an-email"}, el validador detectará ambos problemas.

Construyendo schemas paso a paso

Empieza con el tipo. Cada schema comienza con "type": object, array, string, number, integer, boolean o null.

Agrega restricciones. Para strings: minLength, maxLength, pattern (regex). Para números: minimum, maximum, multipleOf. Para arrays: minItems, maxItems, uniqueItems. La guía oficial de JSON Schema tiene la lista completa.

Marca los campos requeridos. Usa el array "required" a nivel de objeto. Solo lista los campos que realmente deben estar presentes — no hagas todo requerido a menos que sea intencional.

Define objetos anidados. Simplemente anida definiciones de schema dentro de "properties". Aquí tienes un usuario con una dirección:

¿Ese pattern en el código postal? Asegura que solo se acepten códigos postales estadounidenses de 5 dígitos. Este tipo de validación real previene que datos basura se cuelen en tu base de datos.

Por qué deberías usarlo de verdad

Validación de API: Valida los cuerpos de las peticiones entrantes en el borde de tu API. Los datos incorrectos se rechazan con mensajes de error claros antes de que toquen tu lógica de negocio. La mayoría de frameworks lo soportan — Ajv para JavaScript es extremadamente rápido.

Validación de configuración: Valida archivos de configuración al iniciar tu app. Falla rápido con un claro "a tu configuración le falta el campo database.host" en vez de una excepción críptica de puntero nulo 5 minutos después.

Documentación: JSON Schema funciona como documentación viva. Herramientas como Swagger UI generan documentación de API directamente desde los schemas.

Generación de código: Genera interfaces TypeScript, structs de Go o dataclasses de Python desde tu schema. Escríbelo una vez, úsalo en todas partes.

Testing: Valida respuestas de API en tu suite de pruebas para detectar regresiones automáticamente.

Empezar en 30 segundos

¿La forma más rápida de empezar? Genera un schema a partir de datos JSON existentes. Pega una respuesta JSON de ejemplo en nuestro JSON Schema Generator — analizará los datos y producirá un schema que puedes refinar. Luego usa nuestro JSON Schema Validator para probarlo contra datos reales.

También puedes validar programáticamente. Aquí tienes un ejemplo rápido en Node.js con Ajv:

Para Python, echa un vistazo a la biblioteca jsonschema. Para Java, está everit-json-schema. Prácticamente todos los lenguajes tienen buen soporte — consulta la lista completa de implementaciones.

Características avanzadas de Schema que deberías conocer

Una vez que domines lo básico, JSON Schema tiene algunas características potentes que hacen posible la validación compleja.

oneOf, anyOf, allOf — Combinando Schemas:

A veces un campo puede ser uno de varios tipos. Por ejemplo, una API podría aceptar un ID de tipo string o un ID numérico:

Este schema acepta tanto {"id": "PRD-1234"} como {"id": 42} pero rechaza {"id": -1} o {"id": "invalid"}.

$ref — Definiciones de Schema reutilizables:

A medida que tus schemas crecen, querrás evitar repetir las mismas definiciones. La palabra clave $ref te permite referenciar definiciones compartidas:

Ahora tanto billing_address como shipping_address usan exactamente las mismas reglas de validación. Cambia la definición de address una vez, y ambos campos se actualizan. Esto es esencial para mantener schemas grandes manejables.

additionalProperties — Bloquea tus objetos:

Por defecto, JSON Schema permite propiedades adicionales que no están listadas en properties. Esto a menudo NO es lo que quieres — campos inesperados podrían indicar un bug del cliente o una incompatibilidad de versiones. Establece "additionalProperties": false para rechazar campos desconocidos:

Con este schema, {"name": "Alice", "email": "[email protected]", "admin": true} sería rechazado porque admin no es una propiedad definida.

Errores comunes de JSON Schema

Incluso desarrolladores experimentados cometen estos errores al escribir schemas:

1. Olvidar que required está a nivel de objeto, no a nivel de propiedad. Esto es incorrecto:

La forma correcta es:

2. Usar "type": "number" cuando quieres decir "type": "integer". El tipo number acepta decimales como 3.14, mientras que integer solo acepta números enteros. Si tu campo es un contador o un ID, usa integer.

3. No especificar format para patrones comunes. JSON Schema tiene validadores de formato integrados para email, uri, date-time, ipv4, ipv6, uuid y más. Úsalos en vez de escribir patrones regex complejos.

4. Hacer todo requerido. Solo marca campos como requeridos si realmente deben estar presentes. Sobre-restringir tu schema hace más difícil la evolución de la API — agregar un nuevo campo opcional es un cambio no disruptivo, pero pierdes esa flexibilidad si todo es requerido.

Ejemplo del mundo real: Schema de producto E-Commerce

Veamos un schema práctico que podrías usar para una API de productos:

Este schema asegura que cada producto tenga un nombre (1-200 caracteres), un precio positivo y una categoría de una lista fija. Los tags son opcionales pero deben ser strings únicos con un máximo de 10. La palabra clave enum es increíblemente útil para campos que solo deben aceptar valores específicos.

Versiones de JSON Schema: Qué Draft usar

JSON Schema ha pasado por varios drafts — cada uno publicado como un Internet-Draft del IETF — y esto puede ser confuso para los recién llegados. Aquí tienes un resumen rápido:

Para proyectos nuevos, usa 2020-12 (el más reciente). Si trabajas con una base de código existente, verifica qué draft soporta tu validador. La mayoría de validadores modernos como Ajv soportan Draft 7 y posteriores.

Integrando JSON Schema en tu flujo de trabajo

Aquí tienes un enfoque práctico para añadir validación JSON Schema a una API Express.js:

Este patrón te da validación automática de peticiones con mensajes de error claros. La opción allErrors: true asegura que todos los errores de validación se reporten de una vez, no solo el primero.

Pruébalo tú mismo

¿Listo para añadir validación de schema a tu proyecto? Empieza con estas herramientas:

• JSON Schema Generator — Pega cualquier dato JSON y obtén un schema generado automáticamente. Perfecto para crear schemas a partir de respuestas de API de ejemplo.
• JSON Schema Validator — Prueba tu schema contra datos reales para asegurarte de que detecta lo que debe y permite lo que debe.
• JSON Validator — Verifica rápidamente que tu JSON sea sintácticamente válido antes de preocuparte por la validación de schema.

JSON Schema puede parecer trabajo extra al principio, pero se paga muchas veces al detectar bugs en el límite de tu sistema en vez de en lo profundo de tu lógica de negocio.