Several small amendments to initial overlay spec version

MAINTAINERS.md

@@ -0,0 +1,8 @@
+## Active
+* Darrel Miller [@darrelmiller](https://github.com/darrelmiller)
+* Jeremy Whitlock [@whitlockjc](https://github.com/whitlockjc)
+* Marsh Gardiner [@earth2marsh](https://github.com/earth2marsh)
+* Mike Ralphson [@MikeRalphson](https://github.com/MikeRalphson)
+* Ron Ratovsky [@webron](https://github.com/webron)
+* Uri Sarid [@usarid](https://github.com/usarid)
+

versions/1.0.0.md

@@ -32,7 +32,7 @@ TBD
 ## Definitions
 
 ##### <a name="overlayDocument"></a>Overlay Document
-An overlay document contains an ordered list of [Update Objects](#overlayUpdates) that are to be applied to the target document. Each [Update Object](#updateObject) has a `target` property and a modifier type (add, merge, remove).  The `target` property is a [JMESPath](http://jmespath.org/specification.html) query that identifies what part of the target document is to be updated and the modifier determines the change.
+An overlay document contains an ordered list of [Update Objects](#overlayUpdates) that are to be applied to the target document. Each [Update Object](#updateObject) has a `target` property and a modifier type (`add`, `merge`, or `remove`).  The `target` property is a [JMESPath](https://jmespath.org/specification.html) query that identifies what part of the target document is to be updated and the modifier determines the change.
 
 ## Specification
 
@@ -63,7 +63,7 @@ TBD
 ### <a name="relativeReferencesURL"></a>Relative References in URLs
 
 Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2).
-*** Unless specified otherwise, relative references are resolved using the URLs defined in the [`Server Object`](#serverObject) as a Base URL. Note that these themselves MAY be relative to the referring document.
+Unless specified otherwise, relative references are resolved using the URL of the referring document.
 
 ### Schema
 
@@ -79,14 +79,14 @@ Field Name | Type | Description
 ---|:---:|---
 <a name="overlayVersion"></a>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. 
 <a name="overlayInfo"></a>info | [Info Object](#infoObject) | **REQUIRED**. Provides metadata about the Overlay. The metadata MAY be used by tooling as required.
-<a name="overlayExtends"></a> extends | `string` | URL to an OpenAPI document this overlay applies to. This MUST be in the form of a URL.
-<a name="overlayUpdates"></a>updates | [[Update Object](#UpdateObject)] | **REQUIRED** An ordered list of update objects to be applied to the target document. The array MUST contain at least one value.
+<a name="overlayExtends"></a> 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.
+<a name="overlayUpdates"></a>updates | [[Update Object](#updateObject)] | **REQUIRED** An ordered list of update objects to be applied to the target document. The array MUST contain at least one value.
 
-*** This object MAY be extended with [Specification Extensions](#specificationExtensions).
+*** This object MAY be extended with [Specification Extensions](#specificationExtensions). ***
 
 The list of update objects MUST be applied in sequential order to ensure a consistent outcome. Updates are applied to the result of the previous updates. This enables objects to be deleted in one update and then re-created in a subsequent update, for example.
 
-The `extends` property can be used to indicate that the Overlay was designed to update a specific OpenAPI description. Where no `extends` is provided it is the responsibility of tooling to apply the Overlay documents to the appropriate OpenAPI description.
+The `extends` property can be used to indicate that the Overlay was designed to update a specific OpenAPI document. Where no `extends` is provided it is the responsibility of tooling to apply the Overlay documents to the appropriate OpenAPI document(s).
 
 #### <a name="infoObject"></a>Info Object
 
@@ -101,11 +101,11 @@ Field Name | Type | Description
 <a name="infoVersion"></a>version | `string` | **REQUIRED**. A version identifer for indicating changes to the Overlay document.
 
 
-*** This object MAY be extended with [Specification Extensions](#specificationExtensions).
+*** This object MAY be extended with [Specification Extensions](#specificationExtensions). ***
 
 #### <a name="updateObject"></a>Update Object
 
-This object represents one or more changes to be applied to the target document at the location defined by the target JMESPath.
+This object represents one or more changes to be applied to the target document at the location defined by the target JMESPath expression.
 
 ##### Fixed Fields
 
@@ -116,9 +116,11 @@ Field Name | Type | Description
 <a name="updateMerge"></a>merge | Any | An object with the properties and values to be merged with the object(s) referenced by the `target`. Property has no impact if `remove` property is `true`.
 <a name="updateRemove"></a>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` JMESPath 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.
+
 The properties of the merge object MUST be compatible with the target object referenced by the JMESPath key. When the Overlay document is applied, the properties in the merge object replace properties in the target object with the same name and new properties are appended to the target object.
 
-*** This object MAY be extended with [Specification Extensions](#specificationExtensions).
+*** This object MAY be extended with [Specification Extensions](#specificationExtensions). ***
 
 ### Examples
 
@@ -152,7 +154,7 @@ updates:
 
 #### Targeted Overlays
 
-Alternatively, where only a small number of updates need to be applied to a large document, each [Update Object](#updateObject) can be more targeted.
+Alternatively, where only a small number of updates need to be applied to a large document, each [Update Object](#updateObject) MAY be more targeted.
 
 ```yaml
 overlay: 1.0.0
@@ -168,14 +170,14 @@ updates:
     description: This is the updated description
 - target: paths."/bar"
   merge:
-      post:
-          description: This is an updated description of a child object
-          x-safe: false
+    post:
+      description: This is an updated description of a child object
+      x-safe: false
 ```
 
 #### Wildcard Overlays Examples
 
-One significant advantage of using the JMESPath syntax that it allows referencing multiple nodes in the target document.  This would allow a single update object to be applied to multiple target objects using wildcards.
+One significant advantage of using the JMESPath syntax is that it allows referencing multiple nodes in the target document.  This would allow a single update object to be applied to multiple target objects using wildcards.
 
 ```yaml
 overlay: 1.0.0
@@ -194,7 +196,7 @@ updates:
 
 #### Array Modification Examples
 
-Due to the fact that we can now reference specific elements of the parameter array, it allows adding parameters. Parameters can be deleted using the `remove` property.  Use of indexes to remove array items should be avoided where possible as indexes will change when items are removed.
+Array elements MAY be added using the 'add' modifier type. 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.  Update modifier type 'merge' MUST NOT be used with arrays.
 
 ```yaml
 overlay: 1.0.0
@@ -220,12 +222,12 @@ updates:
 
 #### Traits Examples
 
-By annotating an OpenAPI description using extension such as `x-oai-traits` an author of OpenAPI description can identify where overlay updates should be applied.
+By annotating a target document (such as an OpenAPI document) using specification extensions such as `x-oai-traits`, the author of the target document MAY identify where overlay updates should be applied.
 
 ```yaml
 openapi: 3.1.0
 info:
-  title: Api with a paged collection
+  title: API with a paged collection
   version: 1.0.0
 paths:
   /items:
@@ -236,7 +238,7 @@ paths:
           description: OK
 ```
 
-With the above OpenAPI description, following Overlay document will apply the necessary updates to describe how paging is implemented, where that trait has been applied.
+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.
 
 ```yaml
 overlay: 1.0.0
@@ -249,25 +251,29 @@ updates:
     parameters:
       - name: top
         in: query
+        # ...
       - name: skip
         in: query
+        # ...
 ```
 
-This approach allows flipping control of where Overlays apply updates to the OpenAPI description itself.
+This approach allows inversion of control as to where the Overlay updates apply to the target document itself.
 
 ### <a name="specificationExtensions"></a>Specification Extensions
 
-While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
+While the Overlay Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
 
-The extensions properties are implemented as patterned fields that are always prefixed by `"x-"`.
+The extension properties are implemented as patterned fields that are always prefixed by `"x-"`.
 
 Field Pattern | Type | Description
 ---|:---:|---
-<a name="infoExtensions"></a>^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. Field names beginning `x-oai-` and `x-oas-` are reserved for uses defined by the [OpenAPI Initiative](https://www.openapis.org/). The value can be `null`, a primitive, an array or an object.
+<a name="overlayExtensions"></a>^x- | Any | Allows extensions to the Overlay Specification. The field name MUST begin with `x-`, for example, `x-internal-id`. Field names beginning `x-oai-` and `x-oas-` are reserved for uses defined by the [OpenAPI Initiative](https://www.openapis.org/). The value MAY be `null`, a primitive, an array or an object.
 
 The extensions may or may not be supported by the available tooling, but those may be extended as well to add requested support (if tools are internal or open-sourced).
 
 
 ## <a name="revisionHistory"></a>Appendix A: Revision History
 
-1.0       | TBD | First release of the Overlay Specification
+Version   | Date       | Notes
+---       | ---        | ---
+1.0.0     | TBD        | First release of the Overlay Specification