Merge remote-tracking branch 'upstream/main' into Align-example-secti…

…on-titles

README.md

@@ -1,23 +1,19 @@
-# Overlay-Specification
+# Overlay Specification
 
-The Overlay Specification is a community-driven open specification within the [OpenAPI Initiative](https://www.openapis.org/), a Linux Foundation Collaborative Project.
+The Overlay Specification defines a document format for information that will augment an existing OpenAPI description without entangling that information in the OpenAPI description's source doccument(s).
 
-The Overlay specification defines a way of creating documents that contain information to be merged with an OpenAPI description at some later point in time, for the purpose of updating the OpenAPI description with additional information.
+This specification is a community-driven, open specification within the [OpenAPI Initiative](https://www.openapis.org/), a Linux Foundation Collaborative Project.
 
-Overlays can address a wide range of scenarios that have been frequently requested by OpenAPI users:
+Overlays support a range of scenarios, including:
 
-- Support multi-language API descriptions by using Overlays to contain language translations.
-- Provide configuration information for different deployment environments.
-- Allow separation of concerns for metadata such as gateway configuration or SLA information.
-- Support a traits like capability for applying a set of configuration data, such as multiple parameters, or multiple headers to a targeted object.
-- Provide default responses, or parameters where they are not explicitly provided.
-- Apply configuration data globally or based on filter conditions.
+- Translating documentation into another language
+- Providing configuration information for different deployment environments
+- Allowing separation of concerns for metadata such as gateway configuration or SLA information
+- Supporting a traits-like capability for applying a set of configuration data, such as multiple parameters or multiple headers, for targeted objects
+- Providing default responses or parameters where they were not explicitly provided
+- Appling configuration data globally or based on filter conditions
 
-## Current Status
-
-The current specification is sufficiently stable for implementers to start experimenting.  We are looking for implementation experience to guide our decisions on the remaining open issues.
-
-## Tools that support Overlays
+## Tools that Support Overlays
 
 If you are looking for tools to use with Overlays, try these:
 

versions/1.0.0.md

@@ -2,7 +2,7 @@
 
 ## Abstract
 
-The Overlay specification defines a way of creating documents that contain information to be merged with an [[OpenAPI]] Description at some later point in time, for the purpose of updating the OpenAPI description with additional information.
+The Overlay Specification defines a document format for information that will augment an existing [[OpenAPI]] description without entangling that information in the OpenAPI description's source doccument(s).
 
 ## Version 1.0.0
 
@@ -12,12 +12,10 @@ 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 a 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.
-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.
-An Overlay may be specific to a single OpenAPI description, or be designed to apply the same transform to any OpenAPI description.
+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. An Overlay may be specific to a single OpenAPI description or be designed to apply the same transform to any OpenAPI description.
 
 ## Definitions
 
@@ -29,10 +27,9 @@ An Overlay is a JSON or YAML structure containing an ordered list of [Action Obj
 
 ### 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 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.
+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 tool providers.
-Check with your tool provider for the details of what is supported in each tool.
+**Note:** Version 1.0.0 of the Overlay Specification was released after spending some time in draft and a few early-adopting tool providers. Check with your tool provider for the details of what is supported in each tool.
 
 ### Format
 
@@ -232,7 +229,7 @@ actions:
 
 #### Traits Example
 
-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.
+By annotating a target document (such as an [[OpenAPI]] document) using [Specification Extensions](#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