Merge branch 'v3.2-dev' into self2

Author: ralfhandl

.gitignore

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

CONTRIBUTING.md

@@ -336,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.
@@ -348,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._
 
@@ -399,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"
@@ -439,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

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
+        }
+    }
+}
+