diff --git a/README.md b/README.md index 788db9d..d936954 100644 --- a/README.md +++ b/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[?@.name=='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) diff --git a/versions/1.1.0-dev.md b/versions/1.1.0-dev.md index a9c404a..8d74cc6 100644 --- a/versions/1.1.0-dev.md +++ b/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 | | ---- | :----: | ---- | -| target | `string` | **REQUIRED** A JSONPath expression selecting nodes in the target document. | +| target | `string` | **REQUIRED** A RFC9535 JSONPath query expression selecting nodes in the target document. | | description | `string` | A description of the action. [[CommonMark]] syntax MAY be used for rich text representation. | | 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`. | | 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.