¿Odias los anuncios? Ir Sin publicidad Hoy 

Validación de esquema JSON Captura de violaciones de contrato de API antes de su lanzamiento

Publicado el 11 de mayo de 2026

La validación de esquema JSON detecta violaciones del contrato de API en la fuente. Aprende las palabras clave principales, el middleware AJV para Express, la integración con FastAPI, la detección de desviación de esquema y la relación con OpenAPI.

Validación de Esquema JSON: Detectar violaciones del contrato de API antes de su lanzamiento 1

ANUNCIO · ¿ELIMINAR?

Si tu API devuelve un campo que tu esquema indica que no existe, o acepta un cuerpo de solicitud con una propiedad requerida ausente, tienes un incumplimiento del contrato. Estos errores son sutiles, a menudo silenciosos, y son extremadamente costosos de encontrar en producción. La validación de esquema JSON es la capa que los detecta más temprano —más cerca de donde se introducen.

Este guía cubre cómo funciona el esquema JSON, qué validadores utilizar en Node.js, Python y AWS, y cómo mantener tu esquema lejos de la realidad.

¿Qué es un esquema JSON?

JSON Schema es un vocabulario para describir la estructura de un documento JSON. No es código —es metadatos. Escribes un esquema que declara cómo debe verse un objeto JSON válido, luego lo validas.

El esquema en sí es un documento JSON. Un ejemplo mínimo:

{
  "$schema": "https://json-schema.org/draft/2020-12",
  "type": "object",
  "properties": {
    "email": { "type": "string", "format": "email" },
    "age":   { "type": "integer", "minimum": 0 }
  },
  "required": ["email"]
}

Eso es todo. Proporciona este esquema a un validador con cualquier carga JSON, y obtendrás un resultado de aprobación o una lista estructurada de errores.

Palabras clave principales

Un conjunto pequeño de palabras clave cubre la mayoría de las necesidades de validación en el mundo real:

Palabra clave	Qué valida	Ejemplo
`type`	Tipo de valor	`"type": "string"`
`properties`	Forma de los campos de un objeto	`"properties": { "name": { "type": "string" } }`
`required`	Propiedades que deben estar presentes	`"required": ["email", "password"]`
`additionalProperties`	Si se permiten propiedades desconocidas	`"additionalProperties": false`
`enum`	El valor debe ser uno de un conjunto fijo	`"enum": ["admin", "editor", "viewer"]`
`format`	Verificación semántica de formato	`"format": "email"` o `"format": "date-time"`
`pattern`	La cadena debe coincidir con una expresión regular	`"pattern": "^[a-z0-9-]+$"`
`$ref`	Referencia a otro esquema	`"$ref": "#/$defs/Address"`

additionalProperties: false merece mención especial. Es la palabra clave que hace que tu esquema sea estricto —cualquier propiedad no declarada en properties genera un error de validación. Está desactivada por defecto, lo que significa que la mayoría de los esquemas aceptan campos basura sin que se note a menos que lo actives.

Un esquema completo: solicitud de registro de usuario

Aquí tienes un esquema JSON completo para el cuerpo de la solicitud de un punto de entrada de registro. Este es el tipo de esquema que escribirías una vez y que validarias en cada capa que accede al punto de entrada.

{
  "$schema": "https://json-schema.org/draft/2020-12",
  "title": "UserRegistration",
  "type": "object",
  "required": ["email", "password", "username"],
  "additionalProperties": false,
  "properties": {
    "email": {
      "type": "string",
      "format": "email"
    },
    "password": {
      "type": "string",
      "minLength": 8
    },
    "username": {
      "type": "string",
      "pattern": "^[a-zA-Z0-9_]{3,32}$"
    },
    "role": {
      "type": "string",
      "enum": ["user", "admin"],
      "default": "user"
    },
    "birthDate": {
      "type": "string",
      "format": "date"
    }
  }
}

Puedes probarlo interactivamente contra cualquier carga usando el Validador de esquema JSON IO Tools antes de integrarlo en tu código base.

Validación de cuerpos de solicitud de API

Express + AJV

AJV es el validador más rápido de esquema JSON para Node.js. Aquí tienes un middleware de Express que valida el cuerpo de la solicitud antes de que llegue al manejador:

import Ajv from "ajv";
import addFormats from "ajv-formats";

const ajv = new Ajv({ allErrors: true });
addFormats(ajv);

function validateBody(schema) {
  const validate = ajv.compile(schema);
  return (req, res, next) => {
    if (validate(req.body)) {
      return next();
    }
    res.status(400).json({
      error: "Validation failed",
      details: validate.errors,
    });
  };
}

// Usage
app.post("/register", validateBody(registrationSchema), registerHandler);

allErrors: true le dice a AJV que recoja todos los errores en el documento en lugar de detenerse al primero —útil cuando deseas devolver todos los errores de validación al cliente en un solo momento.

Nginx

