sync main to v1.1-dev

.github/CODEOWNERS

@@ -0,0 +1 @@
+* @oai/tsc

.github/templates/agenda.md

@@ -3,7 +3,7 @@
 
 
 
- Meeting link: 
+ Meeting link: <https://zoom-lfx.platform.linuxfoundation.org/meeting/99628896838?password=f3ff9796-d6a0-4749-b39e-93dc7eafe7cd>
 
 
 

.github/workflows/agenda.yaml

@@ -2,6 +2,9 @@ name: Create meeting template
 
 on:
   workflow_dispatch: {}
+  schedule:
+    # every two weeks on tuesday at 10AM PST (with DST)
+    - cron: '0 17 */14 * 2'
 
 jobs:
   create-discussion:
@@ -16,6 +19,11 @@ jobs:
           echo 'AGENDA<<EOF' >> $GITHUB_ENV
           cat .github/templates/agenda.md >> $GITHUB_ENV
           echo 'EOF' >> $GITHUB_ENV
+      - name: Get Next Meeting Date
+        id: get-next-meeting-date
+        run: |
+          NEXT_MEETING_DATE=$(date -d "next Tuesday" +%Y-%m-%d)
+          echo "NEXT_MEETING_DATE=$NEXT_MEETING_DATE" >> $GITHUB_ENV
       - name: Create discussion with agenda
         id: create-repository-discussion
         uses: octokit/[email protected]
@@ -24,7 +32,7 @@ jobs:
         with:
           variables: | 
             body: "${{ env.AGENDA }}"
-            title: "Overlays Meeting"
+            title: "Overlays Meeting (${{ env.NEXT_MEETING_DATE }})"
             repositoryId: 'MDEwOlJlcG9zaXRvcnkzNTk4NjU5MDI='
             categoryId: 'DIC_kwDOFXMeLs4COVB8'
           query: |

.github/workflows/respec.yaml

@@ -19,9 +19,18 @@ jobs:
   respec:
     if: github.repository == 'OAI/Overlay-Specification'
 
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
 
     steps:
+    - name: Generate access token
+      id: generate-token
+      uses: actions/create-github-app-token@v1
+      with:
+        app-id: ${{ secrets.OAI_SPEC_PUBLISHER_APPID }}
+        private-key: ${{ secrets.OAI_SPEC_PUBLISHER_PRIVATE_KEY }}
+        owner: OAI
+        repositories: OpenAPI-Specification
+
     - uses: actions/checkout@v4 # checkout main branch
       with:
         fetch-depth: 0
@@ -35,7 +44,7 @@ jobs:
 
     - uses: actions/checkout@v4 # checkout gh-pages branch
       with:
-        token: ${{ secrets.OAS_REPO_TOKEN }}
+        token: ${{ steps.generate-token.outputs.token }}
         repository: OAI/OpenAPI-Specification  # TODO: change to OAI/...
         ref: gh-pages
         path: deploy
@@ -46,16 +55,14 @@ 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 }}
+        token: ${{ steps.generate-token.outputs.token }}
         branch: update-overlay-respec-version
         base: gh-pages
         delete-branch: true
         path: deploy
         labels: Housekeeping
-        team-reviewers: OAI/tsc
-        title: Update ReSpec-rendered specification versions for Overlay
+        reviewers: darrelmiller,webron,earth2marsh,lornajane,mikekistler,miqui,handrews,ralfhandl
+        title: Overlay - Update ReSpec-rendered specification versions
         commit-message: Update ReSpec-rendered specification versions
         signoff: true
         body: |

.github/workflows/schema-publish.yaml

@@ -0,0 +1,66 @@
+name: schema-publish
+
+# author: @ralfhandl
+
+#
+# This workflow copies the x.y schemas to the gh-pages branch
+#
+
+# run this on push to main
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch: {}
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Generate access token
+        id: generate-token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ secrets.OAI_SPEC_PUBLISHER_APPID }}
+          private-key: ${{ secrets.OAI_SPEC_PUBLISHER_PRIVATE_KEY }}
+          owner: OAI
+          repositories: OpenAPI-Specification
+
+      - uses: actions/checkout@v4 # checkout main branch
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4 # setup Node.js
+        with:
+          node-version: 20.x
+
+      - name: Install dependencies
+        run: npm ci
+
+      - uses: actions/checkout@v4 # checkout gh-pages branch
+        with:
+          token: ${{ steps.generate-token.outputs.token }}
+          repository: OAI/OpenAPI-Specification
+          ref: gh-pages
+          path: deploy
+
+      - name: run main script
+        run: scripts/schema-publish.sh
+
+      - name: Create Pull Request
+        uses: peter-evans/create-pull-request@v7
+        with:
+          token: ${{ steps.generate-token.outputs.token }}
+          branch: publish-overlay-schema-iteration
+          base: gh-pages
+          delete-branch: true
+          path: deploy
+          labels: Housekeeping,Schema
+          reviewers: darrelmiller,webron,earth2marsh,lornajane,mikekistler,miqui,handrews,ralfhandl
+          title: Overlay - Publish Schema Iterations
+          commit-message: New Overlay schema iterations
+          signoff: true
+          body: |
+            This pull request is automatically triggered by GitHub action `schema-publish` in the OAI/Overlay-Specification repo.
+            The `schemas/**/*.yaml` files have changed and JSON files are automatically generated.

CONTRIBUTING.md

@@ -7,6 +7,38 @@ Pull requests are also welcome, but it is recommended to create an issue first,
 Questions and comments are also welcome - use the GitHub Discussions feature.
 You will also find notes from past meetings in the Discussion tab.
 
