From 2ce3cfecb7bb6537774b564e8c73b62a0fdc9fe6 Mon Sep 17 00:00:00 2001 From: Mike Kistler Date: Tue, 17 Sep 2024 06:33:47 -0500 Subject: [PATCH 01/11] Fix description vs document terminology --- versions/3.1.1.md | 55 ++++++++++++++++++++++++----------------------- 1 file changed, 28 insertions(+), 27 deletions(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 5995be5365..9042fe50a8 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -10,7 +10,7 @@ This document is licensed under [The Apache License, Version 2.0](https://www.ap The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to HTTP APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. -An OpenAPI description can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases. +An OpenAPI Description can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases. For examples of OpenAPI usage and additional documentation, please visit [[?OpenAPI-Learn]]. @@ -91,11 +91,11 @@ The OpenAPI Specification is versioned using a `major`.`minor`.`patch` versionin 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. -An OpenAPI description document compatible with OAS 3.\*.\* contains a required [`openapi`](#oas-version) field which designates the version of the OAS that it uses. +An OpenAPI Description compatible with OAS 3.\*.\* contains a required [`openapi`](#oas-version) field which designates the version of the OAS that it uses. ### Format -An OpenAPI description document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format. +An OpenAPI Description that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format. For example, if a field has an array value, the JSON array representation will be used: @@ -117,18 +117,15 @@ In order to preserve the ability to round-trip between YAML and JSON formats, YA * Tags MUST be limited to those allowed by [YAML's JSON schema ruleset](https://yaml.org/spec/1.2/spec.html#id2803231), which defines a subset of the YAML syntax and is unrelated to [[JSON-Schema-2020-12|JSON Schema]]. * Keys used in YAML maps MUST be limited to a scalar string, as defined by the [YAML Failsafe schema ruleset](https://yaml.org/spec/1.2/spec.html#id2802346). -**Note:** While APIs may be described by OpenAPI documents in either YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML. +**Note:** While APIs may be described by OpenAPI Description in either YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML. ### OpenAPI Description Structure -An OpenAPI Description (OAD) MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the author. In the latter case, [Reference Object](#reference-object), [Path Item Object](#path-item-object) and [Schema Object](#schema-object) `$ref` keywords, as well as the [Link Object](#link-object) `operationRef` keyword, are used. +An OpenAPI Description (OAD) MAY be structured as a single JSON or YAML document or composed from elements distributed across multiple documents at the discretion of the author. In the latter case, [Reference Object](#reference-object), [Path Item Object](#path-item-object) and [Schema Object](#schema-object) `$ref` keywords, as well as the [Link Object](#link-object) `operationRef` keyword, are used. -Any document consisting entirely of an [OpenAPI Object](#openapi-object) is known as a **syntactically complete OpenAPI document**. -An OpenAPI document that does _not_ reference any other documents is known as a **self-contained OpenAPI document**. -A single-document description is therefore _both_ syntactically complete _and_ self-contained. -In a multi-document description, the document containing the OpenAPI Object where parsing begins for a specific API's description is known as that API's **entry OpenAPI document**, or simply **entry document**. +In a multi-document OAD, the document containing the OpenAPI Object where parsing begins is known as that OAD's **entry document**. -It is RECOMMENDED that the entry OpenAPI document be named: `openapi.json` or `openapi.yaml`. +It is RECOMMENDED that the entry document of an OAD be named: `openapi.json` or `openapi.yaml`. #### Parsing Documents @@ -157,10 +154,10 @@ It is the responsibility of an embedding format to define how to parse embedded #### Structural Interoperability -When parsing an OAD, JSON or YAML objects are parsed into specific Objects (such as [Operation Objects](#operation-object), [Response Objects](#response-object), [Reference Objects](#reference-object), etc.) based on the parsing context. Depending on how references are arranged, a given JSON or YAML object can be parsed in multiple different contexts: +JSON or YAML objects within an OAD are interpreted as specific Objects (such as [Operation Objects](#operation-object), [Response Objects](#response-object), [Reference Objects](#reference-object), etc.) based on their context. Depending on how references are arranged, a given JSON or YAML object can be interpreted in multiple different contexts: -* As a syntactically complete OpenAPI Description document -* As the Object type implied by its parent Object within the document +* The root object of the entry document is interpreted as an OpenAPI Object +* As the Object type implied by its parent Object within the description * As a reference target, with the Object type matching the reference source's context If the same JSON/YAML object is parsed multiple times and the respective contexts require it to be parsed as _different_ Object types, the resulting behavior is _implementation defined_, and MAY be treated as an error if detected. An example would be referencing an empty Schema Object under `#/components/schemas` where a Path Item Object is expected, as an empty object is valid for both types. For maximum interoperability, it is RECOMMENDED that OpenAPI Description authors avoid such scenarios. @@ -316,13 +313,13 @@ In the following description, if a field is not explicitly **REQUIRED** or descr #### OpenAPI Object -This is the root object of the [OpenAPI document](#openapi-description). +This is the root object of the [OpenAPI Description](#openapi-description). ##### Fixed Fields | Field Name | Type | Description | | ---- | :----: | ---- | -| openapi | `string` | **REQUIRED**. This string MUST be the [version number](#versions) 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 API [`info.version`](#info-version) string. | +| openapi | `string` | **REQUIRED**. This string MUST be the [version number](#versions) of the OpenAPI Specification that the OpenAPI Description uses. The `openapi` field SHOULD be used by tooling to interpret the OpenAPI Description. This is _not_ related to the API [`info.version`](#info-version) string. | | 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. | | servers | [[Server Object](#server-object)] | An array of Server Objects, which provide connectivity information to a target server. If the `servers` field is not provided, or is an empty array, the default value would be a [Server Object](#server-object) with a [url](#server-url) value of `/`. | @@ -350,7 +347,7 @@ The metadata MAY be used by the clients if needed, and MAY be presented in editi | termsOfService | `string` | A URI for the Terms of Service for the API. This MUST be in the form of a URI. | | contact | [Contact Object](#contact-object) | The contact information for the exposed API. | | license | [License Object](#license-object) | The license information for the exposed API. | -| version | `string` | **REQUIRED**. The version of the OpenAPI document (which is distinct from the [OpenAPI Specification version](#oas-version) or the version of the API being described). | +| version | `string` | **REQUIRED**. The version of the OpenAPI Description (which is distinct from the [OpenAPI Specification version](#oas-version) or the version of the API being described). | This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -456,7 +453,7 @@ An object representing a Server. | Field Name | Type | Description | | ---- | :----: | ---- | -| url | `string` | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in `{`braces`}`. | +| url | `string` | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the entry document of the OpenAPI Description is being served. Variable substitutions will be made when a variable is named in `{`braces`}`. | | description | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. | | variables | Map[`string`, [Server Variable Object](#server-variable-object)] | A map between a variable name and its value. The value is used for substitution in the server's URL template. | @@ -2227,7 +2224,7 @@ Because examples using these fields represent the final serialized form of the d The singular `example` field in the Parameter or Media Type Object is concise and convenient for simple examples, but does not offer any other advantages over using Example Objects under `examples`. Some examples cannot be represented directly in JSON or YAML. -For all three ways of providing examples, these can be shown as string values with any escaping necessary to make the string valid in the JSON or YAML format of the OpenAPI Description document. +For all three ways of providing examples, these can be shown as string values with any escaping necessary to make the string valid in the JSON or YAML format of the OpenAPI Description. With the Example Object, such values can alternatively be handled through the `externalValue` field. ##### Example Object Examples @@ -2667,7 +2664,7 @@ description: Pets operations #### Reference Object -A simple object to allow referencing other components in the OpenAPI document, internally and externally. +A simple object to allow referencing other components in the OpenAPI Description, internally and externally. The `$ref` string value contains a URI [RFC3986](https://tools.ietf.org/html/rfc3986), which identifies the value being referenced. @@ -3322,7 +3319,7 @@ However, the exact nature of such conversions are implementation-defined. ##### Examples -For these examples, assume all schemas are in the entry OpenAPI document; for handling of `discriminator` in referenced documents see [Resolving Implicit Connections](#resolving-implicit-connections). +For these examples, assume all schemas are in a single-document OpenAPI Description; for handling of `discriminator` in referenced documents see [Resolving Implicit Connections](#resolving-implicit-connections). In OAS 3.x, a response payload MAY be described to be exactly one of any number of types: @@ -3346,7 +3343,7 @@ MyResponseType: propertyName: petType ``` -The expectation now is that a property with name `petType` _MUST_ be present in the response payload, and the value will correspond to the name of a schema defined in the OpenAPI description. Thus the response payload: +The expectation now is that a property with name `petType` _MUST_ be present in the response payload, and the value will correspond to the name of a schema defined in the OpenAPI Description. Thus the response payload: ```json { @@ -4065,7 +4062,7 @@ The extensions properties are implemented as patterned fields that are always pr The OpenAPI Initiative maintains several [[OpenAPI-Registry|extension registries]], including registries for [individual extension keywords](https://spec.openapis.org/registry/extension/) and [extension keyword namespaces](https://spec.openapis.org/registry/namespace/). -Extensions are one of the best ways to prove the viability of proposed additions to the specification. +Extensions are one of the best ways to prove the viability of proposed additions to the specification. It is therefore RECOMMENDED that implementations be designed for extensibility to support community experimentation. Support for any one extension is OPTIONAL, and support for one extension does not imply support for others. @@ -4084,9 +4081,9 @@ Two examples of this: ## Security Considerations -### OpenAPI Document Formats +### OpenAPI Description Formats -OpenAPI description documents use JSON, YAML, and JSON Schema, and therefore share their security considerations: +OpenAPI Descriptions use JSON, YAML, and JSON Schema, and therefore share their security considerations: * [JSON](https://www.iana.org/assignments/media-types/application/json) * [YAML](https://www.iana.org/assignments/media-types/application/yaml) @@ -4095,15 +4092,19 @@ OpenAPI description documents use JSON, YAML, and JSON Schema, and therefore sha ### Tooling and Usage Scenarios -In addition, OpenAPI description documents are processed by a wide variety of tooling for numerous different purposes, such as client code generation, documentation generation, server side routing, and API testing. OpenAPI description authors must consider the risks of the scenarios where the OpenAPI description may be used. +In addition, OpenAPI Descriptions are processed by a wide variety of tooling for numerous different purposes, such as client code generation, documentation generation, server side routing, and API testing. OpenAPI Description authors must consider the risks of the scenarios where the OpenAPI Description may be used. ### Security Schemes -An OpenAPI description describes the security schemes used to protect the resources it defines. The security schemes available offer varying degrees of protection. Factors such as the sensitivity of the data and the potential impact of a security breach should guide the selection of security schemes for the API resources. Some security schemes, such as basic auth and OAuth Implicit flow, are supported for compatibility with existing APIs. However, their inclusion in OpenAPI does not constitute an endorsement of their use, particularly for highly sensitive data or operations. +An OpenAPI Description describes the security schemes used to protect the resources it defines. The security schemes available offer varying degrees of protection. Factors such as the sensitivity of the data and the potential impact of a security breach should guide the selection of security schemes for the API resources. Some security schemes, such as basic auth and OAuth Implicit flow, are supported for compatibility with existing APIs. However, their inclusion in OpenAPI does not constitute an endorsement of their use, particularly for highly sensitive data or operations. ### Handling External Resources -OpenAPI description documents may contain references to external resources that may be dereferenced automatically by consuming tools. External resources may be hosted on different domains that may be untrusted. References in an OpenAPI document, or across OpenAPI documents within a multi-document OpenAPI description, may cause a cycle. Tooling must detect and handle cycles to prevent resource exhaustion. +OpenAPI Descriptions may contain references to external resources that may be dereferenced automatically by consuming tools. External resources may be hosted on different domains that may be untrusted. + +### Handling Reference Cycles + +References in an OpenAPI Description may cause a cycle. Tooling must detect and handle cycles to prevent resource exhaustion. ### Markdown and HTML Sanitization From 56d4d23e28ec63f37b5d7aa475b2180197e2b933 Mon Sep 17 00:00:00 2001 From: Mike Kistler Date: Tue, 17 Sep 2024 07:48:14 -0500 Subject: [PATCH 02/11] Apply suggestions from PR review Co-authored-by: Ralf Handl --- versions/3.1.1.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 9042fe50a8..1dd75de65b 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -117,7 +117,7 @@ In order to preserve the ability to round-trip between YAML and JSON formats, YA * Tags MUST be limited to those allowed by [YAML's JSON schema ruleset](https://yaml.org/spec/1.2/spec.html#id2803231), which defines a subset of the YAML syntax and is unrelated to [[JSON-Schema-2020-12|JSON Schema]]. * Keys used in YAML maps MUST be limited to a scalar string, as defined by the [YAML Failsafe schema ruleset](https://yaml.org/spec/1.2/spec.html#id2802346). -**Note:** While APIs may be described by OpenAPI Description in either YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML. +**Note:** While APIs may be described by OpenAPI Descriptions in either YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML. ### OpenAPI Description Structure @@ -157,7 +157,7 @@ It is the responsibility of an embedding format to define how to parse embedded JSON or YAML objects within an OAD are interpreted as specific Objects (such as [Operation Objects](#operation-object), [Response Objects](#response-object), [Reference Objects](#reference-object), etc.) based on their context. Depending on how references are arranged, a given JSON or YAML object can be interpreted in multiple different contexts: * The root object of the entry document is interpreted as an OpenAPI Object -* As the Object type implied by its parent Object within the description +* As the Object type implied by its parent Object within the OpenAPI Description * As a reference target, with the Object type matching the reference source's context If the same JSON/YAML object is parsed multiple times and the respective contexts require it to be parsed as _different_ Object types, the resulting behavior is _implementation defined_, and MAY be treated as an error if detected. An example would be referencing an empty Schema Object under `#/components/schemas` where a Path Item Object is expected, as an empty object is valid for both types. For maximum interoperability, it is RECOMMENDED that OpenAPI Description authors avoid such scenarios. From e17eb202ff86e33c71d675af90337f924460c4bb Mon Sep 17 00:00:00 2001 From: Mike Kistler Date: Tue, 17 Sep 2024 08:06:20 -0500 Subject: [PATCH 03/11] Commit suggestions from PR review. Co-authored-by: Ralf Handl --- versions/3.1.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 1dd75de65b..d23983eeeb 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -4083,7 +4083,7 @@ Two examples of this: ### OpenAPI Description Formats -OpenAPI Descriptions use JSON, YAML, and JSON Schema, and therefore share their security considerations: +OpenAPI Descriptions use a combination of JSON, YAML, and JSON Schema, and therefore share their security considerations: * [JSON](https://www.iana.org/assignments/media-types/application/json) * [YAML](https://www.iana.org/assignments/media-types/application/yaml) From 65a9e486ce1c6e6814baa53afe46052427d8df85 Mon Sep 17 00:00:00 2001 From: Mike Kistler Date: Thu, 3 Oct 2024 14:27:43 -0500 Subject: [PATCH 04/11] Updates based on TDC Meeting --- versions/3.1.1.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index d23983eeeb..11367e8973 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -22,6 +22,10 @@ For extension registries and other specifications published by the OpenAPI Initi An OpenAPI Description (OAD) formally describes the surface of an API and its semantics. It is composed of an [entry document](#openapi-description-structure) and any/all of its referenced documents. An OAD uses and conforms to the OpenAPI Specification, and MUST contain at least one [paths](#paths-object) field, [components](#oas-components) field, or [webhooks](#oas-webhooks) field. +### OpenAPI Document + +An OpenAPI Document is a single JSON or YAML document that conforms to the OpenAPI Specification. + ### Schema A "schema" is a formal description of syntax and structure. @@ -91,11 +95,11 @@ The OpenAPI Specification is versioned using a `major`.`minor`.`patch` versionin 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. -An OpenAPI Description compatible with OAS 3.\*.\* contains a required [`openapi`](#oas-version) field which designates the version of the OAS that it uses. +An OpenAPI Document compatible with OAS 3.\*.\* contains a required [`openapi`](#oas-version) field which designates the version of the OAS that it uses. ### Format -An OpenAPI Description that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format. +An OpenAPI Document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format. For example, if a field has an array value, the JSON array representation will be used: @@ -121,7 +125,7 @@ In order to preserve the ability to round-trip between YAML and JSON formats, YA ### OpenAPI Description Structure -An OpenAPI Description (OAD) MAY be structured as a single JSON or YAML document or composed from elements distributed across multiple documents at the discretion of the author. In the latter case, [Reference Object](#reference-object), [Path Item Object](#path-item-object) and [Schema Object](#schema-object) `$ref` keywords, as well as the [Link Object](#link-object) `operationRef` keyword, are used. +An OpenAPI Description (OAD) MAY be made up of a single JSON or YAML document or be divided into multiple, connected parts at the discretion of the author. In the latter case, [Reference Object](#reference-object), [Path Item Object](#path-item-object) and [Schema Object](#schema-object) `$ref` keywords, as well as the [Link Object](#link-object) `operationRef` keyword, are used. In a multi-document OAD, the document containing the OpenAPI Object where parsing begins is known as that OAD's **entry document**. @@ -156,7 +160,7 @@ It is the responsibility of an embedding format to define how to parse embedded JSON or YAML objects within an OAD are interpreted as specific Objects (such as [Operation Objects](#operation-object), [Response Objects](#response-object), [Reference Objects](#reference-object), etc.) based on their context. Depending on how references are arranged, a given JSON or YAML object can be interpreted in multiple different contexts: -* The root object of the entry document is interpreted as an OpenAPI Object +* As the root object of the [entry document](#openapi-description-structure), which is always interpreted as an OpenAPI Object * As the Object type implied by its parent Object within the OpenAPI Description * As a reference target, with the Object type matching the reference source's context @@ -319,7 +323,7 @@ This is the root object of the [OpenAPI Description](#openapi-description). | Field Name | Type | Description | | ---- | :----: | ---- | -| openapi | `string` | **REQUIRED**. This string MUST be the [version number](#versions) of the OpenAPI Specification that the OpenAPI Description uses. The `openapi` field SHOULD be used by tooling to interpret the OpenAPI Description. This is _not_ related to the API [`info.version`](#info-version) string. | +| openapi | `string` | **REQUIRED**. This string MUST be the [version number](#versions) 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 API [`info.version`](#info-version) string. | | 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. | | servers | [[Server Object](#server-object)] | An array of Server Objects, which provide connectivity information to a target server. If the `servers` field is not provided, or is an empty array, the default value would be a [Server Object](#server-object) with a [url](#server-url) value of `/`. | @@ -347,7 +351,7 @@ The metadata MAY be used by the clients if needed, and MAY be presented in editi | termsOfService | `string` | A URI for the Terms of Service for the API. This MUST be in the form of a URI. | | contact | [Contact Object](#contact-object) | The contact information for the exposed API. | | license | [License Object](#license-object) | The license information for the exposed API. | -| version | `string` | **REQUIRED**. The version of the OpenAPI Description (which is distinct from the [OpenAPI Specification version](#oas-version) or the version of the API being described). | +| version | `string` | **REQUIRED**. The version of the OpenAPI Document (which is distinct from the [OpenAPI Specification version](#oas-version) or the version of the API being described or the version of the OpenAPI Description). | This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -3319,7 +3323,7 @@ However, the exact nature of such conversions are implementation-defined. ##### Examples -For these examples, assume all schemas are in a single-document OpenAPI Description; for handling of `discriminator` in referenced documents see [Resolving Implicit Connections](#resolving-implicit-connections). +For these examples, assume all schemas are in the [entry document](#openapi-description-structure) of the OAD; for handling of `discriminator` in referenced documents see [Resolving Implicit Connections](#resolving-implicit-connections). In OAS 3.x, a response payload MAY be described to be exactly one of any number of types: From 4753b040f9b3e310b19b483aeb046a39bb18cdda Mon Sep 17 00:00:00 2001 From: Mike Kistler Date: Wed, 2 Oct 2024 07:10:23 -0500 Subject: [PATCH 05/11] A few more document -> description changes --- versions/3.1.1.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 11367e8973..aabd1c6d78 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -329,9 +329,9 @@ This is the root object of the [OpenAPI Description](#openapi-description). | servers | [[Server Object](#server-object)] | An array of Server Objects, which provide connectivity information to a target server. If the `servers` field is not provided, or is an empty array, the default value would be a [Server Object](#server-object) with a [url](#server-url) value of `/`. | | paths | [Paths Object](#paths-object) | The available paths and operations for the API. | | webhooks | Map[`string`, [Path Item Object](#path-item-object)] | The incoming webhooks that MAY be received as part of this API and that the API consumer MAY choose to implement. Closely related to the `callbacks` feature, this section describes requests initiated other than by an API call, for example by an out of band registration. The key name is a unique string to refer to each webhook, while the (optionally referenced) Path Item Object describes a request that may be initiated by the API provider and the expected responses. An [example](https://learn.openapis.org/examples/v3.1/webhook-example.html) is available. | -| components | [Components Object](#components-object) | An element to hold various schemas for the document. | +| components | [Components Object](#components-object) | An element to hold various schemas for the description. | | security | [[Security Requirement Object](#security-requirement-object)] | A declaration of which security mechanisms can be used across the API. The list of values includes alternative Security Requirement Objects that can be used. Only one of the Security Requirement Objects need to be satisfied to authorize a request. Individual operations can override this definition. The list can be incomplete, up to being empty or absent. To make security explicitly optional, an empty security requirement (`{}`) can be included in the array. | -| tags | [[Tag Object](#tag-object)] | A list of tags used by the document with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operation-object) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique. | +| tags | [[Tag Object](#tag-object)] | A list of tags used by the description with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operation-object) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique. | | externalDocs | [External Documentation Object](#external-documentation-object) | Additional external documentation. | This object MAY be extended with [Specification Extensions](#specification-extensions). From 3adc6da4b8201d9e8821f454d24c9b337893948e Mon Sep 17 00:00:00 2001 From: Mike Kistler Date: Fri, 4 Oct 2024 06:53:26 -0500 Subject: [PATCH 06/11] Address more PR review comments --- versions/3.1.1.md | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index aabd1c6d78..2937cc82dd 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -20,11 +20,11 @@ For extension registries and other specifications published by the OpenAPI Initi ### OpenAPI Description -An OpenAPI Description (OAD) formally describes the surface of an API and its semantics. It is composed of an [entry document](#openapi-description-structure) and any/all of its referenced documents. An OAD uses and conforms to the OpenAPI Specification, and MUST contain at least one [paths](#paths-object) field, [components](#oas-components) field, or [webhooks](#oas-webhooks) field. +An OpenAPI Description (OAD) formally describes the surface of an API and its semantics. It is composed of an [entry document](#openapi-description-structure), which must be an OpenAPI Document, and any/all of its referenced documents. An OAD uses and conforms to the OpenAPI Specification, and MUST contain at least one [paths](#paths-object) field, [components](#oas-components) field, or [webhooks](#oas-webhooks) field. ### OpenAPI Document -An OpenAPI Document is a single JSON or YAML document that conforms to the OpenAPI Specification. +An OpenAPI Document is a single JSON or YAML document that conforms to the OpenAPI Specification. An OpenAPI Document compatible with OAS 3.\*.\* contains a required [`openapi`](#oas-version) field which designates the version of the OAS that it uses. ### Schema @@ -95,8 +95,6 @@ The OpenAPI Specification is versioned using a `major`.`minor`.`patch` versionin 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. -An OpenAPI Document compatible with OAS 3.\*.\* contains a required [`openapi`](#oas-version) field which designates the version of the OAS that it uses. - ### Format An OpenAPI Document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format. @@ -125,7 +123,7 @@ In order to preserve the ability to round-trip between YAML and JSON formats, YA ### OpenAPI Description Structure -An OpenAPI Description (OAD) MAY be made up of a single JSON or YAML document or be divided into multiple, connected parts at the discretion of the author. In the latter case, [Reference Object](#reference-object), [Path Item Object](#path-item-object) and [Schema Object](#schema-object) `$ref` keywords, as well as the [Link Object](#link-object) `operationRef` keyword, are used. +An OpenAPI Description (OAD) MAY be made up of a single JSON or YAML document or be divided into multiple, connected parts at the discretion of the author. In the latter case, [Reference Object](#reference-object), [Path Item Object](#path-item-object) and [Schema Object](#schema-object) `$ref` keywords, as well as the [Link Object](#link-object) `operationRef` keyword, and the URI form of the [Discriminator Object](#discriminator-object) mapping keyword, are used to identify the referenced elements. In a multi-document OAD, the document containing the OpenAPI Object where parsing begins is known as that OAD's **entry document**. @@ -329,7 +327,7 @@ This is the root object of the [OpenAPI Description](#openapi-description). | servers | [[Server Object](#server-object)] | An array of Server Objects, which provide connectivity information to a target server. If the `servers` field is not provided, or is an empty array, the default value would be a [Server Object](#server-object) with a [url](#server-url) value of `/`. | | paths | [Paths Object](#paths-object) | The available paths and operations for the API. | | webhooks | Map[`string`, [Path Item Object](#path-item-object)] | The incoming webhooks that MAY be received as part of this API and that the API consumer MAY choose to implement. Closely related to the `callbacks` feature, this section describes requests initiated other than by an API call, for example by an out of band registration. The key name is a unique string to refer to each webhook, while the (optionally referenced) Path Item Object describes a request that may be initiated by the API provider and the expected responses. An [example](https://learn.openapis.org/examples/v3.1/webhook-example.html) is available. | -| components | [Components Object](#components-object) | An element to hold various schemas for the description. | +| components | [Components Object](#components-object) | An element to hold various Objects for the description. | | security | [[Security Requirement Object](#security-requirement-object)] | A declaration of which security mechanisms can be used across the API. The list of values includes alternative Security Requirement Objects that can be used. Only one of the Security Requirement Objects need to be satisfied to authorize a request. Individual operations can override this definition. The list can be incomplete, up to being empty or absent. To make security explicitly optional, an empty security requirement (`{}`) can be included in the array. | | tags | [[Tag Object](#tag-object)] | A list of tags used by the description with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operation-object) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique. | | externalDocs | [External Documentation Object](#external-documentation-object) | Additional external documentation. | @@ -2228,7 +2226,7 @@ Because examples using these fields represent the final serialized form of the d The singular `example` field in the Parameter or Media Type Object is concise and convenient for simple examples, but does not offer any other advantages over using Example Objects under `examples`. Some examples cannot be represented directly in JSON or YAML. -For all three ways of providing examples, these can be shown as string values with any escaping necessary to make the string valid in the JSON or YAML format of the OpenAPI Description. +For all three ways of providing examples, these can be shown as string values with any escaping necessary to make the string valid in the JSON or YAML format of documents that comprise the OpenAPI Description. With the Example Object, such values can alternatively be handled through the `externalValue` field. ##### Example Object Examples @@ -2378,7 +2376,7 @@ For computing links and providing instructions to execute them, a [runtime expre | Field Name | Type | Description | | ---- | :----: | ---- | -| operationRef | `string` | A URI identifying an OAS operation. This field is mutually exclusive of the `operationId` field, and MUST point to an [Operation Object](#operation-object). Relative `operationRef` values MAY be used to locate an existing [Operation Object](#operation-object) in the OpenAPI description. See the rules for resolving [Relative References](#relative-references-in-api-description-uris). | +| operationRef | `string` | A URI reference to an OAS operation. This field is mutually exclusive of the `operationId` field, and MUST point to an [Operation Object](#operation-object). Relative `operationRef` values MAY be used to locate an existing [Operation Object](#operation-object) in the OpenAPI Description. | | operationId | `string` | The name of an _existing_, resolvable OAS operation, as defined with a unique `operationId`. This field is mutually exclusive of the `operationRef` field. | | parameters | Map[`string`, Any \| [{expression}](#runtime-expressions)] | A map representing parameters to pass to an operation as specified with `operationId` or identified via `operationRef`. The key is the parameter name to be used (optionally qualified with the parameter location, e.g. `path.id` for an `id` parameter in the path), whereas the value can be a constant or an expression to be evaluated and passed to the linked operation. | | requestBody | Any \| [{expression}](#runtime-expressions) | A literal value or [{expression}](#runtime-expressions) to use as a request body when calling the target operation. | @@ -2477,7 +2475,7 @@ links: username: $response.body#/username ``` -or an absolute `operationRef`: +or a URI `operationRef`: ```yaml links: From 8346834065070b5e2dace985d48fe5688e54dc18 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Mon, 7 Oct 2024 14:02:03 +0200 Subject: [PATCH 07/11] Update versions/3.1.1.md --- versions/3.1.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 2937cc82dd..f5f30ce269 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -123,7 +123,7 @@ In order to preserve the ability to round-trip between YAML and JSON formats, YA ### OpenAPI Description Structure -An OpenAPI Description (OAD) MAY be made up of a single JSON or YAML document or be divided into multiple, connected parts at the discretion of the author. In the latter case, [Reference Object](#reference-object), [Path Item Object](#path-item-object) and [Schema Object](#schema-object) `$ref` keywords, as well as the [Link Object](#link-object) `operationRef` keyword, and the URI form of the [Discriminator Object](#discriminator-object) mapping keyword, are used to identify the referenced elements. +An OpenAPI Description (OAD) MAY be made up of a single JSON or YAML document or be divided into multiple, connected parts at the discretion of the author. In the latter case, [Reference Object](#reference-object), [Path Item Object](#path-item-object) and [Schema Object](#schema-object) `$ref` fields, as well as the [Link Object](#link-object) `operationRef` field, and the URI form of the [Discriminator Object](#discriminator-object) `mapping` field, are used to identify the referenced elements. In a multi-document OAD, the document containing the OpenAPI Object where parsing begins is known as that OAD's **entry document**. From b0f72534f1b3e8d440b5d7130de76e20fed994a9 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Thu, 10 Oct 2024 17:27:19 +0100 Subject: [PATCH 08/11] Update versions/3.1.1.md --- versions/3.1.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index f5f30ce269..8a4410aeba 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -159,7 +159,7 @@ It is the responsibility of an embedding format to define how to parse embedded JSON or YAML objects within an OAD are interpreted as specific Objects (such as [Operation Objects](#operation-object), [Response Objects](#response-object), [Reference Objects](#reference-object), etc.) based on their context. Depending on how references are arranged, a given JSON or YAML object can be interpreted in multiple different contexts: * As the root object of the [entry document](#openapi-description-structure), which is always interpreted as an OpenAPI Object -* As the Object type implied by its parent Object within the OpenAPI Description +* As the Object type implied by its parent Object within the document * As a reference target, with the Object type matching the reference source's context If the same JSON/YAML object is parsed multiple times and the respective contexts require it to be parsed as _different_ Object types, the resulting behavior is _implementation defined_, and MAY be treated as an error if detected. An example would be referencing an empty Schema Object under `#/components/schemas` where a Path Item Object is expected, as an empty object is valid for both types. For maximum interoperability, it is RECOMMENDED that OpenAPI Description authors avoid such scenarios. From 94119fe4ecd07ff1ce47421f1722a7c8a5d17153 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Thu, 10 Oct 2024 12:45:44 -0700 Subject: [PATCH 09/11] Revert to "OpenAPI document" for Server url Per post-TDC call with Darrel. --- versions/3.1.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 8a4410aeba..947a6f8fcc 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -455,7 +455,7 @@ An object representing a Server. | Field Name | Type | Description | | ---- | :----: | ---- | -| url | `string` | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the entry document of the OpenAPI Description is being served. Variable substitutions will be made when a variable is named in `{`braces`}`. | +| url | `string` | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in `{`braces`}`. | | description | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. | | variables | Map[`string`, [Server Variable Object](#server-variable-object)] | A map between a variable name and its value. The value is used for substitution in the server's URL template. | From 0f96aae7a27b36941ab977c799a6b9c32f8225db Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Fri, 11 Oct 2024 11:50:34 -0700 Subject: [PATCH 10/11] Better use of defined terminology Co-authored-by: Ralf Handl --- versions/3.1.1.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 947a6f8fcc..2ff23a4f8e 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -327,9 +327,9 @@ This is the root object of the [OpenAPI Description](#openapi-description). | servers | [[Server Object](#server-object)] | An array of Server Objects, which provide connectivity information to a target server. If the `servers` field is not provided, or is an empty array, the default value would be a [Server Object](#server-object) with a [url](#server-url) value of `/`. | | paths | [Paths Object](#paths-object) | The available paths and operations for the API. | | webhooks | Map[`string`, [Path Item Object](#path-item-object)] | The incoming webhooks that MAY be received as part of this API and that the API consumer MAY choose to implement. Closely related to the `callbacks` feature, this section describes requests initiated other than by an API call, for example by an out of band registration. The key name is a unique string to refer to each webhook, while the (optionally referenced) Path Item Object describes a request that may be initiated by the API provider and the expected responses. An [example](https://learn.openapis.org/examples/v3.1/webhook-example.html) is available. | -| components | [Components Object](#components-object) | An element to hold various Objects for the description. | +| components | [Components Object](#components-object) | An element to hold various Objects for the OpenAPI Description. | | security | [[Security Requirement Object](#security-requirement-object)] | A declaration of which security mechanisms can be used across the API. The list of values includes alternative Security Requirement Objects that can be used. Only one of the Security Requirement Objects need to be satisfied to authorize a request. Individual operations can override this definition. The list can be incomplete, up to being empty or absent. To make security explicitly optional, an empty security requirement (`{}`) can be included in the array. | -| tags | [[Tag Object](#tag-object)] | A list of tags used by the description with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operation-object) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique. | +| tags | [[Tag Object](#tag-object)] | A list of tags used by the OpenAPI Description with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operation-object) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique. | | externalDocs | [External Documentation Object](#external-documentation-object) | Additional external documentation. | This object MAY be extended with [Specification Extensions](#specification-extensions). From 07d5e39dab564dc15ae9f2783873075c84aa7a9f Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Sat, 12 Oct 2024 10:53:05 -0700 Subject: [PATCH 11/11] Sync relative Server url language with 3.0.4. --- versions/3.1.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 2ff23a4f8e..d8daaca58e 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -455,7 +455,7 @@ An object representing a Server. | Field Name | Type | Description | | ---- | :----: | ---- | -| url | `string` | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in `{`braces`}`. | +| url | `string` | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the document containing the Server Object is being served. Variable substitutions will be made when a variable is named in `{`braces`}`. | | description | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. | | variables | Map[`string`, [Server Variable Object](#server-variable-object)] | A map between a variable name and its value. The value is used for substitution in the server's URL template. |