### Install Dependencies and Run Tests

Source: https://github.com/oai/overlay-specification/blob/main/schemas/v1.1/readme.md

Installs project dependencies and runs the test suite. Ensure you have Node.js and npm installed.

```bash
npm install
npm test
```

--------------------------------

### Install Dependencies with npm

Source: https://github.com/oai/overlay-specification/blob/main/CONTRIBUTING.md

Run this command to install the necessary Node.js dependencies for building the specification locally.

```sh
npm install
```

--------------------------------

### Targeted Overlay Example

Source: https://github.com/oai/overlay-specification/blob/main/versions/1.1.0.md

Apply targeted overlays for specific updates to a large document. This method is more efficient when only a few changes are needed.

```yaml
overlay: 1.1.0
info:
  title: Targeted Overlay
  version: 1.0.0
actions:
  - target: $.paths['/foo'].get.description
    update: This is the new description
  - target: $.paths['/bar'].get.description
    update: This is the updated description
  - target: $.paths['/bar']
    update:
      post:
        description: This is an updated description of a child object
        x-safe: false
```

--------------------------------

### Apply Wildcard Overlay to Multiple Paths

Source: https://github.com/oai/overlay-specification/blob/main/versions/1.1.0.md

Use wildcards in the target to apply updates to multiple nodes simultaneously. This example adds a safe flag to all GET operations.

```yaml
overlay: 1.0.0
info:
  title: Update many objects at once
  version: 1.0.0
actions:
  - target: $.paths.*.get
    update:
      x-safe: true
```

--------------------------------

### Structured Overlay Example

Source: https://github.com/oai/overlay-specification/blob/main/versions/1.1.0.md

Use this structured overlay to update properties throughout the target document by mirroring its structure. This is efficient for large-scale modifications.

```yaml
overlay: 1.0.0
info:
  title: Structured Overlay
  version: 1.0.0
actions:
  - target: '$' # Root of document
    update:
      info:
        x-overlay-applied: structured-overlay
      paths:
        '/':
          summary: 'The root resource'
          get:
            summary: 'Retrieve the root resource'
            x-rate-limit: 100
        '/pets':
          get:
            summary: 'Retrieve a list of pets'
            x-rate-limit: 100
      components:
      tags:
```

--------------------------------

### Add Array Element with Update Action

Source: https://github.com/oai/overlay-specification/blob/main/versions/1.1.0.md

Add a new element to an array using the `update` action. This example adds a new parameter to GET operations.

```yaml
overlay: 1.0.0
info:
  title: Add an array element
  version: 1.0.0
actions:
  - target: $.paths.*.get.parameters
    update:
      name: newParam
      in: query
```

--------------------------------

### Overlay with Relative Extends URI

Source: https://github.com/oai/overlay-specification/blob/main/versions/1.1.0.md

Example of an Overlay document using a relative URI reference for the 'extends' property, pointing to a local target OpenAPI document.

```yaml
overlay: 1.0.0
info:
  title: Overlay for the Tic Tac Toe API document
  version: 1.0.0
extends: './tictactoe.yaml'
```

--------------------------------

### Update Many Objects with Wildcard

Source: https://context7.com/oai/overlay-specification/llms.txt

Use JSONPath wildcards to apply the same change to multiple matching nodes. This example marks every GET operation as safe.

```yaml
overlay: 1.0.0
info:
  title: Update many objects at once
  version: 1.0.0
actions:
  # Mark every GET operation as safe
  - target: $.paths.*.get
    update:
      x-safe: true
  # Point every GET `filter` query param to a shared schema
  - target: "$.paths.*.get.parameters[?@.name=='filter' && @.in=='query']"
    update:
      schema:
        $ref: '#/components/schemas/filterSchema'
```

--------------------------------

### Overlay with Absolute Extends URI

Source: https://github.com/oai/overlay-specification/blob/main/versions/1.1.0.md

Example of an Overlay document specifying an absolute URI for the 'extends' property, indicating the target OpenAPI document.

```yaml
overlay: 1.0.0
info:
  title: Overlay for the Tic Tac Toe API document
  version: 1.0.0
extends: 'https://raw.githubusercontent.com/OAI/learn.openapis.org/refs/heads/main/examples/v3.1/tictactoe.yaml'
...
```

