¿Cómo puedo usar overlays de OpenAPI para enriquecer esquemas con reglas de validación adicionales? #

A veces se aplican reglas de validación más estrictas en un contexto que en otro: un entorno de sandbox puede aceptar datos de entrada más laxos para facilitar las pruebas, mientras que producción impone restricciones más rigurosas; o bien puede presentarse a los desarrolladores un conjunto “recomendado” de restricciones solo a efectos de documentación, sin que todos los servicios consumidores lo apliquen todavía. La OpenAPI Overlay Specification te permite añadir estas palabras clave adicionales de JSON Schema a un esquema existente sin editar la definición canónica del componente.

Añadir restricciones de formato y patrón #

overlay: 1.0.0
info:
  title: Stricter Validation Overlay
  version: 1.0.0
actions:
  - target: $.components.schemas.User.properties.email
    update:
      format: "email"
      pattern: "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$"
  - target: $.components.schemas.User.properties.phoneNumber
    update:
      pattern: "^\\+[1-9]\\d{1,14}$"
      description: "Must be in E.164 format."

Endurecer los límites numéricos para producción #

  - target: $.components.schemas.Order.properties.quantity
    update:
      minimum: 1
      maximum: 1000

Un overlay para sandbox podría, en cambio, dejar estos límites más flexibles o directamente omitirlos, lo que permite a los probadores enviar valores extremos que producción rechaza.

Añadir restricciones enum de forma progresiva #

Al introducir una nueva restricción enum en un campo de cadena que antes era de formato libre, suele ser más seguro desplegarla primero solo como documentación (mediante la descripción) y únicamente después como un overlay de cumplimiento obligatorio, una vez que hayas confirmado que ningún cliente existente envía valores fuera de rango:

  - target: $.components.schemas.Order.properties.status
    update:
      enum: ["pending", "processing", "shipped", "delivered", "cancelled"]

Añadir sugerencias de validación entre campos #

Palabras clave de JSON Schema como dependentRequired (disponibles gracias al soporte completo de JSON Schema 2020-12 en OpenAPI 3.1) pueden añadirse para documentar requisitos condicionales:

  - target: $.components.schemas.ShippingAddress
    update:
      dependentRequired:
        poBox: ["poBoxCountryCode"]

Combinar varias restricciones en una sola pasada #

  - target: $.components.schemas.Product.properties.sku
    update:
      pattern: "^[A-Z]{3}-\\d{6}$"
      minLength: 10
      maxLength: 10
      description: "Three uppercase letters, a hyphen, then six digits."

Validar que el overlay no rompa los datos existentes #

Antes de aplicar restricciones más estrictas en producción, ejecuta el esquema enriquecido contra una muestra de cargas útiles históricas reales para comprobar que ningún dato legítimo existente empiece a fallar de repente en la validación:

redocly join openapi.yaml --overlay validation-overlay.yaml -o dist/openapi.yaml
ajv validate -s dist/openapi.yaml --data "samples/*.json"

Aplicar el overlay de forma selectiva #

Como el grado de rigor de la validación suele tener que variar según el entorno, esta técnica se combina de forma natural con overlays por entorno; consulta la guía relacionada a continuación para combinar ambos enfoques.

Lecturas relacionadas #

Consulta ¿Qué es la OpenAPI Overlay Specification? y ¿Cómo puedo usar overlays de OpenAPI para personalizar la documentación por entorno (dev/staging/prod)? para combinar overlays específicos de entorno y de validación.

Última actualización: 16 de julio de 2026.