Describe behavior for primitive values in update and remove

versions/1.1.0-dev.md

@@ -115,19 +115,14 @@ This object represents one or more changes to be applied to the target document
 | ---- | :----: | ---- |
 | <a name="action-target"></a>target | `string` | **REQUIRED** A RFC9535 JSONPath query 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 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 entry to append to each selected array. This field has no impact if the `remove` field of this action object is `true` or if the `copy` field contains a value. |
-| <a name="action-copy"></a>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. |
-| <a name="action-remove"></a>remove | `boolean` | A boolean value that indicates that each of the target objects or arrays MUST be removed from the the map or array it is contained in. The default value is `false`. |
+| <a name="action-update"></a>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. |
+| <a name="action-copy"></a>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. |
+| <a name="action-remove"></a>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`. |
 
-The result of the `target` JSONPath expression MUST be zero or more objects or arrays (not primitive types or `null` values).
 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.
+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.
 
-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.
@@ -137,8 +132,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
@@ -176,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:
@@ -241,6 +232,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.