Merge pull request #215 from baywet/fix/ref-rfc-9535

fix/ref rfc 9535

Author: baywet

README.md

@@ -30,6 +30,24 @@ If you are looking for tools to use with Overlays, try these:
 
 (Is something missing from the list? Send us a pull request to add it!)
 
+## Support for RFC9535 JSONPath
+
+[[RFC9535]] is a recent specification and libraries implementing JSONPath support might predate the RFC. Those libraries might differ entirely (expressions syntax is incompatible), implement additional capabilities (superset of the RFC), or support only a subset of the RFC.
+
+In case the tool being use is not fully compliant with RFC9535, users MIGHT have to update some JSONPath query expressions to accommodate for the implementation in use.
+
+This example JSONPath query expression:
+
+```jsonpath
+$.paths.*.get.parameters[[email protected]=='filter' && @.in=='query']
+```
+
+might require additional optional parenthesis with some implementations like so:
+
+```jsonpath
+$.paths.*.get.parameters[?(@.name=='filter' && @.in=='query)']
+```
+
 ## Licensing
 
 See: [License (Apache-2.0)](./LICENSE)

versions/1.1.0-dev.md

@@ -21,7 +21,7 @@ The main purpose of the Overlay Specification is to provide a way to repeatably
 
 ### Overlay
 
-An Overlay is a JSON or YAML structure containing an ordered list of [Action Objects](#overlay-actions) that are to be applied to the target document. Each [Action Object](#action-object) has a `target` property and a modifier type (`update` or `remove`). The `target` property is a [[RFC9535|JSONPath]] query expression that identifies the elements of the target document to be updated and the modifier determines the change.
+An Overlay is a JSON or YAML structure containing an ordered list of [Action Objects](#overlay-actions) that are to be applied to the target document. Each [Action Object](#action-object) has a `target` property and a modifier type (`update` or `remove`). The `target` property is a [[RFC9535|RFC9535 JSONPath]] query expression that identifies the elements of the target document to be updated and the modifier determines the change.
 
 ## Specification
 
@@ -113,7 +113,7 @@ This object represents one or more changes to be applied to the target document
 
 | Field Name | Type | Description |
 | ---- | :----: | ---- |
-| <a name="action-target"></a>target | `string` | **REQUIRED** A JSONPath expression selecting nodes in 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 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`. |
 | <a name="action-remove"></a>remove | `boolean` | A boolean value that indicates that the target object or array MUST be removed from the the map or array it is contained in. The default value is `false`. |
@@ -284,6 +284,13 @@ The extensions may or may not be supported by the available tooling, but those m
 Overlay files MAY choose to follow the convention of a `purpose.overlay.yaml` file naming pattern.
 Other file naming conventions are also supported.
 
+### RFC9535 compliance
+
+[[RFC9535]] is a recent specification and libraries implementing JSONPath support might predate the RFC. Those libraries might differ entirely (expressions syntax is incompatible), or implement additional capabilities (superset of the RFC). A tool or library MUST fully implement [[RFC9535]] when parsing and expanding JSONPath query expressions to be compliant with the Overlay specification.
+
+Interoperable Overlay Documents MUST use RFC9535 JSONPath query expressions and MUST NOT use tool-specific JSONPath extensions.
+
+
 ### Comments in OpenAPI descriptions
 
 Some formats, like [YAML](https://yaml.org/) or [JSONC](https://jsonc.org/), support using comments which do not impact the semantic meaning of the description. Applying Overlay Actions to a description MAY result in the loss of such comments in the updated description. The exact behavior is specific to the tool implementing the Overlay Specification.