feat: add capability to use existing content of OpenAPI as input to allow for renaming/editing scenarios

schemas/v1.1/schema.yaml

@@ -0,0 +1,66 @@
+$id: https://spec.openapis.org/overlay/1.1/schema/WORK-IN-PROGRESS
+$schema: https://json-schema.org/draft/2020-12/schema
+description: The description of Overlay v1.1.x documents
+type: object
+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"
+required:
+  - overlay
+  - info
+  - actions
+$ref: "#/$defs/specification-extensions"
+unevaluatedProperties: false
+$defs:
+  info-object:
+    type: object
+    properties:
+      title:
+        type: string
+      version:
+        type: string
+    required:
+      - title
+      - version
+    $ref: "#/$defs/specification-extensions"
+    unevaluatedProperties: false
+  action-object:
+    properties:
+      target:
+        type: string
+        pattern: ^\$
+      description:
+        type: string
+      update:
+        type:
+          - string
+          - boolean
+          - object
+          - array
+          - number
+          - "null"
+      remove:
+        type: boolean
+        default: false
+      destination:
+        type: string
+        pattern: ^\$
+    required:
+      - target
+    $ref: "#/$defs/specification-extensions"
+    unevaluatedProperties: false
+  specification-extensions:
+    patternProperties:
+      ^x-: true

versions/1.0.0.md → src/overlay.md

@@ -4,7 +4,7 @@
 
 The Overlay Specification defines a document format for information that augments an existing [[OpenAPI]] description yet remains separate from the OpenAPI description's source document(s).
 
-## Version 1.0.0
+## Version 1.1.0
 
 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP 14](https://tools.ietf.org/html/bcp14) [RFC2119](https://tools.ietf.org/html/rfc2119) [RFC8174](https://tools.ietf.org/html/rfc8174) when, and only when, they appear in all capitals, as shown here.
 
@@ -115,8 +115,9 @@ This object represents one or more changes to be applied to the target document
 | ---- | :----: | ---- |
 | <a name="action-target"></a>target | `string` | **REQUIRED** A JSONPath expression selecting nodes in the target document. |
 | <a name="action-description"></a>description | `string` | A description of the action. [[CommonMark]] syntax MAY be used for rich text representation. |
-| <a name="action-update"></a>update | Any | If the `target` selects an object node, the value of this field MUST be an object with the properties and values to merge with the selected node. If the `target` selects an array, the value of this field MUST be an entry to append to the array. This field has no impact if the `remove` field of this action object is `true`. |
+| <a name="action-update"></a>update | Any | If the `target` selects an object node, the value of this field MUST be an object with the properties and values to merge with the selected node. If the `target` selects an array, the value of this field MUST be an entry to append to the array. |
 | <a name="action-remove"></a>remove | `boolean` | A boolean value that indicates that the target object or array MUST be removed from the the map or array it is contained in. The default value is `false`. |
+| <a name="action-destination"></a>destination | `string` | A JSONPath expression selecting destination nodes in the target document. If set, this indicates that each node in the target expression (after applying the update) should be appended as a child to the destination node. If not set, the target is mutated in-place. |
 
 The result of the `target` JSONPath expression MUST be zero or more objects or arrays (not primitive types or `null` values).
 
@@ -226,6 +227,51 @@ actions:
     remove: true
 ```
 
+#### Destination Example
+
+The `destination` property enables moving or copying elements from one location to another in the target document. This is useful for reorganizing content or creating shared references.
+
+##### Renaming Path Items
+
+To rename a path from `/item` to `/newitem`:
+
+```yaml
+overlay: 1.0.0
+info:
+  title: Rename path items
+  version: 1.0.0
+actions:
+  - target: $.paths
+    update: 
+      "/newitem": {}
+  - target: $.paths["/item"]
+    destination: $.paths["/newitem"]
+    remove: true
+```
+
+This transforms:
+
+```yaml
+paths:
+  /item:
+    summary: 'The root resource'
+    get:
+      summary: 'Retrieve the root resource'
+      # ...
+```
+
+To:
+
+```yaml
+paths:
+  /newitem:
+    summary: 'The root resource'
+    get:
+      summary: 'Retrieve the root resource'
+      # ...
+```
+
+
 #### Traits Example
 
 By annotating a target document (such as an [[OpenAPI]] document) using [Specification Extensions](#specification-extensions) such as `x-oai-traits`, the author of the target document MAY identify where overlay updates should be applied.
@@ -281,4 +327,5 @@ The extensions may or may not be supported by the available tooling, but those m
 
 | Version | Date | Notes |
 | ---- | ---- | ---- |
+| 1.1.0 | TBD | Added `destination` field to Action Object for moving/copying elements |
 | 1.0.0 | 2024-10-17 | First release of the Overlay Specification |