--------------------------------

### Validate Overlay File with npm script

Source: https://context7.com/oai/overlay-specification/llms.txt

Commands to install dependencies and validate an overlay file using the provided 'validate.mjs' script. Supports verbose output and running the full test suite.

```bash
# Install dependencies
npm install

# Validate a single overlay file against the v1.0 schema
node scripts/validate.mjs path/to/my.overlay.yaml

# Validate with verbose output
node scripts/validate.mjs --format=VERBOSE path/to/my.overlay.yaml

# Run the full test suite
npm test
```

--------------------------------

### Append Array Elements with Update

Source: https://context7.com/oai/overlay-specification/llms.txt

When the target node is an array, the `update` value is appended to it. This example adds a default 'api-version' query parameter to all GET operations.

```yaml
overlay: 1.0.0
info:
  title: Add a query parameter to all GET operations
  version: 1.0.0
actions:
  - target: $.paths.*.get.parameters
    update:
      name: api-version
      in: query
      required: false
      schema:
        type: string
        default: '2024-01'
```

--------------------------------

### Move/Rename Path Item

Source: https://context7.com/oai/overlay-specification/llms.txt

Achieve a rename/move operation by combining `update` to create the destination, `copy` to populate it, and `remove` to delete the original. This example renames '/items' to '/new-items'.

```yaml
# Rename /items → /new-items
overlay: 1.1.0
info:
  title: Update the path for an API endpoint
  version: 1.0.0
actions:
  - target: '$.paths'
    update: { "/new-items": {} }             # 1. create destination
  - target: '$.paths["/new-items"]'
    copy: '$.paths["/items"]'               # 2. copy source to destination
  - target: '$.paths["/items"]'
    remove: true                             # 3. delete the original
    description: Moves (renames) /items to /new-items

# Input paths:  /items, /some-items
# Output paths: /new-items, /some-items
```

--------------------------------

### Apply Overlay Updates Based on Traits

Source: https://github.com/oai/overlay-specification/blob/main/versions/1.1.0.md

Use Specification Extensions like `x-oai-traits` in the target document to identify where overlay updates should be applied. This example applies paging parameters only to paths marked with the 'paged' trait.

```yaml
openapi: 3.1.0
info:
  title: API with a paged collection
  version: 1.0.0
paths:
  /items:
    get:
      x-oai-traits: ['paged']
      responses:
        200:
          description: OK
  /items/{id}/subitems:
    get:
      x-oai-traits: ['paged']
      parameters:
        - name: id
          in: path
          required: true
      responses:
        200:
          description: OK
  /other:
    get:
      responses:
        200:
          description: OK
```

```yaml
overlay: 1.0.0
info:
  title: Apply Traits
  version: 1.0.0
actions:
  - target: $.paths[?(@.get['x-oai-traits'][?(@ == 'paged')])].get
    update:
      parameters:
        - name: top
          in: query
          # ...
        - name: skip
          in: query
          # ...
```

--------------------------------

### Copy Path Item to New Location

Source: https://github.com/oai/overlay-specification/blob/main/versions/1.1.0.md

Use the `copy` action to recursively copy all elements from one node to another. This example copies the operations from the `/items` path to a new `/some-items` path.

```yaml
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
```

```yaml
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 without ensuring the node exists before the copy'
```

--------------------------------

### Remove Primitive Array Element (v1.1+)

Source: https://context7.com/oai/overlay-specification/llms.txt

In v1.1+, filter expressions can remove primitive values from string arrays. This example removes the tag 'internal' from GET operations.

```yaml
# v1.1 — remove a primitive value from a string array
---
overlay: 1.1.0
info:
  title: Remove a primitive array element
  version: 1.0.0
actions:
  - target: "$.paths.*.get.tags[?@ == 'internal']"
    remove: true
```

--------------------------------

### Initialize Google Analytics

Source: https://github.com/oai/overlay-specification/blob/main/scripts/md2html/analytics/google.html

Include this JavaScript snippet in your HTML to initialize Google Analytics and start sending data. Replace 'UA-831873-42' with your actual Google Analytics tracking ID.

