feat: OpenAPI Overlay 1.1.0

Author: thim81

CHANGELOG.md

@@ -1,5 +1,11 @@
 ## unreleased
 
+- Overlay: add OpenAPI Overlay 1.1.0 support
+- Overlay: add `copy` action support with strict `from` validation
+- Overlay: enforce strict action validation and type compatibility for update/copy actions
+- Types: extend overlay typings with `copy`, `from`, and overlay metadata fields
+- Docs: update overlay examples and guidance to 1.1.0
+
 ## [1.29.5] - 2026-02-28
 
 - Filter: combine inverseTags and inverseFlag (#192)
@@ -431,4 +437,4 @@ Initial commit with features
 - Format via CLI
 - Format via config files
 - Use via as Module
-- Support for OpenAPI 3.0
+- Support for OpenAPI 3.0

bin/cli.js

@@ -420,9 +420,8 @@ async function run(oaFile, options) {
 
     const cliOut = [];
     cliLog.unusedActions.forEach(action => {
-      const description = action.description || 'No description provided';
       cliOut.push(
-        `- Target: ${action.target}\n  Type: ${action.update ? 'update' : action.remove ? 'remove' : 'unknown'}`
+        `- Target: ${action.target}\n  Type: ${action.update ? 'update' : action.remove ? 'remove' : action.copy ? 'copy' : 'unknown'}`
       );
     });
 

readme.md

@@ -1201,22 +1201,25 @@ operationIds:
 The OpenAPI Overlay functionality allows users to apply actions such as updates and removals to an OpenAPI Specification (OAS). This feature is useful for dynamically modifying OAS documents during development, testing, or publishing workflows.
 
 ### What is an OpenAPI Overlay?
-An [OpenAPI Overlay](https://spec.openapis.org/overlay/v1.0.0.html) is a specification that defines a structured set of actions to be applied to an existing OpenAPI document. It enables:
+An [OpenAPI Overlay](https://spec.openapis.org/overlay/v1.1.0.html) is a specification that defines a structured set of actions to be applied to an existing OpenAPI document. It enables:
 
 - Updating existing fields, such as descriptions, parameters, or endpoints.
 - Adding new fields or objects to the OpenAPI document.
 - Removing fields or objects that are no longer relevant.
+- Copying values from one location in the source document to another location.
 
 An overlay document follows the structure below:
 
-```
-overlay: 1.0.0
+```yaml
+overlay: 1.1.0
 info:
   title: Example Overlay
+  description: Overlay to add docs metadata and copy values
   version: 1.0.0
+x-overlay-owner: docs-team
 actions:
-  - target: "$"   // JSONPath definition of the targetted element of the document
-    update: // The action to be applied: update or remove
+  - target: "$"   # JSONPath definition of the targeted element of the document
+    update:       # The action to be applied: update, remove, or copy
       info:
         description: "Updated description for the OpenAPI specification."
   - target: "$.paths['/example']"
@@ -1225,9 +1228,12 @@ actions:
         description: "Updated GET description for /example endpoint."
   - target: "$.paths['/example'].get.parameters"
     remove: true   # Example of removing an element
+  - target: "$.info.title"
+    copy: true
+    from: "$.info.version"
 ```
 
-Fore more information about the OpenAPI Overlay options, see [OpenAPI Overlay Specification 1.0.0](https://www.openapis.org/blog/2024/10/22/announcing-overlay-specification) 
+Fore more information about the OpenAPI Overlay options, see [OpenAPI Overlay Specification 1.1.0](https://spec.openapis.org/overlay/v1.1.0.html).
 
 Use the `--overlayFile` option to specify the overlay file and apply it to your OpenAPI document.
 
@@ -1239,10 +1245,11 @@ $ openapi-format openapi.yaml --overlayFile overlay.yaml -o openapi-updated.yaml
 You can also let the overlay declare the base OpenAPI document using the top-level `extends` property. When `extends` is present, the input file argument becomes optional:
 
 ```yaml
-overlay: 1.0.0
+overlay: 1.1.0
 info:
   title: Overlay for Tic Tac Toe
   version: 1.0.0
+  description: Overlay for docs-only adjustments
 extends: 'https://raw.githubusercontent.com/OAI/learn.openapis.org/refs/heads/main/examples/v3.1/tictactoe.yaml'
 # actions: [...]  # optional
 ```
@@ -1256,6 +1263,11 @@ $ 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.
+- `.overlay.yaml` is the recommended file naming convention for overlays.
+- Overlay actions are processed in strict mode and validated before applying:
+  - `target` must be valid JSONPath.
+  - At least one of `update`, `remove`, or `copy` must be present.
+  - `copy: true` requires `from`, and `from` must resolve to exactly one source node.
 
 ## CLI generate usage
 

test/__utils__/test-utils.js

@@ -44,7 +44,12 @@ async function loadTest(folder, inputType = 'yaml', outType = 'yaml') {
 
 function cli(args, cwd) {
   return new Promise(resolve => {
-    exec(`node ${path.resolve('./bin/cli')} ${args.join(' ')}`, {cwd}, (error, stderr, stdout) => {
+    const env = {...process.env};
+    if (env.FORCE_COLOR && env.NO_COLOR) {
+      delete env.NO_COLOR;
+    }
+
+    exec(`node ${path.resolve('./bin/cli')} ${args.join(' ')}`, {cwd, env}, (error, stderr, stdout) => {
       resolve({
         code: error && error.code ? error.code : 0,
         error,

test/overlay-110-copy/input.yaml

@@ -0,0 +1,12 @@
+openapi: 3.0.3
+info:
+  title: Sample API
+  version: 1.0.0
+paths: {}
+components:
+  schemas:
+    Source:
+      type: object
+      properties:
+        id:
+          type: string

test/overlay-110-copy/options.yaml

@@ -0,0 +1,2 @@
+output: output.yaml
+overlayFile: overlay.overlay.yaml

test/overlay-110-copy/output.yaml

@@ -0,0 +1,13 @@
+openapi: 3.0.3
+info:
+  title: 1.0.0
+  version: 1.0.0
+  description: Applied by overlay 1.1.0
+paths: {}
+components:
+  schemas:
+    Source:
+      type: object
+      properties:
+        id:
+          type: string

test/overlay-110-copy/overlay.overlay.yaml

@@ -0,0 +1,13 @@
+overlay: 1.1.0
+info:
+  title: Overlay 1.1 copy
+  version: 1.0.0
+  description: Updates and copies metadata
+x-overlay-owner: tooling-team
+actions:
+  - target: $.info
+    update:
+      description: Applied by overlay 1.1.0
+  - target: $.info.title
+    copy: true
+    from: $.info.version

test/overlay-combi/overlay.yaml

@@ -11,5 +11,5 @@ actions:
     remove: true
   - target: $.servers
     update:
-      - url: 'https://api.new-example.com'
-        description: New server
+      url: 'https://api.new-example.com'
+      description: New server

test/overlay.test.js

@@ -16,7 +16,9 @@ describe('openapi-format CLI overlay tests', () => {
     };
 
     await openapiOverlay(baseOAS, {overlaySet});
-    expect(consoleSpy).toHaveBeenCalledWith('Action with missing target');
+    expect(consoleSpy).toHaveBeenCalledWith(
+      'Overlay action #1: action target must be a JSONPath string starting with "$".'
+    );
     consoleSpy.mockRestore();
   });
 
@@ -81,7 +83,7 @@ describe('openapi-format CLI overlay tests', () => {
     };
 
     await openapiOverlay(baseOAS, {overlaySet});
-    expect(consoleSpy).toHaveBeenCalledWith('Remove operations are not supported at the root level.');
+    expect(consoleSpy).toHaveBeenCalledWith('Overlay action #1: remove is not supported at target "$".');
     consoleSpy.mockRestore();
   });
 
@@ -216,6 +218,171 @@ describe('openapi-format CLI overlay tests', () => {
     });
   });
 
+  it('should append update values to array targets', async () => {
+    const baseOAS = {servers: [{url: 'https://api.example.com'}]};
+    const overlaySet = {
+      actions: [{target: '$.servers', update: {url: 'https://api.backup.example.com'}}]
+    };
+
+    const result = await openapiOverlay(baseOAS, {overlaySet});
+    expect(result.data.servers).toEqual([
+      {url: 'https://api.example.com'},
+      {url: 'https://api.backup.example.com'}
+    ]);
+  });
+
+  it('should replace primitive values when using update', async () => {
+    const baseOAS = {info: {title: 'Old title'}};
+    const overlaySet = {
+      actions: [{target: '$.info.title', update: 'New title'}]
+    };
+
+    const result = await openapiOverlay(baseOAS, {overlaySet});
+    expect(result.data.info.title).toBe('New title');
+  });
+
+  it('should reject type mismatch for primitive target update', async () => {
+    const consoleSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+    const baseOAS = {info: {title: 'Old title'}};
+    const overlaySet = {
+      actions: [{target: '$.info.title', update: {value: 'New title'}}]
+    };
+
+    const result = await openapiOverlay(baseOAS, {overlaySet});
+    expect(result.data.info.title).toBe('Old title');
+    expect(result.resultData.totalUsedActions).toBe(0);
+    expect(consoleSpy).toHaveBeenCalledWith(
+      'Overlay action #1: update type mismatch - primitive target requires primitive value.'
+    );
+    consoleSpy.mockRestore();
+  });
+
+  it('should copy object values into object targets', async () => {
+    const baseOAS = {
+      info: {title: 'My API', contact: {name: 'Support'}},
+      components: {}
+    };
+    const overlaySet = {
+      actions: [{target: '$.components', copy: true, from: '$.info'}]
+    };
+
+    const result = await openapiOverlay(baseOAS, {overlaySet});
+    expect(result.data.components).toEqual({
+      title: 'My API',
+      contact: {name: 'Support'}
+    });
+    expect(result.resultData.totalUsedActions).toBe(1);
+  });
+
+  it('should append copied values to array targets', async () => {
+    const baseOAS = {
+      servers: [{url: 'https://api.example.com'}],
+      sourceServer: {url: 'https://api.backup.example.com'}
+    };
+    const overlaySet = {
+      actions: [{target: '$.servers', copy: true, from: '$.sourceServer'}]
+    };
+
+    const result = await openapiOverlay(baseOAS, {overlaySet});
+    expect(result.data.servers).toEqual([
+      {url: 'https://api.example.com'},
+      {url: 'https://api.backup.example.com'}
+    ]);
+  });
+
+  it('should replace primitive targets when copying primitive values', async () => {
+    const baseOAS = {
+      info: {title: 'Old title', description: 'New title'}
+    };
+    const overlaySet = {
+      actions: [{target: '$.info.title', copy: true, from: '$.info.description'}]
+    };
+
+    const result = await openapiOverlay(baseOAS, {overlaySet});
+    expect(result.data.info.title).toBe('New title');
+  });
+
+  it('should reject copy action when from resolves zero nodes', async () => {
+    const consoleSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+    const baseOAS = {
+      info: {title: 'API'},
+      components: {}
+    };
+    const overlaySet = {
+      actions: [{target: '$.components', copy: true, from: '$.missing'}]
+    };
+
+    const result = await openapiOverlay(baseOAS, {overlaySet});
+    expect(result.resultData.totalUsedActions).toBe(0);
+    expect(result.resultData.totalUnusedActions).toBe(1);
+    expect(consoleSpy).toHaveBeenCalledWith(
+      'Overlay action #1: "from" must resolve to exactly one node, resolved 0.'
+    );
+    consoleSpy.mockRestore();
+  });
+
+  it('should reject copy action when from resolves multiple nodes', async () => {
+    const consoleSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+    const baseOAS = {
+      servers: [{url: 'https://api.example.com'}, {url: 'https://api.backup.example.com'}],
+      components: {}
+    };
+    const overlaySet = {
+      actions: [{target: '$.components', copy: true, from: '$.servers[*]'}]
+    };
+
+    const result = await openapiOverlay(baseOAS, {overlaySet});
+    expect(result.resultData.totalUsedActions).toBe(0);
+    expect(result.resultData.totalUnusedActions).toBe(1);
+    expect(consoleSpy).toHaveBeenCalledWith(
+      'Overlay action #1: "from" must resolve to exactly one node, resolved 2.'
+    );
+    consoleSpy.mockRestore();
+  });
+
+  it('should apply remove then update then copy in action order', async () => {
+    const baseOAS = {
+      info: {title: 'Old title'},
+      source: {description: 'Copied description'}
+    };
+    const overlaySet = {
+      actions: [
+        {
+          target: '$',
+          remove: true,
+          update: {info: {title: 'Updated title'}},
+          copy: true,
+          from: '$.source'
+        }
+      ]
+    };
+
+    const consoleSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+    const result = await openapiOverlay(baseOAS, {overlaySet});
+    expect(result.data.info.title).toBe('Updated title');
+    expect(result.data.description).toBe('Copied description');
+    expect(result.resultData.totalUsedActions).toBe(1);
+    expect(consoleSpy).toHaveBeenCalledWith('Overlay action #1: remove is not supported at target "$".');
+    consoleSpy.mockRestore();
+  });
+
+  it('should reject unsupported overlay version', async () => {
+    const consoleSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+    const baseOAS = {openapi: '3.0.0', info: {title: 'Test API'}};
+    const overlaySet = {
+      overlay: '2.0.0',
+      actions: [{target: '$.info', update: {description: 'Ignored'}}]
+    };
+
+    const result = await openapiOverlay(baseOAS, {overlaySet});
+    expect(result.data.info.description).toBeUndefined();
+    expect(result.resultData.totalUsedActions).toBe(0);
+    expect(consoleSpy).toHaveBeenCalledWith(
+      'Unsupported overlay version "2.0.0". Supported versions are 1.0.x and 1.1.x.'
+    );
+    consoleSpy.mockRestore();
+  });
+
   it('should add a new unique item to the array during deepMerge', () => {
     const target = [{name: 'param1', in: 'query', description: 'First parameter'}];
     const source = [{name: 'param2', in: 'query', description: 'Second parameter'}];