From 492b9ccc7b5e26d5a3d49d4cdd8b721f0b149a7d Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Fri, 18 Oct 2024 11:56:31 -0700 Subject: [PATCH 1/5] schemas: WORK-IN-PROGRESS placeholders, terminology * Replace all dates with WORK-IN-PROGRESS * Append a date segement (as WORK-IN-PROGRESS) where missing * Adjust refs and other fields to WORK-IN-PROGRESS * Remove mention of specific patch releases * Use capital-D Document and Description according to new rules --- schemas/v3.0/schema.yaml | 4 ++-- schemas/v3.1/dialect/base.schema.yaml | 6 +++--- schemas/v3.1/meta/base.schema.yaml | 4 ++-- schemas/v3.1/schema-base.yaml | 10 +++++----- schemas/v3.1/schema.yaml | 6 +++--- 5 files changed, 15 insertions(+), 15 deletions(-) diff --git a/schemas/v3.0/schema.yaml b/schemas/v3.0/schema.yaml index 0123b9f645..acaf506eb5 100644 --- a/schemas/v3.0/schema.yaml +++ b/schemas/v3.0/schema.yaml @@ -1,6 +1,6 @@ -id: https://spec.openapis.org/oas/3.0/schema/2021-09-28 +id: https://spec.openapis.org/oas/3.0/schema/WORK-IN-PROGRESS $schema: http://json-schema.org/draft-04/schema# -description: The description of OpenAPI v3.0.x documents, as defined by https://spec.openapis.org/oas/v3.0.3 +description: The description of OpenAPI v3.0.x Documents type: object required: - openapi diff --git a/schemas/v3.1/dialect/base.schema.yaml b/schemas/v3.1/dialect/base.schema.yaml index 30996abb0e..4f3fbc95dd 100644 --- a/schemas/v3.1/dialect/base.schema.yaml +++ b/schemas/v3.1/dialect/base.schema.yaml @@ -1,8 +1,8 @@ -$id: https://spec.openapis.org/oas/3.1/dialect/base +$id: https://spec.openapis.org/oas/3.1/dialect/base/WORK-IN-PROGRESS $schema: https://json-schema.org/draft/2020-12/schema title: OpenAPI 3.1 Schema Object Dialect -description: A JSON Schema dialect describing schemas found in OpenAPI documents +description: A JSON Schema dialect describing schemas found in OpenAPI v3.1 Descriptions $dynamicAnchor: meta @@ -18,4 +18,4 @@ $vocabulary: allOf: - $ref: https://json-schema.org/draft/2020-12/schema - - $ref: https://spec.openapis.org/oas/3.1/meta/base + - $ref: https://spec.openapis.org/oas/3.1/meta/base/WORK-IN-PROGRESS diff --git a/schemas/v3.1/meta/base.schema.yaml b/schemas/v3.1/meta/base.schema.yaml index e2849e4115..f692bf1642 100644 --- a/schemas/v3.1/meta/base.schema.yaml +++ b/schemas/v3.1/meta/base.schema.yaml @@ -1,7 +1,7 @@ -$id: https://spec.openapis.org/oas/3.1/meta/base +$id: https://spec.openapis.org/oas/3.1/meta/base/WORK-IN-PROGRESS $schema: https://json-schema.org/draft/2020-12/schema -title: OAS Base vocabulary +title: OAS Base Vocabulary description: A JSON Schema Vocabulary used in the OpenAPI Schema Dialect $dynamicAnchor: meta diff --git a/schemas/v3.1/schema-base.yaml b/schemas/v3.1/schema-base.yaml index 01a5209a01..73118178b9 100644 --- a/schemas/v3.1/schema-base.yaml +++ b/schemas/v3.1/schema-base.yaml @@ -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/base/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/base/WORK-IN-PROGRESS' properties: $schema: $ref: '#/$defs/dialect' diff --git a/schemas/v3.1/schema.yaml b/schemas/v3.1/schema.yaml index bd1925ca9c..9c94b2413d 100644 --- a/schemas/v3.1/schema.yaml +++ b/schemas/v3.1/schema.yaml @@ -1,7 +1,7 @@ -$id: 'https://spec.openapis.org/oas/3.1/schema/2022-10-07' +$id: 'https://spec.openapis.org/oas/3.1/schema/WORK-IN-PROGRESS' $schema: 'https://json-schema.org/draft/2020-12/schema' -description: The description of OpenAPI v3.1.x documents without schema validation, as defined by https://spec.openapis.org/oas/v3.1.0 +description: The description of OpenAPI v3.1.x Documents without Schema Object validation type: object properties: @@ -13,7 +13,7 @@ properties: jsonSchemaDialect: type: string format: uri - default: 'https://spec.openapis.org/oas/3.1/dialect/base' + default: 'https://spec.openapis.org/oas/3.1/dialect/base/WORK-IN-PROGRESS' servers: type: array items: From 8e23d02690483f948bd88f05627d7feb1a113930 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Mon, 21 Oct 2024 10:03:54 -0700 Subject: [PATCH 2/5] Update the schema READMEs for current practice --- schemas/v3.0/README.md | 27 +++++++++++++------ schemas/v3.1/README.md | 60 ++++++++++++++++++++---------------------- 2 files changed, 48 insertions(+), 39 deletions(-) diff --git a/schemas/v3.0/README.md b/schemas/v3.0/README.md index 84956279da..e503a14184 100644 --- a/schemas/v3.0/README.md +++ b/schemas/v3.0/README.md @@ -1,16 +1,27 @@ OpenAPI 3.0.X JSON Schema --- -Here you can find the JSON Schema for validating OpenAPI definitions of versions 3.0.X. +This directory contains the YAML source for generating the JSON Schema for validating OpenAPI definitions of versions 3.0.X, which is 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 source in this directory, which has `WORK-IN-PROGRESS` in its `id`, is _not intended for direct use_. + +## 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.0/schema/2019-04-02` means this iteration was created on April 2nd, 2019. -To submit improvements to the schema, modify the schema.yaml file only. +The special URL with `latest` in place of the date is intended to provide an HTTP redirect to the most recent dated schema. + +## Improving the schema + +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). -The TSC will then: -- Run tests on the updated schema -- Update the iteration version -- Convert the schema.yaml to schema.json -- Publish the new version +Improvements can be submitted by opening a PR against the `main` branch. diff --git a/schemas/v3.1/README.md b/schemas/v3.1/README.md index 01da62b56d..cce2128965 100644 --- a/schemas/v3.1/README.md +++ b/schemas/v3.1/README.md @@ -1,41 +1,39 @@ -# OpenAPI 3.1.X JSON Schema +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 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 sources in this directory, which have `WORK-IN-PROGRESS` in their `$id`s, is _not intended for direct use_. -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. +## Choosing which schema to use -## Contributing -To submit improvements to the schema, modify the schema.yaml file only. +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: -The TSC will then: -- Run tests on the updated schema -- Update the iteration version -- Convert the schema.yaml to schema.json -- Publish the new version +* `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 -## Tests -The test suite is included as a git submodule of https://github.com/Mermade/openapi3-examples. +The name "base" for the dialect was intended to indicate that the OAS dialect could be further extended. -```bash -npx mocha --recursive tests -``` +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). -You can also validate a document individually. +## Schema `$id` dates -```bash -scripts/validate.js path/to/document/to/validate.yaml -``` +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` +The special URL with `latest` in place of the date is intended to provide an HTTP redirect to the most recent dated schema. + +## Improving the schemas + +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. From c0f07c907f46747f3558815ed4fc8bebe66bfe2d Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Mon, 21 Oct 2024 18:11:39 -0700 Subject: [PATCH 3/5] "base" can't be both a file and a directory --- schemas/v3.1/dialect/base.schema.yaml | 4 ++-- schemas/v3.1/meta/base.schema.yaml | 2 +- schemas/v3.1/schema-base.yaml | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/schemas/v3.1/dialect/base.schema.yaml b/schemas/v3.1/dialect/base.schema.yaml index 4f3fbc95dd..d300d94feb 100644 --- a/schemas/v3.1/dialect/base.schema.yaml +++ b/schemas/v3.1/dialect/base.schema.yaml @@ -1,4 +1,4 @@ -$id: https://spec.openapis.org/oas/3.1/dialect/base/WORK-IN-PROGRESS +$id: https://spec.openapis.org/oas/3.1/dialect/WORK-IN-PROGRESS $schema: https://json-schema.org/draft/2020-12/schema title: OpenAPI 3.1 Schema Object Dialect @@ -18,4 +18,4 @@ $vocabulary: allOf: - $ref: https://json-schema.org/draft/2020-12/schema - - $ref: https://spec.openapis.org/oas/3.1/meta/base/WORK-IN-PROGRESS + - $ref: https://spec.openapis.org/oas/3.1/meta/WORK-IN-PROGRESS diff --git a/schemas/v3.1/meta/base.schema.yaml b/schemas/v3.1/meta/base.schema.yaml index f692bf1642..6cfce4976d 100644 --- a/schemas/v3.1/meta/base.schema.yaml +++ b/schemas/v3.1/meta/base.schema.yaml @@ -1,4 +1,4 @@ -$id: https://spec.openapis.org/oas/3.1/meta/base/WORK-IN-PROGRESS +$id: https://spec.openapis.org/oas/3.1/meta/WORK-IN-PROGRESS $schema: https://json-schema.org/draft/2020-12/schema title: OAS Base Vocabulary diff --git a/schemas/v3.1/schema-base.yaml b/schemas/v3.1/schema-base.yaml index 73118178b9..ea239c03e9 100644 --- a/schemas/v3.1/schema-base.yaml +++ b/schemas/v3.1/schema-base.yaml @@ -10,11 +10,11 @@ properties: $defs: dialect: - const: 'https://spec.openapis.org/oas/3.1/dialect/base/WORK-IN-PROGRESS' + 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/WORK-IN-PROGRESS' + $ref: 'https://spec.openapis.org/oas/3.1/dialect/WORK-IN-PROGRESS' properties: $schema: $ref: '#/$defs/dialect' From b92822776058f87653fc00268cf4a075341311bc Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Tue, 22 Oct 2024 08:26:43 -0700 Subject: [PATCH 4/5] Link to issue tracking "latest" schema access --- schemas/v3.0/README.md | 2 +- schemas/v3.1/README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/schemas/v3.0/README.md b/schemas/v3.0/README.md index 713a1cf9ef..5bda66cf5a 100644 --- a/schemas/v3.0/README.md +++ b/schemas/v3.0/README.md @@ -14,7 +14,7 @@ This allows the schemas for a release line (in this case 3.0) to be updated inde 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.0/schema/2019-04-02` means this iteration was created on April 2nd, 2019. -The special URL with `latest` in place of the date is intended to provide an HTTP redirect to the most recent dated schema. +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. ## Improving the schema diff --git a/schemas/v3.1/README.md b/schemas/v3.1/README.md index ff19b72c88..a3d4c87ea0 100644 --- a/schemas/v3.1/README.md +++ b/schemas/v3.1/README.md @@ -27,7 +27,7 @@ This allows the schemas for a release line (in this case 3.0) to be updated inde 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 special URL with `latest` in place of the date is intended to provide an HTTP redirect to the most recent dated schema. +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. ## Improving the schemas From 520a7c3a9fa493487e88b78c54c02e0a6afb91b4 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Tue, 22 Oct 2024 18:16:17 +0200 Subject: [PATCH 5/5] Update schemas/v3.1/schema.yaml To be consistent with the other YAML files --- schemas/v3.1/schema.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/schemas/v3.1/schema.yaml b/schemas/v3.1/schema.yaml index 9c94b2413d..dbb4c756ad 100644 --- a/schemas/v3.1/schema.yaml +++ b/schemas/v3.1/schema.yaml @@ -13,7 +13,7 @@ properties: jsonSchemaDialect: type: string format: uri - default: 'https://spec.openapis.org/oas/3.1/dialect/base/WORK-IN-PROGRESS' + default: 'https://spec.openapis.org/oas/3.1/dialect/WORK-IN-PROGRESS' servers: type: array items: