¿Qué es JSON Schema?
JSON Schema es un meta-lenguaje para describir cómo debe verse un documento JSON. Defínis
tipos (string, integer, object, array),
propiedades requeridas, valores mínimos y máximos, formatos (email, date-time, uri) y
patrones regex. Validadores como Ajv chequean un payload contra el schema y reportan los
errores con paths exactos.
Estructura básica
Un schema empieza con $schema apuntando al draft, $id con la URI
única, y type declarando el tipo raíz. Para un objeto, properties
lista cada campo y required los obligatorios. additionalProperties: false
rechaza campos no declarados; útil para evitar typos.
Formatos comunes
- email: valida un email RFC 5322.
- date-time: ISO 8601 (ej. 2024-01-15T10:30:00Z).
- date: solo fecha (2024-01-15).
- uuid: UUID v1-v8.
- uri: URL válida.
- ipv4, ipv6: direcciones IP.
Validación de strings
minLength, maxLength y pattern (regex) son tus
amigos. Ejemplo de teléfono argentino:
"pattern": "^\\+?54-?[0-9]{9,12}$". enum limita a un
conjunto fijo: "enum": ["pending", "paid", "shipped"].
Validación de números
minimum, maximum, exclusiveMinimum, exclusiveMaximum
y multipleOf. Para precios: "minimum": 0, "multipleOf": 0.01.
integer en lugar de number rechaza decimales.
Validación de arrays
items describe el schema de cada elemento. minItems,
maxItems y uniqueItems son útiles para listas. Para arrays con
diferentes tipos por posición (tuplas), usá prefixItems en draft 2020-12.
Combinaciones: oneOf, anyOf, allOf
oneOf exige que matchee exactamente uno; útil para discriminated unions.
anyOf matchea uno o más. allOf exige que matchee todos; usado
para extender schemas. not niega un schema.
De schema a tipos
json-schema-to-typescript convierte un schema en interfaces TS. Mantenés una
sola fuente de verdad: el schema valida en runtime y los tipos cuidan el código. Lo opuesto,
generar schemas desde tipos TS, está disponible vía typescript-json-schema o
ts-json-schema-generator.