Qué es JSON Schema
JSON Schema es un vocabulario para describir y validar documentos JSON. Un esquema es a su vez un documento JSON que describe la estructura esperada: qué campos son obligatorios, de qué tipo deben ser, qué rangos valen, qué patrones admiten las cadenas y cómo son los objetos anidados.
Piénsalo como un sistema de tipos para datos guardados o en tránsito, parecido a las interfaces de TypeScript pero para JSON puro y utilizable desde cualquier lenguaje.
Estructura básica
json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"name": { "type": "string" },
"age": { "type": "integer", "minimum": 0 },
"email": { "type": "string", "format": "email" }
},
"required": ["name", "email"]
}
Este esquema define un objeto con tres propiedades (name, age y email), de las cuales name e email son obligatorias. La edad tiene que ser un entero mayor o igual que 0.
Tipos de datos
JSON Schema admite todos los tipos de JSON: string, number, integer, boolean, array, object y null.
Puedes permitir varios tipos a la vez: "type": ["string", "null"] acepta una cadena o un nulo.
Validación de cadenas
json
{
"type": "string",
"minLength": 3,
"maxLength": 50,
"pattern": "^[a-zA-Z0-9_]+$"
}
format ofrece formatos con nombre: "email", "uri", "date" (AAAA-MM-DD), "date-time" (ISO 8601), "uuid" e "ipv4". Ojo: por defecto format es solo una anotación, así que los validadores tienen que activarlo expresamente para que se cumpla.
Validación de números
json
{
"type": "number",
"minimum": 0,
"maximum": 100,
"multipleOf": 0.01
}
exclusiveMinimum y exclusiveMaximum dejan fuera los valores límite. multipleOf comprueba que el valor sea múltiplo del número indicado, muy útil con importes: 0.01 obliga a dos decimales.
Validación de listas
json
{
"type": "array",
"items": { "type": "string" },
"minItems": 1,
"maxItems": 10,
"uniqueItems": true
}
items define el esquema de todos los elementos de la lista. prefixItems (del borrador 2020-12) valida elementos por posición, como en una tupla.
Validación de objetos
json
{
"type": "object",
"properties": {
"id": { "type": "integer" },
"name": { "type": "string" }
},
"required": ["id"],
"additionalProperties": false
}
additionalProperties: false rechaza cualquier propiedad que no figure en properties. Va bien para una validación estricta, pero puede romper la compatibilidad futura: es un error habitual en API de larga vida.
Palabras clave de composición
**allOf**: el valor tiene que ser válido contra todos los esquemas indicados. Se usa para extender o combinar esquemas.
**anyOf**: el valor tiene que ser válido contra al menos uno. Se usa para tipos flexibles.
**oneOf**: el valor tiene que ser válido contra exactamente uno.
**not**: el valor no debe ser válido contra ese esquema.
json
{
"oneOf": [
{ "type": "string" },
{ "type": "integer" }
]
}
Reutilizar con $ref y $defs
Define componentes reutilizables en $defs y referéncialos con $ref:
json
{
"$defs": {
"address": {
"type": "object",
"properties": {
"street": { "type": "string" },
"city": { "type": "string" }
}
}
},
"properties": {
"billing": { "$ref": "#/$defs/address" },
"shipping": { "$ref": "#/$defs/address" }
}
}
Versiones del estándar
JSON Schema tiene varios borradores publicados. El 2020-12 es el estándar actual, y el draft-07 lo siguen admitiendo muchísimas bibliotecas. Comprueba qué borrador admite tu biblioteca de validación antes de escribir esquemas.
El validador de JSON Schema de NoxaKit comprueba tu JSON contra un esquema en el navegador. Y el conversor de JSON a TypeScript genera interfaces a partir de una muestra de JSON, un buen punto de partida para escribir el esquema.