From 24c7b830620036b950a6ca1f8b798748fec44433 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Tue, 4 Nov 2025 18:57:56 +0100 Subject: [PATCH 1/5] Cover primitive values in update and remove This applies the rules for merging property values to non-object update values. --- versions/1.1.0-dev.md | 26 ++++++++++++++++---------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/versions/1.1.0-dev.md b/versions/1.1.0-dev.md index a4cc888..1fe1075 100644 --- a/versions/1.1.0-dev.md +++ b/versions/1.1.0-dev.md @@ -115,17 +115,13 @@ This object represents one or more changes to be applied to the target document | ---- | :----: | ---- | | target | `string` | **REQUIRED** A RFC9535 JSONPath query 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` or if the `copy` field contains a value. | +| 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 object. If the `target` selects an array node, the value of this field MUST be an array to concatenate with the selected array, or an object or primitive value to append to the selected array. If the `target` selects a primitive node, the value of this field MUST be a primitive value to replace the selected node. This field has no impact if the `remove` field of this action object is `true` or if the `copy` field contains a value. | | copy | `string` | A JSONPath expression selecting a single node to copy into the `target` nodes. 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` or if the `update` field contains a value. | -| 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`. | +| remove | `boolean` | A boolean value that indicates that the target nodes MUST be removed from the the map or array it is contained in. The default value is `false`. | -The result of the `target` JSONPath expression MUST be zero or more objects or arrays (not primitive types or `null` values). Should the `target` JSONPath result in selecting two or more nodes, they MUST be either all objects or all arrays. +If the `target` JSONPath expression selects two or more nodes, they MUST be either all objects or all arrays or all primitives. -To update a primitive property value such as a string, the `target` expression should select the _containing_ object in the target document and `update` should contain an object with the property and its new primitive value. - -Primitive-valued items of an array cannot be replaced or removed individually, only the complete array can be replaced with a `remove` action followed by an `update` or `copy` action. - -The properties of the `update` or `copy` object MUST be compatible with the target object referenced by the JSONPath key. When the Overlay document is applied, the `update` object is merged with the target object by recursively applying these steps: +The properties of the `update` or `copy` object MUST be compatible with the target object referenced by the JSONPath key. When the Overlay document is applied, the `update` or `copy` object is merged with the target object by recursively applying these steps: - A property that only exists in the target object is left unchanged. - A property that only exists in the `update` or `copy` object is inserted into the target object. @@ -135,8 +131,6 @@ The properties of the `update` or `copy` object MUST be compatible with the targ - An object value of the `update` or `copy` property is recursively merged with an object value of the target property. - Other property value combinations are incompatible and result in an error. -The properties of the resolved `copy` object MUST be compatible with the target object referenced by the JSONPath key. When the Overlay document is applied, the properties in the resolved `copy` object are recursively merged with the properties in the target object with the same names; new properties are added to the target object. - This object MAY be extended with [Specification Extensions](#specification-extensions). ### Examples @@ -239,6 +233,18 @@ actions: remove: true ``` +This also works for primitive target nodes: + +```yaml +overlay: 1.1.0 +info: + title: Remove a primitive array element + version: 1.0.0 +actions: + - target: $.paths.*.get.tags[?@ == 'dummy'] + remove: true +``` + #### 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. From 8c8ea281b8ca5a1c6a5ef1bae642737e95157ee4 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Tue, 4 Nov 2025 23:15:00 +0100 Subject: [PATCH 2/5] @baywet's recommendation --- versions/1.1.0-dev.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/1.1.0-dev.md b/versions/1.1.0-dev.md index 1fe1075..e36d087 100644 --- a/versions/1.1.0-dev.md +++ b/versions/1.1.0-dev.md @@ -116,7 +116,7 @@ This object represents one or more changes to be applied to the target document | target | `string` | **REQUIRED** A RFC9535 JSONPath query 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 object. If the `target` selects an array node, the value of this field MUST be an array to concatenate with the selected array, or an object or primitive value to append to the selected array. If the `target` selects a primitive node, the value of this field MUST be a primitive value to replace the selected node. This field has no impact if the `remove` field of this action object is `true` or if the `copy` field contains a value. | -| copy | `string` | A JSONPath expression selecting a single node to copy into the `target` nodes. 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` or if the `update` field contains a value. | +| copy | `string` | A JSONPath expression selecting a single node to copy into the `target` nodes. 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 object. If the `target` selects an array node, the value of this field MUST be an array to concatenate with the selected array, or an object or primitive value to append to the selected array. If the `target` selects a primitive node, the value of this field MUST be a primitive value to replace the selected node. This field has no impact if the `remove` field of this action object is `true` or if the `update` field contains a value. | | remove | `boolean` | A boolean value that indicates that the target nodes MUST be removed from the the map or array it is contained in. The default value is `false`. | If the `target` JSONPath expression selects two or more nodes, they MUST be either all objects or all arrays or all primitives. From ea4726c490c918630f2bfc4393a6a584a928d1f3 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Wed, 5 Nov 2025 09:39:00 +0100 Subject: [PATCH 3/5] multiple target nodes --- versions/1.1.0-dev.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/versions/1.1.0-dev.md b/versions/1.1.0-dev.md index e36d087..00223ce 100644 --- a/versions/1.1.0-dev.md +++ b/versions/1.1.0-dev.md @@ -107,7 +107,7 @@ This object MAY be extended with [Specification Extensions](#specification-exten #### Action Object -This object represents one or more changes to be applied to the target document at the location defined by the target JSONPath expression. +This object represents one or more changes to be applied to the target document at the locations defined by the target JSONPath expression. ##### Fixed Fields @@ -115,11 +115,12 @@ This object represents one or more changes to be applied to the target document | ---- | :----: | ---- | | target | `string` | **REQUIRED** A RFC9535 JSONPath query 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 object. If the `target` selects an array node, the value of this field MUST be an array to concatenate with the selected array, or an object or primitive value to append to the selected array. If the `target` selects a primitive node, the value of this field MUST be a primitive value to replace the selected node. This field has no impact if the `remove` field of this action object is `true` or if the `copy` field contains a value. | +| update | Any | If the `target` selects object nodes, the value of this field MUST be an object with the properties and values to merge with each selected object. If the `target` selects array nodes, the value of this field MUST be an array to concatenate with each selected array, or an object or primitive value to append to each selected array. If the `target` selects primitive nodes, the value of this field MUST be a primitive value to replace each selected node. This field has no impact if the `remove` field of this action object is `true` or if the `copy` field contains a value. | | copy | `string` | A JSONPath expression selecting a single node to copy into the `target` nodes. 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 object. If the `target` selects an array node, the value of this field MUST be an array to concatenate with the selected array, or an object or primitive value to append to the selected array. If the `target` selects a primitive node, the value of this field MUST be a primitive value to replace the selected node. This field has no impact if the `remove` field of this action object is `true` or if the `update` field contains a value. | -| remove | `boolean` | A boolean value that indicates that the target nodes MUST be removed from the the map or array it is contained in. The default value is `false`. | +| remove | `boolean` | A boolean value that indicates that each of the target nodes MUST be removed from the the map or array it is contained in. The default value is `false`. | -If the `target` JSONPath expression selects two or more nodes, they MUST be either all objects or all arrays or all primitives. +If the `target` JSONPath expression selects zero nodes, the action succeeds without changing the target document. +If the `target` JSONPath expression selects two or more nodes for an `update` or `copy` action, the selected nodes MUST be either all objects or all arrays or all primitives. The properties of the `update` or `copy` object MUST be compatible with the target object referenced by the JSONPath key. When the Overlay document is applied, the `update` or `copy` object is merged with the target object by recursively applying these steps: From 8c4b7bd8fda56d11e72a7827eb4b2d9a07914ad9 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Thu, 6 Nov 2025 16:57:10 +0100 Subject: [PATCH 4/5] Align copy with update --- versions/1.1.0-dev.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/1.1.0-dev.md b/versions/1.1.0-dev.md index 692950d..8ebe00c 100644 --- a/versions/1.1.0-dev.md +++ b/versions/1.1.0-dev.md @@ -116,7 +116,7 @@ This object represents one or more changes to be applied to the target document | target | `string` | **REQUIRED** A RFC9535 JSONPath query 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 object nodes, the value of this field MUST be an object with the properties and values to merge with each selected object. If the `target` selects array nodes, the value of this field MUST be an array to concatenate with each selected array, or an object or primitive value to append to each selected array. If the `target` selects primitive nodes, the value of this field MUST be a primitive value to replace each selected node. This field has no impact if the `remove` field of this action object is `true` or if the `copy` field contains a value. | -| copy | `string` | A JSONPath expression selecting a single node to copy into the `target` nodes. 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 object. If the `target` selects an array node, the value of this field MUST be an array to concatenate with the selected array, or an object or primitive value to append to the selected array. If the `target` selects a primitive node, the value of this field MUST be a primitive value to replace the selected node. This field has no impact if the `remove` field of this action object is `true` or if the `update` field contains a value. | +| copy | `string` | A JSONPath expression selecting a single node to copy into the `target` nodes. If the `target` selects object nodes, the value of this field MUST be an object with the properties and values to merge with each selected object. If the `target` selects array nodes, the value of this field MUST be an array to concatenate with each selected array, or an object or primitive value to append to each selected array. If the `target` selects primitive nodes, the value of this field MUST be a primitive value to replace each selected node. This field has no impact if the `remove` field of this action object is `true` or if the `update` field contains a value. | | remove | `boolean` | A boolean value that indicates that each of the target nodes MUST be removed from the the map or array it is contained in. The default value is `false`. | If the `target` JSONPath expression selects zero nodes, the action succeeds without changing the target document. @@ -287,7 +287,7 @@ info: title: Apply Traits version: 1.0.0 actions: - - target: $.paths.*.get[?(@['x-oai-traits'][?(@ == 'paged')])] + - target: $.paths[?(@.get['x-oai-traits'][?(@ == 'paged')])].get update: parameters: - name: top From f8bb38340a1ce0c500525f999c7b2c2048dd4ef4 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Thu, 6 Nov 2025 17:05:17 +0100 Subject: [PATCH 5/5] Directly update description with 1.1 feature --- versions/1.1.0-dev.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/versions/1.1.0-dev.md b/versions/1.1.0-dev.md index 8ebe00c..7dfb526 100644 --- a/versions/1.1.0-dev.md +++ b/versions/1.1.0-dev.md @@ -169,17 +169,15 @@ actions: Alternatively, where only a small number of updates need to be applied to a large document, each [Action Object](#action-object) MAY be more targeted. ```yaml -overlay: 1.0.0 +overlay: 1.1.0 info: title: Targeted Overlay version: 1.0.0 actions: - - target: $.paths['/foo'].get - update: - description: This is the new description - - target: $.paths['/bar'].get - update: - description: This is the updated description + - 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: