Merge remote-tracking branch 'upstream/v3.2-dev' into 3.2-schema-test-coverage

Author: ralfhandl

.github/workflows/check-restricted-files.yaml

@@ -18,5 +18,27 @@ jobs:
       - name: Check changed files
         shell: bash
         run: |
+          if [[ "${{ github.event.pull_request.head.repo.full_name }}" == "OAI/OpenAPI-Specification" ]] && \
+             [[ "${{ github.event.pull_request.base.repo.full_name }}" == "OAI/OpenAPI-Specification" ]]; then
+ 
+            if [[ "${{ github.event.pull_request.head.ref }}" == "main" ]] && \
+               [[ "${{ github.event.pull_request.base.ref }}" == "dev" ]]; then
+              echo Sync from main to dev
+              exit 0
+            fi
+
+            if [[ "${{ github.event.pull_request.head.ref }}" == "dev" ]] && \
+               [[ "${{ github.event.pull_request.base.ref }}" =~ ^v[0-9]+\.[0-9]+-dev$ ]]; then
+              echo Sync from dev to ${{ github.event.pull_request.base.ref }}
+              exit 0
+            fi
+
+            if [[ "${{ github.event.pull_request.head.ref }}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+-rel$ ]] && \
+               [[ "${{ github.event.pull_request.base.ref }}" == "main" ]]; then
+              echo Release from ${{ github.event.pull_request.head.ref }} to main
+              exit 0
+            fi
+          fi
+
           echo This PR contains changes to files that should not be changed
           exit 1

.github/workflows/sync-dev-to-vX.Y-dev.yaml

@@ -0,0 +1,45 @@
+name: sync-dev-to-vX.Y-dev
+
+# author: @ralfhandl
+
+#
+# This workflow creates PRs to update the vX.Y-dev branch with the latest changes from dev
+#
+
+# run this on push to dev
+on:
+  push:
+    branches:
+      - dev
+
+jobs:
+  sync-branches:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Create pull requests
+        id: pull_requests
+        shell: bash
+        run: |
+          DEV_BRANCHES=$(git branch -r --list origin/v?.?-dev)
+          for DEV_BRANCH in $DEV_BRANCHES; do
+            BASE=${DEV_BRANCH:7}
+            EXISTS=$(gh pr list --base $BASE --head $HEAD \
+              --json number --jq '.[] | .number')
+            if [ ! -z "$EXISTS" ]; then
+              echo "PR #$EXISTS already wants to merge $HEAD into $BASE"
+              continue
+            fi
+
+            gh pr create --base $BASE --head $HEAD \
+              --label "Housekeeping" \
+              --title "$BASE: update from $HEAD" \
+              --body "Merge \`$HEAD\` into \`$BASE\`."
+          done
+        env:
+          GH_TOKEN: ${{ github.token }}
+          HEAD: dev

.gitignore

@@ -8,5 +8,5 @@ node_modules/
 deploy/
 deploy-preview/
 coverage/
-history
+_site/
 Gemfile.lock

CONTRIBUTING.md

@@ -195,6 +195,25 @@ Reviews requesting changes should have their changes addressed regardless of how
 The specification versions are published to the [spec site](https://spec.openapis.org) by creating an `vX.Y.Z-rel` branch where `src/oas.md` is renamed to the appropriate `versions/X.Y.Z.md` file and then merged to `main`.
 This renaming on the `vX.Y.Z-rel` branch preserves the commit history for the published file on `main` when using `git log --follow` (as is the case for all older published files).
 
+The steps for creating a `vX.Y.Z-rel` branch are:
+
+1. Update `EDITORS.md` on `main`
+2. Merge `main` into `dev` and `dev` into `vX.Y-dev` via PRs
+   - Sync PRs are automatically created by workflows `sync-main-to-dev` and `sync-dev-to-vX.Y-dev`
+3. Prepare spec files in `vX.Y-dev`
+   - `npm run format-markdown`
+   - `npm run build-src`
+   - open `deploy-preview/oas.html` in browser and verify correct formatting
+   - adjust and repeat until done
+   - merge changes to `src/oas.md` back into `vX.Y-dev` via PR
+4. Create `vX.Y.Z-rel` from `vX.Y-dev` and adjust it
+   - move `src/oas.md` to `versions/X.Y.Z.md`
+   - copy `EDITORS.md` to `versions/X.Y.Z-editors.md`
+   - delete `src/schemas` 
+   - delete `tests/schema`
+5. Merge `vX.Y.Z-rel` into `main` via PR
+   - this PR should only add files `versions/X.Y.Z.md` and `versions/X.Y.Z-editors.md`
+
 The HTML renderings of the specification versions are automatically generated from the `versions` directory on `main` by the [`respec` workflow](https://github.com/OAI/OpenAPI-Specification/blob/main/.github/workflows/respec.yaml), which generates a pull request for publishing the HTML renderings to the [spec site](https://spec.openapis.org).
 
 ### Schema Iterations
@@ -317,7 +336,7 @@ For information on the branch and release strategy for OAS 3.0.4 and 3.1.1 and e
 ### Branch roles
 
 * `main` is used to publish finished work and hold the authoritative versions of general documentation such as this document, which can be merged out to other branches as needed.  The `src` tree is ***not*** present on `main`.
-* `dev` is the primary branch for working with the `src` tree, which is kept up-to-date with the most recent release on the most recent minor (X.Y) release line, and serves as the base for each new minor release line.  Development infrastructure that is not needed on `main` is maintained here, and can be merged out to other non-`main` branches as needed.
+* `dev` is the primary branch for working with the `src` tree.  Development infrastructure that is not needed on `main` is maintained here, and can be merged out to other non-`main` branches as needed.
   Changes on `main` are automatically included in a pull request to `dev` (see the (section on [branch sync](#branch-sync-automation)).
 * `vX.Y-dev` is the minor release line development branch for X.Y, including both the initial X.Y.0 minor version and all subsequent X.Y.Z patch versions.  All PRs are made to oldest active `vX.Y-dev` branch to which the change is relevant, and then merged forward as shown in the diagram further down in this document.
 * `vX.Y.Z-rel` is the release branch for an X.Y.Z release (including when Z == 0).  It exists primarily for `git mv`-ing `src/oas.md` to the appropriate `versions/X.Y.Z.md` location before merging back to `main`, and can also be used for any emergency post-release fixes that come up, such as when a 3rd party changes URLs in a way that breaks published links.
@@ -329,17 +348,15 @@ Upon release:
 * Pre-release steps:
     * The most recent _published_ patch release from the previous line is merged up to `vX.Y-dev`, if relevant
     * If doing simultaneous releases on multiple lines, do them from the oldest to newest line
-    * If the release is the most recent on the current line, merge `vX.Y-dev` to `dev`
     * For example, if releasing 3.1.3 and 3.2.0:
-        * release 3.1.3 first, including merging `v3.1-dev` to `dev` as 3.1 is current at that moment
-        * release 3.2.0 second, also merging `v3.2-dev` to `dev` as 3.2 becomes current at that point
-        * any subsequent 3.1.4 would **_not_** trigger a merge of `v3.1-dev` to `dev`, as 3.1 would no longer be current
+        * release 3.1.3 first
+        * release 3.2.0 second
 * Release branching and merging:
     * branch `vX.Y.Z-rel` from `vX.Y-dev` (same commit that was merged to `dev` if relevant)
-    * After renaming `src/oas.md` to `versions/X.Y.Z.md`, merge `vX.Y.Z-rel` to `main`
+    * After renaming `src/oas.md` to `versions/X.Y.Z.md` and [other adjustments](#specification-versions), merge `vX.Y.Z-rel` to `main`
 * Publishing to the [spec site](https://spec.openapis.org) is triggered by the merge to `main`
 * Post-release steps:
-    * If this was a major or minor release (Z == 0), branch `vX.Y+1-dev` from `dev`, from the commit where `vX.Y-dev` was merged to `dev`
+    * If this was a major or minor release (Z == 0), branch `vX.Y+1-dev` from `vX.Y-dev`
 
 _Release lines are grouped by color, although the colors of `dev` and `main` are not significant as these diagrams are limited to only 8 colors._
 
@@ -380,31 +397,50 @@ gitGraph TB:
   checkout v3.1-dev
   branch v3.1.2-rel order:3
   commit id:"rename src/oas.md to versions/3.1.2.md"
-  checkout dev
-  merge v3.1-dev id:"update dev with active line patch release"
+
   checkout main
   merge v3.1.2-rel tag:"3.1.2"
+  checkout dev
+  merge main id:"auto-sync from main"
+  checkout v3.1-dev
+  merge dev  id:"auto-sync from dev"
   checkout v3.2-dev
+  merge dev  id:"auto-sync from dev "
+
   commit id:"more 3.2.0 work"
   checkout v3.1-dev
   commit id:"update version in src/oas.md to 3.1.3"
   commit id:"another 3.1.x fix"
   checkout v3.2-dev
   commit id:"still more 3.2.0 work"
   merge v3.1-dev id:"merge 3.1.3 fixes before releasing"
-  checkout dev
-  merge v3.1-dev id:"update dev with last pre-minor release patch release"
-  merge v3.2-dev id:"update dev with minor release"
+
   checkout v3.1-dev
   branch v3.1.3-rel order:4
   commit id:"rename src/oas.md to versions/3.1.3.md"
   checkout v3.2-dev
   branch v3.2.0-rel order:7
   commit id:"rename src/oas.md to versions/3.2.0.md"
+
   checkout main
   merge v3.1.3-rel tag:"3.1.3"
+  checkout dev
+  merge main id:" auto-sync from main"
+  checkout v3.1-dev
+  merge dev  id:" auto-sync from dev"
+  checkout v3.2-dev
+  merge dev  id:" auto-sync from dev "
+
+  checkout main
   merge v3.2.0-rel tag:"3.2.0"
   checkout dev
+  merge main id:"  auto-sync from main"
+  checkout v3.1-dev
+  merge dev  id:"  auto-sync from dev"
+  checkout v3.2-dev
+  merge dev  id:"  auto-sync from dev "
+
+  checkout v3.2-dev
   branch v3.3-dev order:9
   checkout v3.1-dev
   commit id:"update version in src/oas.md to 3.1.4"
@@ -420,17 +456,36 @@ gitGraph TB:
   merge v3.1-dev id:"merge 3.1.4 fixes before releasing"
   checkout v3.3-dev
   merge v3.2-dev id:"merge 3.1.4 / 3.2.1 fixes"
-  checkout dev
-  merge v3.2-dev id:"merge patch from active release line"
+
   checkout v3.1-dev
   branch v3.1.4-rel order:5
   commit id:"rename src/oas.md to versions/3.1.4.md"
   checkout v3.2-dev
   branch v3.2.1-rel order:8
   commit id:"rename src/oas.md to versions/3.2.1.md"
+
   checkout main
   merge v3.1.4-rel tag:"3.1.4"
+  checkout dev
+  merge main id:"   auto-sync from main"
+  checkout v3.1-dev
+  merge dev  id:"   auto-sync from dev"
+  checkout v3.2-dev
+  merge dev  id:"   auto-sync from dev "
+  checkout v3.3-dev
+  merge dev  id:"   auto-sync from dev  "
+
+  checkout main
   merge v3.2.1-rel tag:"3.2.1"
+  checkout dev
+  merge main id:"    auto-sync from main"
+  checkout v3.1-dev
+  merge dev  id:"    auto-sync from dev"
+  checkout v3.2-dev
+  merge dev  id:"    auto-sync from dev "
+  checkout v3.3-dev
+  merge dev  id:"    auto-sync from dev  "
+
   checkout v3.2-dev
   commit id:"update version in src/oas.md to 3.2.2"
   checkout v3.3-dev
@@ -442,9 +497,11 @@ gitGraph TB:
 To keep changes in sync, we have some GitHub actions that open pull requests to take changes from `main` onto the `dev` branch, and from `dev` to each active version branch.
 
 - `sync-main-to-dev` opens a pull request with all the changes from the `main` branch that aren't yet included on `dev`.
-  This needs a single approval from either maintainers or TSC and can be merged.
-  The aim is to bring build script and repository documentation changes to the other branches.
-  Published versions of the specifications and schemas will also move across branches with this approach.
+- `sync-dev-to-vX.Y-dev` opens pull requests with all the changes from `dev` that aren't yet included on the corresponding `vX.Y-dev` branch.
+
+These need a single approval from either maintainers or TSC and can be merged.
+The aim is to bring build script and repository documentation changes to the other branches.
+Published versions of the specifications and schemas will also move across branches with this approach.
 
 ## Appendix: Issue Automation
 

README.md

@@ -19,8 +19,6 @@ This GitHub project is the starting point for OpenAPI. Here you will find the in
 
 This repository contains [the Markdown sources](versions) for [all published OpenAPI Specification versions](https://spec.openapis.org/). For release notes and release candidate versions, refer to the [releases page](releases).
 
-Each folder in this repository, such as [schemas](schemas) and [tests](tests), should contain folders pertaining to the current and previous versions of the specification.
-
 ## See It in Action
 
 If you just want to see it work, check out the [list of current examples](https://learn.openapis.org/examples/).

_archive_/README.md

@@ -0,0 +1,3 @@
+# Archive
+
+This folder contains files that are no longer actively maintained.

_archive_/schemas/README.md

@@ -0,0 +1,9 @@
+# Archive of outdated JSON Schema Files
+
+> [!TIP]
+> JSON Schema files for validating OpenAPI descriptions using current OpenAPI versions are available on https://spec.openapis.org/#openapi-specification-schemas.
+>
+> These schema files are maintained in the `src/schemas` folder of the corresponding `vX.Y-dev` branch in this repository.
+
+> [!CAUTION]
+> Schema files in this folder are not maintained any more and are not intended for productive use.

_archive_/schemas/v1.2/README.md

@@ -0,0 +1,5 @@
+# Swagger Specification JSON Schemas
+
+The work on the JSON Schema for the Swagger Specification was donated to the community by [Francis Galiegue](https://github.com/fge)!
+
+Keep in mind that due to some JSON Schema limitations, not all constraints can be described. The missing constraints will be listed here in the future.

_archive_/schemas/v1.2/apiDeclaration.json

@@ -0,0 +1,61 @@
+{
+    "id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/apiDeclaration.json#",
+    "$schema": "http://json-schema.org/draft-04/schema#",
+    "type": "object",
+    "required": [ "swaggerVersion", "basePath", "apis" ],
+    "properties": {
+        "swaggerVersion": { "enum": [ "1.2" ] },
+        "apiVersion": { "type": "string" },
+        "basePath": {
+            "type": "string",
+            "format": "uri",
+            "pattern": "^https?://"
+        },
+        "resourcePath": {
+            "type": "string",
+            "format": "uri",
+            "pattern": "^/"
+        },
+        "apis": {
+            "type": "array",
+            "items": { "$ref": "#/definitions/apiObject" }
+        },
+        "models": {
+            "type": "object",
+            "additionalProperties": {
+                "$ref": "modelsObject.json#"
+            }
+        },
+        "produces": { "$ref": "#/definitions/mimeTypeArray" },
+        "consumes": { "$ref": "#/definitions/mimeTypeArray" },
+        "authorizations": { "$ref": "authorizationObject.json#" }
+    },
+    "additionalProperties": false,
+    "definitions": {
+        "apiObject": {
+            "type": "object",
+            "required": [ "path", "operations" ],
+            "properties": {
+                "path": {
+                    "type": "string",
+                    "format": "uri-template",
+                    "pattern": "^/"
+                },
+                "description": { "type": "string" },
+                "operations": {
+                    "type": "array",
+                    "items": { "$ref": "operationObject.json#" }
+                }
+            },
+            "additionalProperties": false
+        },
+        "mimeTypeArray": {
+            "type": "array",
+            "items": {
+                "type": "string",
+                "format": "mime-type"
+            },
+            "uniqueItems": true
+        }
+    }
+}

_archive_/schemas/v1.2/authorizationObject.json

@@ -0,0 +1,59 @@
+{
+    "id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/authorizationObject.json#",
+    "$schema": "http://json-schema.org/draft-04/schema#",
+    "type": "object",
+    "additionalProperties": {
+        "oneOf": [
+            {
+                "$ref": "#/definitions/basicAuth"
+            },
+            {
+                "$ref": "#/definitions/apiKey"
+            },
+            {
+                "$ref": "#/definitions/oauth2"
+            }
+        ]
+    },
+    "definitions": {
+        "basicAuth": {
+            "required": [ "type" ],
+            "properties": {
+                "type": { "enum": [ "basicAuth" ] }
+            },
+            "additionalProperties": false
+        },
+        "apiKey": {
+            "required": [ "type", "passAs", "keyname" ],
+            "properties": {
+                "type": { "enum": [ "apiKey" ] },
+                "passAs": { "enum": [ "header", "query" ] },
+                "keyname": { "type": "string" }
+            },
+            "additionalProperties": false
+        },
+        "oauth2": {
+            "type": "object",
+            "required": [ "type", "grantTypes" ],
+            "properties": {
+                "type": { "enum": [ "oauth2" ] },
+                "scopes": {
+                    "type": "array",
+                    "items": { "$ref": "#/definitions/oauth2Scope" }
+                },
+                "grantTypes": { "$ref": "oauth2GrantType.json#" }
+            },
+            "additionalProperties": false
+        },
+        "oauth2Scope": {
+            "type": "object",
+            "required": [ "scope" ],
+            "properties": {
+                "scope": { "type": "string" },
+                "description": { "type": "string" }
+            },
+            "additionalProperties": false
+        }
+    }
+}
+