diff --git a/src/oas.md b/src/oas.md index 788fcb205a..4948790dba 100644 --- a/src/oas.md +++ b/src/oas.md @@ -28,6 +28,26 @@ 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 + +Standardized API Features (SAFs) are features defined by other standards +bodies and referred to from an OpenAPI Description. SAFs are defined for +use with OpenAPI in companion specifications, which are versioned independently +of this specification. A companion specification describes opt-in rules for +SAF-specific Objects, and can also define exceptions to the rules of this +specification. + +Many SAFs have behavior that is difficult or impossible to infer from +descriptions of paths, parameters, headers, or other operation elements, +and so benefit from special handling. For example, the Authorization header +is managed through the Security Scheme Object rather than the Parameter Object. + +Defining SAFs separately keeps this specification focused: an OpenAPI +Description uses only the companion specifications it needs, and tools can +state which ones they support. Independent versioning also lets companion +specifications keep pace with SAFs that evolve faster than HTTP or this +specification. + ### Undefined and Implementation-Defined Behavior This specification deems certain situations to have either _undefined_ or _implementation-defined_ behavior. @@ -95,6 +115,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. | +| features | 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 the security SAF's rule that the `Authorization` header MUST be ignored in a Parameter Object, 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. | @@ -108,6 +129,11 @@ 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 `features` preserves compatibility with OAS 3.2 +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. @@ -127,6 +153,39 @@ 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 Specification Versions Across Multiple Documents + +The `openapi` and `features` 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 `features` +are the same in all documents, and the major and minor version numbers for +`openapi` and each SAF specification in `features` 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 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; 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 +with v3.3, OAS 3.0 is not compatible with any other version. + +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 +`features` 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 +features: + security: 1.0.0 + lifecycle: 1.1.0 +``` + ##### 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..71d54ec9c6 100644 --- a/src/schemas/validation/schema.yaml +++ b/src/schemas/validation/schema.yaml @@ -8,6 +8,16 @@ properties: openapi: type: string pattern: '^3\.3\.[0-9]+(-.+)?$' + features: + type: object + propertyNames: + type: string + pattern: '^[A-Za-z][A-Za-z0-9_]*$' + additionalProperties: + type: string + pattern: '^[0-9]+\.[0-9]+\.[0-9]+$' + default: + security: '1.1.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..08abe70a0b 100644 --- a/tests/schema/pass/info-object-example.yaml +++ b/tests/schema/pass/info-object-example.yaml @@ -1,5 +1,8 @@ # including External Documentation Object Example openapi: 3.3.0 +features: + security: 1.0.0 + lifecycle: 1.1.0 $self: https://example.com/openapi info: title: Example Pet Store App