From eab08e924a1ecd88691dc09c012d49358187c03f Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Thu, 22 Jan 2026 12:26:11 -0800 Subject: [PATCH 1/2] Explain that schemas are for mandatory requirements We do not host linting schemas here. --- CONTRIBUTING.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 406e35cfc3..9eea8dfeea 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -257,6 +257,24 @@ Schemas are updated in and directly published from the `vX.Y-dev` branches. As part of the publishing process, the YAML source files are converted to JSON, renamed to the relevant last-changed dates, and `WORK-IN-PROGRESS` placeholders are replaced with these dates as appropriate. This is usually done by the [`schema-publish` workflow](https://github.com/OAI/OpenAPI-Specification/blob/main/.github/workflows/schema-publish.yaml) which detects changes on each `vX.Y-dev` branch, which generates a pull request for publishing the new schema iterations to the [spec site](https://spec.openapis.org). The workflow can also be run manually if required. +#### Schemas and OAS Requirements + +Not all uses of OAS Objects and fields are necessarily useful. +However, the OAS does not forbid various questionable combinations, for +reasons ranging from preserving possible future use with new features to +maintaining compatibility with past versions that neglected to forbid something. + +The schemas published by the OpenAPI Initiative _only_ validate mandatory +OAS requirements. This means that a field value or combination with another +field is only forbidden in a schema if there is a corresponding MUST / MUST NOT / +SHALL / SHALL NOT requirement that prevents it. + +Schemas that apply further restrictions to enforce desired usage are outside +of the scope of the OpenAPI Initiative. When opening an issue or PR for +schema changes, please ensure that the changes are backed by clear OAS +requirements. Otherwise, the issue or PR will be closed with a note pointing +to this section. + ## Release Process and Scope This section relates to the 3.x versions only. From d6655e16c3f26aed9afb3eb4d54827507b22e1ff Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Sun, 25 Jan 2026 16:49:57 -0800 Subject: [PATCH 2/2] Remove 1st paragraph (review feedback) --- CONTRIBUTING.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9eea8dfeea..724639da17 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -259,11 +259,6 @@ As part of the publishing process, the YAML source files are converted to JSON, #### Schemas and OAS Requirements -Not all uses of OAS Objects and fields are necessarily useful. -However, the OAS does not forbid various questionable combinations, for -reasons ranging from preserving possible future use with new features to -maintaining compatibility with past versions that neglected to forbid something. - The schemas published by the OpenAPI Initiative _only_ validate mandatory OAS requirements. This means that a field value or combination with another field is only forbidden in a schema if there is a corresponding MUST / MUST NOT /