¿Qué es la especificación OpenAPI Overlay? #

A medida que las API se vuelven más complejas y sus descripciones se comparten entre múltiples consumidores, equipos y herramientas, cada vez es más importante poder personalizar o ampliar un documento OpenAPI sin modificar su origen. La especificación OpenAPI Overlay se diseñó precisamente para resolver este problema. Proporciona un mecanismo estructurado y reutilizable para aplicar modificaciones concretas sobre un documento OpenAPI existente, lo que permite una separación limpia entre la descripción canónica de la API y las personalizaciones específicas de cada consumidor o despliegue.

¿Qué problema resuelve la especificación Overlay? #

Imagina un equipo que mantiene un único documento OpenAPI de referencia que describe una API de gran tamaño. Distintas partes interesadas necesitan vistas diferentes:

Los desarrolladores internos pueden necesitar la descripción técnica completa con todos los detalles de implementación.
Los portales de documentación pública pueden requerir ejemplos adicionales, descripciones en lenguaje sencillo y los endpoints internos ocultos.
Los generadores de SDK pueden necesitar campos de extensión específicos o convenciones de operationId distintas de las del documento canónico.
Las integraciones con socios pueden requerir un subconjunto de endpoints con descripciones localizadas.

Sin un mecanismo formal de overlays, los equipos acaban manteniendo varias copias divergentes del mismo documento OpenAPI, una pesadilla de mantenimiento. La especificación Overlay ofrece una alternativa fundamentada: definir el documento base una sola vez y describir las diferencias en un archivo de overlay independiente que se puede aplicar sobre él cuando sea necesario.

Estructura de un documento Overlay #

Un documento Overlay es, en sí mismo, un archivo YAML o JSON con una estructura definida. Sus campos de nivel superior son:

overlay: la versión de la especificación Overlay que se utiliza (por ejemplo, 1.1.0).
info: metadatos sobre el overlay, incluidos title y version. A partir de la versión 1.1.0, info también admite un campo opcional description (con compatibilidad con CommonMark) que documenta la finalidad del overlay.
extends: una referencia URI opcional (absoluta o relativa) que identifica el documento OpenAPI concreto que el overlay está diseñado para actualizar, como ./tictactoe.yaml.
actions: una lista ordenada de acciones del overlay que se deben aplicar.

Cada acción del arreglo (array) actions especifica:

target: una expresión JSONPath que identifica qué partes del documento OpenAPI se deben modificar.
update: un objeto, arreglo (array) o valor primitivo que se fusiona con los nodos coincidentes.
remove: un valor booleano (true) para eliminar los nodos coincidentes.
copy: una expresión JSONPath que selecciona un nodo para copiarlo en los nodos coincidentes, añadida en la versión 1.1.0.

Este es un ejemplo básico:

overlay: 1.0.0
info:
  title: Public API Overlay
  version: 1.0.0
actions:
  - target: $.info
    update:
      description: "This is the public-facing version of our API."
  - target: $.paths['/internal/admin']
    remove: true

En este ejemplo, el overlay reemplaza el campo info.description y elimina un endpoint interno antes de publicar el documento externamente. El propio documento OpenAPI base nunca se toca.

Selección basada en JSONPath #

La potencia de los overlays proviene de su uso de JSONPath para seleccionar los elementos que se van a modificar. JSONPath es un lenguaje de consulta para documentos JSON (y, por extensión, YAML), similar a XPath para XML. Permite seleccionar nodos individuales, arreglos de nodos u objetos profundamente anidados mediante una sintaxis de consulta expresiva.

Por ejemplo:

$.paths.*: selecciona todos los elementos de ruta (path items).
$.paths.*.*.responses: selecciona todos los objetos de respuesta de todas las operaciones.
$.components.schemas.User: selecciona el componente de esquema User.
$.paths['/orders'].post.summary: selecciona el resumen de la operación POST /orders.

Esta flexibilidad significa que un overlay puede realizar cambios precisos exactamente en las partes adecuadas de un documento, sin riesgo de efectos secundarios no deseados.

A partir de la versión 1.1.0, la especificación Overlay exige que las expresiones target sean totalmente compatibles con el RFC 9535, el estándar formal de JSONPath, para que los overlays sigan siendo interoperables entre herramientas. Dado que algunas bibliotecas de JSONPath son anteriores al RFC 9535 o solo implementan un subconjunto, es posible que ciertas expresiones de filtro necesiten paréntesis adicionales según la implementación utilizada; por ejemplo, $.paths.*.get.parameters[?(@.name=='filter' && @.in=='query')] en lugar de $.paths.*.get.parameters[?@.name=='filter' && @.in=='query'].

Acciones de Overlay: `update`, `remove` y `copy` #

`update` #

La acción update realiza una fusión profunda del objeto proporcionado con el nodo coincidente. Esto significa que las claves no mencionadas en la actualización se conservan, mientras que las mencionadas se sobrescriben o se añaden. Es similar a JSON Merge Patch (RFC 7396).

- target: $.paths['/users/{id}'].get
  update:
    summary: "Retrieve a user by their unique identifier"
    x-internal-note: "Cached for 60 seconds"

La versión 1.1.0 aclaró que update también funciona directamente sobre nodos con valores primitivos. Por ejemplo, seleccionar un nodo de tipo cadena y proporcionar una cadena nueva lo reemplaza en su lugar:

- target: $.paths['/foo'].get.description
  update: This is the new description

`remove` #

La acción remove elimina por completo el nodo coincidente del documento:

- target: $.paths['/internal/metrics']
  remove: true

Resulta especialmente útil para crear versiones públicas de documentos que no deben exponer endpoints internos o administrativos. Desde la versión 1.1.0, remove también funciona sobre elementos primitivos individuales dentro de un arreglo (array), como eliminar una única etiqueta:

- target: $.paths.*.get.tags[?@ == 'dummy']
  remove: true

`copy` #

Introducida en la versión 1.1.0, la acción copy obtiene su valor de otro lugar del mismo documento de destino, en lugar de un valor literal incluido en el overlay. Se comporta como update, pero el valor que se fusiona se selecciona mediante otra expresión JSONPath en lugar de escribirse directamente. Esto permite duplicar, renombrar o mover partes de un documento.

overlay: 1.1.0
info:
  title: Rename the items path
  version: 1.0.0
actions:
  - target: '$.paths'
    update: { "/new-items": {} }
  - target: '$.paths["/new-items"]'
    copy: '$.paths["/items"]'
  - target: '$.paths["/items"]'
    remove: true
    description: 'moves (renames) the "items" path item to "new-items"'

Esta secuencia primero se asegura de que exista el nodo de destino, copia en él el contenido del nodo de origen y, por último, elimina el original, con lo que /items pasa a llamarse /new-items. Como las acciones se aplican en orden, copy puede combinarse con update y remove para implementar movimientos, cambios de nombre o duplicaciones que no eran posibles solo con update/remove.

Casos de uso reales #

Documentación para varias audiencias #

Una plataforma que atiende tanto a desarrolladores internos como a socios externos puede mantener un único documento OpenAPI canónico y definir overlays independientes para cada audiencia. El overlay externo puede eliminar los endpoints internos y simplificar las descripciones, mientras que el overlay interno puede añadir anotaciones técnicas más detalladas y enlaces a runbooks internos.

Personalización de SDK #

Los generadores de SDK como openapi-generator suelen leer campos de extensión x- para controlar el comportamiento de la generación de código. Los overlays permiten a los equipos inyectar estas extensiones en el documento en el momento de la generación sin contaminar la especificación canónica.

Localización #

Un overlay puede añadir o reemplazar campos description en distintos idiomas, lo que permite ofrecer documentación de la API localizada a partir de una única fuente sin mantener documentos traducidos por separado.

Lanzamientos escalonados de API #

