JSON Schema

JSON Schema es una forma estándar de describir cómo es un documento JSON válido: qué propiedades existen, sus tipos, cuáles son obligatorias, qué valores y formatos se permiten. Después, un validador comprueba los datos reales contra el esquema e informa de cada incumplimiento. Para los testers de APIs, convierte “la respuesta parece correcta” en una única comprobación repetible de toda la forma de la respuesta. La versión actual de la especificación es el draft 2020-12; el draft-07 se sigue usando muchísimo.

Ejemplo

Un esquema para un usuario devuelto por GET /users/{id}:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["id", "email", "role", "createdAt"],
  "properties": {
    "id": { "type": "integer", "minimum": 1 },
    "email": { "type": "string", "format": "email" },
    "role": { "enum": ["admin", "member", "viewer"] },
    "createdAt": { "type": "string", "format": "date-time" },
    "nickname": { "type": ["string", "null"] }
  },
  "additionalProperties": false
}

Validación en Node con Ajv (ajv/dist/2020 admite el draft 2020-12, y ajv-formats añade email y date-time):

import Ajv2020 from 'ajv/dist/2020';
import addFormats from 'ajv-formats';

const ajv = new Ajv2020({ allErrors: true });
addFormats(ajv);
const validate = ajv.compile(userSchema);

if (!validate(responseBody)) {
  console.log(validate.errors);
}

En Java, el módulo json-schema-validator de REST Assured ofrece matchesJsonSchemaInClasspath("schemas/user.json") para usarlo dentro de .body(...). Comprueba qué draft admite tu validador antes de usar palabras clave más recientes.

Por qué importa

• Una sola assertion cubre toda la forma. Los campos que faltan, los tipos incorrectos y los null inesperados se detectan sin escribir una comprobación por campo.
• Detecta filtraciones. "additionalProperties": false falla si la respuesta de repente incluye algo como passwordHash.
• Documenta el contrato. Las especificaciones OpenAPI usan JSON Schema para describir los cuerpos de petición y respuesta.

Errores comunes

• Esquemas que aceptan cualquier cosa. Un esquema sin required pasa con {}. Enumera siempre los campos obligatorios.
• Suponer que format se aplica. Muchos validadores tratan format como una simple anotación a menos que se active la validación de formatos.
• Validar solo el esquema. Una respuesta puede cumplir el esquema y aun así contener el usuario equivocado. Mantén assertions de valores para los datos que importan.