```javascript
window.dataLayer = window.dataLayer || [];
function gtag(){
  dataLayer.push(arguments);
}

gtag('js', new Date());
gtag('config', 'UA-831873-42');
```

--------------------------------

### Remove Named Array Element

Source: https://context7.com/oai/overlay-specification/llms.txt

Filter expressions can remove specific elements from arrays, including object properties or primitive values. This example removes a parameter named 'dummy' from GET operations.

```yaml
# Remove parameter named "dummy" from every GET operation
- target: "$.paths.*.get.parameters[?@.name == 'dummy']"
  remove: true
```

--------------------------------

### Apply Pagination Trait to Operations

Source: https://context7.com/oai/overlay-specification/llms.txt

This overlay applies the 'paged' trait to all GET operations that have it defined, injecting 'top' and 'skip' query parameters.

```yaml
overlay: 1.0.0
info:
  title: Apply Traits
  version: 1.0.0
actions:
  - target: "$.paths[?(@.get['x-oai-traits'][?(@ == 'paged')])].get"
    update:
      parameters:
        - name: top
          in: query
          schema:
            type: integer
            default: 20
        - name: skip
          in: query
          schema:
            type: integer
            default: 0
```

--------------------------------

### Copy Node Contents (v1.1+)

Source: https://context7.com/oai/overlay-specification/llms.txt

Introduced in v1.1, `copy` merges nodes from a source JSONPath expression into the target node. This example copies the '/items' path item into '/some-items'.

```yaml
# Simple copy: merge /items path item into /some-items
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 all operations from /items into /some-items

# Result: /some-items gains the GET operation from /items
#         while keeping its own DELETE operation
```

--------------------------------

### JSONPath Query Example

Source: https://github.com/oai/overlay-specification/blob/main/README.md

This JSONPath query selects parameters named 'filter' that are of type 'query'. Some JSONPath implementations might require additional parentheses for complex expressions.

```jsonpath
$.paths.*.get.parameters[?@.name=='filter' && @.in=='query']
```

```jsonpath
$.paths.*.get.parameters[?(@.name=='filter' && @.in=='query')]
```

--------------------------------

### Remove Dev Server by Description

Source: https://context7.com/oai/overlay-specification/llms.txt

Use filter expressions with `remove: true` to delete nodes matched by a JSONPath expression. This example removes the 'Dev' server by its description, avoiding index-based removal.

```yaml
# Remove the dev server by description, not by index
overlay: 1.0.0
info:
  title: Remove dev server
  version: 1.0.0
extends: openapi-with-servers.yaml
actions:
  - target: "$.servers[?( @.description == 'Dev' )]"
    remove: true
```

--------------------------------

### Build Final HTML Specifications

Source: https://github.com/oai/overlay-specification/blob/main/CONTRIBUTING.md

Execute this command to generate stand-alone HTML files for all final specifications. The output will be placed in the local `deploy/overlay` folder.

```sh
npm run build
```

--------------------------------

### Build Work-in-Progress HTML Specifications

Source: https://github.com/oai/overlay-specification/blob/main/CONTRIBUTING.md

Use this command to generate stand-alone HTML files for all work-in-progress specifications. The output will be saved in the local `deploy-preview` folder.

```sh
npm run build-dev
```

--------------------------------

### Use Specification Extensions (x- fields)

Source: https://context7.com/oai/overlay-specification/llms.txt

Demonstrates adding custom metadata using 'x-' prefixed fields on various objects within an Overlay document, including 'info' and 'action'.

```yaml
overlay: 1.0.0
info:
  title: Gateway Configuration Overlay
  version: 1.0.0
  x-team: platform-engineering            # custom metadata on info
actions:
  - target: $.paths.*.get
    x-applied-by: gateway-pipeline        # custom metadata on action
    update:
      x-gateway-auth: bearer
      x-rate-limit-tier: standard
```

--------------------------------

### Replace Servers with Sandbox URL

Source: https://context7.com/oai/overlay-specification/llms.txt

This overlay removes the existing servers array and injects a single local development URL, useful for generated SDKs or sandbox portals.

