Overlays

Apply structured update and remove actions to your OpenAPI document using the OpenAPI Overlay Specification .

CLI Usage

Terminal

npx openapi-format openapi.yaml --overlayFile overlay.yaml -o openapi-updated.yaml

Overlay Structure

An overlay document defines actions with JSONPath targets:

overlay.yaml

overlay: 1.0.0
info:
  title: Example Overlay
  version: 1.0.0
actions:
  - target: "$"
    update:
      info:
        description: "Updated API description."
  - target: "$.paths['/example']"
    update:
      get:
        description: "Updated GET description."
  - target: "$.paths['/example'].get.parameters"
    remove: true

Example: Update Description

overlay.yaml

overlay: 1.0.0
info:
  title: Update API info
  version: 1.0.0
actions:
  - target: "$"
    update:
      info:
        description: "The official Pet Store API — production ready."

Before

openapi: 3.0.3
info:
  title: Pet Store API
  version: 1.0.0
  description: A sample API
paths:
  /pets:
    get:
      summary: List all pets

After — description updated

openapi: 3.0.3
info:
  title: Pet Store API
  version: 1.0.0
  description: "The official Pet Store API — production ready."
paths:
  /pets:
    get:
      summary: List all pets

Example: Add Server & Update Endpoint

overlay.yaml

overlay: 1.0.0
info:
  title: Production overlay
  version: 1.0.0
actions:
  - target: "$"
    update:
      servers:
        - url: https://api.example.com/v1
          description: Production server
  - target: "$.paths['/pets'].get"
    update:
      summary: "List all pets (paginated)"
      description: "Returns a paginated list of pets."
      parameters:
        - name: limit
          in: query
          schema:
            type: integer

Before

openapi: 3.0.3
info:
  title: Pet Store API
  version: 1.0.0
paths:
  /pets:
    get:
      summary: List all pets

After — server & parameter added

openapi: 3.0.3
info:
  title: Pet Store API
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
    description: Production server
paths:
  /pets:
    get:
      summary: "List all pets (paginated)"
      description: "Returns a paginated list of pets."
      parameters:
        - name: limit
          in: query
          schema:
            type: integer

Example: Remove Fields

overlay.yaml

overlay: 1.0.0
info:
  title: Cleanup overlay
  version: 1.0.0
actions:
  - target: "$.paths['/internal/debug']"
    remove: true
  - target: "$.paths['/pets'].get.x-internal"
    remove: true

Before

openapi: 3.0.3
info:
  title: API
  version: 1.0.0
paths:
  /pets:
    get:
      x-internal: true
      summary: List all pets
  /internal/debug:
    get:
      summary: Debug endpoint

After — debug path & flag removed

openapi: 3.0.3
info:
  title: API
  version: 1.0.0
paths:
  /pets:
    get:
      summary: List all pets

Using extends

The overlay can declare a base OpenAPI document with extends, making the input file optional:

overlay.yaml

overlay: 1.0.0
info:
  title: Overlay for Tic Tac Toe
  version: 1.0.0
extends: 'https://raw.githubusercontent.com/.../tictactoe.yaml'
actions:
  - target: "$"
    update:
      info:
        description: "Modified description"

Terminal

# No input file needed when extends is set
npx openapi-format --overlayFile overlay.yaml -o openapi-updated.yaml

Notes

extends supports both local paths and remote HTTP(S) URLs
Local relative paths are resolved relative to the overlay file's location