En este artículo
¿Qué es JSON Schema?
JSON Schema es un vocabulario para anotar y validar documentos JSON. Define la estructura, los tipos y las restricciones que un documento JSON debe cumplir. Piénsalo como un contrato: el esquema describe cómo lucen los datos válidos, y los validadores verifican si un documento cumple ese contrato.
JSON Schema está escrito en JSON, lo que lo hace legible por máquinas e independiente del lenguaje. Es compatible con validadores en todos los principales lenguajes de programación (JavaScript/Ajv, Python/jsonschema, Java/everit, Go/gojsonschema) y se usa para validación de APIs, archivos de configuración y generación de formularios.
Conceptos básicos de JSON Schema
Las palabras clave fundamentales definen la estructura de los documentos JSON válidos.
- type — especifica el tipo JSON permitido: string, number, integer, boolean, object, array o null. La restricción más fundamental.
- properties y required — para objetos, 'properties' define el esquema de cada campo y 'required' lista los campos obligatorios. Los campos que no están en 'required' son opcionales por defecto.
- enum y const — 'enum' restringe un valor a un conjunto fijo de opciones, mientras que 'const' lo restringe a un único valor exacto. Útil para campos de estado, categorías y opciones de configuración.
- pattern y format — 'pattern' valida cadenas contra una expresión regular. 'format' proporciona validación semántica como 'email', 'uri', 'date-time' e 'ipv4' sin regex.
Estas palabras clave básicas cubren la mayoría de las necesidades de validación. Un esquema simple puede definir un tipo objeto con la propiedad 'name' (string) obligatoria y 'age' (integer, mínimo 0) opcional.
Funciones avanzadas del esquema
Para requisitos de validación complejos, JSON Schema ofrece composición, referencias y lógica condicional.
- Referencias $ref — reutiliza definiciones de esquema referenciándolas con $ref. Apunta a definiciones dentro del mismo documento ($ref: #/$defs/Address) o archivos externos. Elimina la duplicación en esquemas grandes.
- allOf / anyOf / oneOf — palabras clave de composición que combinan múltiples esquemas. 'allOf' requiere que todos los sub-esquemas coincidan, 'anyOf' requiere al menos uno, y 'oneOf' requiere exactamente uno. Útil para tipos polimórficos.
- if / then / else — esquemas condicionales que aplican diferentes reglas de validación según los valores de los datos. Por ejemplo, si el país es 'US' entonces el código postal debe coincidir con un patrón de 5 dígitos; de lo contrario, se permite cualquier formato.
- additionalProperties — controla si un objeto puede contener propiedades no listadas en 'properties'. Establece en false para validación estricta o en un esquema para restringir propiedades adicionales.
Pruébalo gratis — sin registro
Validar JSON Schema →Versiones del borrador de esquema
JSON Schema ha evolucionado a través de varias versiones de borrador, cada una añadiendo nuevas funciones y refinando el comportamiento existente.
- Draft-04 — la primera versión ampliamente adoptada. Introdujo $ref, required como array y palabras clave de validación básicas. Aún se usa en muchos sistemas heredados y OpenAPI 3.0.
- Draft-06 — añadió la palabra clave const, propertyNames, contains para arrays y esquemas booleanos (true/false como esquemas válidos). Adiciones menores pero útiles.
- Draft-07 — añadió lógica condicional if/then/else, anotaciones readOnly/writeOnly y palabras clave de codificación de contenido. La versión de borrador más popular hoy.
- 2019-09 (Draft 2019-09) — reestructuración mayor. Introdujo $defs (reemplazando definitions), $anchor, unevaluatedProperties y el sistema de vocabulario. Mejor para diseño de esquemas a gran escala.
- 2020-12 (Draft 2020-12) — el borrador estable más reciente. Referencias dinámicas refinadas, prefixItems añadido para validación de tuplas (reemplazando items como array) y formatos de salida mejorados. Recomendado para nuevos proyectos.
Casos de uso comunes
JSON Schema se usa en cualquier lugar donde los datos JSON necesitan validarse o documentarse.
- Validación de API — valida cuerpos de solicitud y parámetros de consulta contra esquemas en middleware Express/Fastify. Las especificaciones OpenAPI/Swagger integran JSON Schema para la definición de contratos de API.
- Validación de configuración — valida archivos de configuración de la aplicación (JSON, YAML convertido a JSON) al inicio. Detecta errores tipográficos y campos faltantes antes de que causen errores en tiempo de ejecución.
- Generación de formularios — herramientas como react-jsonschema-form y vue-jsonschema-form generan automáticamente formularios HTML a partir de definiciones JSON Schema, incluyendo reglas de validación y widgets UI.
- Generación de código — genera interfaces TypeScript, structs Go o dataclasses Python a partir de definiciones JSON Schema. Mantiene los tipos sincronizados con los contratos de API.
Errores de validación comunes
Al validar JSON contra un esquema, estos son los errores más frecuentes que encontrarás.
- Tipo incorrecto — el tipo del valor no coincide con la restricción 'type' del esquema. Ejemplos comunes: string donde se espera number, null para un campo no anulable, u objeto donde se requiere un array.
- Campos requeridos faltantes — el objeto JSON no tiene una propiedad listada en el array 'required'. Los validadores informan qué campo específico falta.
- Error de patrón — un valor de cadena no coincide con la expresión regular 'pattern'. Esto suele detectar formatos de email inválidos, números de teléfono o identificadores personalizados que no siguen el patrón esperado.
- Error de resolución de $ref — el esquema hace referencia a otro esquema mediante $ref que no puede encontrarse. Esto ocurre cuando falta una entrada en $defs, la ruta es incorrecta o los archivos de esquema externos no son accesibles.
Preguntas frecuentes
¿Qué borrador de JSON Schema debo usar para nuevos proyectos?
Use Draft 2020-12 para nuevos proyectos a menos que tenga restricciones. Tiene más funcionalidades (prefixItems para tuplas, unevaluatedProperties, referencias dinámicas) y la mejor calidad de especificación. Si necesita compatibilidad con OpenAPI 3.0, use Draft-04. Si necesita el soporte de bibliotecas más amplio, Draft-07 es la opción más segura — casi todos los validadores lo soportan.
¿Cómo reutilizo esquemas en varios archivos?
Use $ref para referenciar esquemas por URI. Para definiciones locales, coloque los esquemas reutilizables bajo $defs en el mismo archivo y referenciarlos con $ref: '#/$defs/NombreEsquema'. Para referencias entre archivos, use URIs relativas ($ref: './address.json') o absolutas. La mayoría de los validadores soportan la resolución de $ref tanto local como remota.
¿Puede JSON Schema validar objetos anidados?
Sí. Defina esquemas anidados en 'properties' del objeto padre. Cada propiedad anidada puede tener su propio tipo, campos requeridos y reglas de validación. Para estructuras muy anidadas, use $ref para mantener el esquema legible. No hay límite de profundidad de anidamiento — el validador valida recursivamente cada nivel.