From d5ddeca137d310058cdc3ca614b36399e7c60e6d Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Sun, 1 Sep 2024 15:31:49 +0100 Subject: [PATCH 1/8] Add an intro, a note about versions, and remove the data types section since it is empty --- versions/1.0.0.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/versions/1.0.0.md b/versions/1.0.0.md index e345968..41dfca9 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -8,7 +8,12 @@ This document is licensed under [The Apache License, Version 2.0](https://www.ap ## Introduction -TBD +The Overlay specification is an extension or companion to the OpenAPI specification. +An Overlay describes a set of changes to be applied or "overlaid" onto an existing OpenAPI document. + +The main purpose of Overlays to provide a way to repeatably apply transformations to one or many OpenAPI descriptions. +Use cases include updating descriptions, adding metadata to be consumed by another tool, or removing certain elements from an API description before sharing it with partners. +Overlays may be specific to a single OpenAPI description, or be designed to apply the same transform to any OpenAPI description. ## Table of Contents @@ -27,7 +32,6 @@ TBD - [Examples](#examples) - [Specification Extensions](#specificationExtensions) - [Appendix A: Revision History](#revisionHistory) - ## Definitions @@ -38,7 +42,10 @@ An overlay document contains an ordered list of [Action Objects](#overlayActions ### Versions -TBD +The Overlay Specification is versioned using a `major`.`minor`.`patch` versioning scheme. The `major`.`minor` portion of the version string (for example 1.0) SHALL designate the Arazzo feature set. `.patch` versions address errors in, or provide clarifications to, this document, not the feature set. The patch version SHOULD NOT be considered by tooling, making no distinction between 1.0.0 and 1.0.1 for example. + +**Note:** Version 1.0.0 of the Overlay Specification is being released after spending some time in draft, and after being adopted by tools providers. +Check with your tool provider for the details of what is supported in each tool. ### Format @@ -56,10 +63,6 @@ In order to preserve the ability to round-trip between YAML and JSON formats, YA It is RECOMMENDED that the root Overlay document be named: overlay.json or overlay.yaml. -### Data Types - -TBD - ### 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). From 9e2dcb6e418096da54ee046e59c50160be0db337 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Sun, 8 Sep 2024 21:08:53 +0100 Subject: [PATCH 2/8] Apply suggestions from code review Co-authored-by: Ralf Handl --- versions/1.0.0.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/versions/1.0.0.md b/versions/1.0.0.md index 41dfca9..bec8805 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -11,7 +11,7 @@ This document is licensed under [The Apache License, Version 2.0](https://www.ap The Overlay specification is an extension or companion to the OpenAPI specification. An Overlay describes a set of changes to be applied or "overlaid" onto an existing OpenAPI document. -The main purpose of Overlays to provide a way to repeatably apply transformations to one or many OpenAPI descriptions. +The main purpose of Overlays is to provide a way to repeatably apply transformations to one or many OpenAPI descriptions. Use cases include updating descriptions, adding metadata to be consumed by another tool, or removing certain elements from an API description before sharing it with partners. Overlays may be specific to a single OpenAPI description, or be designed to apply the same transform to any OpenAPI description. @@ -42,9 +42,9 @@ An overlay document contains an ordered list of [Action Objects](#overlayActions ### Versions -The Overlay Specification is versioned using a `major`.`minor`.`patch` versioning scheme. The `major`.`minor` portion of the version string (for example 1.0) SHALL designate the Arazzo feature set. `.patch` versions address errors in, or provide clarifications to, this document, not the feature set. The patch version SHOULD NOT be considered by tooling, making no distinction between 1.0.0 and 1.0.1 for example. +The Overlay Specification is versioned using a `major`.`minor`.`patch` versioning scheme. The `major`.`minor` portion of the version string (for example 1.0) SHALL designate the Overlay feature set. `.patch` versions address errors in, or provide clarifications to, this document, not the feature set. The patch version SHOULD NOT be considered by tooling, making no distinction between 1.0.0 and 1.0.1 for example. -**Note:** Version 1.0.0 of the Overlay Specification is being released after spending some time in draft, and after being adopted by tools providers. +**Note:** Version 1.0.0 of the Overlay Specification is being released after spending some time in draft, and after being adopted by tool providers. Check with your tool provider for the details of what is supported in each tool. ### Format From ffa3377d500b5789c8e26ef896a12bef0c7cd231 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Sun, 8 Sep 2024 21:12:46 +0100 Subject: [PATCH 3/8] Better OpenAPI wording in the intro --- versions/1.0.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/1.0.0.md b/versions/1.0.0.md index bec8805..b99ad29 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -9,7 +9,7 @@ This document is licensed under [The Apache License, Version 2.0](https://www.ap ## Introduction The Overlay specification is an extension or companion to the OpenAPI specification. -An Overlay describes a set of changes to be applied or "overlaid" onto an existing OpenAPI document. +An Overlay describes a set of changes to be applied or "overlaid" onto an existing OpenAPI description. The main purpose of Overlays is to provide a way to repeatably apply transformations to one or many OpenAPI descriptions. Use cases include updating descriptions, adding metadata to be consumed by another tool, or removing certain elements from an API description before sharing it with partners. From 1aeaa200b70cbb1b21cdbbeff9e0bd5411d50284 Mon Sep 17 00:00:00 2001 From: Lorna Mitchell Date: Tue, 10 Sep 2024 16:45:15 +0100 Subject: [PATCH 4/8] Improve Overlay definition and intro, with supervision --- versions/1.0.0.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/versions/1.0.0.md b/versions/1.0.0.md index b99ad29..d3b1882 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -11,9 +11,9 @@ This document is licensed under [The Apache License, Version 2.0](https://www.ap The Overlay specification is an extension or companion to the OpenAPI specification. An Overlay describes a set of changes to be applied or "overlaid" onto an existing OpenAPI description. -The main purpose of Overlays is to provide a way to repeatably apply transformations to one or many OpenAPI descriptions. +The main purpose of the Overlay Specification is to provide a way to repeatably apply transformations to one or many OpenAPI descriptions. Use cases include updating descriptions, adding metadata to be consumed by another tool, or removing certain elements from an API description before sharing it with partners. -Overlays may be specific to a single OpenAPI description, or be designed to apply the same transform to any OpenAPI description. +An Overlay may be specific to a single OpenAPI description, or be designed to apply the same transform to any OpenAPI description. ## Table of Contents @@ -35,8 +35,9 @@ Overlays may be specific to a single OpenAPI description, or be designed to appl ## Definitions -##### Overlay Document -An overlay document contains an ordered list of [Action Objects](#overlayActions) that are to be applied to the target document. Each [Action Object](#actionObject) has a `target` property and a modifier type (`update` or `remove`). The `target` property is a [JSONPath](https://datatracker.ietf.org/wg/jsonpath/documents/) query expression that identifies the elements of the target document to be updated and the modifier determines the change. +##### Overlay + +An Overlay is a JSON or YAML structure containing an ordered list of [Action Objects](#overlayActions) that are to be applied to the target document. Each [Action Object](#actionObject) has a `target` property and a modifier type (`update` or `remove`). The `target` property is a [JSONPath](https://datatracker.ietf.org/wg/jsonpath/documents/) query expression that identifies the elements of the target document to be updated and the modifier determines the change. ## Specification From fc517a06f6cbbc769ad9dc655aebedce8d2045f2 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Tue, 10 Sep 2024 16:45:40 +0100 Subject: [PATCH 5/8] Update versions/1.0.0.md Co-authored-by: Ralf Handl --- versions/1.0.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/1.0.0.md b/versions/1.0.0.md index d3b1882..274dd3e 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -8,7 +8,7 @@ This document is licensed under [The Apache License, Version 2.0](https://www.ap ## Introduction -The Overlay specification is an extension or companion to the OpenAPI specification. +The Overlay Specification is an extension or companion to the [[OpenAPI]] specification. An Overlay describes a set of changes to be applied or "overlaid" onto an existing OpenAPI description. The main purpose of the Overlay Specification is to provide a way to repeatably apply transformations to one or many OpenAPI descriptions. From 665a0fbd68ef7dad2fba86aa7006c797869fb86f Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Tue, 10 Sep 2024 18:08:31 +0200 Subject: [PATCH 6/8] Update 1.0.0.md --- versions/1.0.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/1.0.0.md b/versions/1.0.0.md index df88224..aecf5da 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -19,7 +19,7 @@ An Overlay may be specific to a single OpenAPI description, or be designed to ap ### Overlay -An Overlay is a JSON or YAML structure containing an ordered list of [Action Objects](#overlayActions) that are to be applied to the target document. Each [Action Object](#actionObject) has a `target` property and a modifier type (`update` or `remove`). The `target` property is a [JSONPath](https://datatracker.ietf.org/wg/jsonpath/documents/) 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](#overlayActions) that are to be applied to the target document. Each [Action Object](#actionObject) has a `target` property and a modifier type (`update` or `remove`). The `target` property is a [JSONPath](https://datatracker.ietf.org/wg/jsonpath/documents/) query expression that identifies the elements of the target document to be updated and the modifier determines the change. ## Specification From 09700c3aab993aa01ff2b2d1415c279df01c110f Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Tue, 10 Sep 2024 18:10:15 +0200 Subject: [PATCH 7/8] Fix links --- versions/1.0.0.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/1.0.0.md b/versions/1.0.0.md index aecf5da..7cf3b58 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -19,7 +19,7 @@ An Overlay may be specific to a single OpenAPI description, or be designed to ap ### Overlay -An Overlay is a JSON or YAML structure containing an ordered list of [Action Objects](#overlayActions) that are to be applied to the target document. Each [Action Object](#actionObject) has a `target` property and a modifier type (`update` or `remove`). The `target` property is a [JSONPath](https://datatracker.ietf.org/wg/jsonpath/documents/) 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 [JSONPath](https://datatracker.ietf.org/wg/jsonpath/documents/) query expression that identifies the elements of the target document to be updated and the modifier determines the change. ## Specification @@ -57,7 +57,7 @@ In the following description, if a field is not explicitly **REQUIRED** or descr #### Overlay Object -This is the root object of the [Overlay document](#overlay-document). +This is the root object of the [Overlay](#overlay). ##### Fixed Fields From dec193f03a7c47cc3227cda4db6a6c69d08d5f0b Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Tue, 10 Sep 2024 18:15:42 +0200 Subject: [PATCH 8/8] respec-style reference --- versions/1.0.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/1.0.0.md b/versions/1.0.0.md index 7cf3b58..3f9aafd 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -19,7 +19,7 @@ An Overlay may be specific to a single OpenAPI description, or be designed to ap ### 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 [JSONPath](https://datatracker.ietf.org/wg/jsonpath/documents/) 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|JSONPath]] query expression that identifies the elements of the target document to be updated and the modifier determines the change. ## Specification