Explicit definition of how to recursively merge objects

versions/1.1.0-dev.md

@@ -122,9 +122,17 @@ The result of the `target` JSONPath expression MUST be zero or more objects or a
 
 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.
+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` object MUST be compatible with the target object referenced by the JSONPath key. When the Overlay document is applied, the properties in the `update` object are recursively merged with the properties in the target object with the same names; new properties are added to the target object.
+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:
+
+- 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.
+- If a property exists in both `update` or `copy` and target object:
+  - A primitive value of the `update` or `copy` property replaces a primitive value of the target property.
+  - An array value of the `update` or `copy` property is concatenated with an array value of the target property.
+  - 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.
 
 This object MAY be extended with [Specification Extensions](#specification-extensions).
 
@@ -244,6 +252,21 @@ paths:
       responses:
         200:
           description: OK
+  /items/{id}/subitems:
+    get:
+      x-oai-traits: ['paged']
+      parameters:
+        - name: id
+          in: path
+          required: true
+      responses:
+        200:
+          description: OK
+  /other:
+    get:
+      responses:
+        200:
+          description: OK
 ```
 
 With the above OpenAPI document, the following Overlay document will apply the necessary updates to describe how paging is implemented, where that trait has been applied.
@@ -254,7 +277,7 @@ info:
   title: Apply Traits
   version: 1.0.0
 actions:
-  - target: $.paths.*.get[[email protected].paged]
+  - target: $.paths.*.get[?(@.x-oai-traits[?(@ == 'paged')])]
     update:
       parameters:
         - name: top
@@ -265,6 +288,50 @@ actions:
           # ...
 ```
 
+resulting in
+
+```yaml
+openapi: 3.1.0
+info:
+  title: API with a paged collection
+  version: 1.0.0
+paths:
+  /items:
+    get:
+      x-oai-traits: ["paged"]
+      responses:
+        200:
+          description: OK
+      parameters:
+        - name: top
+          in: query
+          # ...
+        - name: skip
+          in: query
+          # ...
+  /items/{id}/subitems:
+    get:
+      x-oai-traits: ["paged"]
+      parameters:
+        - name: id
+          in: path
+          required: true
+        - name: top
+          in: query
+          # ...
+        - name: skip
+          in: query
+          # ...
+      responses:
+        200:
+          description: OK
+  /other:
+    get:
+      responses:
+        200:
+          description: OK
+```
+
 This approach allows inversion of control as to where the Overlay updates apply to the target document itself.
 
 ### Specification Extensions