La guía completa de JSON Schema (Draft 7)

¿Qué es JSON Schema?

Un JSON Schema es, en sí mismo, un documento JSON que describe la forma de otros datos JSON. Úsalo para validar cargas útiles de APIs, documentar los formatos esperados, generar código (TypeScript, Go) y detectar datos incorrectos antes de que lleguen a tu lógica.

Palabras clave principales

La palabra clave type restringe un valor a string, number, boolean, null, object o array. properties y required describen la forma del objeto; items describe los elementos del array.

{
  "type": "object",
  "properties": {
    "name": { "type": "string", "minLength": 1 },
    "age": { "type": "number", "minimum": 0, "maximum": 150 },
    "email": { "type": "string", "format": "email" }
  },
  "required": ["name", "email"]
}

Más allá de type: enum restringe a un conjunto fijo, const exige un valor exacto, pattern coincide con una expresión regular, minLength/maxLength limitan la longitud de la cadena y additionalProperties: false prohíbe las claves desconocidas.

Un esquema de API del mundo real

Aquí hay un esquema para un endpoint de registro de usuario. Observa cómo cada restricción sirve también como documentación, y cómo required + additionalProperties: false hacen que el contrato sea estricto.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "username": { "type": "string", "pattern": "^[a-zA-Z0-9_]{3,30}$" },
    "email": { "type": "string", "format": "email" },
    "password": { "type": "string", "minLength": 8 },
    "acceptTerms": { "type": "boolean", "const": true }
  },
  "required": ["username", "email", "password", "acceptTerms"],
  "additionalProperties": false
}

Buenas prácticas

Declara siempre $schema para que los validadores sepan a qué draft apuntas. Añade campos description: se convierten en documentación viva de la API. Prefiere format (email, uri) antes que expresiones regulares hechas a mano. Usa additionalProperties: false para APIs estrictas, pero permítelo cuando la extensibilidad importe. Evita los esquemas profundamente anidados: fatorízalos con $ref y definitions.