Merge branch 'main' into patch-1

Author: ralfhandl

.github/workflows/respec.yaml

@@ -35,7 +35,7 @@ jobs:
     - uses: actions/checkout@v4 # checkout gh-pages branch
       with:
         token: ${{ secrets.OAS_REPO_TOKEN }}
-        repository: ralfhandl/OpenAPI-Specification  # TODO: change to OAI/...
+        repository: OAI/OpenAPI-Specification  # TODO: change to OAI/...
         ref: gh-pages
         path: deploy
 
@@ -45,13 +45,15 @@ jobs:
     - name: Create Pull Request
       uses: peter-evans/create-pull-request@v7
       with:
+        # A personal access token is required to push changes to the repository.
+        # This token needs to be refreshed regularly and stored in the repository secrets.
         token: ${{ secrets.OAS_REPO_TOKEN }}
         branch: update-overlay-respec-version
         base: gh-pages
         delete-branch: true
         path: deploy
         labels: Housekeeping
-        # team-reviewers: OAI/tsc
+        team-reviewers: OAI/tsc
         title: Update ReSpec-rendered specification versions for Overlay
         commit-message: Update ReSpec-rendered specification versions
         signoff: true

README.md

@@ -1,21 +1,28 @@
-# Overlay-Specification
+# Overlay Specification
 
