From 99a50e50d71128b64e1287824c7471155f6f9192 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Sat, 25 Jul 2026 13:44:10 -0700 Subject: [PATCH 1/4] First pass at explaining SAFs --- src/oas.md | 39 ++++++++++++++++++++++ src/schemas/validation/schema.yaml | 7 ++++ tests/schema/pass/info-object-example.yaml | 2 ++ 3 files changed, 48 insertions(+) diff --git a/src/oas.md b/src/oas.md index 788fcb205a..c57e46bb7e 100644 --- a/src/oas.md +++ b/src/oas.md @@ -28,6 +28,25 @@ At this time, such elements are expected to remain part of the OAS until the nex Occasionally, non-backwards compatible changes may be made in `minor` versions of the OAS where impact is believed to be low relative to the benefit provided. +### Standardized API Features + +Many API features have behavior that is difficult or impossible to infer from +descriptions of paths, parameters, headers, or other operation elements that +this specification supports. + +We refer to such features that are standardized by other standards bodies +as Standardized API Features, or SAFs. These features benefit from special +handling, such as how the `Authorization` header is managed through the +Security Scheme Object rather than the Parameter Object. Security features +also illustrate another aspect of SAFs, which is that they often evolve +at a more rapid pace than the core of HTTP. + +To better support security features and expand into other SAFs, the OpenAPI +Initiative is introducing companion specifications grouping independently +versioned SAFs. These specifications describe opt-in rules that establish +SAF-specific Objects as well as exception rules such as those regarding +the `Authorization` header and Security Schemes. + ### Undefined and Implementation-Defined Behavior This specification deems certain situations to have either _undefined_ or _implementation-defined_ behavior. @@ -95,6 +114,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. | +| usingFeatures | Map[`string`, `string`] | A map of [SAF](#standardized-api-features) names, as defined in various companion specifications, to a valid version string for the named SAF. Implementations MUST apply the SAF's rules, such as treating header parameters that are managed by the SAF as illegal in Parameter Objects, while processing the current document. The default is `{"legacySecurity": "3.3.0"}`. | | $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. See [JSON Schema Keywords](#json-schema-keywords) to determine the default value. | @@ -127,6 +147,25 @@ It is RECOMMENDED that the entry document of an OAD be named `openapi.json` or ` An OpenAPI Object MAY be embedded in another format, called the **embedding format**, just as JSON Schema is embedded in the OAS in the form of Schema Objects. It is the responsibility of an embedding format to define how to parse embedded content, and OAS implementations that do not document support for an embedding format cannot be expected to parse embedded OAS content correctly. +##### OpenAPI and SAF Versions Across Multiple Documents + +The `openapi` and `usingFeatures` fields define how the document that contains +them is to be parsed. When using multiple documents in an OAD, interoperability +is only guaranteed if the SAFs in `usingFeatures` are the same in all +documents, and the major and minor version numbers for `openapi` and each +SAF in `usingFeatures` match. + +Implementations MUST raise an error if different SAFs are included in +different documents within the OAD, and SHOULD raise an error if any +SAF or `openapi` version in a referenced document is not compatible +with the corresponding version in the entry document. Implementations +MAY raise an error if the major and minor versions are compatible but +not the same; otherise the behavior is implementation-defined. + +Only the major and minor version numbers determine compatibility. +However, note that while OAS v3.1 is compatible with v3.2, which is compatible +with v3.3, OAS 3.0 is not compatible with any other version. + ##### Parsing Documents Each document in an OAD MUST be fully parsed in order to locate possible reference targets. diff --git a/src/schemas/validation/schema.yaml b/src/schemas/validation/schema.yaml index f5a23171e2..1025994a45 100644 --- a/src/schemas/validation/schema.yaml +++ b/src/schemas/validation/schema.yaml @@ -8,6 +8,13 @@ properties: openapi: type: string pattern: '^3\.3\.[0-9]+(-.+)?$' + usingFeatures: + type: object + additionalProperties: + type: string + pattern: '^\d\.\d\.\d' + default: + legacySecurity: '3.3.0' $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 aebef5cb04..ae1f7e5d29 100644 --- a/tests/schema/pass/info-object-example.yaml +++ b/tests/schema/pass/info-object-example.yaml @@ -1,5 +1,7 @@ # including External Documentation Object Example openapi: 3.3.0 +usingFeatures: + legacySecurity: 3.3.0 $self: https://example.com/openapi info: title: Example Pet Store App From fa98b58c8b71a485b70b75a09acd1987fb38c478 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Wed, 7 Oct 2026 13:48:11 -0700 Subject: [PATCH 2/4] Explain usingSafs defaults, give example. --- src/oas.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index c57e46bb7e..f98aec0ef2 100644 --- a/src/oas.md +++ b/src/oas.md @@ -114,7 +114,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. | -| usingFeatures | Map[`string`, `string`] | A map of [SAF](#standardized-api-features) names, as defined in various companion specifications, to a valid version string for the named SAF. Implementations MUST apply the SAF's rules, such as treating header parameters that are managed by the SAF as illegal in Parameter Objects, while processing the current document. The default is `{"legacySecurity": "3.3.0"}`. | +| usingFeatures | Map[`string`, `string`] | A map of [SAF](#standardized-api-features) names, as defined in various companion specifications, to a valid version string for the named SAF. Implementations MUST apply the SAF's rules, such as treating header parameters that are managed by the SAF as illegal in Parameter Objects, while processing the current document. The default is `{"legacySecurity": "3.3.0"}` (see below). | | $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. See [JSON Schema Keywords](#json-schema-keywords) to determine the default value. | @@ -128,6 +128,9 @@ In addition to the required fields, at least one of the `components`, `paths`, o This object MAY be extended with [Specification Extensions](#specification-extensions). +The default value for `usingFeatures` preserves compatible behavior for the +[Security Scheme](#security-scheme-object), [OAuth Flows](#oauth-flows-object), [OAuth Flow](#oauth-flow-object), and [Security Requirement](#security-requirement-object) Objects. + To ensure interoperability, references MUST use the target document's `$self` URI if the `$self` field is present. Implementations MAY choose to support referencing by other URIs such as the retrieval URI even when `$self` is present, however this behavior is not interoperable and relying on it is NOT RECOMMENDED. @@ -166,6 +169,19 @@ Only the major and minor version numbers determine compatibility. However, note that while OAS v3.1 is compatible with v3.2, which is compatible with v3.3, OAS 3.0 is not compatible with any other version. +In this example, the `legacySecurity` SAF from the OAS Security Specification +and the `deprecation` SAF from the OAS Lifecycle Specification are being +used. Note that while `legacySecurity: 3.3.0` is the default value for the +`usingFeatures` field, if an explicit value is given for the field, the +`legacySecurity` SAF MUST be explicitly specified for it to be used. + +```yaml +openapi: 3.3.0 +usingFeatures: + legacySecurity: 3.3.0 + deprecation: 1.0.0 +``` + ##### Parsing Documents Each document in an OAD MUST be fully parsed in order to locate possible reference targets. From 17cbc3a09fa2e8e11660f7e95a5df40cc93c433a Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Wed, 14 Oct 2026 17:07:47 -0700 Subject: [PATCH 3/4] Update for specification granularity versioning. --- src/oas.md | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/src/oas.md b/src/oas.md index f98aec0ef2..e66aa5b715 100644 --- a/src/oas.md +++ b/src/oas.md @@ -42,10 +42,10 @@ also illustrate another aspect of SAFs, which is that they often evolve at a more rapid pace than the core of HTTP. To better support security features and expand into other SAFs, the OpenAPI -Initiative is introducing companion specifications grouping independently -versioned SAFs. These specifications describe opt-in rules that establish -SAF-specific Objects as well as exception rules such as those regarding -the `Authorization` header and Security Schemes. +Initiative is introducing companion specifications that are versioned +independently of this specification. These new specifications describe +opt-in rules that establish SAF-specific Objects, as well as exception rules +such as those regarding the `Authorization` header and Security Schemes. ### Undefined and Implementation-Defined Behavior @@ -114,7 +114,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. | -| usingFeatures | Map[`string`, `string`] | A map of [SAF](#standardized-api-features) names, as defined in various companion specifications, to a valid version string for the named SAF. Implementations MUST apply the SAF's rules, such as treating header parameters that are managed by the SAF as illegal in Parameter Objects, while processing the current document. The default is `{"legacySecurity": "3.3.0"}` (see below). | +| featureVersions | Map[`string`, `string`] | A map of [SAF](#standardized-api-features) specification names, as defined in various companion specifications, to a valid version string for the named specification. Implementations MUST apply the SAF specification's rules, such as treating header parameters that are managed by the SAF as illegal in Parameter Objects, while processing the current document. The default is `{"security": "1.0.0"}` (see below). | | $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. See [JSON Schema Keywords](#json-schema-keywords) to determine the default value. | @@ -128,7 +128,7 @@ In addition to the required fields, at least one of the `components`, `paths`, o This object MAY be extended with [Specification Extensions](#specification-extensions). -The default value for `usingFeatures` preserves compatible behavior for the +The default value for `featureVersions` preserves compatible behavior for the [Security Scheme](#security-scheme-object), [OAuth Flows](#oauth-flows-object), [OAuth Flow](#oauth-flow-object), and [Security Requirement](#security-requirement-object) Objects. To ensure interoperability, references MUST use the target document's `$self` URI if the `$self` field is present. @@ -150,13 +150,13 @@ It is RECOMMENDED that the entry document of an OAD be named `openapi.json` or ` An OpenAPI Object MAY be embedded in another format, called the **embedding format**, just as JSON Schema is embedded in the OAS in the form of Schema Objects. It is the responsibility of an embedding format to define how to parse embedded content, and OAS implementations that do not document support for an embedding format cannot be expected to parse embedded OAS content correctly. -##### OpenAPI and SAF Versions Across Multiple Documents +##### OpenAPI and SAF Specification Versions Across Multiple Documents -The `openapi` and `usingFeatures` fields define how the document that contains +The `openapi` and `featureVersions` fields define how the document that contains them is to be parsed. When using multiple documents in an OAD, interoperability -is only guaranteed if the SAFs in `usingFeatures` are the same in all -documents, and the major and minor version numbers for `openapi` and each -SAF in `usingFeatures` match. +is only guaranteed if the SAF specification versions in `featureVersions` +are the same in all documents, and the major and minor version numbers for +`openapi` and each SAF in `featureVersions` match. Implementations MUST raise an error if different SAFs are included in different documents within the OAD, and SHOULD raise an error if any @@ -169,17 +169,17 @@ Only the major and minor version numbers determine compatibility. However, note that while OAS v3.1 is compatible with v3.2, which is compatible with v3.3, OAS 3.0 is not compatible with any other version. -In this example, the `legacySecurity` SAF from the OAS Security Specification -and the `deprecation` SAF from the OAS Lifecycle Specification are being -used. Note that while `legacySecurity: 3.3.0` is the default value for the -`usingFeatures` field, if an explicit value is given for the field, the -`legacySecurity` SAF MUST be explicitly specified for it to be used. +In this example, the the OAS Security Specification (`security`) +and the OAS Lifecycle Specification (`lifecycle`) are being used. +Note that while `security: 1.0.0` is the default value for the +`featureVersions` field, if an explicit value is given for the field, then +`security: 1.0.0` MUST be explicitly specified for it to be used. ```yaml openapi: 3.3.0 -usingFeatures: - legacySecurity: 3.3.0 - deprecation: 1.0.0 +featureVersions: + security: 1.0.0 + deprecation: 1.1.0 ``` ##### Parsing Documents From 5c0fbb5b78db33182ca11460bbd6c14997563249 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Thu, 15 Oct 2026 09:50:56 -0700 Subject: [PATCH 4/4] Minor fixes --- src/oas.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/src/oas.md b/src/oas.md index e66aa5b715..b7917cdf60 100644 --- a/src/oas.md +++ b/src/oas.md @@ -114,7 +114,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. | -| featureVersions | Map[`string`, `string`] | A map of [SAF](#standardized-api-features) specification names, as defined in various companion specifications, to a valid version string for the named specification. Implementations MUST apply the SAF specification's rules, such as treating header parameters that are managed by the SAF as illegal in Parameter Objects, while processing the current document. The default is `{"security": "1.0.0"}` (see below). | +| featureVersions | Map[`string`, `string`] | A map of [SAF](#standardized-api-features) specification names, as defined in various companion specifications, to a valid version string for the named specification. Implementations MUST apply the SAF specification's rules, such as treating header parameters that are managed by the SAF specifications as illegal in Parameter Objects, while processing the current document. The default is `{"security": "1.0.0"}` (see below). | | $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. See [JSON Schema Keywords](#json-schema-keywords) to determine the default value. | @@ -156,14 +156,15 @@ The `openapi` and `featureVersions` fields define how the document that contains them is to be parsed. When using multiple documents in an OAD, interoperability is only guaranteed if the SAF specification versions in `featureVersions` are the same in all documents, and the major and minor version numbers for -`openapi` and each SAF in `featureVersions` match. +`openapi` and each SAF specification in `featureVersions` match. Implementations MUST raise an error if different SAFs are included in different documents within the OAD, and SHOULD raise an error if any -SAF or `openapi` version in a referenced document is not compatible +SAF specification version or `openapi` version in a referenced document +is not compatible with the corresponding version in the entry document. Implementations MAY raise an error if the major and minor versions are compatible but -not the same; otherise the behavior is implementation-defined. +not the same; otherwise the behavior is implementation-defined. Only the major and minor version numbers determine compatibility. However, note that while OAS v3.1 is compatible with v3.2, which is compatible