From 180fd7c582847ef7c5003c565f88cb13a42addee Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Tue, 16 Dec 2025 13:17:17 -0500 Subject: [PATCH 1/3] docs: adds an upgrade guide for overlay 1.1 --- upgrading/index.md | 1 + upgrading/overlay-v1.0-to-v1.1.md | 88 +++++++++++++++++++++++++++++++ 2 files changed, 89 insertions(+) create mode 100644 upgrading/overlay-v1.0-to-v1.1.md diff --git a/upgrading/index.md b/upgrading/index.md index 321b49d..eb89bf4 100644 --- a/upgrading/index.md +++ b/upgrading/index.md @@ -21,5 +21,6 @@ Each version upgrade guide covers: - [Upgrading from OpenAPI 3.0 to 3.1](v3.0-to-v3.1): Learn about the significant changes and how to migrate your API descriptions. - [Upgrading from OpenAPI 3.1 to 3.2](v3.1-to-v3.2): Discover the latest features and migration path for the newest version. +- [Upgrading from Overlay 1.0 to 1.1](overlay-v1.0-to-v1.1): Discover the latest features and migration path for the newest version. Choose the appropriate guide based on your current OpenAPI version and target version. diff --git a/upgrading/overlay-v1.0-to-v1.1.md b/upgrading/overlay-v1.0-to-v1.1.md new file mode 100644 index 0000000..7dd68de --- /dev/null +++ b/upgrading/overlay-v1.0-to-v1.1.md @@ -0,0 +1,88 @@ +--- +layout: default +title: Overlay - Upgrading Between Versions 1.0 and 1.1 +parent: Upgrading Between Versions +nav_order: 1 +--- + +# Overlay - Upgrading Between Versions 1.0 and 1.1 + +Overlay 1.1 introduces significant new functionality and improvements. This guide covers the changes required to migrate your Overlay 1.0 descriptions to version 1.1. + +## Getting started + +Begin by updating the version number in your Overlay document. Locate this line in your JSON or YAML file: + +```yaml +overlay: 1.0.0 +``` + +Update it to: + +```yaml +overlay: 1.1.0 +``` + +## Copy elements from the OpenAPI document + +The following example illustrates how you can now use the copy action to update a target node with a value from the document being processed. Saving you from having duplicate definitions in your overlay document. + +```yaml +overlay: 1.0.0 +info: + title: Copy a schema component + version: 1.1.0 +actions: + - target: '$.components.schemas' + description: Ensure the target schema is present + update: + Bar: {} + - target: '$.components.schemas['Bar']' + copy: '$.components.schemas['Foo']' + description: Copy the Foo Schema to Bar +``` + +## Name the file according to the convention for better tooling integration + +You might want to rename your overlay documents to end with `.overlay.yaml|json` to get better integration with tooling. + +## Ensure your JSONPath are RFC 9535 for better interoperability + +This example JSONPath query expression: + +```jsonpath +$.paths.*.get.parameters[?(@.name=='filter' && @.in=='query)'] +``` + +Should in fact be: + +```jsonpath +$.paths.*.get.parameters[?@.name=='filter' && @.in=='query'] +``` + +## Removing/Updating primitive values is now fully supported + +```yaml +overlay: 1.1.0 +info: + title: Targeted Overlay + version: 1.0.0 +actions: + - target: $.paths['/foo'].get.description + update: This is the new description + - target: $.paths['/bar'].get.description + update: This is the updated description +``` + +Before it used to require updating the parent object. + +## Add a description to your overlay document + +```yaml +overlay: 1.1.0 +info: + title: Overlay with description + version: 1.0.0 + description: This overlay document has a long description thanks to the new field. +actions: [] +``` From 84281e2fc00be7e0291d6df63c24cf0737e34558 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Tue, 16 Dec 2025 14:23:11 -0500 Subject: [PATCH 2/3] docs: better example for RFC9535 compliance Signed-off-by: Vincent Biret --- upgrading/overlay-v1.0-to-v1.1.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/upgrading/overlay-v1.0-to-v1.1.md b/upgrading/overlay-v1.0-to-v1.1.md index 7dd68de..f8974dc 100644 --- a/upgrading/overlay-v1.0-to-v1.1.md +++ b/upgrading/overlay-v1.0-to-v1.1.md @@ -51,13 +51,13 @@ You might want to rename your overlay documents to end with `.overlay.yaml|json` This example JSONPath query expression: ```jsonpath -$.paths.*.get.parameters[?(@.name=='filter' && @.in=='query)'] +$.paths.*.get[?(@.x-oai-traits[?(@ == 'paged')])] ``` Should in fact be: ```jsonpath -$.paths.*.get.parameters[?@.name=='filter' && @.in=='query'] +$.paths.*.get[?(@['x-oai-traits'][?(@ == 'paged')])] ``` ## Removing/Updating primitive values is now fully supported From 82425b6714a97da827793439e702fa86dbead0f6 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Tue, 16 Dec 2025 14:37:27 -0500 Subject: [PATCH 3/3] docs: expands the non compliant examples. Signed-off-by: Vincent Biret --- upgrading/overlay-v1.0-to-v1.1.md | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/upgrading/overlay-v1.0-to-v1.1.md b/upgrading/overlay-v1.0-to-v1.1.md index f8974dc..1f6d157 100644 --- a/upgrading/overlay-v1.0-to-v1.1.md +++ b/upgrading/overlay-v1.0-to-v1.1.md @@ -48,7 +48,9 @@ You might want to rename your overlay documents to end with `.overlay.yaml|json` ## Ensure your JSONPath are RFC 9535 for better interoperability -This example JSONPath query expression: +### Missing square brackets around property names + +This example JSONPath query expression, which filters path items based on an OpenAPI extension property: ```jsonpath $.paths.*.get[?(@.x-oai-traits[?(@ == 'paged')])] @@ -60,6 +62,24 @@ Should in fact be: $.paths.*.get[?(@['x-oai-traits'][?(@ == 'paged')])] ``` +Because square brackets are required for property selection. + +### Use of the undefined `in` keyword + +This example JSONPath query expression, which selects tags matching *Enterprise-Only*: + +```jsonpath +$.paths..[?('Enterprise-Only' in @.tags)] +``` + +Should instead be: + +```jsonpath +$.paths..[?(@.tags[?(@ == 'Enterprise-Only')])] +``` + +Since the `in` keyword is undefined in the RFC. + ## Removing/Updating primitive values is now fully supported ```yaml