En Python, FastAPI utiliza Pydantic en el fondo y genera un esquema JSON a partir de tus anotaciones de tipo de forma automática. Si estás trabajando con un esquema JSON crudo desde una fuente externa en lugar de modelos de Pydantic, jsonschema es la biblioteca estándar:

from jsonschema import validate, ValidationError

schema = { ... }  # your schema dict

try:
    validate(instance=request_body, schema=schema)
except ValidationError as e:
    return {"error": e.message}, 400

AWS API Gateway

API Gateway soporta la validación del cuerpo de solicitud de forma nativa. Definirás un modelo (que es un documento de esquema JSON) y lo asociarás al método como un REQUEST_BODY validador. Las solicitudes que fallen en la validación son rechazadas al nivel del gateway —antes de que tu función Lambda se ejecute. Esto elimina una clase completa de errores en los manejadores y reduce las invocaciones de frío para tráfico inválido.

Esquemas reutilizables con `$ref` y `$defs`

Cuando múltiples esquemas comparten una estructura común —como una dirección, un monto monetario o un objeto de paginación— definirla una sola vez en $defs y referenciársela con $ref:

{
  "$defs": {
    "Address": {
      "type": "object",
      "required": ["street", "city", "country"],
      "properties": {
        "street": { "type": "string" },
        "city":   { "type": "string" },
        "country": { "type": "string", "pattern": "^[A-Z]{2}$" }
      }
    }
  },
  "type": "object",
  "properties": {
    "billingAddress":  { "$ref": "#/$defs/Address" },
    "shippingAddress": { "$ref": "#/$defs/Address" }
  }
}

Para proyectos más grandes, los esquemas viven en archivos separados y $ref punta a una URI. Validadores que soporten la palabra clave y la resolución de URI pueden cargar esquemas de forma diferida o desde un registro —AJV maneja esto mediante $id Drift de esquema addSchema().

El drift de esquema ocurre cuando el esquema y la API real se desvían. Es más común de lo que parece: el esquema se escribe una vez, la API evoluciona y nadie actualiza el esquema.

Los síntomas son sutiles. Un campo se renombra en el código pero no en el esquema —la validación sigue pasando porque

no está establecida en falso. Un campo requerido se vuelve opcional en la práctica porque el código ya no lo verifica —el esquema sigue diciendo que es requerido, pero nadie lo nota hasta que un cliente envía una solicitud sin él. additionalProperties Detectar el drift requiere tratar la validación del esquema como una prueba, no como una comprobación en tiempo de ejecución. Algunos equipos lo automatizan con pruebas de instantáneas contra fijos de respuestas reales. Otros ejecutan el validador de esquema en CI contra un conjunto de solicitudes capturadas. El punto es que el esquema debe ser probado regularmente, no solo desplegado una vez.

JSON Schema y OpenAPI

OpenAPI (anteriormente Swagger) utiliza JSON Schema para describir los cuerpos de solicitud y respuesta, pero con algunas modificaciones. Versiones anteriores (OpenAPI 2.0, 3.0) usaban un subconjunto de JSON Schema con extensiones. OpenAPI 3.1 se alinea más estrechamente con JSON Schema draft 2020-12, por lo que los esquemas son en gran parte intercambiables.

La diferencia práctica: OpenAPI envuelve los esquemas en un documento más grande que también describe rutas, operaciones, autenticación y servidores. JSON Schema por sí solo es simplemente un contrato de validación. Si estás construyendo una API basada en esquemas, puedes escribir el esquema JSON para cada punto de entrada, validar contra él y luego transferir esos esquemas directamente a un documento OpenAPI.

Generación de esquemas a partir de datos existentes

Escribir esquemas a mano funciona bien para nuevas APIs. Para APIs existentes con comportamiento no documentado, a menudo es más rápido generar un esquema a partir de cargas reales y luego ajustarlo.

(Python) y

Herramientas como genson (Node.js) toman objetos JSON de ejemplo y producen un esquema preliminar. El esquema generado es casi siempre demasiado permissive —todo se vuelve opcional, no hay generate-schema — pero te da un punto de partida. Luego añades additionalProperties: false , ajustas requireddefiniciones, y añades type restricciones donde los valores están acotados. enum Este enfoque también ayuda al incorporar una API de terceros sin documentación de esquema. Ejecuta varias respuestas a través de un generador de esquemas, combínalas y tendrás un contrato funcional para validar.

La validación de esquema JSON debe estar presente en cada capa que acepte datos estructurados —como middleware HTTP, consumidores de colas de mensajes, rutas de escritura en bases de datos. Cuanto antes se detecte un incumplimiento del contrato, más barato será corregirlo. Un

validador de esquema JSON en línea te permite prototipar esquemas contra cargas reales antes de comprometerte con una integración de biblioteca, lo que lo convierte en el primer paso adecuado para cualquier trabajo de validación. Validación de esquema JSON: capturando incumplimientos de contrato de API antes de que se envíen 2