Does `update` use "deep merge" or "shallow merge"?

[ralfhandl]

The Action Object definition currently states that

properties in the merge object replace properties in the target object with the same name

If that is to be the case, then the Structured Overlays Example would replace existing path item objects with sparse and incomplete objects, containing only an incomplete operation object for GET, missing for example the required responses field.

The "Structured Overlays Example" will only work if nested objects within the update object are also merged with their counterpart in the target, recursively. Nested arrays would still have to replace their counterpart in the target, same as primitive values.

[ralfhandl]

Experiments:

• bump-sh
  • uses "deep merge" instead of "replace"
  • appends overlay arrays to target arrays
• speakeasy
  • uses "deep merge" instead of "replace"
  • appends overlay arrays to target arrays

[lornajane]

The wording isn't accurate but the tools seem to do a good and expected thing.

Suggested wording:

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.