```yaml
# sandbox.overlay.yaml
overlay: 1.1.0
info:
  title: Change server URL
  description: Replace servers list with a single sandbox or local development URL
  version: 1.0.0
actions:
  - target: '$.servers'
    remove: true
  - target: '$'
    update:
      servers:
        - url: http://api-test-tunnel.local
          description: Local development server
```

--------------------------------

### Overlay File Naming Convention

Source: https://context7.com/oai/overlay-specification/llms.txt

Overlay files should follow the `purpose.overlay.yaml` naming pattern. Both JSON and YAML formats are valid, with YAML 1.2 recommended.

```yaml
my-api/
├── openapi.yaml                        # canonical source description
├── add-license.overlay.yaml            # adds licensing metadata
├── sandbox.overlay.yaml                # replaces servers for local dev
├── remove-internal.overlay.yaml        # strips internal-only endpoints
└── translate-es.overlay.yaml           # Spanish documentation overlay
```

--------------------------------

### Ensure Target Exists, Then Copy

Source: https://context7.com/oai/overlay-specification/llms.txt

Actions are applied sequentially. This sequence first creates an empty path item using `update`, then copies content into it using `copy`.

```yaml
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": {} }           # 1. create the empty path item
  - target: '$.paths["/other-items"]'
    copy: '$.paths["/items"]'                # 2. fill it from /items
    description: Ensures the node exists before copying
```

--------------------------------

### Add License Info to OpenAPI Document

Source: https://context7.com/oai/overlay-specification/llms.txt

A minimal overlay to merge a license block into the 'info' object of an OpenAPI description if it's missing.

```yaml
# add-license.overlay.yaml
overlay: '1.0.0'
info:
  title: Add MIT license
  version: '1.0.0'
actions:
  - target: '$.info'
    update:
      license:
        name: MIT
        url: https://opensource.org/licenses/MIT
```

--------------------------------

### Info Object for Overlay Metadata

Source: https://context7.com/oai/overlay-specification/llms.txt

Provides metadata about the overlay itself. 'title' and 'version' are required, while 'description' supports CommonMark markdown.

```yaml
overlay: 1.1.0
info:
  title: Translate API Docs to Spanish
  version: 1.3.0
  description: |
    Replaces all English `description` and `summary` fields with
    their Spanish equivalents for the public developer portal.
actions:
  - target: '$.info'
    update:
      description: 'API de gestión de mascotas — consulte /pets para más detalles.'
```

--------------------------------

### Basic Overlay Document Structure

Source: https://context7.com/oai/overlay-specification/llms.txt

Defines the root structure of an overlay file, including version, metadata, and actions. The 'extends' field can optionally lock the overlay to a specific target document.

```yaml
# my-api.overlay.yaml
overlay: 1.1.0
info:
  title: Production API Overlay
  version: 2.0.0
  description: Applies production-specific settings to the Pet Store API
extends: './petstore.yaml'   # optional: locks overlay to this target
actions:
  - target: '$.info'
    update:
      x-overlay-applied: production-overlay
  - target: '$.servers'
    remove: true
  - target: '$'
    update:
      servers:
        - url: https://api.example.com/v1
          description: Production server
```

--------------------------------

### Overlay Specification JSON Schema (v1.1 abridged)

Source: https://context7.com/oai/overlay-specification/llms.txt

An abridged version of the JSON Schema for Overlay Specification version 1.1, defining the structure and requirements for overlay files.

```yaml
# schemas/v1.1/schema.yaml (abridged)
$id: https://spec.openapis.org/overlay/1.1/schema/WORK-IN-PROGRESS
$schema: https://json-schema.org/draft/2020-12/schema
type: object
required: [overlay, info, actions]
properties:
  overlay:
    type: string
    pattern: '^1\.1\.\d+$'
  info:
    $ref: "#/$defs/info-object"
  extends:
    type: string
    format: uri-reference
  actions:
    type: array
    minItems: 1
    uniqueItems: true
    items:
      $ref: "#/$defs/action-object"
```

--------------------------------

### Update Action: Root-Level Structured Overlay

Source: https://context7.com/oai/overlay-specification/llms.txt

Targets the document root ('$') to update deeply nested paths throughout the document, mirroring the target document's structure.

