From a4fa9c6ab978c1d7d43e53d02f364d47e4a676de Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Sat, 30 Mar 2024 16:27:20 +0000 Subject: [PATCH 1/4] Update overlays spec to use add/replace action names --- versions/1.0.0.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/versions/1.0.0.md b/versions/1.0.0.md index e345968..18ae539 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -32,7 +32,7 @@ TBD ## Definitions ##### Overlay Document -An overlay document contains an ordered list of [Action Objects](#overlayActions) that are to be applied to the target document. Each [Action Object](#actionObject) has a `target` property and a modifier type (`update` or `remove`). The `target` property is a [JSONPath](https://datatracker.ietf.org/wg/jsonpath/documents/) query expression that identifies the elements of the target document to be updated and the modifier determines the change. +An overlay document contains an ordered list of [Action Objects](#overlayActions) that are to be applied to the target document. Each [Action Object](#actionObject) has a `target` property and a modifier type (`add`, `replace`, or `remove`). The `target` property is a [JSONPath](https://datatracker.ietf.org/wg/jsonpath/documents/) query expression that identifies the elements of the target document to be updated and the modifier determines the change. ## Specification @@ -80,7 +80,7 @@ Field Name | Type | Description overlay | `string` | **REQUIRED**. This string MUST be the [version number](#versions) of the Overlay Specification that the Overlay document uses. The `overlay` field SHOULD be used by tooling to interpret the Overlay document. info | [Info Object](#infoObject) | **REQUIRED**. Provides metadata about the Overlay. The metadata MAY be used by tooling as required. extends | `string` | URL to the target document (such as an OpenAPI document) this overlay applies to. This MUST be in the form of a URL. -actions | [[Action Object](#actionObject)] | **REQUIRED** An ordered list of actions to be applied to the target document. The array MUST contain at least one value. + actions | [[Action Object](#actionObject)] | **REQUIRED** An ordered list of actions to be applied to the target document. The array MUST contain at least one value. This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -111,10 +111,11 @@ This object represents one or more changes to be applied to the target document Field Name | Type | Description ---|:---:|--- -target | `string` | **REQUIRED** A JSONPath query expression referencing the target objects in the target document. -description | `string` | A description of the action. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. -update | Any | An object with the properties and values to be merged with the object(s) referenced by the `target`. This property has no impact if `remove` property is `true`. -remove | `boolean` | A boolean value that indicates that the target object is to be removed from the the map or array it is contained in. The default value is `false`. +target | `string` | **REQUIRED** A JSONPath query expression referencing the target objects in the target document. +description | `string` | A description of the action. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. +add | Any | An object with the properties and values to be merged with the object(s) referenced by the `target`. If an object property exists, it is overwritten with the new value. Array elements are appended to any existing entries already in the array. This property MUST NOT be used with the `replace` property in the same action object. This property has no impact if `remove` property is `true`. +replace | Any | An object with the properties and values to be merged with the object(s) referenced by the `target`. The entire contents of the target object or array is replaced by the new value(s) supplied. This property MUST NOT be used with the `add` property in the same action object. This property has no impact if `remove` property is `true`. +remove | `boolean` | A boolean value that indicates that the target object is to be removed from the the map or array it is contained in. The default value is `false`. The result of the `target` JSONPath query expression must be zero or more objects or arrays (not primitive types or `null` values). If you wish to update a primitive value such as a string, the `target` expression should select the *containing* object in the target document. @@ -135,7 +136,7 @@ info: version: 1.0.0 actions: - target: "$" # Root of document - update: + add: info: x-overlay-applied: structured-overlay paths: @@ -163,13 +164,13 @@ info: version: 1.0.0 actions: - target: $.paths['/foo'].get - update: + add: description: This is the new description - target: $.paths['/bar'].get - update: + add: description: This is the updated description - target: $.paths['/bar'] - update: + add: post: description: This is an updated description of a child object x-safe: false @@ -247,7 +248,7 @@ info: version: 1.0.0 actions: - target: $.paths.*.get[?@.x-oai-traits.paged] - update: + add: parameters: - name: top in: query From 4d96e9553c74d351e6a817aa39d4bb34d9ddce81 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Sat, 30 Mar 2024 16:39:40 +0000 Subject: [PATCH 2/4] Add an example of replacing an array --- versions/1.0.0.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/versions/1.0.0.md b/versions/1.0.0.md index 18ae539..4027455 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -197,7 +197,7 @@ actions: #### Array Modification Examples -Array elements MAY be deleted using the `remove` property. Use of array indexes to remove array items should be avoided where possible as indexes will change when items are removed. +Array elements MAY be appended to existing, empty or non-existent array fields using the `update` property. ```yaml overlay: 1.0.0 @@ -211,6 +211,20 @@ actions: in: query ``` +Arrays MAY be set to a set list of entries using the `replace` property. In this operation, the array will contain only the specified element(s), regardless of what the previous value of the target was. + +```yaml +overlay: 1.0.0 +info: + title: Replace a whole array + version: 1.0.0 + - target: '$.servers' + replace: + - description: Test server + url: https://testing.example.com/ + +Array elements MAY be deleted using the `remove` property. Use of array indexes to remove array items should be avoided where possible as indexes will change when items are removed. + ```yaml overlay: 1.0.0 info: From af6605e82ba10f21d5701576ccf723a110aa512f Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Mon, 6 May 2024 18:34:35 +0100 Subject: [PATCH 3/4] Update versions/1.0.0.md Thanks! Co-authored-by: Darrel --- versions/1.0.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/1.0.0.md b/versions/1.0.0.md index 4027455..d59b3da 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -197,7 +197,7 @@ actions: #### Array Modification Examples -Array elements MAY be appended to existing, empty or non-existent array fields using the `update` property. +Array elements MAY be appended to existing, empty or non-existent array fields using the `add` property. ```yaml overlay: 1.0.0 From f4a0658cdb46039ad055c5847083c3b0ca6fec97 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Mon, 6 May 2024 18:36:42 +0100 Subject: [PATCH 4/4] Fix the description of replace --- versions/1.0.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/1.0.0.md b/versions/1.0.0.md index d59b3da..86a8ace 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -114,7 +114,7 @@ Field Name | Type | Description target | `string` | **REQUIRED** A JSONPath query expression referencing the target objects in the target document. description | `string` | A description of the action. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. add | Any | An object with the properties and values to be merged with the object(s) referenced by the `target`. If an object property exists, it is overwritten with the new value. Array elements are appended to any existing entries already in the array. This property MUST NOT be used with the `replace` property in the same action object. This property has no impact if `remove` property is `true`. -replace | Any | An object with the properties and values to be merged with the object(s) referenced by the `target`. The entire contents of the target object or array is replaced by the new value(s) supplied. This property MUST NOT be used with the `add` property in the same action object. This property has no impact if `remove` property is `true`. +replace | Any | An object with the properties and values to be written at the location referenced by the `target`. The entire contents of the target object or array is replaced by the new value(s) supplied. This property MUST NOT be used with the `add` property in the same action object. This property has no impact if `remove` property is `true`. remove | `boolean` | A boolean value that indicates that the target object is to be removed from the the map or array it is contained in. The default value is `false`. The result of the `target` JSONPath query expression must be zero or more objects or arrays (not primitive types or `null` values). If you wish to update a primitive value such as a string, the `target` expression should select the *containing* object in the target document.