+## Key information
+
+This project is covered by our [Code of Conduct](https://github.com/OAI/OpenAPI-Specification?tab=coc-ov-file#readme).
+All participants are expected to read and follow this code.
+
+No changes, however trivial, are ever made to the contents of published specifications (the files in the `versions/` folder).
+Exceptions may be made when links to external documents have been changed by a 3rd party, in order to keep our documents accurate.
+
+Published versions of the specification are in the `versions/` folder.
+The under-development versions of the specification are in the file `src/overlay.md` on the appropriately-versioned branch.
+For example, work on the next release for 1.1 is on `v1.1-dev` in the file `src/overlay.md`.
+
+The [spec site](https://spec.openapis.org) is the source of truth for the OpenAPI Overlay specification as it contains all the citations and author credits.
+
+The OpenAPI project is almost entirely staffed by volunteers.
+Please be patient with the people in this project, who all have other jobs and are active here because we believe this project has a positive impact in the world.
+
+## Pull Requests
+
+Pull requests are always welcome but please read the section below on [branching strategy](#branching-strategy) before you start.
+
+Pull requests must come from a fork; create a fresh branch on your fork based on the target branch for your change.
+
+### Branching Strategy
+
+Overview of branches:
+
+- `main` holds the published versions of the specification, utility scripts and supporting documentation.
+- `dev` is for development infrastructure and other changes that apply to multiple versions of development.
+- Branches named `vX.Y-dev` are the active development branches for future releases.
+  All changes should be applied to the _earliest_ branch where the changes are relevant in the first instance.
+
 ## Build the HTML version to publish
 
 We use ReSpec to render the markdown specification as HTML for publishing and easier reading.

README.md

@@ -21,6 +21,11 @@ If you are looking for tools to use with Overlays, try these:
 - [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/)
+- [openapi-format CLI/UI](https://github.com/thim81/openapi-format)
+- [oas-patch CLI](https://github.com/mcroissant/oas_patcher)
+- [oas-overlay-java](https://github.com/IBM/oas-overlay-java)
+- [Specmatic](https://specmatic.io/) - [Docs](https://docs.specmatic.io/documentation/contract_tests.html#overlays)
+- [BinkyLabs.OpenApi.Overlays - dotnet](https://github.com/BinkyLabs/openapi-overlays-dotnet)
 
 (Is something missing from the list? Send us a pull request to add it!)
 

compliant-sets/README.md

@@ -0,0 +1,9 @@
+# OpenAPI Overlay Compliant Sets
+
+The folders in this directory contain sets of "known good" Overlays, along with OpenAPI descriptions before and after the Overlay.
+These files are offered as examples of how a series of Overlays are expected to be applied, with the aim of supporting people building tools that apply Overlays.
+
+Each directory contains:
+- `overlay.yaml` - the Overlay
+- `openapi.yaml` - an OpenAPI description to use
+- `output.yaml` - the OpenAPI description after the Overlay has been applied

compliant-sets/add-a-license/openapi.yaml

@@ -0,0 +1,70 @@
+openapi: 3.1.0
+info:
+  version: 1.0.0
+  title: Imaginary town
+servers:
+  - url: 'https://example.com'
+    description: Example server
+paths:
+  /buildings:
+    get:
+      summary: All buildings
+      operationId: buildingsList
+      responses:
+        '200':
+          description: Return all known buildings
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Building'
+  '/buildings/{buildingId}':
+    get:
+      summary: Specific building
+      operationId: buildingById
+      parameters:
+        - name: buildingId
+          in: path
+          required: true
+          description: Which building to return
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Return a building
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Building'
+  /locations:
+    get:
+      summary: All locations
+      operationId: locationList
+      responses:
+        '200':
+          description: Returns all locations
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    location_id:
+                      type: integer
+                      example: 44
+                    name:
+                      type: string
+                      example: North Village
+components:
+  schemas:
+    Building:
+      type: object
+      properties:
+        building:
+          type: string
+          example: house
+        location_id:
+          type: integer
+          example: 44

compliant-sets/add-a-license/output.yaml

@@ -0,0 +1,74 @@
+openapi: 3.1.0
+info:
+  version: 1.0.0
+  title: Imaginary town
+  license:
+    name: MIT
+    url: 'https://opensource.org/licenses/MIT'
+servers:
+  - url: 'https://example.com'
+    description: Example server
+paths:
+  /buildings:
+    get:
+      summary: All buildings
+      operationId: buildingsList
+      responses:
+        '200':
+          description: Return all known buildings
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Building'
+  '/buildings/{buildingId}':
+    get:
+      summary: Specific building
+      operationId: buildingById
+      parameters:
+        - name: buildingId
+          in: path
+          required: true
+          description: Which building to return
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Return a building
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Building'
+  /locations:
+    get:
+      summary: All locations
+      operationId: locationList
+      responses:
+        '200':
+          description: Returns all locations
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    location_id:
+                      type: integer
+                      example: 44
+                    name:
+                      type: string
+                      example: North Village
+components:
+  schemas:
+    Building:
+      type: object
+      properties:
+        building:
+          type: string
+          example: house
+        location_id:
+          type: integer
+          example: 44
+

compliant-sets/add-a-license/overlay.yaml

@@ -0,0 +1,10 @@
+overlay: '1.0.0'
+info:
+  title: Add MIT license
+  version: '1.0.0'
+actions:
+  - target: '$.info'
+    update:
+      license:
+        name: MIT
+        url: https://opensource.org/licenses/MIT