```yaml
overlay: 1.0.0
info:
  title: Structured Overlay
  version: 1.0.0
actions:
  - target: '$'   # Root of document
    update:
      info:
        x-overlay-applied: structured-overlay
      paths:
        '/':
          summary: The root resource
          get:
            summary: Retrieve the root resource
            x-rate-limit: 100
        '/pets':
          get:
            summary: Retrieve a list of pets
            x-rate-limit: 100
```

--------------------------------

### Copy Path Item to New Path

Source: https://github.com/oai/overlay-specification/blob/main/versions/1.1.0.md

Copies all operations from an existing path item to a new path item after ensuring the target path exists. Use this to duplicate API endpoints.

```yaml
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

```

```yaml
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'

```

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

```

--------------------------------

### Validate a Document Individually

Source: https://github.com/oai/overlay-specification/blob/main/schemas/v1.1/readme.md

Validates a specific YAML document using the provided script. Replace 'path/to/document/to/validate.yaml' with the actual file path.

```bash
node scripts/validate.mjs path/to/document/to/validate.yaml
```

--------------------------------

### Move Path Item using Update, Copy, and Remove

Source: https://github.com/oai/overlay-specification/blob/main/versions/1.1.0.md

Renames a path item by first ensuring the target path exists, then copying the source content, and finally removing the original source. This is useful for refactoring API endpoints.

```yaml
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

```

```yaml
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"'

```

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

```

--------------------------------

### Remove Primitive Array Element

Source: https://github.com/oai/overlay-specification/blob/main/versions/1.1.0.md

Demonstrates removing a primitive value from an array using the `remove` action.

```yaml
overlay: 1.1.0
info:
  title: Remove a primitive array element
  version: 1.0.0
actions:
  - target: $.paths.*.get.tags[?@ == 'dummy']
    remove: true
```

--------------------------------

### Remove Array Element with Remove Action

Source: https://github.com/oai/overlay-specification/blob/main/versions/1.1.0.md

Remove an array element using the `remove` action. It's recommended to avoid using array indexes for removal to prevent issues with changing indices.

```yaml
overlay: 1.0.0
info:
  title: Remove an array element
  version: 1.0.0
actions:
  - target: $.paths.*.get.parameters[?@.name == 'dummy']
    remove: true
```

--------------------------------

### Update Action: Replace Primitives

Source: https://context7.com/oai/overlay-specification/llms.txt

Replaces a primitive node (string, number, boolean) directly when targeted by a JSONPath expression.

```yaml
overlay: 1.1.0
info:
  title: Targeted Overlay
  version: 1.0.0
actions:
  - target: "$.paths['/foo'].get.description"
    update: This is the new description          # replaces the string value
  - target: "$.paths['/bar'].get.description"
    update: This is the updated description
  - target: "$.paths['/bar']"
    update:
      post:
        description: This is an updated description of a child object
        x-safe: false
```

--------------------------------

### Update Action: Merge Objects

Source: https://context7.com/oai/overlay-specification/llms.txt

Performs a deep merge when updating a node. New properties are added, existing primitives are replaced, arrays are concatenated, and nested objects are merged recursively.

```yaml
# Input openapi.yaml excerpt:
# paths:
#   /buildings:
#     get:
#       summary: All buildings

overlay: 1.0.0
info:
  title: Add a building endpoint description
  version: 1.0.0
actions:
  - target: "$.paths['/buildings'].get"
    update:
      description: Returns a paginated list of all buildings in the system.
      summary: All of the available buildings
      x-rate-limit: 100

# Result:
# paths:
#   /buildings:
#     get:
#       summary: All of the available buildings          ← replaced
#       description: Returns a paginated list …          ← inserted
#       x-rate-limit: 100                                ← inserted
```

--------------------------------

### Remove Error Responses

Source: https://context7.com/oai/overlay-specification/llms.txt

This snippet demonstrates removing specific error response codes (500 and default) from all paths using filter expressions.

```yaml
# Remove 500 and default error responses across all paths
# (useful before sharing a public-facing API description)
---
overlay: 1.0.0
info:
  title: Response code removal
  version: 1.0.0
actions:
  - target: $.paths..responses['500']
    remove: true
  - target: $.paths..responses['default']
    remove: true
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.