diff --git a/versions/3.0.4.md b/versions/3.0.4.md index 856ab0dbe5..1fbb207b7e 100644 --- a/versions/3.0.4.md +++ b/versions/3.0.4.md @@ -59,7 +59,7 @@ Some examples of possible media type definitions: The HTTP Status Codes are used to indicate the status of the executed operation. 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. @@ -102,7 +102,7 @@ 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. @@ -117,8 +117,8 @@ 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) and [Path Item Object](#path-item-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 entry OpenAPI document be named: `openapi.json` or `openapi.yaml`. @@ -143,7 +143,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. @@ -158,7 +158,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`. @@ -168,7 +168,7 @@ These limitations are expected to be addressed in a future release. See [Security Requirement in a Referenced Document](#security-requirement-in-a-referenced-document) for an example of the possible resolutions, including which one is recommended by this section. The behavior for Discrimator Object non-URI mappings and for the Operation Object's `tags` field operate on the same principles. -Note that no aspect of implicit connection resolution changes how [URLs are resolved](#relative-references-in-urls), or restricts their possible targets. +Note that no aspect of implicit connection resolution changes how [URLs are resolved](#relative-references-in-urls) or restricts their possible targets. ### Data Types @@ -249,7 +249,7 @@ This is the root object of the [OpenAPI document](#openapi-description). | servers | [[Server Object](#server-object)] | An array of Server Objects, which provide connectivity information to a target server. If the `servers` property is not provided, or is an empty array, the default value would be a [Server Object](#server-object) with a [url](#server-url) value of `/`. | | paths | [Paths Object](#paths-object) | **REQUIRED**. The available paths and operations for the API. | | 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. | @@ -277,8 +277,8 @@ This object MAY be extended with [Specification Extensions](#specification-exten ```json { - "title": "Sample Pet Store App", - "description": "This is a sample server for a pet store.", + "title": "Example Pet Store App", + "description": "This is an example server for a pet store.", "termsOfService": "https://example.com/terms/", "contact": { "name": "API Support", @@ -294,8 +294,8 @@ This object MAY be extended with [Specification Extensions](#specification-exten ``` ```yaml -title: Sample Pet Store App -description: This is a sample server for a pet store. +title: Example Pet Store App +description: This is an example server for a pet store. termsOfService: https://example.com/terms/ contact: name: API Support @@ -372,7 +372,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. | @@ -487,7 +487,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 @@ -790,8 +790,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. If an alternative server object is specified at the Root 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 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). @@ -892,13 +892,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 in 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 only 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` SHALL be ignored by consumers. | | responses | [Responses Object](#responses-object) | **REQUIRED**. 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). @@ -1072,20 +1072,20 @@ 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. | +| 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) \| [Reference Object](#reference-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). | @@ -1096,7 +1096,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 | | -------------------------------------- | :--------------------------------------------------: | -------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -1122,9 +1122,9 @@ See [Appendix E](#appendix-e-percent-encoding-and-form-media-types) for a discus Assume a parameter named `color` has one of the following values: -```text +```js string -> "blue" - array -> ["blue","black","brown"] + array -> ["blue", "black", "brown"] object -> { "R": 100, "G": 200, "B": 150 } ``` @@ -1132,12 +1132,12 @@ 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](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 | @@ -1156,7 +1156,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 { @@ -1320,7 +1320,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). @@ -1419,7 +1419,7 @@ See [Working With Examples](#working-with-examples) for further guidance regardi | schema | [Schema Object](#schema-object) \| [Reference Object](#reference-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 its encoding information. 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). @@ -1487,7 +1487,7 @@ 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. Specifically: +In contrast to OpenAPI 2.0, `file` input/output content in OpenAPI 3 is described with the same semantics as any other schema type. Specifically: ```yaml # content transferred in binary (octet-stream): @@ -1531,18 +1531,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. @@ -1579,7 +1579,7 @@ See [Appendix B](#appendix-b-data-type-conversion) for a discussion of data type | Field Name | Type | Description | | ------------------------------------------------- | :-------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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`. | -| 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`. | +| 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`. | | 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`. | See also [Appendix C: Using RFC6570 Implementations](#appendix-c-using-rfc6570-implementations) for additional guidance. @@ -1595,7 +1595,7 @@ However, if all three of `style`, `explode`, and `allowReserved` fields are abse * All three keywords are to be entirely ignored, rather than treated as having their default values * Encoding is to be based on `contentType` alone, whether it is present with an explicit value or absent and treated as having its default value -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 @@ -1607,7 +1607,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: @@ -1687,7 +1687,7 @@ However, this is not guaranteed and the value would still need to be percent-dec ##### 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](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. @@ -1700,16 +1700,16 @@ Note that there are significant restrictions on what headers can be used with `m 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 `format: byte` 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 `base64`. -If `format: byte` is used for a multipart field that has an Encoding Object with a `headers` field containing `Content-Transfer-Encoding` with a schema that disallows `base64`, the result is undefined for serialization and parsing. +Using `format: "byte"` 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 `base64`. +If `format: "byte"` is used for a multipart field that has an Encoding Object with a `headers` field containing `Content-Transfer-Encoding` with a schema that disallows `base64`, the result is undefined for serialization and parsing. -Per the JSON Schema specification, `contentMediaType` without `contentEncoding` present is treated as if `contentEncoding: identity` were present. While useful for embedding text documents such as `text/html` into JSON strings, it is not useful for a `multipart/form-data` part, as it just causes the document to be treated as `text/plain` instead of its actual media type. Use the Encoding Object without `contentMediaType` if no `contentEncoding` is required. +Per the JSON Schema specification, `contentMediaType` without `contentEncoding` present is treated as if `contentEncoding: "identity"` were present. While useful for embedding text documents such as `text/html` into JSON strings, it is not useful for a `multipart/form-data` part, as it just causes the document to be treated as `text/plain` instead of its actual media type. Use the Encoding Object without `contentMediaType` if no `contentEncoding` is required. See [Appendix E](#appendix-e-percent-encoding-and-form-media-types) for a detailed examination of percent-encoding concerns for form media types. ###### 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: @@ -1805,7 +1805,7 @@ 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 +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 @@ -1816,13 +1816,13 @@ call. | Field Name | Type | Description | | -------------------------------------- | :------------------------------------------------------------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| default | [Response Object](#response-object) \| [Reference Object](#reference-object) | The documentation of responses other than the ones declared for specific HTTP response codes. Use this field to cover undeclared responses. A [Reference Object](#reference-object) can link to a response that the [OpenAPI Object's components/responses](#components-responses) section defines. | +| default | [Response Object](#response-object) \| [Reference Object](#reference-object) | The documentation of responses other than the ones declared for specific HTTP response codes. Use this field to cover undeclared responses. A [Reference Object](#reference-object) can link to a response that the [OpenAPI Object's `components.responses`](#components-responses) section defines. | ##### Patterned Fields | 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. A [Reference Object](#reference-object) can link to a response that is defined in the [OpenAPI Object's components/responses](#components-responses) section. 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. A [Reference Object](#reference-object) can link to a response that is defined in the [OpenAPI Object's `components.responses`](#components-responses) section. 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). @@ -1872,7 +1872,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 @@ -1881,7 +1881,7 @@ Describes a single response from an API Operation, including design-time, static | --------------------------------------------- | :-----------------------------------------------------------------------------------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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#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/\* | +| 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). @@ -2013,7 +2013,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. ##### Patterned Fields @@ -2063,14 +2063,14 @@ 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/1 | | | $response.header.Location | | ##### Callback Object Examples -The following example uses the user provided `queryUrl` query string parameter to define the callback URL. This is an example of how to use a callback object to describe a WebHook callback that goes with the subscription operation to enable registering for the WebHook. +The following example uses the user provided `queryUrl` query string parameter to define the callback URL. This is an example of how to use a Callback Object to describe a WebHook callback that goes with the subscription operation to enable registering for the WebHook. ```yaml myCallback: @@ -2128,8 +2128,8 @@ Tooling implementations MAY choose to validate compatibility automatically, and #### Working With Examples Example Objects can be used in both [Parameter Objects](#parameter-object) and [Media Type Objects](#media-type-object). -In both Objects, this is done through the `examples` (plural) field. -However, there are two other ways to provide examples: The `example` (singular) field that is mutually exclusive with `examples` in both Objects, and the `example` (singular) field in the [Schema Object](#schema-object) that appears in the `schema` field of both Objects. +In both objects, this is done through the `examples` (plural) field. +However, there are two other ways to provide examples: The `example` (singular) field that is mutually exclusive with `examples` in both objects, and the `example` (singular) field in the [Schema Object](#schema-object) that appears in the `schema` field of both objects. Each of these fields has slightly different considerations. The Schema Object's `example` field is used to show example values without regard to how they might be formatted as parameters or within media type representations. @@ -2138,7 +2138,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. @@ -2157,10 +2157,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: @@ -2283,7 +2285,7 @@ The presence of a link does not guarantee the caller's ability to successfully i 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 @@ -2304,7 +2306,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 @@ -2370,10 +2372,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`: @@ -2398,8 +2400,8 @@ links: username: $response.body#/username ``` -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. +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 @@ -2409,22 +2411,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). @@ -2456,7 +2458,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 @@ -2475,16 +2477,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). | @@ -2665,12 +2667,12 @@ The following properties are taken from the JSON Schema definition but their def * oneOf - Inline or referenced schema MUST be of a [Schema Object](#schema-object) and not a standard JSON Schema. * anyOf - Inline or referenced schema MUST be of a [Schema Object](#schema-object) and not a standard JSON Schema. * not - Inline or referenced schema MUST be of a [Schema Object](#schema-object) and not a standard JSON Schema. -* items - Value MUST be an object and not an array. Inline or referenced schema MUST be of a [Schema Object](#schema-object) and not a standard JSON Schema. `items` MUST be present if the `type` is `array`. +* items - Value MUST be an object and not an array. Inline or referenced schema MUST be of a [Schema Object](#schema-object) and not a standard JSON Schema. `items` MUST be present if `type` is `"array"`. * properties - Property definitions MUST be a [Schema Object](#schema-object) and not a standard JSON Schema (inline or referenced). * additionalProperties - Value can be boolean or object. Inline or referenced schema MUST be of a [Schema Object](#schema-object) and not a standard JSON Schema. Consistent with JSON Schema, `additionalProperties` defaults to `true`. * description - [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. * format - See [Data Type Formats](#data-type-format) for further details. While relying on JSON Schema's defined formats, the OAS offers a few additional predefined formats. -* default - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, if `type` is `string`, then `default` can be `"foo"` but cannot be `1`. +* default - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined `type` for the Schema Object defined at the same level. For example, if `type` is `"string"`, then `default` can be `"foo"` but cannot be `1`. Alternatively, any time a Schema Object can be used, a [Reference Object](#reference-object) can be used in its place. This allows referencing definitions instead of defining them inline. @@ -2682,10 +2684,10 @@ Other than the JSON Schema subset fields, the following fields MAY be used for f | Field Name | Type | Description | | ----------------------------------------------- | :-----------------------------------------------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| nullable | `boolean` | A `true` value adds `"null"` to the allowed type specified by the `type` keyword, only if `type` is explicitly defined within the same Schema Object. Other Schema Object constraints retain their defined behavior, and therefore may disallow the use of `null` as a value. A `false` value leaves the specified or default `type` unmodified. The default value is `false`. | +| nullable | `boolean` | This keyword only takes effect if `type` is explicitly defined within the same Schema Object. A `true` value indicates that both `null` values and values of the type specified by `type` are allowed. Other Schema Object constraints retain their defined behavior, and therefore may disallow the use of `null` as a value. A `false` value leaves the specified or default `type` unmodified. The default value is `false`. | | 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. | -| readOnly | `boolean` | Relevant only for Schema `"properties"` definitions. Declares the property as "read only". This means that it MAY be sent as part of a response but SHOULD NOT be sent as part of the request. If the property is marked as `readOnly` being `true` and is in the `required` list, the `required` will take effect on the response only. A property MUST NOT be marked as both `readOnly` and `writeOnly` being `true`. Default value is `false`. | -| writeOnly | `boolean` | Relevant only for Schema `"properties"` definitions. Declares the property as "write only". Therefore, it MAY be sent as part of a request but SHOULD NOT be sent as part of the response. If the property is marked as `writeOnly` being `true` and is in the `required` list, the `required` will take effect on the request only. A property MUST NOT be marked as both `readOnly` and `writeOnly` being `true`. Default value is `false`. | +| readOnly | `boolean` | Relevant only for Schema Object `properties` definitions. Declares the property as "read only". This means that it MAY be sent as part of a response but SHOULD NOT be sent as part of the request. If the property is marked as `readOnly` being `true` and is in the `required` list, the `required` will take effect on the response only. A property MUST NOT be marked as both `readOnly` and `writeOnly` being `true`. Default value is `false`. | +| writeOnly | `boolean` | Relevant only for Schema Object `properties` definitions. Declares the property as "write only". Therefore, it MAY be sent as part of a request but SHOULD NOT be sent as part of the response. If the property is marked as `writeOnly` being `true` and is in the `required` list, the `required` will take effect on the request only. A property MUST NOT be marked as both `readOnly` and `writeOnly` being `true`. Default value is `false`. | | 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. | @@ -2714,7 +2716,7 @@ The [XML Object](#xml-object) contains additional information about the availabl ##### Schema Object Examples -###### Primitive Sample +###### Primitive Example ```json { @@ -3095,9 +3097,9 @@ The expectation now is that a property with name `petType` _MUST_ be present in } ``` -Will indicate that the `Cat` schema is expected to match 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: @@ -3164,7 +3166,7 @@ Validated against the `Pet` schema, a payload like this: ```json { "petType": "Cat", - "name": "misty" + "name": "Misty" } ``` @@ -3190,11 +3192,11 @@ 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). @@ -3543,7 +3545,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), OAuth2's common flows (implicit, password, client credentials and authorization code) as defined in [RFC6749](https://tools.ietf.org/html/rfc6749), and [[OpenID-Connect-Core]]. +Supported schemes are HTTP authentication, an API key (either as a header, a cookie parameter, or as a query parameter), OAuth2's common flows (implicit, password, client credentials, and authorization code) as defined in [RFC6749](https://tools.ietf.org/html/rfc6749), 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 cases is Authorization Code Grant flow with PKCE. ##### Fixed Fields @@ -3553,7 +3555,7 @@ Please note that as of 2020, the implicit flow is about to be deprecated by [OAu | type | `string` | Any | **REQUIRED**. The type of the security scheme. Valid values are `"apiKey"`, `"http"`, `"oauth2"`, `"openIdConnect"`. | | description | `string` | Any | A description for security scheme. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. | | name | `string` | `apiKey` | **REQUIRED**. The name of the header, query or cookie parameter to be used. | -| in | `string` | `apiKey` | **REQUIRED**. The location of the API key. Valid values are `"query"`, `"header"` or `"cookie"`. | +| in | `string` | `apiKey` | **REQUIRED**. The location of the API key. Valid values are `"query"`, `"header"`, or `"cookie"`. | | 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. | @@ -3561,9 +3563,9 @@ Please note that as of 2020, the implicit flow is about to be deprecated by [OAu 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 { @@ -3577,7 +3579,7 @@ type: http scheme: basic ``` -###### API Key Sample +###### API Key Example ```json { @@ -3593,7 +3595,7 @@ name: api-key in: header ``` -###### JWT Bearer Sample +###### JWT Bearer Example ```json { @@ -3609,7 +3611,7 @@ scheme: bearer bearerFormat: JWT ``` -###### Implicit OAuth2 Sample +###### Implicit OAuth2 Example ```json { @@ -3666,7 +3668,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 { @@ -3778,7 +3780,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 @@ -3874,11 +3876,11 @@ 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`. The value can be any valid JSON value (`null`, a primitive, an array or an object.) | +| ^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be any valid JSON value (`null`, a primitive, an array, or an object.) | 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/). @@ -3948,10 +3950,10 @@ 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://tools.ietf.org/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://tools.ietf.org/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. -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. @@ -3963,7 +3965,7 @@ Two cases do offer standards-based guidance: 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. @@ -3974,7 +3976,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 | | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | @@ -3983,27 +3985,27 @@ 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. 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. Using an implementation with a lower level of support will require additional manual construction of URI Templates to work around the limitations. ### 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 | -| allowReserved | `false` | _n/a_ | -| allowReserved | `true` | `+` prefix operator | -| explode | `false` | _n/a_ | -| explode | `true` | `*` modifier suffix | +| field | value | equivalent | +| ------------- | ---------- | ------------------- | +| 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: @@ -4018,14 +4020,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: @@ -4034,7 +4036,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 @@ -4054,7 +4056,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: @@ -4088,7 +4090,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: @@ -4109,7 +4111,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: @@ -4148,7 +4150,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: {} @@ -4196,7 +4198,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 @@ -4215,24 +4217,24 @@ 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 (`format: byte`). -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 (`format: "byte"`). +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. 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 @@ -4274,28 +4276,28 @@ This specification normatively cites the following relevant standards: | Specification | Date | OAS Usage | Percent-Encoding | Notes | | ---------------------------------------------------------------------- | ------- | --------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [[RFC3986]] | 01/2005 | URI/URL syntax | [[RFC3986]] | obsoletes [[RFC1738]], [[RFC2396]] | -| [[RFC6570]] | 03/2012 | style-based serialization | [[RFC3986]] | does not use `+` for form‑urlencoded | +| [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`. @@ -4310,7 +4312,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.