From 319f888a9077ca56c2995a2649e051c8890be236 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Mon, 8 Sep 2025 08:42:31 -0700 Subject: [PATCH 1/4] Make patch optional in openapi field. --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index f7b626d28c..b0bd614c0d 100644 --- a/src/oas.md +++ b/src/oas.md @@ -94,7 +94,7 @@ In addition to the required fields, at least one of the `components`, `paths`, o | Field Name | Type | Description | | ---- | :----: | ---- | -| openapi | `string` | **REQUIRED**. This string MUST be the [version number](#versions-and-deprecation) of the OpenAPI Specification that the OpenAPI document uses. The `openapi` field SHOULD be used by tooling to interpret the OpenAPI document. This is _not_ related to the [`info.version`](#info-version) string, which describes the OpenAPI document's version. | +| openapi | `string` | **REQUIRED**. This string MUST be the major and minor [version number](#versions-and-deprecation) of the OpenAPI Specification that the OpenAPI Document uses (e.g. `"3.2"`), and MAY also contain the patch number (e.g. `"3.2.0"`), although this is NOT RECOMMENDED. The major and minor version numbers from the `openapi` field MUST be used by tooling to interpret the OpenAPI Document, while the patch number SHOULD be ignored. This field is _not_ related to the [`info.version`](#info-version) string, which describes the OpenAPI document's version. | | $self | `string` | This string MUST be in the form of a URI-reference as defined by [[RFC3986]] [Section 4.1](https://www.rfc-editor.org/rfc/rfc3986#section-4.1). The `$self` field provides the self-assigned URI of this document, which also serves as its base URI in accordance with [[RFC3986]] [Section 5.1.1](https://www.rfc-editor.org/rfc/rfc3986#section-5.1.1). Implementations MUST support identifying the targets of [API description URIs](#relative-references-in-api-description-uris) using the URI defined by this field when it is present. See [Establishing the Base URI](#establishing-the-base-uri) for the base URI behavior when `$self` is absent or relative, and see [Appendix F]((#appendix-f-examples-of-base-uri-determination-and-reference-resolution)) for examples of using `$self` to resolve references. | | info | [Info Object](#info-object) | **REQUIRED**. Provides metadata about the API. The metadata MAY be used by tooling as required. | | jsonSchemaDialect | `string` | The default value for the `$schema` keyword within [Schema Objects](#schema-object) contained within this OAS document. This MUST be in the form of a URI. | From bc19f18aa0583112d1b83c14e8b5d595effd35d3 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Mon, 8 Sep 2025 08:47:56 -0700 Subject: [PATCH 2/4] Schema and test coverage of openapi: X.Y Also remove what looked to be a part of the regex allowing for "-rcN" suffixes, which are not mentioned in the field definition at all. --- src/schemas/validation/schema.yaml | 2 +- tests/schema/pass/info-object-example.yaml | 2 +- tests/schema/pass/mega.yaml | 2 +- tests/schema/pass/minimal_comp.yaml | 2 +- tests/schema/pass/minimal_hooks.yaml | 2 +- tests/schema/pass/minimal_paths.yaml | 2 +- 6 files changed, 6 insertions(+), 6 deletions(-) diff --git a/src/schemas/validation/schema.yaml b/src/schemas/validation/schema.yaml index 0717e2632f..ec49f00da1 100644 --- a/src/schemas/validation/schema.yaml +++ b/src/schemas/validation/schema.yaml @@ -7,7 +7,7 @@ type: object properties: openapi: type: string - pattern: '^3\.2\.\d+(-.+)?$' + pattern: '^3\.2(\.\d+)?$' $self: type: string format: uri-reference diff --git a/tests/schema/pass/info-object-example.yaml b/tests/schema/pass/info-object-example.yaml index 1d36bef06c..eee4218368 100644 --- a/tests/schema/pass/info-object-example.yaml +++ b/tests/schema/pass/info-object-example.yaml @@ -1,5 +1,5 @@ # including External Documentation Object Example -openapi: 3.2.0 +openapi: "3.2" $self: https://example.com/openapi info: title: Example Pet Store App diff --git a/tests/schema/pass/mega.yaml b/tests/schema/pass/mega.yaml index 8304fbe199..2c302ff460 100644 --- a/tests/schema/pass/mega.yaml +++ b/tests/schema/pass/mega.yaml @@ -1,4 +1,4 @@ -openapi: 3.2.0 +openapi: "3.2" info: summary: My API's summary title: My API diff --git a/tests/schema/pass/minimal_comp.yaml b/tests/schema/pass/minimal_comp.yaml index 8f81f7e05e..3e0a119870 100644 --- a/tests/schema/pass/minimal_comp.yaml +++ b/tests/schema/pass/minimal_comp.yaml @@ -1,4 +1,4 @@ -openapi: 3.2.0 +openapi: "3.2" info: title: API version: 1.0.0 diff --git a/tests/schema/pass/minimal_hooks.yaml b/tests/schema/pass/minimal_hooks.yaml index 0e44257ad0..ac8bad6fb3 100644 --- a/tests/schema/pass/minimal_hooks.yaml +++ b/tests/schema/pass/minimal_hooks.yaml @@ -1,4 +1,4 @@ -openapi: 3.2.0 +openapi: "3.2" info: title: API version: 1.0.0 diff --git a/tests/schema/pass/minimal_paths.yaml b/tests/schema/pass/minimal_paths.yaml index c332bba18c..3994cb2f0d 100644 --- a/tests/schema/pass/minimal_paths.yaml +++ b/tests/schema/pass/minimal_paths.yaml @@ -1,4 +1,4 @@ -openapi: 3.2.0 +openapi: "3.2" info: title: API version: 1.0.0 From a590855f71664142e30d9fb3bb3bfc6bdc768f6b Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Mon, 8 Sep 2025 09:11:07 -0700 Subject: [PATCH 3/4] Feedback on wording. --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index b0bd614c0d..c246580a90 100644 --- a/src/oas.md +++ b/src/oas.md @@ -94,7 +94,7 @@ In addition to the required fields, at least one of the `components`, `paths`, o | Field Name | Type | Description | | ---- | :----: | ---- | -| openapi | `string` | **REQUIRED**. This string MUST be the major and minor [version number](#versions-and-deprecation) of the OpenAPI Specification that the OpenAPI Document uses (e.g. `"3.2"`), and MAY also contain the patch number (e.g. `"3.2.0"`), although this is NOT RECOMMENDED. The major and minor version numbers from the `openapi` field MUST be used by tooling to interpret the OpenAPI Document, while the patch number SHOULD be ignored. This field is _not_ related to the [`info.version`](#info-version) string, which describes the OpenAPI document's version. | +| openapi | `string` | **REQUIRED**. This string MUST be the major and minor [version number](#versions-and-deprecation) of the OpenAPI Specification that the OpenAPI Document uses (e.g. `"3.2"`), and MAY also contain the patch number (e.g. `"3.2.0"`). The major and minor version numbers from the `openapi` field MUST be used by tooling to interpret the OpenAPI Document, while the patch number SHOULD be ignored. This field is _not_ related to the [`info.version`](#info-version) string, which describes the OpenAPI document's version. | | $self | `string` | This string MUST be in the form of a URI-reference as defined by [[RFC3986]] [Section 4.1](https://www.rfc-editor.org/rfc/rfc3986#section-4.1). The `$self` field provides the self-assigned URI of this document, which also serves as its base URI in accordance with [[RFC3986]] [Section 5.1.1](https://www.rfc-editor.org/rfc/rfc3986#section-5.1.1). Implementations MUST support identifying the targets of [API description URIs](#relative-references-in-api-description-uris) using the URI defined by this field when it is present. See [Establishing the Base URI](#establishing-the-base-uri) for the base URI behavior when `$self` is absent or relative, and see [Appendix F]((#appendix-f-examples-of-base-uri-determination-and-reference-resolution)) for examples of using `$self` to resolve references. | | info | [Info Object](#info-object) | **REQUIRED**. Provides metadata about the API. The metadata MAY be used by tooling as required. | | jsonSchemaDialect | `string` | The default value for the `$schema` keyword within [Schema Objects](#schema-object) contained within this OAS document. This MUST be in the form of a URI. | From 554f7d21bf6669c093b6492d43159d0f77b29c52 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Tue, 9 Sep 2025 09:57:56 -0700 Subject: [PATCH 4/4] Fix merge error, keep lower-case "document" --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index c246580a90..698471ff84 100644 --- a/src/oas.md +++ b/src/oas.md @@ -94,7 +94,7 @@ In addition to the required fields, at least one of the `components`, `paths`, o | Field Name | Type | Description | | ---- | :----: | ---- | -| openapi | `string` | **REQUIRED**. This string MUST be the major and minor [version number](#versions-and-deprecation) of the OpenAPI Specification that the OpenAPI Document uses (e.g. `"3.2"`), and MAY also contain the patch number (e.g. `"3.2.0"`). The major and minor version numbers from the `openapi` field MUST be used by tooling to interpret the OpenAPI Document, while the patch number SHOULD be ignored. This field is _not_ related to the [`info.version`](#info-version) string, which describes the OpenAPI document's version. | +| openapi | `string` | **REQUIRED**. This string MUST be the major and minor [version number](#versions-and-deprecation) of the OpenAPI Specification that the OpenAPI document uses (e.g. `"3.2"`), and MAY also contain the patch number (e.g. `"3.2.0"`). The major and minor version numbers from the `openapi` field MUST be used by tooling to interpret the OpenAPI document, while the patch number SHOULD be ignored. This field is _not_ related to the [`info.version`](#info-version) string, which describes the OpenAPI document's version. | | $self | `string` | This string MUST be in the form of a URI-reference as defined by [[RFC3986]] [Section 4.1](https://www.rfc-editor.org/rfc/rfc3986#section-4.1). The `$self` field provides the self-assigned URI of this document, which also serves as its base URI in accordance with [[RFC3986]] [Section 5.1.1](https://www.rfc-editor.org/rfc/rfc3986#section-5.1.1). Implementations MUST support identifying the targets of [API description URIs](#relative-references-in-api-description-uris) using the URI defined by this field when it is present. See [Establishing the Base URI](#establishing-the-base-uri) for the base URI behavior when `$self` is absent or relative, and see [Appendix F]((#appendix-f-examples-of-base-uri-determination-and-reference-resolution)) for examples of using `$self` to resolve references. | | info | [Info Object](#info-object) | **REQUIRED**. Provides metadata about the API. The metadata MAY be used by tooling as required. | | jsonSchemaDialect | `string` | The default value for the `$schema` keyword within [Schema Objects](#schema-object) contained within this OAS document. This MUST be in the form of a URI. |