Durante el desarrollo, algunas operaciones pueden marcarse como experimentales o sujetas a cambios. Un overlay puede añadir advertencias o avisos de obsolescencia adecuados para los entornos de preproducción sin afectar al documento de producción.

Aplicar overlays con herramientas #

La especificación Overlay es una incorporación relativamente reciente al ecosistema OpenAPI, pero el soporte de herramientas ha crecido con rapidez. Entre las herramientas con soporte documentado para overlays se encuentran:

Redocly CLI: admite el comando overlay para aplicar archivos de overlay durante el flujo de trabajo del ciclo de vida de la API. Es una de las primeras herramientas en incorporar soporte para overlays.
Bump.sh CLI y Speakeasy CLI: aplican overlays como parte de flujos de trabajo más amplios de documentación de API y generación de SDK.
overlays-js y overlay-jvm: bibliotecas de JavaScript y de JVM para aplicar overlays de forma programática.
apigee-go-gen, openapi-format y oas-patch: utilidades de línea de comandos que incluyen la aplicación de overlays dentro de conjuntos más amplios de herramientas de transformación de OpenAPI.
oas-overlay-java, Specmatic, BinkyLabs.OpenApi.Overlays (.NET), Legba (Clojure) y Zuplo CLI: implementaciones adicionales específicas de cada lenguaje y plataforma.
Pipelines de compilación personalizados: muchos equipos implementan la aplicación de overlays como parte de su pipeline de CI/CD mediante lenguajes de scripting como Python o Node.js, apoyándose en bibliotecas de JSONPath.

El repositorio de la OAI de la especificación Overlay recoge la especificación oficial, las propuestas y una lista actualizada de implementaciones de herramientas.

Relación con otros mecanismos de OpenAPI #

La especificación Overlay es distinta de otros mecanismos de personalización de OpenAPI:

$ref: las referencias se utilizan dentro de un documento para reutilizar componentes. Los overlays operan entre documentos.
Extensiones (campos x-): las extensiones añaden metadatos no estándar dentro de un documento. Los overlays pueden añadir extensiones mediante acciones update.
Callbacks y webhooks: describen el comportamiento de la API; no son mecanismos de personalización de documentos.

Los overlays están diseñados para complementar estas herramientas existentes, no para sustituirlas.

Guías prácticas: cómo usar los overlays de OpenAPI #

Los overlays habilitan una amplia variedad de flujos de trabajo prácticos. Las guías siguientes explican en profundidad aplicaciones específicas del mundo real:

Versionado y estabilidad #

La especificación Overlay alcanzó su primera versión estable, la 1.0.0, en octubre de 2024. Desde entonces se ha actualizado a la versión 1.1.0, publicada el 14 de enero de 2026, que añadió la acción copy, un campo Info.description, soporte explícito para actualizar y eliminar nodos con valores primitivos, una convención de nomenclatura recomendada de archivos purpose.overlay.yaml y el requisito de que las expresiones target sean JSONPath totalmente compatible con el RFC 9535. Los equipos que actualicen overlays existentes deben consultar la guía oficial de actualización. Los equipos que evalúen los overlays para uso en producción deben consultar la última versión de la especificación y confirmar la compatibilidad de sus herramientas antes de adoptarlos en flujos de trabajo críticos.

Conclusión #

La especificación OpenAPI Overlay aborda un problema real de la gestión del ciclo de vida de las API: la necesidad de personalizar y ampliar las descripciones de una API para distintos contextos sin fragmentar la fuente de verdad. Gracias a un modelo de acciones sencillo basado en JSONPath, los overlays permiten mantener un único documento OpenAPI canónico y, al mismo tiempo, producir cualquier número de vistas adaptadas para portales de documentación, generadores de SDK, integraciones con socios y mucho más. A medida que madure el soporte de herramientas, los overlays están llamados a convertirse en una parte estándar de los pipelines de flujo de trabajo profesionales de las API.

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