From f58c7eefaf4c5bd4e5240364622cd5a24c692d4f Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Tue, 17 Dec 2024 17:16:19 +0000 Subject: [PATCH 1/3] Copy 1.0.0 to working spec file location for ongoing development --- versions/1.0.0.md => src/overlay.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename versions/1.0.0.md => src/overlay.md (100%) diff --git a/versions/1.0.0.md b/src/overlay.md similarity index 100% rename from versions/1.0.0.md rename to src/overlay.md From 46a2aa89984a5aadfddfb4dcf633df791c662482 Mon Sep 17 00:00:00 2001 From: Thomas Rooney Date: Thu, 10 Jul 2025 15:45:33 +0100 Subject: [PATCH 2/3] feat: add capability to use existing content of OpenAPI as input to allow renaming/editing --- src/overlay.md | 70 ++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 68 insertions(+), 2 deletions(-) diff --git a/src/overlay.md b/src/overlay.md index fa577f6..e739245 100644 --- a/src/overlay.md +++ b/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 | ---- | :----: | ---- | | target | `string` | **REQUIRED** A JSONPath expression selecting nodes in the target document. | | description | `string` | A description of the action. [[CommonMark]] syntax MAY be used for rich text representation. | -| 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`. | +| 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. | | 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`. | +| 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,70 @@ 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' + # ... +``` + +##### Moving Schemas to Components + +```yaml +overlay: 1.0.0 +info: + title: Move schemas to components + version: 1.0.0 +actions: + - target: $.paths['/pets'].get.responses['200'].content['application/json'].schema + destination: $.components.schemas + update: + $id: 'PetList' + - target: $.paths['/pets/{id}'].get.responses['200'].content['application/json'].schema + destination: $.components.schemas + update: + $id: 'Pet' +``` + +In this example, inline schemas are moved to the components section of the OpenAPI document. The `update` adds an identifier to each schema as it's moved. + #### 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 +346,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 | From dcc3da31cc50933bb41b09176f84b595034a737f Mon Sep 17 00:00:00 2001 From: Thomas Rooney Date: Thu, 10 Jul 2025 15:51:25 +0100 Subject: [PATCH 3/3] chore: clean up proposal --- schemas/v1.1/schema.yaml | 66 ++++++++++++++++++++++++++++++++++++++++ src/overlay.md | 19 ------------ 2 files changed, 66 insertions(+), 19 deletions(-) create mode 100644 schemas/v1.1/schema.yaml diff --git a/schemas/v1.1/schema.yaml b/schemas/v1.1/schema.yaml new file mode 100644 index 0000000..35a2d5b --- /dev/null +++ b/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 diff --git a/src/overlay.md b/src/overlay.md index e739245..51b86a7 100644 --- a/src/overlay.md +++ b/src/overlay.md @@ -271,25 +271,6 @@ paths: # ... ``` -##### Moving Schemas to Components - -```yaml -overlay: 1.0.0 -info: - title: Move schemas to components - version: 1.0.0 -actions: - - target: $.paths['/pets'].get.responses['200'].content['application/json'].schema - destination: $.components.schemas - update: - $id: 'PetList' - - target: $.paths['/pets/{id}'].get.responses['200'].content['application/json'].schema - destination: $.components.schemas - update: - $id: 'Pet' -``` - -In this example, inline schemas are moved to the components section of the OpenAPI document. The `update` adds an identifier to each schema as it's moved. #### Traits Example