diff --git a/versions/3.2.0.md b/versions/3.2.0.md
index 76fde0c665..af3709dfb1 100644
--- a/versions/3.2.0.md
+++ b/versions/3.2.0.md
@@ -12,15 +12,15 @@ The OpenAPI Specification (OAS) defines a standard, language-agnostic interface
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 [learn.openapis.org](https://learn.openapis.org/).
+For examples of OpenAPI usage and additional documentation, please visit [[?OpenAPI-Learn]].
For extension registries and other specifications published by the OpenAPI Initiative, as well as the authoritative rendering of this specification, please visit [spec.openapis.org](https://spec.openapis.org/).
## Definitions
-### OpenAPI Document
+### OpenAPI Description
-A self-contained or composite resource which defines or describes an API or elements of an API. The OpenAPI document MUST contain at least one [paths](#paths-object) field, a [components](#oas-components) field or a [webhooks](#oas-webhooks) field. An OpenAPI document uses and conforms to the OpenAPI Specification.
+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.
### Schema
@@ -30,7 +30,7 @@ This specification also _uses_ schemas in the form of the [Schema Object](#schem
### Path Templating
-Path templating refers to the usage of template expressions, delimited by curly braces ({}), to mark a section of a URL path as replaceable using path parameters.
+Path templating refers to the usage of template expressions, delimited by curly braces (`{}`), to mark a section of a URL path as replaceable using path parameters.
Each template expression in the path MUST correspond to a path parameter that is included in the [Path Item](#path-item-object) itself and/or in each of the Path Item's [Operations](#operation-object). An exception is if the path item is empty, for example due to ACL constraints, matching path parameters are not required.
@@ -59,9 +59,9 @@ Some examples of possible media type definitions:
### HTTP Status Codes
The HTTP Status Codes are used to indicate the status of the executed operation.
-The available status codes are defined by [RFC7231](https://tools.ietf.org/html/rfc7231#section-6) and registered status codes are listed in the [IANA Status Code Registry](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml).
+Status codes SHOULD be selected from the available status codes registered in the [IANA Status Code Registry](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml).
-### HTTP and Case Sensitivity
+### Case Sensitivity
As most field names and values in the OpenAPI Specification are case-sensitive, this document endeavors to call out any case-insensitive names and values.
However, the case sensitivity of field names and values that map directly to HTTP concepts follow the case sensitivity rules of HTTP, even if this document does not make a note of every concept.
@@ -104,13 +104,13 @@ For example, if a field has an array value, the JSON array representation will b
All field names in the specification are **case sensitive**.
This includes all fields that are used as keys in a map, except where explicitly noted that keys are **case insensitive**.
-The [schema](#schema) exposes two types of fields: Fixed fields, which have a declared name, and Patterned fields, which declare a regex pattern for the field name.
+The [schema](#schema) exposes two types of fields: _fixed fields_, which have a declared name, and _patterned fields_, which have a declared pattern for the field name.
Patterned fields MUST have unique names within the containing object.
In order to preserve the ability to round-trip between YAML and JSON formats, YAML version [1.2](https://yaml.org/spec/1.2/spec.html) is RECOMMENDED along with some additional constraints:
-* 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](https://tools.ietf.org/html/draft-bhutton-json-schema-00).
+* 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.
@@ -119,31 +119,31 @@ In order to preserve the ability to round-trip between YAML and JSON formats, YA
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.
-Any document consisting entirely of an OpenAPI Object is known as a **complete OpenAPI document**.
-In a multi-document description, the document containing the [OpenAPI Object](#openapi-object) where parsing begins for a specific API's description is known as that API's **entry OpenAPI document**, or simply **entry document**.
+Any document consisting entirely of an [OpenAPI Object](#openapi-object) is known as a **complete OpenAPI document**.
+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**.
-It is RECOMMENDED that the root OpenAPI document be named: `openapi.json` or `openapi.yaml`.
+It is RECOMMENDED that the entry OpenAPI document be named: `openapi.json` or `openapi.yaml`.
#### Parsing Documents
-In order to properly handle [Schema Objects](#schema-object), OAS 3.1 inherits the parsing requirements of [JSON Schema draft 2020-12 §9](https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00#section-9), with appropriate modifications regarding base URIs as specified in [Relative References In URIs](#relative-references-in-api-description-uris).
+In order to properly handle [Schema Objects](#schema-object), OAS 3.1 inherits the parsing requirements of [JSON Schema Specification Draft 2020-12](https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00#section-9), with appropriate modifications regarding base URIs as specified in [Relative References In URIs](#relative-references-in-api-description-uris).
-This includes a requirement to parse complete documents before deeming a Schema object reference to be unresolvable, in order to detect keywords that might provide the reference target or impact the determination of the appropriate base URI.
+This includes a requirement to parse complete documents before deeming a Schema Object reference to be unresolvable, in order to detect keywords that might provide the reference target or impact the determination of the appropriate base URI.
Implementations MAY support complete-document parsing in any of the following ways:
* Detecting OpenAPI or JSON Schema documents using media types
* Detecting OpenAPI documents through the root `openapi` property
* Detecting JSON Schema documents through detecting keywords or otherwise successfully parsing the document in accordance with the JSON Schema specification
-* Detecting a document containing a referenceable Object at its root based on the expected type of the reference
-* Allowing users to configure the type of documents that might be loaded due to a reference to a non-root Object
+* Detecting a document containing a referenceable object at its root based on the expected type of the reference
+* Allowing users to configure the type of documents that might be loaded due to a reference to a non-root object
Implementations that parse referenced fragments of OpenAPI content without regard for the content of the rest of the containing document will miss keywords that change the meaning and behavior of the reference target.
In particular, failing to take into account keywords that change the base URI introduces security risks by causing references to resolve to unintended URIs, with unpredictable results.
While some implementations support this sort of parsing due to the requirements of past versions of this specification, in version 3.1, the result of parsing fragments in isolation is _undefined_ and likely to contradict the requirements of this specification.
While it is possible to structure certain OpenAPI Descriptions to ensure that they will behave correctly when references are parsed as isolated fragments, depending on this is NOT RECOMMENDED.
-This specification does not explicitly enumerate the conditions under which such behavior is safe, and provides no guarantee for continued safety in any future versions of the OAS.
+This specification does not explicitly enumerate the conditions under which such behavior is safe and provides no guarantee for continued safety in any future versions of the OAS.
A special case of parsing fragments of OAS content would be if such fragments are embedded in another format, referred to as an _embedding format_ with respect to the OAS.
Note that the OAS itself is an embedding format with respect to JSON Schema, which is embedded as Schema Objects.
@@ -170,7 +170,7 @@ In some cases, an unambiguous URI-based alternative is available, and OAD author
| ---- | ---- | ---- |
| [Security Requirement Object](#security-requirement-object) `{name}` | [Security Scheme Object](#security-scheme-object) name under the [Components Object](#components-object) | _n/a_ |
| [Discriminator Object](#discriminator-object) `mapping` _(implicit, or explicit name syntax)_ | [Schema Object](#schema-object) name under the Components Object | `mapping` _(explicit URI syntax)_ |
-| [Operation Object](#operation-object) `tags` | [Tag Object](#tag-object) `name` (in the Components Object) | _n/a_ |
+| [Operation Object](#operation-object) `tags` | [Tag Object](#tag-object) `name` (in the [OpenAPI Object](#openapi-object)'s `tags` array) | _n/a_ |
| [Link Object](#link-object) `operationId` | [Path Item Object](#path-item-object) `operationId` | `operationRef` |
A fifth implicit connection involves appending the templated URL paths of the [Paths Object](#paths-object) to the appropriate [Server Object](#server-object)'s `url` field.
@@ -185,7 +185,7 @@ The implicit connection of `tags` in the Operation Object uses the `name` field
This means resolving component names and tag names both depend on starting from the correct OpenAPI Object.
For resolving component and tag name connections from a referenced (non-entry) document, it is RECOMMENDED that tools resolve from the entry document, rather than the current document.
-This allows Security Scheme Objects and Tag Objects to be defined with the API's deployment information (the top-level Server Objects), and treated as an interface for referenced documents to access.
+This allows Security Scheme Objects and Tag Objects to be defined next to the API's deployment information (the top-level array of Server Objects), and treated as an interface for referenced documents to access.
The interface approach can also work for Discriminator Objects and Schema Objects, but it is also possible to keep the Discriminator Object's behavior within a single document using the relative URI-reference syntax of `mapping`.
@@ -217,7 +217,7 @@ The formats defined by the OAS are:
| `integer` | `int64` | signed 64 bits (a.k.a long) |
| `number` | `float` | |
| `number` | `double` | |
-| `string` | `password` | A hint to UIs to obscure input. |
+| `string` | `password` | A hint to obscure the value. |
#### Working With Binary Data
@@ -240,10 +240,10 @@ Using a `contentEncoding` of `base64url` ensures that URL encoding (as required
The `contentMediaType` keyword is redundant if the media type is already set:
-* as the key for a [`MediaType Object`](#media-type-object)
-* in the `contentType` field of an [`Encoding Object`](#encoding-object)
+* as the key for a [MediaType Object](#media-type-object)
+* in the `contentType` field of an [Encoding Object](#encoding-object)
-If the Schema Object will be processed by a non-OAS-aware JSON Schema implementation, it may be useful to include `contentMediaType` even if it is redundant. However, if `contentMediaType` contradicts a relevant Media Type Object or Encoding Object, then `contentMediaType` SHALL be ignored.
+If the [Schema Object](#schema-object) will be processed by a non-OAS-aware JSON Schema implementation, it may be useful to include `contentMediaType` even if it is redundant. However, if `contentMediaType` contradicts a relevant Media Type Object or Encoding Object, then `contentMediaType` SHALL be ignored.
The `maxLength` keyword MAY be used to set an expected upper bound on the length of a streaming payload. The keyword can be applied to either string data, including encoded binary data, or to unencoded binary data. For unencoded binary, the length is the number of octets.
@@ -253,7 +253,7 @@ The following table shows how to migrate from OAS 3.0 binary data descriptions,
| OAS < 3.1 | OAS 3.1+ | Comments |
| ---- | ---- | ---- |
-| `type: string`
`format: binary` | `contentMediaType: image/png` | if redundant, can be omitted, often resulting in an empty Schema Object |
+| `type: string`
`format: binary` | `contentMediaType: image/png` | if redundant, can be omitted, often resulting in an empty [Schema Object](#schema-object) |
| `type: string`
`format: byte` | `type: string`
`contentMediaType: image/png`
`contentEncoding: base64` | note that `base64url` can be used to avoid re-encoding the base64 string to be URL-safe |
### Rich Text Formatting
@@ -267,16 +267,16 @@ OpenAPI Description authors SHOULD consider how text using such extensions will
### Relative References in API Description URIs
URIs used as references within an OpenAPI Description, or to external documentation or other supplementary information such as a license, are resolved as _identifiers_, and described by this specification as **_URIs_**.
-As noted under [Parsing Documents](#parsing-documents), this specification inherits JSON Schema draft 2020-12's requirements for loading documents and associating them with their expected URIs, which might not match their current location.
+As noted under [Parsing Documents](#parsing-documents), this specification inherits JSON Schema Specification Draft 2020-12's requirements for [loading documents](https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00#section-9) and associating them with their expected URIs, which might not match their current location.
This feature is used both for working in development or test environments without having to change the URIs, and for working within restrictive network configurations or security policies.
Note that some URI fields are named `url` for historical reasons, but the descriptive text for those fields uses the correct "URI" terminology.
Unless specified otherwise, all properties that are URIs MAY be relative references as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2).
-Relative references in [`Schema Objects`](#schema-object), including any that appear as `$id` values, use the nearest parent `$id` as a Base URI, as described by [JSON Schema Specification Draft 2020-12](https://tools.ietf.org/html/draft-bhutton-json-schema-00#section-8.2).
+Relative references in [Schema Objects](#schema-object), including any that appear as `$id` values, use the nearest parent `$id` as a Base URI, as described by [JSON Schema Specification Draft 2020-12](https://tools.ietf.org/html/draft-bhutton-json-schema-00#section-8.2).
-Relative URI references in other Objects, and in Schema Objects where no parent schema contains an `$id`, MUST be resolved using the referring document's base URI, which is determined in accordance with [RFC3986 §5.1.2 – 5.1.4](https://tools.ietf.org/html/rfc3986#section-5.1.2).
+Relative URI references in other Objects, and in Schema Objects where no parent schema contains an `$id`, MUST be resolved using the referring document's base URI, which is determined in accordance with [[RFC3986]] [Section 5.1.2 – 5.1.4](https://tools.ietf.org/html/rfc3986#section-5.1.2).
In practice, this is usually the retrieval URI of the document, which MAY be determined based on either its current actual location or a user-supplied expected location.
If a URI contains a fragment identifier, then the fragment should be resolved per the fragment resolution mechanism of the referenced document. If the representation of the referenced document is JSON or YAML, then the fragment identifier SHOULD be interpreted as a JSON-Pointer as per [RFC6901](https://tools.ietf.org/html/rfc6901).
@@ -286,7 +286,7 @@ If a URI contains a fragment identifier, then the fragment should be resolved pe
API endpoints are by definition accessed as locations, and are described by this specification as **_URLs_**.
Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2).
-Unless specified otherwise, relative references are resolved using the URLs defined in the [`Server Object`](#server-object) as a Base URL. Note that these themselves MAY be relative to the referring document.
+Unless specified otherwise, relative references are resolved using the URLs defined in the [Server Object](#server-object) as a Base URL. Note that these themselves MAY be relative to the referring document.
Relative references in CommonMark hyperlinks are resolved in their rendered context, which might differ from the context of the API description.
@@ -301,7 +301,7 @@ 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-document).
+This is the root object of the [OpenAPI document](#openapi-description).
##### Fixed Fields
@@ -314,7 +314,7 @@ This is the root object of the [OpenAPI document](#openapi-document).
| paths | [Paths Object](#paths-object) | The available paths and operations for the API. |
| webhooks | Map[`string`, [Path Item Object](#path-item-object) \| [Reference Object](#reference-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](../examples/v3.1/webhook-example.yaml) is available. |
| components | [Components Object](#components-object) | An element to hold various schemas for the document. |
-| 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. To make security optional, an empty security requirement (`{}`) can be included in the array. |
+| 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. To make security 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. |
| externalDocs | [External Documentation Object](#external-documentation-object) | Additional external documentation. |
@@ -343,9 +343,9 @@ This object MAY be extended with [Specification Extensions](#specification-exten
```json
{
- "title": "Sample Pet Store App",
+ "title": "Example Pet Store App",
"summary": "A pet store manager.",
- "description": "This is a sample server for a pet store.",
+ "description": "This is an example server for a pet store.",
"termsOfService": "https://example.com/terms/",
"contact": {
"name": "API Support",
@@ -361,9 +361,9 @@ This object MAY be extended with [Specification Extensions](#specification-exten
```
```yaml
-title: Sample Pet Store App
+title: Example Pet Store App
summary: A pet store manager.
-description: This is a sample server for a pet store.
+description: This is an example server for a pet store.
termsOfService: https://example.com/terms/
contact:
name: API Support
@@ -384,7 +384,7 @@ Contact information for the exposed API.
| Field Name | Type | Description |
| ---- | :----: | ---- |
| name | `string` | The identifying name of the contact person/organization. |
-| url | `string` | The URI for to the contact information. This MUST be in the form of a URI. |
+| url | `string` | The URI for the contact information. This MUST be in the form of a URI. |
| email | `string` | The email address of the contact person/organization. This MUST be in the form of an email address. |
This object MAY be extended with [Specification Extensions](#specification-extensions).
@@ -414,7 +414,7 @@ License information for the exposed API.
| Field Name | Type | Description |
| ---- | :----: | ---- |
| name | `string` | **REQUIRED**. The license name used for the API. |
-| identifier | `string` | An [SPDX](https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60) license expression for the API. The `identifier` field is mutually exclusive of the `url` field. |
+| identifier | `string` | An [SPDX](https://spdx.org/licenses/) license expression for the API. The `identifier` field is mutually exclusive of the `url` field. |
| url | `string` | A URI for the license used for the API. This MUST be in the form of a URI. The `url` field is mutually exclusive of the `identifier` field. |
This object MAY be extended with [Specification Extensions](#specification-extensions).
@@ -441,7 +441,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 `{`brackets`}`. |
+| 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. |
@@ -556,7 +556,7 @@ This object MAY be extended with [Specification Extensions](#specification-exten
#### Components Object
Holds a set of reusable objects for different aspects of the OAS.
-All objects defined within the components object will have no effect on the API unless they are explicitly referenced from properties outside the components object.
+All objects defined within the Components Object will have no effect on the API unless they are explicitly referenced from properties outside the Components Object.
##### Fixed Fields
@@ -672,7 +672,7 @@ my.org.User
"securitySchemes": {
"api_key": {
"type": "apiKey",
- "name": "api_key",
+ "name": "api-key",
"in": "header"
},
"petstore_auth": {
@@ -749,7 +749,7 @@ components:
securitySchemes:
api_key:
type: apiKey
- name: api_key
+ name: api-key
in: header
petstore_auth:
type: oauth2
@@ -764,13 +764,13 @@ components:
#### Paths Object
Holds the relative paths to the individual endpoints and their operations.
-The path is appended to the URL from the [`Server Object`](#server-object) in order to construct the full URL. The Paths MAY be empty, due to [Access Control List (ACL) constraints](#security-filtering).
+The path is appended to the URL from the [Server Object](#server-object) in order to construct the full URL. The Paths Object MAY be empty, due to [Access Control List (ACL) constraints](#security-filtering).
##### Patterned Fields
| Field Pattern | Type | Description |
| ---- | :----: | ---- |
-| /{path} | [Path Item Object](#path-item-object) \| [Reference Object](#reference-object) | A relative path to an individual endpoint. The field name MUST begin with a forward slash (`/`). The path is **appended** (no relative URL resolution) to the expanded URL from the [`Server Object`](#server-object)'s `url` field in order to construct the full URL. [Path templating](#path-templating) is allowed. When matching URLs, concrete (non-templated) paths would be matched before their templated counterparts. Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical. In case of ambiguous matching, it's up to the tooling to decide which one to use. |
+| /{path} | [Path Item Object](#path-item-object) \| [Reference Object](#reference-object) | A relative path to an individual endpoint. The field name MUST begin with a forward slash (`/`). The path is **appended** (no relative URL resolution) to the expanded URL from the [Server Object](#server-object)'s `url` field in order to construct the full URL. [Path templating](#path-templating) is allowed. When matching URLs, concrete (non-templated) paths would be matched before their templated counterparts. Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical. In case of ambiguous matching, it's up to the tooling to decide which one to use. |
This object MAY be extended with [Specification Extensions](#specification-extensions).
@@ -859,8 +859,8 @@ The path itself is still exposed to the documentation viewer but they will not k
| head | [Operation Object](#operation-object) | A definition of a HEAD operation on this path. |
| patch | [Operation Object](#operation-object) | A definition of a PATCH operation on this path. |
| trace | [Operation Object](#operation-object) | A definition of a TRACE operation on this path. |
-| servers | [[Server Object](#server-object)] | An alternative `server` array to service all operations in this path. |
-| parameters | [[Parameter Object](#parameter-object) \| [Reference Object](#reference-object)] | A list of parameters that are applicable for all the operations described under this path. These parameters can be overridden at the operation level, but cannot be removed there. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameter-name) and [location](#parameter-in). The list can use the [Reference Object](#reference-object) to link to parameters that are defined at the [OpenAPI Object's components/parameters](#components-parameters). |
+| servers | [[Server Object](#server-object)] | An alternative `servers` array to service all operations in this path. If a `servers` array is specified at the [OpenAPI Object](#oas-servers) level, it will be overridden by this value. |
+| parameters | [[Parameter Object](#parameter-object) \| [Reference Object](#reference-object)] | A list of parameters that are applicable for all the operations described under this path. These parameters can be overridden at the operation level, but cannot be removed there. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameter-name) and [location](#parameter-in). The list can use the [Reference Object](#reference-object) to link to parameters that are defined in the [OpenAPI Object's `components.parameters`](#components-parameters). |
This object MAY be extended with [Specification Extensions](#specification-extensions).
@@ -961,13 +961,13 @@ Describes a single API operation on a path.
| description | `string` | A verbose explanation of the operation behavior. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. |
| externalDocs | [External Documentation Object](#external-documentation-object) | Additional external documentation for this operation. |
| operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions. |
-| parameters | [[Parameter Object](#parameter-object) \| [Reference Object](#reference-object)] | A list of parameters that are applicable for this operation. If a parameter is already defined at the [Path Item](#path-item-parameters), the new definition will override it but can never remove it. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameter-name) and [location](#parameter-in). The list can use the [Reference Object](#reference-object) to link to parameters that are defined at the [OpenAPI Object's components/parameters](#components-parameters). |
+| parameters | [[Parameter Object](#parameter-object) \| [Reference Object](#reference-object)] | A list of parameters that are applicable for this operation. If a parameter is already defined at the [Path Item](#path-item-parameters), the new definition will override it but can never remove it. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameter-name) and [location](#parameter-in). The list can use the [Reference Object](#reference-object) to link to parameters that are defined in the [OpenAPI Object's `components.parameters`](#components-parameters). |
| requestBody | [Request Body Object](#request-body-object) \| [Reference Object](#reference-object) | The request body applicable for this operation. The `requestBody` is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such as [GET](https://tools.ietf.org/html/rfc7231#section-4.3.1), [HEAD](https://tools.ietf.org/html/rfc7231#section-4.3.2) and [DELETE](https://tools.ietf.org/html/rfc7231#section-4.3.5)), `requestBody` is permitted but does not have well-defined semantics and SHOULD be avoided if possible. |
| responses | [Responses Object](#responses-object) | The list of possible responses as they are returned from executing this operation. |
| callbacks | Map[`string`, [Callback Object](#callback-object) \| [Reference Object](#reference-object)] | A map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a [Callback Object](#callback-object) that describes a request that may be initiated by the API provider and the expected responses. |
| deprecated | `boolean` | Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation. Default value is `false`. |
-| security | [[Security Requirement Object](#security-requirement-object)] | A declaration of which security mechanisms can be used for this operation. 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. To make security optional, an empty security requirement (`{}`) can be included in the array. This definition overrides any declared top-level [`security`](#oas-security). To remove a top-level security declaration, an empty array can be used. |
-| servers | [[Server Object](#server-object)] | An alternative `server` array to service this operation. If an alternative `server` object is specified at the Path Item Object or Root level, it will be overridden by this value. |
+| security | [[Security Requirement Object](#security-requirement-object)] | A declaration of which security mechanisms can be used for this operation. 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. To make security optional, an empty security requirement (`{}`) can be included in the array. This definition overrides any declared top-level [`security`](#oas-security). To remove a top-level security declaration, an empty array can be used. |
+| servers | [[Server Object](#server-object)] | An alternative `servers` array to service this operation. If a `servers` array is specified at the [Path Item Object](#path-item-servers) or [OpenAPI Object](#oas-servers) level, it will be overridden by this value. |
This object MAY be extended with [Specification Extensions](#specification-extensions).
@@ -1117,7 +1117,7 @@ There are four possible parameter locations specified by the `in` field:
* path - Used together with [Path Templating](#path-templating), where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example, in `/items/{itemId}`, the path parameter is `itemId`.
* query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`.
-* header - Custom headers that are expected as part of the request. Note that [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive.
+* header - Custom headers that are expected as part of the request. Note that [RFC7230](https://tools.ietf.org/html/rfc7230#section-3.2) states header names are case insensitive.
* cookie - Used to pass a specific cookie value to the API.
##### Fixed Fields
@@ -1141,21 +1141,21 @@ These fields MAY be used with either `content` or `schema`.
This object MAY be extended with [Specification Extensions](#specification-extensions).
-Note that while `"Cookie"` as a `name` is not forbidden with `in: header`, the effect of defining a cookie parameter that way is undefined; use `in: cookie` instead.
+Note that while `"Cookie"` as a `name` is not forbidden if `in` is `"header"`, the effect of defining a cookie parameter that way is undefined; use `in: "cookie"` instead.
###### Fixed Fields for use with `schema`
For simpler scenarios, a [`schema`](#parameter-schema) and [`style`](#parameter-style) can describe the structure and syntax of the parameter.
-When `example` or `examples` are provided in conjunction with the `schema` object, the example SHOULD match the specified schema and follow the prescribed serialization strategy for the parameter.
+When `example` or `examples` are provided in conjunction with the `schema` field, the example SHOULD match the specified schema and follow the prescribed serialization strategy for the parameter.
The `example` and `examples` fields are mutually exclusive, and if either is present it SHALL _override_ any `example` in the schema.
-Serializing with `schema` is NOT RECOMMENDED for `in: cookie` parameters, `in: header` parameters that use HTTP header parameters (name=value pairs following a `;`) in their values, or `in: header` parameters where values might have non-URL-safe characters; see [Appendix D](#appendix-d-serializing-headers-and-cookies) for details.
+Serializing with `schema` is NOT RECOMMENDED for `in: "cookie"` parameters, `in: "header"` parameters that use HTTP header parameters (name=value pairs following a `;`) in their values, or `in: "header"` parameters where values might have non-URL-safe characters; see [Appendix D](#appendix-d-serializing-headers-and-cookies) for details.
| Field Name | Type | Description |
| ---- | :----: | ---- |
-| style | `string` | Describes how the parameter value will be serialized depending on the type of the parameter value. Default values (based on value of `in`): for `query` - `form`; for `path` - `simple`; for `header` - `simple`; for `cookie` - `form`. |
-| explode | `boolean` | When this is true, parameter values of type `array` or `object` generate separate parameters for each value of the array or key-value pair of the map. For other types of parameters this property has no effect. When [`style`](#parameter-style) is `form`, the default value is `true`. For all other styles, the default value is `false`. Note that despite `false` being the default for `deepObject`, the combination of `false` with `deepObject` is undefined. |
-| allowReserved | `boolean` | When this is true, parameter values are serialized using reserved expansion, as defined by [RFC6570](https://datatracker.ietf.org/doc/html/rfc6570#autoid-20), which allows [RFC3986's reserved character set](https://datatracker.ietf.org/doc/html/rfc3986#autoid-13), as well as percent-encoded triples, to pass through unchanged, while still percent-encoding all other disallowed characters (including `%` outside of percent-encoded triples). Applications are still responsible for percent-encoding reserved characters that are [not allowed in the query string](https://datatracker.ietf.org/doc/html/rfc3986#autoid-24) (`[`, `]`, `#`), or have a special meaning in `application/x-www-form-urlencoded` (`-`, `&`, `+`); see Appendices [C](#appendix-c-using-rfc6570-implementations) and [E](#appendix-e-percent-encoding-and-form-media-types) for details. This property only applies to parameters with an `in` value of `query`. The default value is `false`. |
+| style | `string` | Describes how the parameter value will be serialized depending on the type of the parameter value. Default values (based on value of `in`): for `"query"` - `"form"`; for `"path"` - `"simple"`; for `"header"` - `"simple"`; for `"cookie"` - `"form"`. |
+| explode | `boolean` | When this is true, parameter values of type `array` or `object` generate separate parameters for each value of the array or key-value pair of the map. For other types of parameters this property has no effect. When [`style`](#parameter-style) is `"form"`, the default value is `true`. For all other styles, the default value is `false`. Note that despite `false` being the default for `deepObject`, the combination of `false` with `deepObject` is undefined. |
+| allowReserved | `boolean` | When this is true, parameter values are serialized using reserved expansion, as defined by [RFC6570](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3), which allows [RFC3986's reserved character set](https://datatracker.ietf.org/doc/html/rfc3986#section-2.2), as well as percent-encoded triples, to pass through unchanged, while still percent-encoding all other disallowed characters (including `%` outside of percent-encoded triples). Applications are still responsible for percent-encoding reserved characters that are [not allowed in the query string](https://datatracker.ietf.org/doc/html/rfc3986#section-3.4) (`[`, `]`, `#`), or have a special meaning in `application/x-www-form-urlencoded` (`-`, `&`, `+`); see Appendices [C](#appendix-c-using-rfc6570-implementations) and [E](#appendix-e-percent-encoding-and-form-media-types) for details. This property only applies to parameters with an `in` value of `query`. The default value is `false`. |
| schema | [Schema Object](#schema-object) | The schema defining the type used for the parameter. |
| example | Any | Example of the parameter's potential value; see [Working With Examples](#working-with-examples). |
| examples | Map[ `string`, [Example Object](#example-object) \| [Reference Object](#reference-object)] | Examples of the parameter's potential value; see [Working With Examples](#working-with-examples). |
@@ -1165,7 +1165,7 @@ See also [Appendix C: Using RFC6570 Implementations](#appendix-c-using-rfc6570-i
###### Fixed Fields for use with `content`
For more complex scenarios, the [`content`](#parameter-content) property can define the media type and schema of the parameter, as well as give examples of its use.
-Using `content` with a `text/plain` media type is RECOMMENDED for `in: header` and `in: cookie` parameters where the `schema` strategy is not appropriate.
+Using `content` with a `text/plain` media type is RECOMMENDED for `in: "header"` and `in: "cookie"` parameters where the `schema` strategy is not appropriate.
| Field Name | Type | Description |
| ---- | :----: | ---- |
@@ -1183,7 +1183,7 @@ In order to support common ways of serializing simple parameters, a set of `styl
| form | `primitive`, `array`, `object` | `query`, `cookie` | Form style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.8). This option replaces `collectionFormat` with a `csv` (when `explode` is false) or `multi` (when `explode` is true) value from OpenAPI 2.0. |
| spaceDelimited | `array`, `object` | `query` | Space separated array values or object properties and values. This option replaces `collectionFormat` equal to `ssv` from OpenAPI 2.0. |
| pipeDelimited | `array`, `object` | `query` | Pipe separated array values or object properties and values. This option replaces `collectionFormat` equal to `pipes` from OpenAPI 2.0. |
-| deepObject | `object` | `query` | Provides a simple way of rendering nested objects using form parameters. |
+| deepObject | `object` | `query` | Allows objects with scalar properties to be represented using form parameters. The representation of array or object properties is not defined. |
See [Appendix E](#appendix-e-percent-encoding-and-form-media-types) for a discussion of percent-encoding, including when delimiters need to be percent-encoded and options for handling collisions with percent-encoded data.
@@ -1201,16 +1201,16 @@ The following table shows examples, as would be shown with the `example` or `exa
* The value _empty_ denotes the empty string, and is unrelated to the `allowEmptyValue` field
* The behavior of combinations marked _n/a_ is undefined
-* The `undefined` replaces the `empty` column in previous versions of this specification in order to better align with [RFC6570 §2.3](https://www.rfc-editor.org/rfc/rfc6570.html#section-2.3) terminology, which describes certain values including but not limited to `null` as "undefined" values with special handling; notably, the empty string is _not_ undefined
+* The `undefined` column replaces the `empty` column in previous versions of this specification in order to better align with [RFC6570](https://www.rfc-editor.org/rfc/rfc6570.html#section-2.3) terminology, which describes certain values including but not limited to `null` as "undefined" values with special handling; notably, the empty string is _not_ undefined
* For `form` and the non-RFC6570 query string styles `spaceDelimited`, `pipeDelimited`, and `deepObject`, each example is shown prefixed with `?` as if it were the only query parameter; see [Appendix C](#appendix-c-using-rfc6570-implementations) for more information on constructing query strings from multiple parameters, and [Appendix D](#appendix-d-serializing-headers-and-cookies) for warnings regarding `form` and cookie parameters
* Note that the `?` prefix is not appropriate for serializing `application/x-www-form-urlencoded` HTTP message bodies, and MUST be stripped or (if constructing the string manually) not added when used in that context; see the [Encoding Object](#encoding-object) for more information
* The examples are percent-encoded as required by RFC6570 and RFC3986; see [Appendix E](#appendix-e-percent-encoding-and-form-media-types) for a thorough discussion of percent-encoding concerns, including why unencoded `|` (`%7C`), `[` (`%5B`), and `]` (`%5D`) seem to work in some environments despite not being compliant.
-| [`style`](#style-values) | `explode` | `empty` | `string` | `array` | `object` |
+| [`style`](#style-values) | `explode` | `undefined` | `string` | `array` | `object` |
| ---- | ---- | ---- | ---- | ---- | ---- |
| matrix | false | ;color | ;color=blue | ;color=blue,black,brown | ;color=R,100,G,200,B,150 |
| matrix | true | ;color | ;color=blue | ;color=blue;color=black;color=brown | ;R=100;G=200;B=150 |
-| label | false | . | .blue | .blue.black.brown | .R.100.G.200.B.150 |
+| label | false | . | .blue | .blue,black,brown | .R,100,G,200,B,150 |
| label | true | . | .blue | .blue.black.brown | .R=100.G=200.B=150 |
| simple | false | _empty_ | blue | blue,black,brown | R,100,G,200,B,150 |
| simple | true | _empty_ | blue | blue,black,brown | R=100,G=200,B=150 |
@@ -1225,7 +1225,7 @@ The following table shows examples, as would be shown with the `example` or `exa
##### Parameter Object Examples
-A header parameter with an array of 64 bit integer numbers:
+A header parameter with an array of 64-bit integer numbers:
```json
{
@@ -1389,7 +1389,7 @@ Describes a single request body.
| Field Name | Type | Description |
| ---- | :----: | ---- |
| description | `string` | A brief description of the request body. This could contain examples of use. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. |
-| content | Map[`string`, [Media Type Object](#media-type-object)] | **REQUIRED**. The content of the request body. The key is a media type or [media type range](https://tools.ietf.org/html/rfc7231#appendix-D) and the value describes it. For requests that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/\* |
+| content | Map[`string`, [Media Type Object](#media-type-object)] | **REQUIRED**. The content of the request body. The key is a media type or [media type range](https://tools.ietf.org/html/rfc7231#appendix-D) and the value describes it. For requests that match multiple keys, only the most specific key is applicable. e.g. `"text/plain"` overrides `"text/*"` |
| required | `boolean` | Determines if the request body is required in the request. Defaults to `false`. |
This object MAY be extended with [Specification Extensions](#specification-extensions).
@@ -1452,7 +1452,7 @@ content:
$ref: '#/components/schemas/User'
examples:
user:
- summary: User Example
+ summary: User example
externalValue: https://foo.bar/examples/user-example.json
application/xml:
schema:
@@ -1464,7 +1464,7 @@ content:
text/plain:
examples:
user:
- summary: User example in Plain text
+ summary: User example in plain text
externalValue: https://foo.bar/examples/user-example.txt
'*/*':
examples:
@@ -1488,7 +1488,7 @@ See [Working With Examples](#working-with-examples) for further guidance regardi
| schema | [Schema Object](#schema-object) | The schema defining the content of the request, response, parameter, or header. |
| example | Any | Example of the media type; see [Working With Examples](#working-with-examples). |
| examples | Map[ `string`, [Example Object](#example-object) \| [Reference Object](#reference-object)] | Examples of the media type; see [Working With Examples](#working-with-examples). |
-| encoding | Map[`string`, [Encoding Object](#encoding-object)] | A map between a property name and information providing more control over the serialization of the value. The key, being the property name, MUST exist in the schema as a property. The encoding attribute SHALL only apply to [Request Body Objects](#request-body-object), and only when the media type is `multipart` or `application/x-www-form-urlencoded`. If no Encoding Object is provided for a property, the behavior is determined by the default values documented for the Encoding Object. |
+| encoding | Map[`string`, [Encoding Object](#encoding-object)] | A map between a property name and its encoding information. The key, being the property name, MUST exist in the schema as a property. The `encoding` field SHALL only apply to [Request Body Objects](#request-body-object), and only when the media type is `multipart` or `application/x-www-form-urlencoded`. If no Encoding Object is provided for a property, the behavior is determined by the default values documented for the Encoding Object. |
This object MAY be extended with [Specification Extensions](#specification-extensions).
@@ -1556,9 +1556,9 @@ application/json:
##### Considerations for File Uploads
-In contrast with the 2.0 specification, `file` input/output content in OpenAPI is described with the same semantics as any other schema type.
+In contrast to OpenAPI 2.0, `file` input/output content in OpenAPI 3 is described with the same semantics as any other schema type.
-In contrast with the 3.0 specification, the `format` keyword has no effect on the content-encoding of the schema. Instead, JSON Schema's `contentEncoding` and `contentMediaType` keywords are used. See [Working With Binary Data](#working-with-binary-data) for how to model various scenarios with these keywords, and how to migrate from the previous `format` usage.
+In contrast to OpenAPI 2.0, the `format` keyword has no effect on the content-encoding of the schema. Instead, JSON Schema's `contentEncoding` and `contentMediaType` keywords are used. See [Working With Binary Data](#working-with-binary-data) for how to model various scenarios with these keywords, and how to migrate from the previous `format` usage.
Examples:
@@ -1601,18 +1601,18 @@ To upload multiple files, a `multipart` media type MUST be used as shown under [
##### Support for x-www-form-urlencoded Request Bodies
-See [Encoding the `x-www-form-urlencoded` Media Type](#encoding-the-x-www-form-urlencoded-media-type) for guidance and examples, both with and without the `encoding` attribute.
+See [Encoding the `x-www-form-urlencoded` Media Type](#encoding-the-x-www-form-urlencoded-media-type) for guidance and examples, both with and without the `encoding` field.
##### Special Considerations for `multipart` Content
-See [Encoding `multipart` Media Types](#encoding-multipart-media-types) for further guidance and examples, both with and without the `encoding` attribute.
+See [Encoding `multipart` Media Types](#encoding-multipart-media-types) for further guidance and examples, both with and without the `encoding` field.
#### Encoding Object
A single encoding definition applied to a single schema property.
See [Appendix B](#appendix-b-data-type-conversion) for a discussion of converting values of various types to string representations.
-Properties are correlated with `multipart` parts using the `name` parameter to `Content-Disposition: form-data`, and with `application/x-www-form-urlencoded` using the query string parameter names.
+Properties are correlated with `multipart` parts using the [`name` parameter](https://www.rfc-editor.org/rfc/rfc7578#section-4.2) of `Content-Disposition: form-data`, and with `application/x-www-form-urlencoded` using the query string parameter names.
In both cases, their order is implementation-defined.
See [Appendix E](#appendix-e-percent-encoding-and-form-media-types) for a detailed examination of percent-encoding concerns for form media types.
@@ -1651,11 +1651,11 @@ See [Appendix B](#appendix-b-data-type-conversion) for a discussion of data type
| ---- | :----: | ---- |
| style | `string` | Describes how a specific property value will be serialized depending on its type. See [Parameter Object](#parameter-object) for details on the [`style`](#parameter-style) property. The behavior follows the same values as `query` parameters, including default values. Note that the initial `?` used in query strings is not used in `application/x-www-form-urlencoded` message bodies, and MUST be removed (if using an RFC6570 implementation) or simply not added (if constructing the string manually). This property SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded` or `multipart/form-data`. If a value is explicitly defined, then the value of [`contentType`](#encoding-content-type) (implicit or explicit) SHALL be ignored. |
| explode | `boolean` | When this is true, property values of type `array` or `object` generate separate parameters for each value of the array, or key-value-pair of the map. For other types of properties this property has no effect. When [`style`](#encoding-style) is `form`, the default value is `true`. For all other styles, the default value is `false`. Note that despite `false` being the default for `deepObject`, the combination of `false` with `deepObject` is undefined. This property SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded` or `multipart/form-data`. If a value is explicitly defined, then the value of [`contentType`](#encoding-content-type) (implicit or explicit) SHALL be ignored. |
-| allowReserved | `boolean` | When this is true, parameter values are serialized using reserved expansion, as defined by [RFC6570](https://datatracker.ietf.org/doc/html/rfc6570#autoid-20), which allows [RFC3986's reserved character set](https://datatracker.ietf.org/doc/html/rfc3986#autoid-13), as well as percent-encoded triples, to pass through unchanged, while still percent-encoding all other disallowed characters (including `%` outside of percent-encoded triples). Applications are still responsible for percent-encoding reserved characters that are [not allowed in the query string](https://datatracker.ietf.org/doc/html/rfc3986#autoid-24) (`[`, `]`, `#`), or have a special meaning in `application/x-www-form-urlencoded` (`-`, `&`, `+`); see Appendices [C](#appendix-c-using-rfc6570-implementations) and [E](#appendix-e-percent-encoding-and-form-media-types) for details. The default value is `false`. This property SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded` or `multipart/form-data`. If a value is explicitly defined, then the value of [`contentType`](#encoding-content-type) (implicit or explicit) SHALL be ignored. |
+| allowReserved | `boolean` | When this is true, parameter values are serialized using reserved expansion, as defined by [RFC6570](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3), which allows [RFC3986's reserved character set](https://datatracker.ietf.org/doc/html/rfc3986#section-2.2), as well as percent-encoded triples, to pass through unchanged, while still percent-encoding all other disallowed characters (including `%` outside of percent-encoded triples). Applications are still responsible for percent-encoding reserved characters that are [not allowed in the query string](https://datatracker.ietf.org/doc/html/rfc3986#section-3.4) (`[`, `]`, `#`), or have a special meaning in `application/x-www-form-urlencoded` (`-`, `&`, `+`); see Appendices [C](#appendix-c-using-rfc6570-implementations) and [E](#appendix-e-percent-encoding-and-form-media-types) for details. The default value is `false`. This property SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded` or `multipart/form-data`. If a value is explicitly defined, then the value of [`contentType`](#encoding-content-type) (implicit or explicit) SHALL be ignored. |
See also [Appendix C: Using RFC6570 Implementations](#appendix-c-using-rfc6570-implementations) for additional guidance, including on difficulties caused by the interaction between RFC6570's percent-encoding rules and the `multipart/form-data` media type.
-Note that the presence of at least one of `style`, `explode`, or `allowReserved` with an explicit value is equivalent to using `schema` with `in: query` Parameter Objects.
+Note that the presence of at least one of `style`, `explode`, or `allowReserved` with an explicit value is equivalent to using `schema` with `in: "query"` Parameter Objects.
The absence of all three of those fields is the equivalent of using `content`, but with the media type specified in `contentType` rather than through a Media Type Object.
##### Encoding the `x-www-form-urlencoded` Media Type
@@ -1667,7 +1667,7 @@ See [Appendix E](#appendix-e-percent-encoding-and-form-media-types) for a detail
###### Example: URL Encoded Form with JSON Values
-When there is no [`encoding` field](#media-type-encoding), the serialization strategy is based on the Encoding Object's default values:
+When there is no [`encoding`](#media-type-encoding) field, the serialization strategy is based on the Encoding Object's default values:
```yaml
requestBody:
@@ -1742,23 +1742,23 @@ name=example&icon=iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAIAAAD91JpzAAAABGdBTUEAALGPC_
```
Note that the `=` padding characters at the end need to be percent-encoded, even with the "URL safe" `contentEncoding: base64url`.
-Some base64-decoding implementations may be able to use the string without the padding per [RFC4648 §3.2](https://datatracker.ietf.org/doc/html/rfc4648#section-3.2).
+Some base64-decoding implementations may be able to use the string without the padding per [RFC4648](https://datatracker.ietf.org/doc/html/rfc4648#section-3.2).
However, this is not guaranteed, so it may be more interoperable to keep the padding and rely on percent-decoding.
##### Encoding `multipart` Media Types
-It is common to use `multipart/form-data` as a `Content-Type` when transferring forms as request bodies. In contrast to 2.0, a `schema` is REQUIRED to define the input parameters to the operation when using `multipart` content. This supports complex structures as well as supporting mechanisms for multiple file uploads.
+It is common to use `multipart/form-data` as a `Content-Type` when transferring forms as request bodies. In contrast to OpenAPI 2.0, a `schema` is REQUIRED to define the input parameters to the operation when using `multipart` content. This supports complex structures as well as supporting mechanisms for multiple file uploads.
-The `form-data` disposition and its `name` parameter are mandatory for `multipart/form-data` ([RFC7578 §4.2](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.2)).
-Array properties are handled by applying the same `name` to multiple parts, as is recommended by [RFC7578 §4.3](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.3) for supplying multiple values per form field.
-See [RFC7578 §5](https://www.rfc-editor.org/rfc/rfc7578.html#section-5) for guidance regarding non-ASCII part names.
+The `form-data` disposition and its `name` parameter are mandatory for `multipart/form-data` ([RFC7578](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.2)).
+Array properties are handled by applying the same `name` to multiple parts, as is recommended by [RFC7578](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.3) for supplying multiple values per form field.
+See [RFC7578](https://www.rfc-editor.org/rfc/rfc7578.html#section-5) for guidance regarding non-ASCII part names.
-Various other `multipart` types, most notable `multipart/mixed` ([RFC2046 §5.1.3](https://www.rfc-editor.org/rfc/rfc2046.html#section-5.1.3)) neither require nor forbid specific `Content-Disposition` values, which means care must be taken to ensure that any values used are supported by all relevant software.
+Various other `multipart` types, most notable `multipart/mixed` ([RFC2046](https://www.rfc-editor.org/rfc/rfc2046.html#section-5.1.3)) neither require nor forbid specific `Content-Disposition` values, which means care must be taken to ensure that any values used are supported by all relevant software.
It is not currently possible to correlate schema properties with unnamed, ordered parts in media types such as `multipart/mixed`, but implementations MAY choose to support such types when `Content-Disposition: form-data` is used with a `name` parameter.
-Note that there are significant restrictions on what headers can be used with `multipart` media types in general ([RFC2046 §5.1](https://www.rfc-editor.org/rfc/rfc2046.html#section-5.1)) and `multi-part/form-data` in particular ([RFC7578 §4.8](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.8)).
+Note that there are significant restrictions on what headers can be used with `multipart` media types in general ([RFC2046](https://www.rfc-editor.org/rfc/rfc2046.html#section-5.1)) and `multi-part/form-data` in particular ([RFC7578](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.8)).
-Note also that `Content-Transfer-Encoding` is deprecated for `multipart/form-data` ([RFC7578 §4.7](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.7)) where binary data is supported, as it is in HTTP.
+Note also that `Content-Transfer-Encoding` is deprecated for `multipart/form-data` ([RFC7578](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.7)) where binary data is supported, as it is in HTTP.
+Using `contentEncoding` for a multipart field is equivalent to specifying an [Encoding Object](#encoding-object) with a `headers` field containing `Content-Transfer-Encoding` with a schema that requires the value used in `contentEncoding`.
+If `contentEncoding` is used for a multipart field that has an Encoding Object with a `headers` field containing `Content-Transfer-Encoding` with a schema that disallows the value from `contentEncoding`, the result is undefined for serialization and parsing.
@@ -1770,7 +1770,7 @@ See [Appendix E](#appendix-e-percent-encoding-and-form-media-types) for a detail
###### Example: Basic Multipart Form
-When the `encoding` attribute is _not_ used, the encoding is determined by the Encoding Object's defaults:
+When the `encoding` field is _not_ used, the encoding is determined by the Encoding Object's defaults:
```yaml
requestBody:
@@ -1792,7 +1792,6 @@ requestBody:
# subschema, which is an object, so `application/json`
type: array
items:
- type: object
$ref: '#/components/schemas/Address'
```
@@ -1843,7 +1842,7 @@ requestBody:
###### Example: Multipart Form with Multiple Files
-In accordance with [RFC7578 §4.3](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.3), multiple files for a single form field are uploaded using the same name (`file` in this example) for each file's part:
+In accordance with [RFC7578](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.3), multiple files for a single form field are uploaded using the same name (`file` in this example) for each file's part:
```yaml
requestBody:
@@ -1867,10 +1866,10 @@ The container maps a HTTP response code to the expected response.
The documentation is not necessarily expected to cover all possible HTTP response codes because they may not be known in advance.
However, documentation is expected to cover a successful operation response and any known errors.
-The `default` MAY be used as a default response object for all HTTP codes
-that are not covered individually by the `Responses Object`.
+The `default` MAY be used as a default Response Object for all HTTP codes
+that are not covered individually by the Responses Object.
-The `Responses Object` MUST contain at least one response code, and if only one
+The Responses Object MUST contain at least one response code, and if only one
response code is provided it SHOULD be the response for a successful operation
call.
@@ -1884,7 +1883,7 @@ call.
| Field Pattern | Type | Description |
| ---- | :----: | ---- |
-| [HTTP Status Code](#http-status-codes) | [Response Object](#response-object) \| [Reference Object](#reference-object) | Any [HTTP status code](#http-status-codes) can be used as the property name, but only one property per code, to describe the expected response for that HTTP status code. This field MUST be enclosed in quotation marks (for example, "200") for compatibility between JSON and YAML. To define a range of response codes, this field MAY contain the uppercase wildcard character `X`. For example, `2XX` represents all response codes between `[200-299]`. Only the following range definitions are allowed: `1XX`, `2XX`, `3XX`, `4XX`, and `5XX`. If a response is defined using an explicit code, the explicit code definition takes precedence over the range definition for that code. |
+| [HTTP Status Code](#http-status-codes) | [Response Object](#response-object) \| [Reference Object](#reference-object) | Any [HTTP status code](#http-status-codes) can be used as the property name, but only one property per code, to describe the expected response for that HTTP status code. This field MUST be enclosed in quotation marks (for example, "200") for compatibility between JSON and YAML. To define a range of response codes, this field MAY contain the uppercase wildcard character `X`. For example, `2XX` represents all response codes between `200` and `299`. Only the following range definitions are allowed: `1XX`, `2XX`, `3XX`, `4XX`, and `5XX`. If a response is defined using an explicit code, the explicit code definition takes precedence over the range definition for that code. |
This object MAY be extended with [Specification Extensions](#specification-extensions).
@@ -1934,7 +1933,7 @@ default:
#### Response Object
-Describes a single response from an API Operation, including design-time, static
+Describes a single response from an API operation, including design-time, static
`links` to operations based on the response.
##### Fixed Fields
@@ -1942,8 +1941,8 @@ Describes a single response from an API Operation, including design-time, static
| Field Name | Type | Description |
| ---- | :----: | ---- |
| description | `string` | **REQUIRED**. A description of the response. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. |
-| headers | Map[`string`, [Header Object](#header-object) \| [Reference Object](#reference-object)] | Maps a header name to its definition. [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive. If a response header is defined with the name `"Content-Type"`, it SHALL be ignored. |
-| content | Map[`string`, [Media Type Object](#media-type-object)] | A map containing descriptions of potential response payloads. The key is a media type or [media type range](https://tools.ietf.org/html/rfc7231#appendix-D) and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/\* |
+| headers | Map[`string`, [Header Object](#header-object) \| [Reference Object](#reference-object)] | Maps a header name to its definition. [RFC7230](https://tools.ietf.org/html/rfc7230#section-3.2) states header names are case insensitive. If a response header is defined with the name `"Content-Type"`, it SHALL be ignored. |
+| content | Map[`string`, [Media Type Object](#media-type-object)] | A map containing descriptions of potential response payloads. The key is a media type or [media type range](https://tools.ietf.org/html/rfc7231#appendix-D) and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. `"text/plain"` overrides `"text/*"` |
| links | Map[`string`, [Link Object](#link-object) \| [Reference Object](#reference-object)] | A map of operations links that can be followed from the response. The key of the map is a short name for the link, following the naming constraints of the names for [Component Objects](#components-object). |
This object MAY be extended with [Specification Extensions](#specification-extensions).
@@ -2009,9 +2008,9 @@ Plain text response with headers:
"content": {
"text/plain": {
"schema": {
- "type": "string",
- "example": "whoa!"
- }
+ "type": "string"
+ },
+ "example": "whoa!"
}
},
"headers": {
@@ -2075,7 +2074,7 @@ description: object created
A map of possible out-of band callbacks related to the parent operation.
Each value in the map is a [Path Item Object](#path-item-object) that describes a set of requests that may be initiated by the API provider and the expected responses.
-The key value used to identify the path item object is an expression, evaluated at runtime, that identifies a URL to use for the callback operation.
+The key value used to identify the Path Item Object is an expression, evaluated at runtime, that identifies a URL to use for the callback operation.
To describe incoming requests from the API provider independent from another API call, use the [`webhooks`](#oas-webhooks) field.
@@ -2100,17 +2099,21 @@ For example, given the following HTTP request:
POST /subscribe/myevent?queryUrl=https://clientdomain.com/stillrunning HTTP/1.1
Host: example.org
Content-Type: application/json
-Content-Length: 187
+Content-Length: 188
{
- "failedUrl" : "https://clientdomain.com/failed",
- "successUrls" : [
+ "failedUrl": "https://clientdomain.com/failed",
+ "successUrls": [
"https://clientdomain.com/fast",
"https://clientdomain.com/medium",
"https://clientdomain.com/slow"
]
}
+```
+
+resulting in:
+```http
201 Created
Location: https://example.org/subscription/1
```
@@ -2123,9 +2126,9 @@ The following examples show how the various expressions evaluate, assuming the c
| $method | POST |
| $request.path.eventType | myevent |
| $request.query.queryUrl | |
-| $request.header.content-Type | application/json |
+| $request.header.content-type | application/json |
| $request.body#/failedUrl | |
-| $request.body#/successUrls/2 | |
+| $request.body#/successUrls/1 | |
| $response.header.Location | |
##### Callback Object Examples
@@ -2199,7 +2202,7 @@ The mutually exclusive fields in the Parameter or Media Type Objects are used to
The exact serialization and encoding is determined by various fields in the Parameter Object, or in the Media Type Object's [Encoding Object](#encoding-object).
Because examples using these fields represent the final serialized form of the data, they SHALL _override_ any `example` in the corresponding Schema Object.
-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`.
+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.
@@ -2218,10 +2221,12 @@ requestBody:
examples:
foo:
summary: A foo example
- value: { 'foo': 'bar' }
+ value:
+ foo: bar
bar:
summary: A bar example
- value: { 'bar': 'baz' }
+ value:
+ bar: baz
application/xml:
examples:
xmlExample:
@@ -2339,12 +2344,12 @@ In this example, the JSON string had to be serialized before encoding it into th
#### Link Object
-The `Link object` represents a possible design-time link for a response.
+The Link Object represents a possible design-time link for a response.
The presence of a link does not guarantee the caller's ability to successfully invoke it, rather it provides a known relationship and traversal mechanism between responses and other operations.
Unlike _dynamic_ links (i.e. links provided **in** the response payload), the OAS linking mechanism does not require link information in the runtime response.
-For computing links, and providing instructions to execute them, a [runtime expression](#runtime-expressions) is used for accessing values in an operation and using them as parameters while invoking the linked operation.
+For computing links and providing instructions to execute them, a [runtime expression](#runtime-expressions) is used for accessing values in an operation and using them as parameters while invoking the linked operation.
##### Fixed Fields
@@ -2365,7 +2370,7 @@ Because of the potential for name clashes, the `operationRef` syntax is preferre
for multi-document OpenAPI descriptions.
Note that it is not possible to provide a constant value to `parameters` that matches the syntax of a runtime expression.
-It is possible to have ambiguous parameter names, e.g. `name: id, in: path` and `name: path.id, in: query`; this is NOT RECOMMENDED and the behavior is implementation-defined, however implementations SHOULD prefer the qualified interpretation (`path.id` as a path parameter), as the names can always be qualified to disambiguate them (e.g. using `query.path.id` for the query parameter).
+It is possible to have ambiguous parameter names, e.g. `name: "id", in: "path"` and `name: "path.id", in: "query"`; this is NOT RECOMMENDED and the behavior is implementation-defined, however implementations SHOULD prefer the qualified interpretation (`path.id` as a path parameter), as the names can always be qualified to disambiguate them (e.g. using `query.path.id` for the query parameter).
##### Examples
@@ -2399,7 +2404,7 @@ paths:
operationId: getUserAddress
parameters:
# get the `id` field from the request path parameter named `id`
- userId: $request.path.id
+ userid: $request.path.id
# the path item of the linked operation
/users/{userid}/address:
parameters:
@@ -2431,10 +2436,10 @@ links:
```
Clients follow all links at their discretion.
-Neither permissions, nor the capability to make a successful call to that link, is guaranteed
+Neither permissions nor the capability to make a successful call to that link is guaranteed
solely by the existence of a relationship.
-##### OperationRef Examples
+##### `operationRef` Examples
As references to `operationId` MAY NOT be possible (the `operationId` is an optional
field in an [Operation Object](#operation-object)), references MAY also be made through a relative `operationRef`:
@@ -2459,8 +2464,8 @@ links:
username: $response.body#/username
```
-Note that in the use of `operationRef`, the _escaped forward-slash_ is necessary when
-using JSON Pointers, and it is necessary to URL-encode `{` and `}` as `%7B` and `%7D`, respectively when using JSON Pointers as URI fragments.
+Note that in the use of `operationRef` the _escaped forward-slash_ is necessary when
+using JSON Pointer, and it is necessary to URL-encode `{` and `}` as `%7B` and `%7D`, respectively, when using JSON Pointer as URI fragments.
##### Runtime Expressions
@@ -2470,22 +2475,22 @@ This mechanism is used by [Link Objects](#link-object) and [Callback Objects](#c
The runtime expression is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax
```abnf
- expression = ( "$url" / "$method" / "$statusCode" / "$request." source / "$response." source )
- source = ( header-reference / query-reference / path-reference / body-reference )
+ expression = "$url" / "$method" / "$statusCode" / "$request." source / "$response." source
+ source = header-reference / query-reference / path-reference / body-reference
header-reference = "header." token
- query-reference = "query." name
- path-reference = "path." name
- body-reference = "body" ["#" json-pointer ]
+ query-reference = "query." name
+ path-reference = "path." name
+ body-reference = "body" ["#" json-pointer ]
json-pointer = *( "/" reference-token )
reference-token = *( unescaped / escaped )
unescaped = %x00-2E / %x30-7D / %x7F-10FFFF
- ; %x2F ('/') and %x7E ('~') are excluded from 'unescaped'
+ ; %x2F ('/') and %x7E ('~') are excluded from 'unescaped'
escaped = "~" ( "0" / "1" )
- ; representing '~' and '/', respectively
+ ; representing '~' and '/', respectively
name = *( CHAR )
token = 1*tchar
- tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." /
- "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA
+ tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "."
+ / "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA
```
Here, `json-pointer` is taken from [RFC6901](https://tools.ietf.org/html/rfc6901), `char` from [RFC7159](https://tools.ietf.org/html/rfc7159#section-7) and `token` from [RFC7230](https://tools.ietf.org/html/rfc7230#section-3.2.6).
@@ -2517,7 +2522,7 @@ The Header Object follows the structure of the [Parameter Object](#parameter-obj
1. `name` MUST NOT be specified, it is given in the corresponding `headers` map.
1. `in` MUST NOT be specified, it is implicitly in `header`.
-1. All traits that are affected by the location MUST be applicable to a location of `header` (for example, [`style`](#parameter-style)). This means that `allowEmptyValue` and `allowReserved` MUST NOT be used, and `style`, if used, MUST be limited to `simple`.
+1. All traits that are affected by the location MUST be applicable to a location of `header` (for example, [`style`](#parameter-style)). This means that `allowEmptyValue` and `allowReserved` MUST NOT be used, and `style`, if used, MUST be limited to `"simple"`.
##### Fixed Fields
@@ -2536,16 +2541,16 @@ This object MAY be extended with [Specification Extensions](#specification-exten
###### Fixed Fields for use with `schema`
For simpler scenarios, a [`schema`](#header-schema) and [`style`](#header-style) can describe the structure and syntax of the header.
-When `example` or `examples` are provided in conjunction with the `schema` object, the example MUST follow the prescribed serialization strategy for the header.
+When `example` or `examples` are provided in conjunction with the `schema` field, the example MUST follow the prescribed serialization strategy for the header.
Serializing with `schema` is NOT RECOMMENDED for headers with parameters (name=value pairs following a `;`) in their values, or where values might have non-URL-safe characters; see [Appendix D](#appendix-d-serializing-headers-and-cookies) for details.
-When `example` or `examples` are provided in conjunction with the `schema` object, the example SHOULD match the specified schema and follow the prescribed serialization strategy for the header.
+When `example` or `examples` are provided in conjunction with the `schema` field, the example SHOULD match the specified schema and follow the prescribed serialization strategy for the header.
The `example` and `examples` fields are mutually exclusive, and if either is present it SHALL _override_ any `example` in the schema.
| Field Name | Type | Description |
| ---- | :----: | ---- |
-| style | `string` | Describes how the header value will be serialized. The default (and only legal value for headers) is `simple`. |
+| style | `string` | Describes how the header value will be serialized. The default (and only legal value for headers) is `"simple"`. |
| explode | `boolean` | When this is true, header values of type `array` or `object` generate a single header whose value is a comma-separated list of the array items or key-value pairs of the map, see [Style Examples](#style-examples). For other data types this property has no effect. The default value is `false`. |
| schema | [Schema Object](#schema-object) \| [Reference Object](#reference-object) | The schema defining the type used for the header. |
| example | Any | Example of the header's potential value; see [Working With Examples](#working-with-examples). |
@@ -2655,7 +2660,7 @@ See the rules for resolving [Relative References](#relative-references-in-api-de
This object cannot be extended with additional properties and any properties added SHALL be ignored.
-Note that this restriction on additional properties is a difference between Reference Objects and [`Schema Objects`](#schema-object) that contain a `$ref` keyword.
+Note that this restriction on additional properties is a difference between Reference Objects and [Schema Objects](#schema-object) that contain a `$ref` keyword.
##### Reference Object Example
@@ -2696,7 +2701,7 @@ $ref: definitions.yaml#/Pet
#### Schema Object
The Schema Object allows the definition of input and output data types.
-These types can be objects, but also primitives and arrays. This object is a superset of the [JSON Schema Specification Draft 2020-12](https://tools.ietf.org/html/draft-bhutton-json-schema-00).
+These types can be objects, but also primitives and arrays. This object is a superset of the [JSON Schema Specification Draft 2020-12](https://tools.ietf.org/html/draft-bhutton-json-schema-00). The empty schema (which allows any instance to validate) MAY be represented by the boolean value `true` and a schema which allows no instance to validate MAY be represented by the boolean value `false`.
For more information about the properties, see [JSON Schema Core](https://tools.ietf.org/html/draft-bhutton-json-schema-00) and [JSON Schema Validation](https://tools.ietf.org/html/draft-bhutton-json-schema-validation-00).
@@ -2705,7 +2710,7 @@ Where JSON Schema indicates that behavior is defined by the application (e.g. fo
##### Properties
-The OpenAPI Schema Object [dialect](https://tools.ietf.org/html/draft-bhutton-json-schema-00#section-4.3.3) is defined as requiring the [OAS base vocabulary](#base-vocabulary), in addition to the vocabularies as specified in the JSON Schema draft 2020-12 [general purpose meta-schema](https://tools.ietf.org/html/draft-bhutton-json-schema-00#section-8).
+The OpenAPI Schema Object [dialect](https://tools.ietf.org/html/draft-bhutton-json-schema-00#section-4.3.3) is defined as requiring the [OAS base vocabulary](#base-vocabulary), in addition to the vocabularies as specified in the JSON Schema Specification Draft 2020-12 [general purpose meta-schema](https://tools.ietf.org/html/draft-bhutton-json-schema-00#section-8).
The OpenAPI Schema Object dialect for this version of the specification is identified by the URI `https://spec.openapis.org/oas/3.1/dialect/base` (the "OAS dialect schema id").
@@ -2723,7 +2728,7 @@ JSON Schema implementations MAY choose to treat keywords defined by the OpenAPI
| Field Name | Type | Description |
| ---- | :----: | ---- |
-| discriminator | [Discriminator Object](#discriminator-object) | Adds support for polymorphism. The discriminator is an object name that is used to differentiate between other schemas which may satisfy the payload description. See [Composition and Inheritance](#composition-and-inheritance-polymorphism) for more details. |
+| discriminator | [Discriminator Object](#discriminator-object) | Adds support for polymorphism. The discriminator is used to determine which of a set of schemas a payload is expected to satisfy. See [Composition and Inheritance](#composition-and-inheritance-polymorphism) for more details. |
| xml | [XML Object](#xml-object) | This MAY be used only on properties schemas. It has no effect on root schemas. Adds additional metadata to describe the XML representation of this property. |
| externalDocs | [External Documentation Object](#external-documentation-object) | Additional external documentation for this schema. |
| example | Any | A free-form property to include an example of an instance for this schema. To represent examples that cannot be naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary.
**Deprecated:** The `example` property has been deprecated in favor of the JSON Schema `examples` keyword. Use of `example` is discouraged, and later versions of this specification may remove it. |
@@ -2736,14 +2741,13 @@ The OpenAPI Specification allows combining and extending model definitions using
`allOf` takes an array of object definitions that are validated _independently_ but together compose a single object.
While composition offers model extensibility, it does not imply a hierarchy between the models.
-To support polymorphism, the OpenAPI Specification adds the `discriminator` field.
-When used, the `discriminator` will be the name of the property that decides which schema definition validates the structure of the model.
+To support polymorphism, the OpenAPI Specification adds the [`discriminator`](#schema-discriminator) field.
+When used, the `discriminator` indicates the name of the property that hints which schema definition is expected to validate the structure of the model.
As such, the `discriminator` field MUST be a required field.
There are two ways to define the value of a discriminator for an inheriting instance.
* Use the schema name.
-* Override the schema name by overriding the property with a new value. If a new value exists, this takes precedence over the schema name.
- As such, inline schema definitions, which do not have a given id, _cannot_ be used in polymorphism.
+* [Override the schema name](#discriminator-mapping) by overriding the property with a new value. If a new value exists, this takes precedence over the schema name.
###### Generic (Template) Data Structures
@@ -2772,7 +2776,7 @@ However, for maximum interoperability, it is RECOMMENDED that OpenAPI descriptio
##### Schema Object Examples
-###### Primitive Sample
+###### Primitive Example
```json
{
@@ -3150,7 +3154,7 @@ components:
$id: fully_generic_array
type: array
items:
- $dynamicRef: "#generic-array"
+ $dynamicRef: '#generic-array'
$defs:
allowAll:
$dynamicAnchor: generic-array
@@ -3237,7 +3241,7 @@ However, the exact nature of such conversions are implementation-defined.
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).
-In OAS 3.0, a response payload MAY be described to be exactly one of any number of types:
+In OAS 3.x, a response payload MAY be described to be exactly one of any number of types:
```yaml
MyResponseType:
@@ -3247,7 +3251,7 @@ MyResponseType:
- $ref: '#/components/schemas/Lizard'
```
-which means the payload _MUST_, by validation, match exactly one of the schemas described by `Cat`, `Dog`, or `Lizard`. In this case, a discriminator MAY act as a "hint" to shortcut validation and selection of the matching schema which may be a costly operation, depending on the complexity of the schema. We can then describe exactly which field tells us which schema to use:
+which means the payload _MUST_, by validation, match exactly one of the schemas described by `Cat`, `Dog`, or `Lizard`. Deserialization of a `oneOf` can be a costly operation, as it requires determining which schema matches the payload and thus should be used in deserialization. This problem also exists for `anyOf` schemas. A `discriminator` MAY be used as a "hint" to improve the efficiency of selection of the matching schema. The `discriminator` field cannot change the validation result of the `oneOf`, it can only help make the deserialization more efficient and provide better error messaging. We can specify the exact field that tells us which schema is expected to match the instance:
```yaml
MyResponseType:
@@ -3268,9 +3272,9 @@ The expectation now is that a property with name `petType` _MUST_ be present in
}
```
-Will indicate that the `Cat` schema be used in conjunction with this payload.
+will indicate that the `Cat` schema is expected to match this payload.
-In scenarios where the value of the discriminator field does not match the schema name or implicit mapping is not possible, an optional `mapping` definition MAY be used:
+In scenarios where the value of the `discriminator` field does not match the schema name or implicit mapping is not possible, an optional `mapping` definition MAY be used:
```yaml
MyResponseType:
@@ -3288,7 +3292,7 @@ MyResponseType:
Here the discriminating value of `dog` will map to the schema `#/components/schemas/Dog`, rather than the default (implicit) value of `#/components/schemas/dog`. If the discriminating value does not match an implicit or explicit mapping, no schema can be determined and validation SHOULD fail.
-When used in conjunction with the `anyOf` construct, the use of the discriminator can avoid ambiguity where multiple schemas may satisfy a single payload.
+When used in conjunction with the `anyOf` construct, the use of the discriminator can avoid ambiguity for serializers/deserializers where multiple schemas may satisfy a single payload.
This example shows the `allOf` usage, which avoids needing to reference all child schemas in the parent:
@@ -3332,16 +3336,16 @@ components:
type: boolean
```
-a payload like this:
+Validated against the `Pet` schema, a payload like this:
```json
{
"petType": "Cat",
- "name": "misty"
+ "name": "Misty"
}
```
-will indicate that the `Cat` schema be used. Likewise this schema:
+will indicate that the `#/components/schemas/Cat` schema is expected to match. Likewise this payload:
```json
{
@@ -3350,7 +3354,7 @@ will indicate that the `Cat` schema be used. Likewise this schema:
}
```
-will map to `Dog` because of the definition in the `mapping` element.
+will map to `#/components/schemas/Dog` because the `dog` entry in the `mapping` element maps to `Dog` which is the schema name for `#/components/schemas/Dog`.
#### XML Object
@@ -3363,15 +3367,15 @@ See examples for expected behavior.
| Field Name | Type | Description |
| ---- | :----: | ---- |
-| name | `string` | Replaces the name of the element/attribute used for the described schema property. When defined within `items`, it will affect the name of the individual XML elements within the list. When defined alongside `type` being `array` (outside the `items`), it will affect the wrapping element and only if `wrapped` is `true`. If `wrapped` is `false`, it will be ignored. |
+| name | `string` | Replaces the name of the element/attribute used for the described schema property. When defined within `items`, it will affect the name of the individual XML elements within the list. When defined alongside `type` being `"array"` (outside the `items`), it will affect the wrapping element if and only if `wrapped` is `true`. If `wrapped` is `false`, it will be ignored. |
| namespace | `string` | The URI of the namespace definition. Value MUST be in the form of a non-relative URI. |
| prefix | `string` | The prefix to be used for the [name](#xml-name). |
| attribute | `boolean` | Declares whether the property definition translates to an attribute instead of an element. Default value is `false`. |
-| wrapped | `boolean` | MAY be used only for an array definition. Signifies whether the array is wrapped (for example, ``) or unwrapped (``). Default value is `false`. The definition takes effect only when defined alongside `type` being `array` (outside the `items`). |
+| wrapped | `boolean` | MAY be used only for an array definition. Signifies whether the array is wrapped (for example, ``) or unwrapped (``). Default value is `false`. The definition takes effect only when defined alongside `type` being `"array"` (outside the `items`). |
This object MAY be extended with [Specification Extensions](#specification-extensions).
-The `namespace` keyword is intended to match the syntax of [XML namespaces](https://www.w3.org/TR/xml-names11/), although there are a few caveats:
+The `namespace` field is intended to match the syntax of [XML namespaces](https://www.w3.org/TR/xml-names11/), although there are a few caveats:
* Versions 3.1.0, 3.0.3, and earlier of this specification erroneously used the term "absolute URI" instead of "non-relative URI", so authors using namespaces that include a fragment should check tooling support carefully.
* XML allows but discourages relative URI-references, while this specification outright forbids them.
@@ -3716,7 +3720,7 @@ animals:
Defines a security scheme that can be used by the operations.
-Supported schemes are HTTP authentication, an API key (either as a header, a cookie parameter or as a query parameter), mutual TLS (use of a client certificate), OAuth2's common flows (implicit, password, client credentials and authorization code) as defined in [RFC6749](https://tools.ietf.org/html/rfc6749), OAuth2 device authorization flow as defined in [RFC8628](https://tools.ietf.org/html/rfc8628), and [OpenID Connect Core](https://openid.net/specs/openid-connect-core-1_0.html).
+Supported schemes are HTTP authentication, an API key (either as a header, a cookie parameter or as a query parameter), mutual TLS (use of a client certificate), OAuth2's common flows (implicit, password, client credentials and authorization code) as defined in [RFC6749](https://tools.ietf.org/html/rfc6749), OAuth2 device authorization flow as defined in [RFC8628](https://tools.ietf.org/html/rfc8628), and [[OpenID-Connect-Core]].
Please note that as of 2020, the implicit flow is about to be deprecated by [OAuth 2.0 Security Best Current Practice](https://tools.ietf.org/html/draft-ietf-oauth-security-topics). Recommended for most use case is Authorization Code Grant flow with PKCE.
##### Fixed Fields
@@ -3730,15 +3734,15 @@ Please note that as of 2020, the implicit flow is about to be deprecated by [OAu
| scheme | `string` | `http` | **REQUIRED**. The name of the HTTP Authentication scheme to be used in the [Authorization header as defined in RFC7235](https://tools.ietf.org/html/rfc7235#section-5.1). The values used SHOULD be registered in the [IANA Authentication Scheme registry](https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml). The value is case-insensitive, as defined in [RFC7235](https://datatracker.ietf.org/doc/html/rfc7235#section-2.1). |
| bearerFormat | `string` | `http` (`"bearer"`) | A hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes. |
| flows | [OAuth Flows Object](#oauth-flows-object) | `oauth2` | **REQUIRED**. An object containing configuration information for the flow types supported. |
-| openIdConnectUrl | `string` | `openIdConnect` | **REQUIRED**. [Well-known URL](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig) to discover the [OpenID provider metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). |
+| openIdConnectUrl | `string` | `openIdConnect` | **REQUIRED**. [Well-known URL](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig) to discover the [[OpenID-Connect-Discovery]] [provider metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). |
| oauth2MetadataUrl | `string` | `oauth2` | URL to the oauth2 authorization server metadata [RFC8414](https://datatracker.ietf.org/doc/html/rfc8414). TLS is required. |
| deprecated | `boolean` | Declares this security scheme to be deprecated. Consumers SHOULD refrain from usage of the declared scheme. Default value is `false`. | |
This object MAY be extended with [Specification Extensions](#specification-extensions).
-##### Security Scheme Object Example
+##### Security Scheme Object Examples
-###### Basic Authentication Sample
+###### Basic Authentication Example
```json
{
@@ -3752,23 +3756,23 @@ type: http
scheme: basic
```
-###### API Key Sample
+###### API Key Example
```json
{
"type": "apiKey",
- "name": "api_key",
+ "name": "api-key",
"in": "header"
}
```
```yaml
type: apiKey
-name: api_key
+name: api-key
in: header
```
-###### JWT Bearer Sample
+###### JWT Bearer Example
```json
{
@@ -3784,7 +3788,21 @@ scheme: bearer
bearerFormat: JWT
```
-###### Implicit OAuth2 Sample
+###### MutualTLS Example
+
+```json
+{
+ "type": "mutualTLS",
+ "description": "Cert must be signed by example.com CA"
+}
+```
+
+```yaml
+type: mutualTLS
+description: Cert must be signed by example.com CA
+```
+
+###### Implicit OAuth2 Example
```json
{
@@ -3847,7 +3865,7 @@ Configuration details for a supported OAuth Flow
This object MAY be extended with [Specification Extensions](#specification-extensions).
-##### OAuth Flow Object Examples
+##### OAuth Flow Object Example
```JSON
{
@@ -3968,7 +3986,7 @@ security:
See [Resolving Implicit Connections](#resolving-implicit-connections) for more information.
-First, our entry document is where parsing begins. It defines the `MySecurity` security scheme to be JWT-based, and it defines a Path Item as a reference to a component in another document:
+First, our [entry document](#openapi-description-structure) is where parsing begins. It defines the `MySecurity` security scheme to be JWT-based, and it defines a Path Item as a reference to a component in another document:
```HTTP
GET /api/description/openapi HTTP/1.1
@@ -4064,13 +4082,13 @@ In the `other` document, the referenced path item has a Security Requirement for
While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
-The extensions properties are implemented as patterned fields that are always prefixed by `"x-"`.
+The extensions properties are implemented as patterned fields that are always prefixed by `x-`.
| Field Pattern | Type | Description |
| ---- | :--: | ---- |
| ^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. Field names beginning `x-oai-` and `x-oas-` are reserved for uses defined by the [OpenAPI Initiative](https://www.openapis.org/). The value can be any valid JSON value (`null`, a primitive, an array or an object.) |
-The OpenAPI Initiative maintains several [extension registries](https://spec.openapis.org/registry/index.html), including registries for [individual extension keywords](https://spec.openapis.org/registry/extension/) and [extension keyword namespaces](https://spec.openapis.org/registry/namespace/).
+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.
It is therefore RECOMMENDED that implementations be designed for extensibility to support community experimentation.
@@ -4097,8 +4115,8 @@ OpenAPI description documents use JSON, YAML, and JSON Schema, and therefore sha
* [JSON](https://www.iana.org/assignments/media-types/application/json)
* [YAML](https://www.iana.org/assignments/media-types/application/yaml)
-* [JSON Schema Core](https://json-schema.org/draft/2020-12/json-schema-core#section-13)
-* [JSON Schema Validation](https://json-schema.org/draft/2020-12/json-schema-validation#name-security-considerations)
+* [JSON Schema Core](https://tools.ietf.org/html/draft-bhutton-json-schema-00#section-13)
+* [JSON Schema Validation](https://tools.ietf.org/html/draft-bhutton-json-schema-validation-00#section-10)
### Tooling and Usage Scenarios
@@ -4120,6 +4138,8 @@ Certain properties allow the use of Markdown which can contain HTML including sc
| Version | Date | Notes |
| ---- | ---- | ---- |
+| 3.2.0 | TBD | Release of the OpenAPI Specification 3.2.0 |
+| 3.1.1 | TBD | Patch release of the OpenAPI Specification 3.1.1 |
| 3.1.0 | 2021-02-15 | Release of the OpenAPI Specification 3.1.0 |
| 3.1.0-rc1 | 2020-10-08 | rc1 of the 3.1 specification |
| 3.1.0-rc0 | 2020-06-18 | rc0 of the 3.1 specification |
@@ -4140,22 +4160,22 @@ Certain properties allow the use of Markdown which can contain HTML including sc
Serializing typed data to plain text, which can occur in `text/plain` message bodies or `multipart` parts, as well as in the `application/x-www-form-urlencoded` format in either URL query strings or message bodies, involves significant implementation- or application-defined behavior.
-Schema Objects validate data based on the [JSON Schema data model](https://datatracker.ietf.org/doc/html/draft-wright-json-schema-00#section-4.2), which only recognizes four primitive data types: strings (which are [only broadly interoperable as UTF-8](https://datatracker.ietf.org/doc/html/rfc7159#section-8.1)), numbers, booleans, and `null`.
-Notably, integers are not a distinct type from other numbers, with `type: integer` being a convenience defined mathematically, rather than based on the presence or absence of a decimal point in any string representation.
+[Schema Objects](#schema-object) validate data based on the [JSON Schema data model](https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00#section-4.2.1), which only recognizes four primitive data types: strings (which are [only broadly interoperable as UTF-8](https://datatracker.ietf.org/doc/html/rfc7159#section-8.1)), numbers, booleans, and `null`.
+Notably, integers are not a distinct type from other numbers, with `type: "integer"` being a convenience defined mathematically, rather than based on the presence or absence of a decimal point in any string representation.
-The [Parameter Object](#parameter-object), [Header Object](#header-object) and [Encoding Object](#encoding-object) offer features to control how to arrange values from array or object types.
+The [Parameter Object](#parameter-object), [Header Object](#header-object), and [Encoding Object](#encoding-object) offer features to control how to arrange values from array or object types.
They can also be used to control how strings are further encoded to avoid reserved or illegal characters.
However, there is no general-purpose specification for converting schema-validated non-UTF-8 primitive data types (or entire arrays or objects) to strings.
Two cases do offer standards-based guidance:
-* [RFC3987 §3.1](https://datatracker.ietf.org/doc/html/rfc3987#section-3.1) provides guidance for converting non-Unicode strings to UTF-8, particularly in the context of URIs (and by extension, the form media types which use the same encoding rules)
-* [RFC6570 §2.3](https://www.rfc-editor.org/rfc/rfc6570#section-2.3) specifies which values, including but not limited to `null`, are considered _undefined_ and therefore treated specially in the expansion process when serializing based on that specification
+* [RFC3987](https://datatracker.ietf.org/doc/html/rfc3987#section-3.1) provides guidance for converting non-Unicode strings to UTF-8, particularly in the context of URIs (and by extension, the form media types which use the same encoding rules)
+* [RFC6570](https://www.rfc-editor.org/rfc/rfc6570#section-2.3) specifies which values, including but not limited to `null`, are considered _undefined_ and therefore treated specially in the expansion process when serializing based on that specification
Implementations of RFC6570 often have their own conventions for converting non-string values, but these are implementation-specific and not defined by the RFC itself.
This is one reason for the OpenAPI Specification to leave these conversions as implementation-defined: It allows using RFC6570 implementations regardless of how they choose to perform the conversions.
-To control the serialization of numbers, booleans, and `null` (or other values RFC6570 deems to be undefined) more precisely, schemas can be defined as `type: string` and constrained using `pattern`, `enum`, `format`, and other keywords to communicate how applications must pre-convert their data prior to schema validation.
+To control the serialization of numbers, booleans, and `null` (or other values RFC6570 deems to be undefined) more precisely, schemas can be defined as `type: "string"` and constrained using `pattern`, `enum`, `format`, and other keywords to communicate how applications must pre-convert their data prior to schema validation.
The resulting strings would not require any further type conversion.
The `format` keyword can assist in serialization.
@@ -4166,7 +4186,7 @@ Requiring input as pre-formatted, schema-validated strings also improves round-t
## Appendix C: Using RFC6570 Implementations
-Serialization is defined in terms of RFC6570 URI Templates in two scenarios:
+Serialization is defined in terms of [RFC6570](https://www.rfc-editor.org/rfc/rfc6570) URI Templates in two scenarios:
| Object | Condition |
| ---- | ---- |
@@ -4175,10 +4195,10 @@ Serialization is defined in terms of RFC6570 URI Templates in two scenarios:
Implementations of this specification MAY use an implementation of RFC6570 to perform variable expansion, however, some caveats apply.
-Note that when using `style: form` RFC6570 expansion to produce an `application/x-www-form-urlencoded` HTTP message body, it is necessary to remove the `?` prefix that is produced to satisfy the URI query string syntax.
+Note that when using `style: "form"` RFC6570 expansion to produce an `application/x-www-form-urlencoded` HTTP message body, it is necessary to remove the `?` prefix that is produced to satisfy the URI query string syntax.
-When using `style` and similar keywords to produce a `multipart/form-data` body, the query string names are placed in the `name` parameter to the `Content-Disposition` part header, and the values are placed in the corresponding part body; the `?`, `=`, and `&` characters are not used.
-Note that while [RFC7578](https://datatracker.ietf.org/doc/html/rfc7578) allows using RFC3986 percent-encoding in "file names", it does not otherwise address the use of percent-encoding within the format.
+When using `style` and similar keywords to produce a `multipart/form-data` body, the query string names are placed in the `name` parameter of the `Content-Disposition` part header, and the values are placed in the corresponding part body; the `?`, `=`, and `&` characters are not used.
+Note that while [RFC7578](https://datatracker.ietf.org/doc/html/rfc7578) allows using [[RFC3986]] percent-encoding in "file names", it does not otherwise address the use of percent-encoding within the format.
RFC7578 discusses character set and encoding issues for `multipart/form-data` in detail, and it is RECOMMENDED that OpenAPI Description authors read this guidance carefully before deciding to use RFC6570-based serialization with this media type.
Note also that not all RFC6570 implementations support all four levels of operators, all of which are needed to fully support the OpenAPI Specification's usage.
@@ -4186,20 +4206,20 @@ Using an implementation with a lower level of support will require additional ma
### Equivalences Between Fields and RFC6570 Operators
-Certain field values translate to RFC6570 operators (or lack thereof):
+Certain field values translate to RFC6570 [operators](https://datatracker.ietf.org/doc/html/rfc6570#section-2.2) (or lack thereof):
| field | value | equivalent |
| ---- | ---- | ---- |
-| style | simple | _n/a_ |
-| style | matrix | `;` prefix operator |
-| style | label | `.` prefix operator |
-| style | form | `?` prefix operator |
+| style | `"simple"` | _n/a_ |
+| style | `"matrix"` | `;` prefix operator |
+| style | `"label"` | `.` prefix operator |
+| style | `"form"` | `?` prefix operator |
| allowReserved | `false` | _n/a_ |
| allowReserved | `true` | `+` prefix operator |
| explode | `false` | _n/a_ |
| explode | `true` | `*` modifier suffix |
-Multiple `style: form` parameters are equivalent to a single RFC6570 [variable list](https://www.rfc-editor.org/rfc/rfc6570#section-2.2) using the `?` prefix operator:
+Multiple `style: "form"` parameters are equivalent to a single RFC6570 [variable list](https://www.rfc-editor.org/rfc/rfc6570#section-2.2) using the `?` prefix operator:
```YAML
parameters:
@@ -4214,14 +4234,14 @@ parameters:
type: string
```
-This example is equivalent to RFC6570's `{?foo*,bar}`, and **_NOT_** `{?foo*}{&bar}`, which is problematic because if `foo` is not defined, the result will be an invalid URI.
+This example is equivalent to RFC6570's `{?foo*,bar}`, and **_NOT_** `{?foo*}{&bar}`. The latter is problematic because if `foo` is not defined, the result will be an invalid URI.
The `&` prefix operator has no equivalent in the Parameter Object.
Note that RFC6570 does not specify behavior for compound values beyond the single level addressed by `explode`. The results of using objects or arrays where no behavior is clearly specified for them is implementation-defined.
### Non-RFC6570 Field Values and Combinations
-Configurations with no direct RFC6570 equivalent SHOULD also be handled according to RFC6570.
+Configurations with no direct [RFC6570](https://datatracker.ietf.org/doc/html/rfc6570) equivalent SHOULD also be handled according to RFC6570.
Implementations MAY create a properly delimited URI Template with variables for individual names and values using RFC6570 regular or reserved expansion (based on `allowReserved`).
This includes:
@@ -4230,7 +4250,7 @@ This includes:
* the combination of the style `form` with `allowReserved: true`, which is not allowed because only one prefix operator can be used at a time
* any parameter name that is not a legal RFC6570 variable name
-The Parameter Object's `name` field has a much more permissive syntax than [RFC6570 variable name syntax](https://www.rfc-editor.org/rfc/rfc6570#section-2.3).
+The Parameter Object's `name` field has a much more permissive syntax than RFC6570 [variable name syntax](https://www.rfc-editor.org/rfc/rfc6570#section-2.3).
A parameter name that includes characters outside of the allowed RFC6570 variable character set MUST be percent-encoded before it can be used in a URI Template.
### Examples
@@ -4250,7 +4270,7 @@ words:
#### RFC6570-Equivalent Expansion
-This array of parameter objects uses regular `style: form` expansion, fully supported by RFC6570:
+This array of Parameter Objects uses regular `style: "form"` expansion, fully supported by [RFC6570](https://datatracker.ietf.org/doc/html/rfc6570):
```YAML
parameters:
@@ -4284,7 +4304,7 @@ when expanded with the data given earlier, we get:
#### Expansion With Non-RFC6570-Supported Options
But now let's say that (for some reason), we really want that `/` in the `b` formula to show up as-is in the query string, and we want our words to be space-separated like in a written phrase.
-To do that, we'll add `allowReserved: true` to `formulas`, and change to `style: spaceDelimited` for `words`:
+To do that, we'll add `allowReserved: true` to `formulas`, and change to `style: "spaceDelimited"` for `words`:
```YAML
parameters:
@@ -4305,7 +4325,7 @@ parameters:
type: string
```
-We can't combine the `?` and `+` RFC6570 prefixes, and there's no way with RFC6570 to replace the `,` separator with a space character.
+We can't combine the `?` and `+` RFC6570 [prefixes](https://datatracker.ietf.org/doc/html/rfc6570#section-2.4.1), and there's no way with RFC6570 to replace the `,` separator with a space character.
So we need to restructure the data to fit a manually constructed URI Template that passes all of the pieces through the right sort of expansion.
Here is one such template, using a made-up convention of `words.0` for the first entry in the words value, `words.1` for the second, and `words.2` for the third:
@@ -4344,7 +4364,7 @@ The `/` and the pre-percent-encoded `%2B` have been left alone, but the disallow
#### Undefined Values and Manual URI Template Construction
-Care must be taken when manually constructing templates to handle the values that [RFC6570 considers to be _undefined_](https://datatracker.ietf.org/doc/html/rfc6570#section-2.3) correctly:
+Care must be taken when manually constructing templates to handle the values that RFC6570 [considers to be _undefined_](https://datatracker.ietf.org/doc/html/rfc6570#section-2.3) correctly:
```YAML
formulas: {}
@@ -4392,7 +4412,7 @@ parameters:
type: string
```
-We can't just pass `❤️: love!` to an RFC6570 implementation.
+We can't just pass `❤️: "love!"` to an RFC6570 implementation.
Instead, we have to pre-percent-encode the name (which is a six-octet UTF-8 sequence) in both the data and the URI Template:
```YAML
@@ -4411,25 +4431,25 @@ This will expand to the result:
## Appendix D: Serializing Headers and Cookies
-RFC6570's percent-encoding behavior is not always appropriate for `in: header` and `in: cookie` parameters.
+[RFC6570](https://www.rfc-editor.org/rfc/rfc6570)'s percent-encoding behavior is not always appropriate for `in: "header"` and `in: "cookie"` parameters.
In many cases, it is more appropriate to use `content` with a media type such as `text/plain` and require the application to assemble the correct string.
-For both cookies ([RFC6265](https://www.rfc-editor.org/rfc/rfc6265)) and HTTP headers using the structured fields ([RFC8941](https://www.rfc-editor.org/rfc/rfc8941)) syntax, non-ASCII content is handled using base64 encoding (`contentEncoding: base64`).
-Note that the standard base64 encoding alphabet includes non-URL-safe characters that are percent-encoded by RFC6570 expansion; serializing values through both encodings is NOT RECOMMENDED.
+For both [RFC6265](https://www.rfc-editor.org/rfc/rfc6265) cookies and HTTP headers using the [RFC8941](https://www.rfc-editor.org/rfc/rfc8941) structured fields syntax, non-ASCII content is handled using base64 encoding (`contentEncoding: "base64"`).
+Note that the standard base64-encoding alphabet includes non-URL-safe characters that are percent-encoded by RFC6570 expansion; serializing values through both encodings is NOT RECOMMENDED.
While `contentEncoding` also supports the `base64url` encoding, which is URL-safe, the header and cookie RFCs do not mention this encoding.
Most HTTP headers predate the structured field syntax, and a comprehensive assessment of their syntax and encoding rules is well beyond the scope of this specification.
-While [RFC8187](https://www.rfc-editor.org/rfc/rfc8187) recommends percent-encoding HTTP field (header or trailer) parameters, these parameters appear after a `;` character.
-With `style: simple`, that delimiter would itself be percent-encoded, violating the general HTTP field syntax.
+While [RFC8187](https://www.rfc-editor.org/rfc/rfc8187) recommends percent-encoding HTTP (header or trailer) field parameters, these parameters appear after a `;` character.
+With `style: "simple"`, that delimiter would itself be percent-encoded, violating the general HTTP field syntax.
-Using `style: form` with `in: cookie` is ambiguous for a single value, and incorrect for multiple values.
+Using `style: "form"` with `in: "cookie"` is ambiguous for a single value, and incorrect for multiple values.
This is true whether the multiple values are the result of using `explode: true` or not.
-This style is specified to be equivalent to RFC6570 form expansion which includes the `?` character (see Appendix C for more details), which is not part of the cookie syntax.
+This style is specified to be equivalent to RFC6570 form expansion which includes the `?` character (see [Appendix C](#appendix-c-using-rfc6570-implementations) for more details), which is not part of the cookie syntax.
However, examples of this style in past versions of this specification have not included the `?` prefix, suggesting that the comparison is not exact.
Because implementations that rely on an RFC6570 implementation and those that perform custom serialization based on the style example will produce different results, it is implementation-defined as to which of the two results is correct.
-For multiple values, `style: form` is always incorrect as name=value pairs in cookies are delimited by `;` (a semicolon followed by a space character) rather than `&`.
+For multiple values, `style: "form"` is always incorrect as name=value pairs in cookies are delimited by `;` (a semicolon followed by a space character) rather than `&`.
## Appendix E: Percent-Encoding and Form Media Types
@@ -4456,7 +4476,7 @@ This means that while these three characters are reserved-but-allowed in query s
### Percent-Encoding and `form-data`
-[RFC7578 §2](https://datatracker.ietf.org/doc/html/rfc7578#section-2) suggests RFC3986-based percent-encoding as a mechanism to keep text-based per-part header data such as file names within the ASCII character set.
+[RFC7578](https://datatracker.ietf.org/doc/html/rfc7578#section-2) suggests RFC3986-based percent-encoding as a mechanism to keep text-based per-part header data such as file names within the ASCII character set.
This suggestion was not part of older (pre-2015) specifications for `form-data`, so care must be taken to ensure interoperability.
The `form-data` media type allows arbitrary text or binary data in its parts, so percent-encoding is not needed and is likely to cause interoperability problems unless the `Content-Type` of the part is defined to require it.
@@ -4471,28 +4491,28 @@ This specification normatively cites the following relevant standards:
| Specification | Date | OAS Usage | Percent-Encoding | Notes |
| ---- | ---- | ---- | ---- | ---- |
-| [RFC3986 URI Generic Syntax](https://datatracker.ietf.org/doc/html/rfc3986) | 01/2005 | URI/URL syntax | RFC3986 | obsoletes RFC1738, RFC2396 |
-| [RFC6570 URI Template](https://datatracker.ietf.org/doc/html/rfc6570) | 03/2012 | style-based serialization | RFC3986 | does not use `+` for form‑urlencoded |
-| [RFC1866 §8.2.1 form‑urlencoded](https://datatracker.ietf.org/doc/html/rfc1866#section-8.2.1) | 11/1995 | content-based serialization | RFC1738 | obsoleted by [HTML 4.01 §17.13.4.1](https://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1), [WHATWG URL §5](https://url.spec.whatwg.org/#urlencoded-serializing) |
+| [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) | 01/2005 | URI/URL syntax | [[RFC3986]] | obsoletes [[RFC1738]], [[RFC2396]] |
+| [RFC6570](https://www.rfc-editor.org/rfc/rfc6570) | 03/2012 | style-based serialization | [[RFC3986]] | does not use `+` for form‑urlencoded |
+| [RFC1866](https://datatracker.ietf.org/doc/html/rfc1866#section-8.2.1) | 11/1995 | content-based serialization | [[RFC1738]] | obsoleted by [[HTML401]] [Section 17.13.4.1](https://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1), [[URL]] [Section 5](https://url.spec.whatwg.org/#urlencoded-serializing) |
Style-based serialization is used in the [Parameter Object](#parameter-object) when `schema` is present, and in the [Encoding Object](#encoding-object) when at least one of `style`, `explode`, or `allowReserved` is present.
See [Appendix C](#appendix-c-using-rfc6570-implementations) for more details of RFC6570's two different approaches to percent-encoding, including an example involving `+`.
-Content-based serialization is defined by the [Media Type Object](#media-type-object), and used with the [Parameter Object](#parameter-object) when the `content` field is present, and with the [Encoding Object](#encoding-object) based on the `contentType` field when the style fields listed in the previous section are absent.
+Content-based serialization is defined by the [Media Type Object](#media-type-object), and used with the [Parameter Object](#parameter-object) when the `content` field is present, and with the [Encoding Object](#encoding-object) based on the `contentType` field when the fields `style`, `explode`, and `allowReserved` are absent.
Each part is encoded based on the media type (e.g. `text/plain` or `application/json`), and must then be percent-encoded for use in a `form-urlencoded` string.
Note that content-based serialization for `form-data` does not expect or require percent-encoding in the data, only in per-part header values.
#### Interoperability with Historical Specifications
-In most cases, generating query strings in strict compliance with RFC3986 is sufficient to pass validation (including JSON Schema's `format: uri` and `format: uri-reference`), but some `form-urlencoded` implementations still expect the slightly more restrictive RFC1738 rules to be used.
+In most cases, generating query strings in strict compliance with [[RFC3986]] is sufficient to pass validation (including JSON Schema's `format: "uri"` and `format: "uri-reference"`), but some `form-urlencoded` implementations still expect the slightly more restrictive [[RFC1738]] rules to be used.
Since all RFC1738-compliant URIs are compliant with RFC3986, applications needing to ensure historical interoperability SHOULD use RFC1738's rules.
#### Interoperability with Web Browser Environments
WHATWG is a [web browser-oriented](https://whatwg.org/faq#what-is-the-whatwg-working-on) standards group that has defined a "URL Living Standard" for parsing and serializing URLs in a browser context, including parsing and serializing `form-urlencoded` data.
-WHATWG's percent-encoding rules for query strings are different depending on whether the query string is [being treated as `form-urlencoded`](https://url.spec.whatwg.org/#application-x-www-form-urlencoded-percent-encode-set) (where it requires more percent-encoding than RFC1738) or [as part of the generic syntax](https://url.spec.whatwg.org/#query-percent-encode-set), where it allows characters that RFC3986 forbids.
+WHATWG's percent-encoding rules for query strings are different depending on whether the query string is [being treated as `form-urlencoded`](https://url.spec.whatwg.org/#application-x-www-form-urlencoded-percent-encode-set) (where it requires more percent-encoding than [[RFC1738]]) or [as part of the generic syntax](https://url.spec.whatwg.org/#query-percent-encode-set), where it allows characters that [[RFC3986]] forbids.
Implementations needing maximum compatibility with web browsers SHOULD use WHATWG's `form-urlencoded` percent-encoding rules.
However, they SHOULD NOT rely on WHATWG's less stringent generic query string rules, as the resulting URLs would fail RFC3986 validation, including JSON Schema's `format: uri` and `format: uri-reference`.
@@ -4507,7 +4527,7 @@ However, care must be taken to use `form-urlencoded` decoding if `+` represents
### Percent-Encoding and Illegal or Reserved Delimiters
-The `[` and `]`, `|`, and space characters, which are used as delimiters for the `deepObject`, `pipeDelimited`, and `spaceDelimited` styles, respectively, all MUST be percent-encoded to comply with RFC3986.
+The `[`, `]`, `|`, and space characters, which are used as delimiters for the `deepObject`, `pipeDelimited`, and `spaceDelimited` styles, respectively, all MUST be percent-encoded to comply with[[RFC3986]].
This requires users to pre-encode the character(s) in some other way in parameter names and values to distinguish them from the delimiter usage when using one of these styles.
The space character is always illegal and encoded in some way by all implementations of all versions of the relevant standards.