diff --git a/versions/1.0.0.md b/versions/1.0.0.md
index e345968..86a8ace 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 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.
@@ -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
@@ -196,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 `add` property.
```yaml
overlay: 1.0.0
@@ -210,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:
@@ -247,7 +262,7 @@ info:
version: 1.0.0
actions:
- target: $.paths.*.get[?@.x-oai-traits.paged]
- update:
+ add:
parameters:
- name: top
in: query