OAS Patcher

February 16, 2026 · View on GitHub

A powerful command-line tool and Python library for working with OpenAPI Specification (OAS) Overlays. Modify and enhance your OpenAPI documents using a declarative overlay approach - no manual editing of large spec files needed!

Documentation PyPI version

Overlay Spec

Key Features

🎯 Overlay System - Apply targeted modifications to OpenAPI documents
📋 Copy Action - Duplicate schemas and components within your API (Overlay 1.1)
📦 Bundle Management - Organize multiple overlays into reusable bundles
🌍 Environment Support - Different configurations for dev, staging, production
🔧 Template Engine - Use variables and dynamic content with Jinja2
✅ Validation - Comprehensive validation for overlays and configurations

Supports OpenAPI Overlay Specification 1.0 and 1.1 - Use the latest features or maintain backward compatibility.

View all features in documentation →

Quick Start

Installation

pip install oas-patch

Basic Usage

  1. Apply an Overlay
oas-patch overlay openapi.yaml overlay.yaml -o modified.yaml
  1. Generate an Overlay (Diff)
oas-patch diff original.yaml modified.yaml -o overlay.yaml
  1. Validate an Overlay
oas-patch validate overlay.yaml

Example

# overlay.yaml
overlay: 1.1.0
info:
  title: Production Environment Overlay
  version: 1.0.0
  description: Configures the API for production use
actions:
  # Update server URL

  - target: "$"
    update:
      servers:
        - url: https://api.production.com
  
  # Copy a schema to create a new one (Overlay 1.1 feature)
  - target: "$.components.schemas.AdminUser"
    copy: "$.components.schemas.User"
    description: Create AdminUser schema based on User schema

Documentation

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.