Uh oh!
There was an error while loading. Please reload this page.
- Notifications
You must be signed in to change notification settings - Fork 9.2k
schemas: add WORK-IN-PROGRESS placeholders, don't mention patch numbers, update terminology#4146
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Uh oh!
There was an error while loading. Please reload this page.
Merged
Changes from all commits
Commits
Show all changes
6 commits
Select commit
Hold shift + click to select a range
492b9cc
schemas: WORK-IN-PROGRESS placeholders, terminology
handrews 8e23d02
Update the schema READMEs for current practice
handrews c0f07c9
"base" can't be both a file and a directory
handrews cc1995d
Merge remote-tracking branch 'upstream/main' into pr/4146
ralfhandl b928227
Link to issue tracking "latest" schema access
handrews 520a7c3
Update schemas/v3.1/schema.yaml
ralfhandl File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Uh oh!
There was an error while loading. Please reload this page.
Jump to
Jump to file
Failed to load files.
Loading
Uh oh!
There was an error while loading. Please reload this page.
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,41 +1,54 @@ | ||
| # OpenAPI 3.1.X JSON Schema | ||
| Here you can find the JSON Schema for validating OpenAPI definitions of versions 3.1.x. | ||
| This directory contains the YAML sources for generating the JSON Schemas for validating OpenAPI definitions of versions 3.1.X, which are published on [https://spec.openapis.org](https://spec.openapis.org). | ||
| As a reminder, the JSON Schema is not the source of truth for the Specification. | ||
| In cases of conflicts between the Specification itself and the JSON Schema, the | ||
| Specification wins. Also, some Specification constraints cannot be represented | ||
| with the JSON Schema so it's highly recommended to employ other methods to | ||
| ensure compliance. | ||
| Due to limitations of GitHub pages, the schemas on the spec site are served with `Content-Type: application/octet-stream`, but should be interpreted as `application/schema+json`. | ||
| The sources in this directory, which have `WORK-IN-PROGRESS` in their `$id`s, is _not intended for direct use_. | ||
| ## Choosing which schema to use | ||
| There are two schemas to choose from for 3.1 usage, both of which have an `$id` that starts with `https://spec.openapis.org/oas/3.1/` and end with date or the `WORK-IN-PROGRESS` placeholder: | ||
| * `https://spec.openapis.org/oas/3.1/schema/{date}` — A self-contained schema that _does not_ validate Schema Objects beyond `type: [object, boolean]` | ||
| * `https://spec.openapis.org/oas/3.1/meta/base/{date}` — The vocabulary metaschema for OAS 3.1's extensions to draft 2020-12 | ||
| * `https://spec.openapis.org/oas/3.1/dialect/base/{date}` — The dialect metaschema that extends the standard `draft/2020-12` metaschema by adding the OAS "base" vocabulary | ||
| * `https://spec.openapis.org/oas/3.1/schema-base/{date}` — A schema that combines the self-contained schema and the "base" dialect schema to validate Schema Objects with the dialect; this schema does not allow changing `$schema` or `jsonSchemaDialect` to other dialects | ||
| The name "base" for the dialect was intended to indicate that the OAS dialect could be further extended. | ||
| An additional schema that validates the Schema Object with the OAS 3.1 dialect but does not restrict changing `$schema` is [under consideration](https://github.com/OAI/OpenAPI-Specification/issues/4147). | ||
| ## Schema `$id` dates | ||
| The published schemas on the spec site have an _iteration date_ in their `id`s. | ||
| This allows the schemas for a release line (in this case 3.0) to be updated independent of the spec patch release cycle. | ||
| The iteration version of the JSON Schema can be found in the `$id` field. | ||
| For example, the value of `$id: https://spec.openapis.org/oas/3.1/schema/2021-03-02` means this iteration was created on March 2nd, 2021. | ||
| The `schema.yaml` schema doesn't validate the JSON Schemas in your OpenAPI | ||
| document because 3.1 allows you to use any JSON Schema dialect you choose. We | ||
| have also included `schema-base.yaml` that extends the main schema to validate | ||
| that all schemas use the default OAS base vocabulary. | ||
| We are [working on](https://github.com/OAI/OpenAPI-Specification/issues/4152) how to best provide programmatic access for determining the latest date for each schema. | ||
| ## Contributing | ||
| ## Improving the schemas | ||
| To submit improvements to the schema, modify the `schema.yaml` and add test cases for your changes. | ||
| As a reminder, the JSON Schema is not the source of truth for the Specification. In cases of conflicts between the Specification itself and the JSON Schema, the Specification wins. Also, some Specification constraints cannot be represented with the JSON Schema so it's highly recommended to employ other methods to ensure compliance. | ||
| The schema only validates the mandatory aspects of the OAS. | ||
| Validating requirements that are optional, or field usage that has undefined or ignored behavior are not within the scope of this schema. | ||
| Schemas to perform additional optional validation are [under consideration](https://github.com/OAI/OpenAPI-Specification/issues/4141). | ||
| Improvements can be submitted by opening a PR against the `main` branch. | ||
| Modify the `*schema*.yaml` files and add test cases for your changes. | ||
| The TSC will then: | ||
| - Run tests on the updated schema | ||
| - Update the iteration version | ||
| - Publish the new version | ||
| ## Tests | ||
| The [test suite](../../tests/v3.1) is part of this package. | ||
| ```bash | ||
| npm install | ||
| npm test | ||
| ``` | ||
| You can also validate a document individually. | ||
| ```bash | ||
| node scripts/validate.mjs path/to/document/to/validate.yaml | ||
| ``` |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,20 +1,20 @@ | ||
| $id: 'https://spec.openapis.org/oas/3.1/schema-base/2022-10-07' | ||
| $id: 'https://spec.openapis.org/oas/3.1/schema-base/WORK-IN-PROGRESS' | ||
| $schema: 'https://json-schema.org/draft/2020-12/schema' | ||
| description: The description of OpenAPI v3.1.x documents using the OpenAPI JSON Schema dialect, as defined by https://spec.openapis.org/oas/v3.1.0 | ||
| description: The description of OpenAPI v3.1.x Documents using the OpenAPI JSON Schema dialect | ||
| $ref: 'https://spec.openapis.org/oas/3.1/schema/2022-10-07' | ||
| $ref: 'https://spec.openapis.org/oas/3.1/schema/WORK-IN-PROGRESS' | ||
| properties: | ||
| jsonSchemaDialect: | ||
| $ref: '#/$defs/dialect' | ||
| $defs: | ||
| dialect: | ||
| const: 'https://spec.openapis.org/oas/3.1/dialect/base' | ||
| const: 'https://spec.openapis.org/oas/3.1/dialect/WORK-IN-PROGRESS' | ||
| schema: | ||
| $dynamicAnchor: meta | ||
| $ref: 'https://spec.openapis.org/oas/3.1/dialect/base' | ||
| $ref: 'https://spec.openapis.org/oas/3.1/dialect/WORK-IN-PROGRESS' | ||
| properties: | ||
| $schema: | ||
| $ref: '#/$defs/dialect' |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.