Skip to content

Commit eab08e9

Browse files
committed
Explain that schemas are for mandatory requirements
We do not host linting schemas here.
1 parent e771a3a commit eab08e9

File tree

1 file changed

+18
-0
lines changed

1 file changed

+18
-0
lines changed

CONTRIBUTING.md

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -257,6 +257,24 @@ Schemas are updated in and directly published from the `vX.Y-dev` branches.
257257

258258
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.
259259

260+
#### Schemas and OAS Requirements
261+
262+
Not all uses of OAS Objects and fields are necessarily useful.
263+
However, the OAS does not forbid various questionable combinations, for
264+
reasons ranging from preserving possible future use with new features to
265+
maintaining compatibility with past versions that neglected to forbid something.
266+
267+
The schemas published by the OpenAPI Initiative _only_ validate mandatory
268+
OAS requirements. This means that a field value or combination with another
269+
field is only forbidden in a schema if there is a corresponding MUST / MUST NOT /
270+
SHALL / SHALL NOT requirement that prevents it.
271+
272+
Schemas that apply further restrictions to enforce desired usage are outside
273+
of the scope of the OpenAPI Initiative. When opening an issue or PR for
274+
schema changes, please ensure that the changes are backed by clear OAS
275+
requirements. Otherwise, the issue or PR will be closed with a note pointing
276+
to this section.
277+
260278
## Release Process and Scope
261279

262280
This section relates to the 3.x versions only.

0 commit comments

Comments
 (0)