JSON Schema es una forma de describir cómo debe ser la estructura de un documento JSON, usando otro documento JSON. En lugar de validar datos a mano con condicionales en el código, se pueden describir de forma declarativa los tipos esperados, los campos obligatorios y las restricciones de valores, y luego comprobar los datos automáticamente.
Palabras clave principales de draft-07
type— el tipo de valor esperado (object, string, number, array, etc.).required— la lista de campos de un objeto que deben estar presentes obligatoriamente.properties— la descripción del esquema para cada campo del objeto por separado.enum— limita un valor a un conjunto concreto de opciones.pattern— valida una cadena con una expresión regular, por ejemplo para el formato del DNI.
Ejemplo: pattern para el DNI español
El DNI español consta de ocho dígitos seguidos de una letra de control: 12345678Z. Un esquema típico usado en pruebas de contrato para una API de registro de usuarios podría describir el campo así: "dni": {"type": "string", "pattern": "^\\d{8}[A-Z]$"}. Esto no comprueba que la letra final sea la correcta según el algoritmo módulo 23 del DNI —para eso hace falta lógica adicional—, pero rechaza de inmediato formatos claramente inválidos, como un DNI con espacios, minúsculas o una longitud incorrecta, antes de que lleguen a la lógica de negocio.
En qué se diferencia de la validación de sintaxis
La validación de JSON normal solo comprueba que el texto sea sintácticamente correcto: llaves, comillas y comas bien puestas. JSON Schema comprueba mucho más: si un objeto tiene un campo obligatorio email, si el valor de age es un número y no una cadena, si status está dentro de la lista de valores permitidos.
Para qué sirve
- Comprobar que la respuesta de una API de terceros cumple el contrato documentado.
- Validar archivos de configuración antes del despliegue para detectar un error a tiempo.
- Documentar la estructura de datos esperada en un formato que se puede comprobar automáticamente de inmediato.
additionalProperties: ¿se pueden añadir campos de más?
Por defecto, JSON Schema permite en un objeto cualquier campo además de los descritos en properties — required y properties solo establecen un mínimo, no una lista exhaustiva. Si hace falta prohibir campos desconocidos, hay que añadir explícitamente "additionalProperties": false — sin ese indicador, el esquema sigue siendo «abierto».