Restructure how we mention the JSON Schemas #4870
Description
This is somewhat related to #4831...
Currently the schemas (used to validate OpenAPI documents, as well as provide aids to implementations parsing the OAD by identifying locations of schemas and other identifiable types) are described by https://spec.openapis.org as "non-normative", and by the specification as "non-authoritative".
- "non-normative" means that the schemas are not an official formal part of the specification, but only there to be helpful and aid understanding;
- "non-authoritative" means that the schemas are not from an official source.
I believe neither of these things are true: the schemas are part of the specification in that they capture, to the best of their ability, the constraints and restrictions described by the specification, and we take effort to ensure that they are correct and in sync with the changes to the specification document, and the schemas do come from an official source (they are published from the very same repository as the specification text itself, authored by the same trusted people).
I would like the schema links to be more prominent in the published specification, listed at the top of https://spec.openapis.org/oas/latest.html (perhaps below "Editors"), or farther up as two new subsections: "Latest Schemas" (four bullet points) and "Previous Schemas" (a single link to https://spec.openapis.org/#specifications). This could be templated so as not to require any manual spec editing should we wish to release a schema update/fix. Alternatively, we could make use of this via ReSpec (see https://respec.org/docs/#otherLinks)
The paragraph at https://spec.openapis.org/oas/latest#schema could be rewritten to indicate that the schemas can be trusted to perform validation of an OAD: while the schemas cannot cover every requirement and constraint of the specification, validation is guaranteed to NOT produce false failures -- that is, while the schemas cannot promise to fail validation on every invalid OAD, we can promise that we will never fail validation for a valid OAD.
Also, https://spec.openapis.org can contain similar wording changes (removing mention of them being non-normative): the schemas can be used to aid parsing, and will find many structural errors in the OAD, so it is fully expected and recommended that all tools make use of these.