¿Cómo puedo usar overlays de OpenAPI para copiar o mover elementos en un documento OpenAPI?

¿Cómo puedo usar overlays de OpenAPI para copiar o mover elementos en un documento OpenAPI? #

Antes de la versión 1.1.0, la OpenAPI Overlay Specification solo ofrecía las acciones update y remove. Ambas son útiles, pero ninguna puede hacer referencia a un valor que ya existe en otra parte del documento de destino: cada valor debe escribirse literalmente en el overlay. La versión 1.1.0 (publicada el 14 de enero de 2026) cierra esa brecha con una nueva acción copy, que obtiene su valor de otra ubicación del documento que se está transformando en lugar de un valor literal del overlay. Esto permite duplicar, renombrar o mover nodos existentes usando únicamente overlays.

En qué se diferencia `copy` de `update` #

La acción copy se comporta como update (combina un objeto, concatena un arreglo (array) o reemplaza un valor primitivo), pero el valor que se combina se selecciona mediante una segunda expresión JSONPath en lugar de escribirse en línea:

target: la expresión JSONPath que selecciona los nodos de destino.
copy: una expresión JSONPath que selecciona un único nodo de origen desde el que copiar.

- target: '$.paths["/some-items"]'
  copy: '$.paths["/items"]'

Si target selecciona un objeto, el valor que se combina proviene del objeto seleccionado por copy. Si target selecciona un arreglo, el valor copiado se concatena o se añade al final, siguiendo las mismas reglas de combinación que update. Una misma acción no puede definir a la vez update y copy: update se ignora si copy está presente.

Copia simple #

Dado el siguiente documento OpenAPI:

openapi: 3.1.0
info:
  title: Example API
  version: 1.0.0
paths:
  /items:
    get:
      responses:
        200:
          description: OK
  /some-items:
    delete:
      responses:
        200:
          description: OK

Este overlay copia todas las operaciones de /items a /some-items, combinándolas con lo que ya existe allí:

overlay: 1.1.0
info:
  title: Copy contents of an existing path to a new location
  version: 1.0.0
actions:
  - target: '$.paths["/some-items"]'
    copy: '$.paths["/items"]'
    description: 'copies recursively all elements from the "items" path item to the new "some-items" path item'

El resultado conserva la operación delete existente en /some-items y añade la operación get copiada de /items:

paths:
  /items:
    get:
      responses:
        200:
          description: OK
  /some-items:
    get:
      responses:
        200:
          description: OK
    delete:
      responses:
        200:
          description: OK

Asegurar que el destino exista antes de copiar #

La acción copy se combina con lo que target resuelva en ese momento. Si la ruta de destino todavía no existe, añade primero una acción update para crearla y luego usa copy sobre ella:

overlay: 1.1.0
info:
  title: Create a path and copy the contents of an existing path to the new path
  version: 1.0.0
actions:
  - target: '$.paths'
    update: { "/other-items": {} }
  - target: '$.paths["/other-items"]'
    copy: '$.paths["/items"]'
    description: 'copies recursively all elements from the "items" path item to the new "other-items" path item while ensuring the node exists before the copy'

Como las acciones de un overlay se aplican en orden secuencial, la acción update se ejecuta primero y crea un elemento de ruta /other-items vacío, y la acción copy posterior ya tiene un lugar en el que combinar.

Mover o renombrar una ruta #

Combinar update, copy y remove en secuencia permite mover o renombrar un nodo existente, algo que las acciones update y remove por sí solas no podían expresar, ya que no pueden hacer referencia a valores existentes:

overlay: 1.1.0
info:
  title: Update the path for an API endpoint
  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"'

Al aplicarlo a un documento que contiene /items, se obtiene un documento en el que /items ya no existe y /new-items contiene todo lo que antes estaba bajo /items:

paths:
  /new-items:
    get:
      responses:
        200:
          description: OK
  /some-items:
    delete:
      responses:
        200:
          description: OK

Este patrón de tres pasos (asegurar que el destino exista, copiar el origen en él y eliminar el origen) es la receta general para cualquier operación de mover o renombrar expresada como un overlay.

Cuándo usar `copy` en lugar de `update` #

copy resulta más útil en estos casos:

Renombrar rutas u operaciones durante la evolución de la API, sin tener que volver a escribir en el overlay todo el cuerpo de la operación.
Duplicar una operación o un esquema bien definidos como punto de partida para uno nuevo ligeramente distinto, seguido de un update específico para ajustar la copia.
Reorganizar un documento de forma programática (por ejemplo, agrupar endpoints bajo una nueva ruta base) cuando el contenido que se mueve es grande o cambia con frecuencia, lo que hace poco práctico escribirlo fijo en el overlay.

Para cambios literales sencillos (reemplazar una descripción, añadir una extensión x- o eliminar un campo), update y remove siguen siendo las herramientas adecuadas, ya que no requieren una segunda consulta JSONPath.

Compatibilidad de las herramientas #

La acción copy forma parte de la versión 1.1.0 de la Overlay Specification. Dado que esta función es más reciente que las acciones originales update y remove, confirma que tus herramientas de overlays se hayan actualizado a una versión que implemente la 1.1.0 antes de depender de copy en pipelines de producción; consulta el repositorio de la Overlay Specification para ver la lista actual de herramientas compatibles con la 1.1.0.

Lecturas relacionadas #

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