-The [Overlay Specification](https://spec.openapis.org/overlay/latest.html) is a community-driven open specification within the [OpenAPI Initiative](https://www.openapis.org/), a Linux Foundation Collaborative Project.
+The [Overlay Specification](https://spec.openapis.org/overlay/latest.html) defines a document format for information that augments an existing OpenAPI description yet remains separate from the OpenAPI description's source document(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
+- Applying configuration data globally or based on filter conditions
 
-## Current Status
+## Tools that Support Overlays
 
-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.
+If you are looking for tools to use with Overlays, try these:
+
+- [Bump.sh CLI](https://github.com/bump-sh/cli)
+- [Speakeasy CLI](https://www.speakeasy.com/docs/speakeasy-cli/getting-started)
+- [overlays-js](https://github.com/lornajane/openapi-overlays-js)
+- [apigee-go-gen CLI](https://apigee.github.io/apigee-go-gen/transform/commands/oas-overlay/)
+
+(Is something missing from the list? Send us a pull request to add it!)
 
 ## Licensing
 

scripts/md2html/md2html.js

@@ -117,7 +117,7 @@ function preface(title,options) {
     preface += `<h1 id="title">${title.split('|')[0]}</h1>`;
     preface += `<p class="copyright">Copyright © ${options.publishDate.getFullYear()} the Linux Foundation</p>`;
     preface += `<section class="notoc" id="abstract"><h2>${abstract}</h2>\n`;
-    preface += options.intro.join('\n');
+    preface += options.abstract.join('\n');
     preface += '</section>';
     preface += '<section class="override" id="sotd" data-max-toc="0">';
     preface += '<h2>Status of This Document</h2>';
@@ -180,17 +180,23 @@ let inTOC = false;
 let inDefs = false;
 let inCodeBlock = false;
 let indents = [0];
-let inIntro = false;
-argv.intro = [];
+let inAbstract = false;
+argv.abstract = [];
 
 // process the markdown
 for (let l in lines) {
     let line = lines[l];
 
-    // extract Introduction section for abstract
-    if (line.startsWith('## Introduction')) inIntro = true;
-    else if (line.startsWith('#')) inIntro = false; 
-    else if (inIntro) argv.intro.push(line);
+    // extract Abstract
+    if (line.startsWith('## Abstract')) { 
+        inAbstract = true;
+        line = '';
+    }
+    else if (line.startsWith('#')) inAbstract = false; 
+    else if (inAbstract) { 
+        argv.abstract.push(line);
+        line = '';
+    }
 
     // remove TOC from older spec versions, respec will generate a new one
     if (line.startsWith('## Table of Contents')) inTOC = true;

versions/1.0.0.md

@@ -1,5 +1,9 @@
 # Overlay Specification
 
+## Abstract
+
+The Overlay Specification defines a document format for information that augments an existing [[OpenAPI]] description yet remains separate from the OpenAPI description's source document(s).
+
 ## Version 1.0.0
 
 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP 14](https://tools.ietf.org/html/bcp14) [RFC2119](https://tools.ietf.org/html/rfc2119) [RFC8174](https://tools.ietf.org/html/rfc8174) when, and only when, they appear in all capitals, as shown here.
@@ -8,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
 
@@ -25,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 being implemented by a few early-adopting tool providers. Check with your tool provider for the details of what is supported in each tool.
 
 ### Format
 
@@ -42,14 +43,9 @@ In order to preserve the ability to round-trip between YAML and JSON formats, [[
 - Tags MUST be limited to those allowed by the [JSON Schema ruleset](https://yaml.org/spec/1.2/spec.html#id2803231).
 - Keys used in YAML maps MUST be limited to a scalar string, as defined by the [YAML Failsafe schema ruleset](https://yaml.org/spec/1.2/spec.html#id2802346).
 
-### Document Structure
-
-It is RECOMMENDED that the root Overlay document be named: `overlay.json` or `overlay.yaml`.
+### Relative References in URIs
 
-### 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).
-Unless specified otherwise, relative references are resolved using the URL of the referring document.
+Unless specified otherwise, all fields that are URI references MAY be relative references as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2).
 
 ### Schema
 
@@ -65,14 +61,35 @@ This is the root object of the [Overlay](#overlay).
 | ---- | :----: | ---- |
 | <a name="overlay-version"></a>overlay | `string` | **REQUIRED**. This string MUST be the [version number](#versions) of the Overlay Specification that the Overlay document uses. The `overlay` field SHOULD be used by tooling to interpret the Overlay document. |
 | <a name="overlay-info"></a>info | [Info Object](#info-object) | **REQUIRED**. Provides metadata about the Overlay. The metadata MAY be used by tooling as required. |
-| <a name="overlay-extends"></a>extends | `string` | URL to the target document (such as an [[OpenAPI]] document) this overlay applies to. This MUST be in the form of a URL. |
+| <a name="overlay-extends"></a>extends | `string` | URI reference that identifies the target document (such as an [[OpenAPI]] document) this overlay applies to. |
 | <a name="overlay-actions"></a>actions | [[Action Object](#action-object)] | **REQUIRED** An ordered list of actions to be applied to the target document. The array MUST contain at least one value. |
 
 This object MAY be extended with [Specification Extensions](#specification-extensions).
 
-The list of actions MUST be applied in sequential order to ensure a consistent outcome. Actions are applied to the result of the previous updates. This enables objects to be deleted in one update and then re-created in a subsequent update, for example.
+The list of actions MUST be applied in sequential order to ensure a consistent outcome. Actions are applied to the result of the previous action. This enables objects to be deleted in one action and then re-created in a subsequent action, for example.
+
+The `extends` property can be used to indicate that the Overlay was designed to update a specific [[OpenAPI]] document. Where no `extends` is provided it is the responsibility of tooling to apply the Overlay document to the appropriate OpenAPI document(s).
+
+In the following example the `extends` property specifies that the overlay is designed to update the OpenAPI Tic Tac Toe example document, identified by an absolute URI.
+
+```yaml
+overlay: 1.0.0
+info:
+  title: Overlay for the Tic Tac Toe API document
+  version: 1.0.0
+extends: 'https://raw.githubusercontent.com/OAI/learn.openapis.org/refs/heads/main/examples/v3.1/tictactoe.yaml'
+...
+```
+
+The `extends` property can also specify a relative URI reference.
 
-The `extends` property can be used to indicate that the Overlay was designed to update a specific [[OpenAPI]] document. Where no `extends` is provided it is the responsibility of tooling to apply the Overlay documents to the appropriate OpenAPI document(s).
+```yaml
+overlay: 1.0.0
+info:
+  title: Overlay for the Tic Tac Toe API document
+  version: 1.0.0
+extends: './tictactoe.yaml'
+```
 
 #### Info Object
 
@@ -98,22 +115,22 @@ This object represents one or more changes to be applied to the target document
 | ---- | :----: | ---- |
 | <a name="action-target"></a>target | `string` | **REQUIRED** A JSONPath 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 should be an object with the properties and values to merge with the node. If the `target` selects an array, the value of this field should 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 is to be removed from the the map or array it is contained in. The default value is `false`. |
+| <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`. |
 
-The result of the `target` JSONPath expression must be zero or more objects or arrays (not primitive types or `null` values).
+The result of the `target` JSONPath expression MUST be zero or more objects or arrays (not primitive types or `null` values).
 
 To update a primitive property value such as a string, the `target` expression should select the _containing_ object in the target document and `update` should contain an object with the property and its new primitive value.
 
 Primitive-valued items of an array cannot be replaced or removed individually, only the complete array can be replaced.
 
-The properties of the update object MUST be compatible with the target object referenced by the JSONPath key. When the Overlay document is applied, the properties in the merge object replace properties in the target object with the same name and new properties are appended to the target object.
+The properties of the `update` object MUST be compatible with the target object referenced by the JSONPath key. When the Overlay document is applied, the properties in the `update` object are recursively merged with the properties in the target object with the same names; new properties are added to the target object.
 
 This object MAY be extended with [Specification Extensions](#specification-extensions).
 
 ### Examples
 
-#### Structured Overlays Example
+#### Structured Overlay Example
 
 When updating properties throughout the target document it may be more efficient to create a single `Action Object` that mirrors the structure of the target document. e.g.
 
@@ -141,14 +158,14 @@ actions:
       tags:
 ```
 
-#### Targeted Overlays
+#### Targeted Overlay Example
 
 Alternatively, where only a small number of updates need to be applied to a large document, each [Action Object](#action-object) MAY be more targeted.
 
 ```yaml
 overlay: 1.0.0
 info:
-  title: Targeted Overlays
+  title: Targeted Overlay
   version: 1.0.0
 actions:
   - target: $.paths['/foo'].get
@@ -164,7 +181,7 @@ actions:
         x-safe: false
 ```
 
-#### Wildcard Overlays Examples
+#### Wildcard Overlay Example
 
 One significant advantage of using the JSONPath syntax is that it allows referencing multiple nodes in the target document. This would allow a single update object to be applied to multiple target objects using wildcards and other multi-value selectors.
 
@@ -183,7 +200,7 @@ actions:
         $ref: '/components/schemas/filterSchema'
 ```
 
-#### Array Modification Examples
+#### Array Modification Example
 
 Array elements MAY be deleted using the `remove` property. Use of array indexes to remove array items should be avoided where possible as indexes will change when items are removed.
 
@@ -209,9 +226,9 @@ actions:
     remove: true
 ```
 
-#### Traits Examples
+#### 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
@@ -264,4 +281,4 @@ The extensions may or may not be supported by the available tooling, but those m
 
 | Version | Date | Notes |
 | ---- | ---- | ---- |
-| 1.0.0 | TBD | First release of the Overlay Specification |
+| 1.0.0 | 2024-10-17 | First release of the Overlay Specification |