From 3030ae382447e13a35c553b0bb189d58fa239170 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Mon, 2 Sep 2024 17:20:26 +0200 Subject: [PATCH 1/3] Latest changes to v3.1.1 --- versions/3.2.0.md | 67 ++++++++++++++++++++++++++++++----------------- 1 file changed, 43 insertions(+), 24 deletions(-) diff --git a/versions/3.2.0.md b/versions/3.2.0.md index eecf592e0f..3c46858234 100644 --- a/versions/3.2.0.md +++ b/versions/3.2.0.md @@ -28,6 +28,10 @@ A "schema" is a formal description of syntax and structure. This document serves as the [schema](#schema) for the OpenAPI Specification format; a non-authoritative JSON Schema based on this document is also provided on [spec.openapis.org](https://spec.openapis.org) for informational purposes. This specification also _uses_ schemas in the form of the [Schema Object](#schema-object). +### Object + +When capitalized, the word "Object" refers to any of the Objects that are named by section headings in this document. + ### Path Templating Path templating refers to the usage of template expressions, delimited by curly braces (`{}`), to mark a section of a URL path as replaceable using path parameters. @@ -135,8 +139,8 @@ Implementations MAY support complete-document parsing in any of the following wa * Detecting OpenAPI or JSON Schema documents using media types * Detecting OpenAPI documents through the root `openapi` field * Detecting JSON Schema documents through detecting keywords or otherwise successfully parsing the document in accordance with the JSON Schema specification -* Detecting a document containing a referenceable object at its root based on the expected type of the reference -* Allowing users to configure the type of documents that might be loaded due to a reference to a non-root object +* Detecting a document containing a referenceable Object at its root based on the expected type of the reference +* Allowing users to configure the type of documents that might be loaded due to a reference to a non-root Object Implementations that parse referenced fragments of OpenAPI content without regard for the content of the rest of the containing document will miss keywords that change the meaning and behavior of the reference target. In particular, failing to take into account keywords that change the base URI introduces security risks by causing references to resolve to unintended URIs, with unpredictable results. @@ -199,27 +203,36 @@ Note that no aspect of implicit connection resolution changes how [URIs are reso ### Data Types -Data types in the OAS are based on the types supported by the [JSON Schema Specification Draft 2020-12](https://tools.ietf.org/html/draft-bhutton-json-schema-00#section-4.2.1). -Note that `integer` as a type is also supported and is defined as a JSON number without a fraction or exponent part. -Models are defined using the [Schema Object](#schema-object), which is a superset of JSON Schema Specification Draft 2020-12. +Data types in the OAS are based on the types defined by the [JSON Schema Validation Specification Draft 2020-12](https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-00#section-6.1.1): +"null", "boolean", "object", "array", "number", "string", or "integer". +Models are defined using the [Schema Object](#schema-object), which is a superset of the JSON Schema Specification Draft 2020-12. + +JSON Schema keywords and `format` values operate on JSON "instances" which may be one of the six JSON data types, "null", "boolean", "object", "array", "number", or "string", with certain keywords and formats only applying to a specific type. For example, the `pattern` keyword and the `date-time` format only apply to strings, and treat any instance of the other five types as _automatically valid._ This means JSON Schema keywords and formats do **NOT** implicitly require the expected type. Use the `type` keyword to explicitly constrain the type. + +Note that the `type` keyword allows `"integer"` as a value for convenience, but keyword and format applicability does not recognize integers as being of a distinct JSON type from other numbers because [[RFC7159|JSON]] itself does not make that distinction. Since there is no distinct JSON integer type, JSON Schema defines integers mathematically. This means that both `1` and `1.0` are [equivalent](https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00#section-4.2.2), and are both considered to be integers. + +#### Data Type Format -As defined by the [JSON Schema Validation specification](https://tools.ietf.org/html/draft-bhutton-json-schema-validation-00#section-7.3), data types can have an optional modifier keyword: `format`. As described in that specification, `format` is treated as a non-validating annotation by default; the ability to validate `format` varies across implementations. +As defined by the [JSON Schema Validation specification](https://tools.ietf.org/html/draft-bhutton-json-schema-validation-00#section-7.3), data types can have an optional modifier keyword: `format`. As described in that specification, `format` is treated as a non-validating annotation by default; the ability to validate `format` varies across implementations. The OpenAPI Initiative also hosts a [Format Registry](https://spec.openapis.org/registry/format/) for formats defined by OAS users and other specifications. Support for any registered format is strictly OPTIONAL, and support for one registered format does not imply support for any others. Types that are not accompanied by a `format` keyword follow the type definition in the JSON Schema. Tools that do not recognize a specific `format` MAY default back to the `type` alone, as if the `format` is not specified. +For the purpose of [JSON Schema validation](https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-00#section-7.1), each format should specify the set of JSON data types for which it applies. In this registry, these types are shown in the "JSON Data Type" column. The formats defined by the OAS are: -| [`type`](#data-types) | [`format`](#data-type-format) | Comments | +| `format` | JSON Data Type | Comments | | ---- | ---- | ---- | -| `integer` | `int32` | signed 32 bits | -| `integer` | `int64` | signed 64 bits (a.k.a long) | -| `number` | `float` | | -| `number` | `double` | | -| `string` | `password` | A hint to obscure the value. | +| `int32` | number | signed 32 bits | +| `int64` | number | signed 64 bits (a.k.a long) | +| `float` | number | | +| `double` | number | | +| `password` | string | A hint to obscure the value. | -#### Working With Binary Data +As noted under [Data Type](#data-types), both `type: number` and `type: integer` are considered to be numbers in the data model. + +#### Working with Binary Data The OAS can describe either _raw_ or _encoded_ binary data. @@ -253,8 +266,8 @@ The following table shows how to migrate from OAS 3.0 binary data descriptions, | OAS < 3.1 | OAS 3.1+ | Comments | | ---- | ---- | ---- | -| `type: string`
`format: binary` | `contentMediaType: image/png` | if redundant, can be omitted, often resulting in an empty [Schema Object](#schema-object) | -| `type: string`
`format: byte` | `type: string`
`contentMediaType: image/png`
`contentEncoding: base64` | note that `base64url` can be used to avoid re-encoding the base64 string to be URL-safe | +| type: string
format: binary | contentMediaType: image/png | if redundant, can be omitted, often resulting in an empty [Schema Object](#schema-object) | +| type: string
format: byte | type: string
contentMediaType: image/png
contentEncoding: base64 | note that `base64url` can be used to avoid re-encoding the base64 string to be URL-safe | ### Rich Text Formatting @@ -312,9 +325,9 @@ This is the root object of the [OpenAPI document](#openapi-description). | jsonSchemaDialect | `string` | The default value for the `$schema` keyword within [Schema Objects](#schema-object) contained within this OAS document. This MUST be in the form of a URI. | | servers | [[Server Object](#server-object)] | An array of Server Objects, which provide connectivity information to a target server. If the `servers` field is not provided, or is an empty array, the default value would be a [Server Object](#server-object) with a [url](#server-url) value of `/`. | | paths | [Paths Object](#paths-object) | The available paths and operations for the API. | -| webhooks | Map[`string`, [Path Item Object](#path-item-object) \| [Reference Object](#reference-object)] ] | The incoming webhooks that MAY be received as part of this API and that the API consumer MAY choose to implement. Closely related to the `callbacks` feature, this section describes requests initiated other than by an API call, for example by an out of band registration. The key name is a unique string to refer to each webhook, while the (optionally referenced) Path Item Object describes a request that may be initiated by the API provider and the expected responses. An [example](../examples/v3.1/webhook-example.yaml) is available. | +| webhooks | Map[`string`, [Path Item Object](#path-item-object) \| [Reference Object](#reference-object)] ] | The incoming webhooks that MAY be received as part of this API and that the API consumer MAY choose to implement. Closely related to the `callbacks` feature, this section describes requests initiated other than by an API call, for example by an out of band registration. The key name is a unique string to refer to each webhook, while the (optionally referenced) Path Item Object describes a request that may be initiated by the API provider and the expected responses. An [example](https://learn.openapis.org/examples/v3.1/webhook-example.html) is available. | | components | [Components Object](#components-object) | An element to hold various schemas for the document. | -| 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. The list can be incomplete, up to being empty or absent. To make security explicitly optional, an empty security requirement (`{}`) can be included in the array. | | tags | [[Tag Object](#tag-object)] | A list of tags used by the document with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operation-object) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique. | | externalDocs | [External Documentation Object](#external-documentation-object) | Additional external documentation. | @@ -1556,9 +1569,9 @@ application/json: ##### Considerations for File Uploads -In contrast to OpenAPI 2.0, `file` input/output content in OpenAPI 3 is described with the same semantics as any other schema type. +In contrast to OpenAPI 2.0, `file` input/output content in OAS 3.x is described with the same semantics as any other schema type. -In contrast to OpenAPI 2.0, the `format` keyword has no effect on the content-encoding of the schema. Instead, JSON Schema's `contentEncoding` and `contentMediaType` keywords are used. See [Working With Binary Data](#working-with-binary-data) for how to model various scenarios with these keywords, and how to migrate from the previous `format` usage. +In contrast to OAS 3.0, the `format` keyword has no effect on the content-encoding of the schema in OAS 3.1. Instead, JSON Schema's `contentEncoding` and `contentMediaType` keywords are used. See [Working With Binary Data](#working-with-binary-data) for how to model various scenarios with these keywords, and how to migrate from the previous `format` usage. Examples: @@ -1576,6 +1589,12 @@ content: application/octet-stream: {} ``` +```yaml +# arbitrary JSON without constraints beyond being syntactically valid: +content: + application/json: {} +``` + These examples apply to either input payloads of file uploads or response payloads. A `requestBody` for submitting a file in a `POST` operation may look like the following example: @@ -2082,7 +2101,7 @@ To describe incoming requests from the API provider independent from another API | Field Pattern | Type | Description | | ---- | :----: | ---- | -| {expression} | [Path Item Object](#path-item-object) \| [Reference Object](#reference-object) | A Path Item Object, or a reference to one, used to define a callback request and expected responses. A [complete example](../examples/v3.0/callback-example.yaml) is available. | +| {expression} | [Path Item Object](#path-item-object) \| [Reference Object](#reference-object) | A Path Item Object, or a reference to one, used to define a callback request and expected responses. A [complete example](https://learn.openapis.org/examples/v3.0/callback-example.html) is available. | This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -2188,7 +2207,7 @@ This object MAY be extended with [Specification Extensions](#specification-exten In all cases, the example value SHOULD be compatible with the schema of its associated value. Tooling implementations MAY choose to validate compatibility automatically, and reject the example value(s) if incompatible. -#### Working With Examples +##### 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. @@ -2686,7 +2705,7 @@ $ref: '#/components/schemas/Pet' $ref: Pet.yaml ``` -##### Relative Documents With Embedded Schema Example +##### Relative Documents with Embedded Schema Example ```json { @@ -3730,7 +3749,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"`, `"mutualTLS"`, `"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. | @@ -4302,7 +4321,7 @@ when expanded with the data given earlier, we get: ?a=x%2By&b=x%2Fy&c=x%5Ey&words=math,is,fun ``` -#### Expansion With Non-RFC6570-Supported Options +#### 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`: From 40c8c6a6c6d825b8d0acc2c831579fa06255dbfc Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Thu, 5 Sep 2024 17:25:36 +0200 Subject: [PATCH 2/3] Port of #4071 --- versions/3.2.0.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/versions/3.2.0.md b/versions/3.2.0.md index 3c46858234..bf54dc5c17 100644 --- a/versions/3.2.0.md +++ b/versions/3.2.0.md @@ -518,7 +518,7 @@ The following shows how variables can be used for a server configuration: "variables": { "username": { "default": "demo", - "description": "this value is assigned by the service provider, in this example `gigantic-server.com`" + "description": "A user-specific subdomain. Use `demo` for a free sandbox environment." }, "port": { "enum": ["8443", "443"], @@ -541,7 +541,7 @@ servers: username: # note! no enum here means it is an open value default: demo - description: this value is assigned by the service provider, in this example `gigantic-server.com` + description: A user-specific subdomain. Use `demo` for a free sandbox environment. port: enum: - '8443' @@ -561,7 +561,7 @@ An object representing a Server Variable for server URL template substitution. | Field Name | Type | Description | | ---- | :----: | ---- | | enum | [`string`] | An enumeration of string values to be used if the substitution options are from a limited set. The array MUST NOT be empty. | -| default | `string` | **REQUIRED**. The default value to use for substitution, which SHALL be sent if an alternate value is _not_ supplied. Note this behavior is different than the [Schema Object's](#schema-object) treatment of default values, because in those cases parameter values are optional. If the [`enum`](#server-variable-enum) is defined, the value MUST exist in the enum's values. | +| default | `string` | **REQUIRED**. The default value to use for substitution, which SHALL be sent if an alternate value is _not_ supplied. If the [`enum`](#server-variable-enum) is defined, the value MUST exist in the enum's values. Note that this behavior is different from the [Schema Object](#schema-object)'s `default` keyword, which documents the receiver's behavior rather than inserting the value into the data. | | description | `string` | An optional description for the server variable. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. | This object MAY be extended with [Specification Extensions](#specification-extensions). From 06945d5714f9a4937ae8099dc673d11c5cdba241 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Fri, 13 Sep 2024 10:02:17 +0200 Subject: [PATCH 3/3] Add #4091, #4088 --- versions/3.2.0.md | 252 ++++++++++++++++++++++++---------------------- 1 file changed, 134 insertions(+), 118 deletions(-) diff --git a/versions/3.2.0.md b/versions/3.2.0.md index bf54dc5c17..a7d847438a 100644 --- a/versions/3.2.0.md +++ b/versions/3.2.0.md @@ -123,7 +123,9 @@ In order to preserve the ability to round-trip between YAML and JSON formats, YA An OpenAPI Description (OAD) MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the author. In the latter case, [Reference Object](#reference-object), [Path Item Object](#path-item-object) and [Schema Object](#schema-object) `$ref` keywords, as well as the [Link Object](#link-object) `operationRef` keyword, are used. -Any document consisting entirely of an [OpenAPI Object](#openapi-object) is known as a **complete OpenAPI document**. +Any document consisting entirely of an [OpenAPI Object](#openapi-object) is known as a **syntactically complete OpenAPI document**. +An OpenAPI document that does _not_ reference any other documents is known as a **self-contained OpenAPI document**. +A single-document description is therefore _both_ syntactically complete _and_ self-contained. In a multi-document description, the document containing the OpenAPI Object where parsing begins for a specific API's description is known as that API's **entry OpenAPI document**, or simply **entry document**. It is RECOMMENDED that the entry OpenAPI document be named: `openapi.json` or `openapi.yaml`. @@ -157,7 +159,7 @@ It is the responsibility of an embedding format to define how to parse embedded When parsing an OAD, JSON or YAML objects are parsed into specific Objects (such as [Operation Objects](#operation-object), [Response Objects](#response-object), [Reference Objects](#reference-object), etc.) based on the parsing context. Depending on how references are arranged, a given JSON or YAML object can be parsed in multiple different contexts: -* As a complete OpenAPI Description document +* As a syntactically complete OpenAPI Description document * As the Object type implied by its parent Object within the document * As a reference target, with the Object type matching the reference source's context @@ -196,7 +198,7 @@ The interface approach can also work for Discriminator Objects and Schema Object There are no URI-based alternatives for the Security Requirement Object or for the Operation Object's `tags` field. 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. +See [Appendix F: Resolving Security Requirements in a Referenced Document](#appendix-f-resolving-security-requirements-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 [URIs are resolved](#relative-references-in-api-description-uris), or restricts their possible targets. @@ -294,6 +296,8 @@ In practice, this is usually the retrieval URI of the document, which MAY be det If a URI contains a fragment identifier, then the fragment should be resolved per the fragment resolution mechanism of the referenced document. If the representation of the referenced document is JSON or YAML, then the fragment identifier SHOULD be interpreted as a JSON-Pointer as per [RFC6901](https://tools.ietf.org/html/rfc6901). +Relative references in CommonMark hyperlinks are resolved in their rendered context, which might differ from the context of the API description. + ### Relative References in API URLs API endpoints are by definition accessed as locations, and are described by this specification as **_URLs_**. @@ -301,8 +305,6 @@ API endpoints are by definition accessed as locations, and are described by this Unless specified otherwise, all fields that are URLs MAY be relative references as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2). Unless specified otherwise, relative references are resolved using the URLs defined in the [Server Object](#server-object) as a Base URL. Note that these themselves MAY be relative to the referring document. -Relative references in CommonMark hyperlinks are resolved in their rendered context, which might differ from the context of the API description. - ### Schema This section describes the structure of the OpenAPI Description format. @@ -1168,12 +1170,12 @@ Serializing with `schema` is NOT RECOMMENDED for `in: "cookie"` parameters, `in: | ---- | :----: | ---- | | 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 field 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 field only applies to parameters with an `in` value of `query`. The default value is `false`. | +| 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-based-serialization) and [E](#appendix-e-percent-encoding-and-form-media-types) for details. This field only applies to parameters with an `in` value of `query`. The default value is `false`. | | schema | [Schema Object](#schema-object) | The schema defining the type used for the parameter. | | example | Any | Example of the parameter's potential value; see [Working With Examples](#working-with-examples). | | examples | Map[ `string`, [Example Object](#example-object) \| [Reference Object](#reference-object)] | Examples of the parameter's potential value; see [Working With Examples](#working-with-examples). | -See also [Appendix C: Using RFC6570 Implementations](#appendix-c-using-rfc6570-implementations) for additional guidance. +See also [Appendix C: Using RFC6570-Based Serialization](#appendix-c-using-rfc6570-based-serialization) for additional guidance. ###### Fixed Fields for use with `content` @@ -1215,7 +1217,7 @@ 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` 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 +* 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-based-serialization) 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. @@ -1670,9 +1672,9 @@ See [Appendix B](#appendix-b-data-type-conversion) for a discussion of data type | ---- | :----: | ---- | | style | `string` | Describes how a specific property value will be serialized depending on its type. See [Parameter Object](#parameter-object) for details on the [`style`](#parameter-style) field. 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 field SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded` or `multipart/form-data`. If a value is explicitly defined, then the value of [`contentType`](#encoding-content-type) (implicit or explicit) SHALL be ignored. | | explode | `boolean` | When this is true, property values of type `array` or `object` generate separate parameters for each value of the array, or key-value-pair of the map. For other types of properties this field 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 field SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded` or `multipart/form-data`. If a value is explicitly defined, then the value of [`contentType`](#encoding-content-type) (implicit or explicit) SHALL be ignored. | -| allowReserved | `boolean` | When this is true, parameter values are serialized using reserved expansion, as defined by [RFC6570](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3), which allows [RFC3986's reserved character set](https://datatracker.ietf.org/doc/html/rfc3986#section-2.2), as well as percent-encoded triples, to pass through unchanged, while still percent-encoding all other disallowed characters (including `%` outside of percent-encoded triples). Applications are still responsible for percent-encoding reserved characters that are [not allowed in the query string](https://datatracker.ietf.org/doc/html/rfc3986#section-3.4) (`[`, `]`, `#`), or have a special meaning in `application/x-www-form-urlencoded` (`-`, `&`, `+`); see Appendices [C](#appendix-c-using-rfc6570-implementations) and [E](#appendix-e-percent-encoding-and-form-media-types) for details. The default value is `false`. This field SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded` or `multipart/form-data`. If a value is explicitly defined, then the value of [`contentType`](#encoding-content-type) (implicit or explicit) SHALL be ignored. | +| allowReserved | `boolean` | When this is true, parameter values are serialized using reserved expansion, as defined by [RFC6570](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3), which allows [RFC3986's reserved character set](https://datatracker.ietf.org/doc/html/rfc3986#section-2.2), as well as percent-encoded triples, to pass through unchanged, while still percent-encoding all other disallowed characters (including `%` outside of percent-encoded triples). Applications are still responsible for percent-encoding reserved characters that are [not allowed in the query string](https://datatracker.ietf.org/doc/html/rfc3986#section-3.4) (`[`, `]`, `#`), or have a special meaning in `application/x-www-form-urlencoded` (`-`, `&`, `+`); see Appendices [C](#appendix-c-using-rfc6570-based-serialization) and [E](#appendix-e-percent-encoding-and-form-media-types) for details. The default value is `false`. This field SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded` or `multipart/form-data`. If a value is explicitly defined, then the value of [`contentType`](#encoding-content-type) (implicit or explicit) SHALL be ignored. | -See also [Appendix C: Using RFC6570 Implementations](#appendix-c-using-rfc6570-implementations) for additional guidance, including on difficulties caused by the interaction between RFC6570's percent-encoding rules and the `multipart/form-data` media type. +See also [Appendix C: Using RFC6570 Implementations](#appendix-c-using-rfc6570-based-serialization) for additional guidance, including on difficulties caused by the interaction between RFC6570's percent-encoding rules and the `multipart/form-data` media type. Note that the presence of at least one of `style`, `explode`, or `allowReserved` with an explicit value is equivalent to using `schema` with `in: "query"` Parameter Objects. 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. @@ -2384,9 +2386,10 @@ For computing links and providing instructions to execute them, a [runtime expre This object MAY be extended with [Specification Extensions](#specification-extensions). A linked operation MUST be identified using either an `operationRef` or `operationId`. -In the case of an `operationId`, it MUST be unique and resolved in the scope of the OpenAPI description. -Because of the potential for name clashes, the `operationRef` syntax is preferred -for multi-document OpenAPI descriptions. +The identified or reference operation MUST be unique, and in the case of an `operationId`, it MUST be resolved within the scope of the OpenAPI Description (OAD). +Because of the potential for name clashes, the `operationRef` syntax is preferred for multi-document OADs. +However, because use of an operation depends on its URL path template in the [Paths Object](#paths-object), operations from any [Path Item Object](#path-item-object) that is referenced multiple times within the OAD cannot be resolved unambiguously. +In such ambiguous cases, the resulting behavior is implementation-defined and MAY result in an error. 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). @@ -2575,7 +2578,7 @@ The `example` and `examples` fields are mutually exclusive, and if either is pre | example | Any | Example of the header's potential value; see [Working With Examples](#working-with-examples). | | examples | Map[ `string`, [Example Object](#example-object) \| [Reference Object](#reference-object)] | Examples of the header's potential value; see [Working With Examples](#working-with-examples). | -See also [Appendix C: Using RFC6570 Implementations](#appendix-c-using-rfc6570-implementations) for additional guidance. +See also [Appendix C: Using RFC6570-Based Serialization](#appendix-c-using-rfc6570-based-serialization) for additional guidance. ###### Fixed Fields for use with `content` @@ -3952,6 +3955,8 @@ When a list of Security Requirement Objects is defined on the [OpenAPI Object](# ##### Security Requirement Object Examples +See also [Appendix F: Resolving Security Requirements in a Referenced Document](#appendix-f-resolving-security-requirements-in-a-referenced-document) for an example using Security Requirement Objects in multi-document OpenAPI Descriptions. + ###### Non-OAuth2 Security Requirement ```json @@ -4001,102 +4006,6 @@ security: - read:pets ``` -###### Security Requirement in a Referenced Document - -See [Resolving Implicit Connections](#resolving-implicit-connections) for more information. - -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 -Host: www.example.com -Accept: application/openapi+json -``` - -```json -"components": { - "securitySchemes": { - "MySecurity": { - "type": "http", - "scheme": "bearer", - "bearerFormat": "JWT" - } - } -}, -"paths": { - "/foo": { - "$ref": "other#/components/pathItems/Foo" - } -} -``` - -```HTTP -GET /api/description/openapi HTTP/1.1 -Host: www.example.com -Accept: application/openapi+yaml -``` - -```yaml -components: - securitySchemes: - MySecurity: - type: http - scheme: bearer - bearerFormat: JWT -paths: - /foo: - $ref: 'other#/components/pathItems/Foo' -``` - -Next, we have our referenced document, `other`. The fact that we don't use file extensions gives the client the flexibility to choose an acceptable format on a resource-by-resource basis, assuming both representations are available: - -```HTTP -GET /api/description/other HTTP/1.1 -Host: www.example.com -Accept: application/openapi+json -``` - -```json -"components": { - "securitySchemes": { - "MySecurity": { - "type": "http", - "scheme": "basic" - } - }, - "pathItems": { - "Foo": { - "get": { - "security": [ - "MySecurity": [] - ] - } - } - } -} -``` - -```HTTP -GET /api/description/other HTTP/1.1 -Host: www.example.com -Accept: application/openapi+yaml -``` - -```yaml -components: - securitySchemes: - MySecurity: - type: http - scheme: basic - pathItems: - Foo: - get: - security: - - MySecurity: [] -``` - -In the `other` document, the referenced path item has a Security Requirement for a Security Scheme, `MySecurity`. The same Security Scheme exists in the original entry document. As outlined in [Resolving Implicit Connections](#resolving-implicit-connections), `MySecurity` is resolved with an [implementation-defined behavior](#undefined-and-implementation-defined-behavior). However, documented in that section, it is RECOMMENDED that tools resolve component names from the [entry document](#openapi-description-structure). As with all implementation-defined behavior, it is important to check tool documentation to determine which behavior is supported. - ### Specification Extensions While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points. @@ -4204,13 +4113,14 @@ However, care must be taken with `format` to ensure that the specific formats ar Requiring input as pre-formatted, schema-validated strings also improves round-trip interoperability as not all programming languages and environments support the same data types. -## Appendix C: Using RFC6570 Implementations +## Appendix C: Using RFC6570-Based Serialization -Serialization is defined in terms of [RFC6570](https://www.rfc-editor.org/rfc/rfc6570) URI Templates in two scenarios: +Serialization is defined in terms of [RFC6570](https://www.rfc-editor.org/rfc/rfc6570) URI Templates in three scenarios: | Object | Condition | | ---- | ---- | | [Parameter Object](#parameter-object) | When `schema` is present | +| [Header Object](#header-object) | When `schema` is present | | [Encoding Object](#encoding-object) | When encoding for `application/x-www-form-urlencoded` and any of `style`, `explode`, or `allowReserved` are used | Implementations of this specification MAY use an implementation of RFC6570 to perform variable expansion, however, some caveats apply. @@ -4254,10 +4164,19 @@ parameters: type: string ``` -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. +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. +Note that RFC6570 does not specify behavior for compound values beyond the single level addressed by `explode`. The result of using objects or arrays where no behavior is clearly specified for them is implementation-defined. + +### Delimiters in Parameter Values + +Delimiters used by RFC6570 expansion, such as the `,` used to join arrays or object values with `style: "simple"`, are all automatically percent-encoded as long as `allowReserved` is `false`. +Note that since RFC6570 does not define a way to parse variables based on a URI Template, users must take care to first split values by delimiter before percent-decoding values that might contain the delimiter character. + +When `allowReserved` is `true`, both percent-encoding (prior to joining values with a delimiter) and percent-decoding (after splitting on the delimiter) must be done manually at the correct time. + +See [Appendix E](#appendix-e-percent-encoding-and-form-media-types) for additional guidance on handling delimiters for `style` values with no RFC6570 equivalent that already need to be percent-encoded when used as delimiters. ### Non-RFC6570 Field Values and Combinations @@ -4339,6 +4258,7 @@ parameters: - name: words in: query style: spaceDelimited + explode: false schema: type: array items: @@ -4465,7 +4385,7 @@ With `style: "simple"`, that delimiter would itself be percent-encoded, violatin 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](#appendix-c-using-rfc6570-implementations) 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-based-serialization) 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. @@ -4492,7 +4412,7 @@ Reserved characters with no special meaning defined within a component can be le However, other specifications can define special meanings, requiring percent-encoding for those characters outside of the additional special meanings. The `form-urlencoded` media type defines special meanings for `=` and `&` as delimiters, and `+` as the replacement for the space character (instead of its percent-encoded form of `%20`). -This means that while these three characters are reserved-but-allowed in query strings by RFC3986, they must be percent-encoded in `form-urlencoded` query strings except when used for their `form-urlencoded` purposes; see [Appendix C](#appendix-c-using-rfc6570-implementations) for an example of handling `+` in form values. +This means that while these three characters are reserved-but-allowed in query strings by RFC3986, they must be percent-encoded in `form-urlencoded` query strings except when used for their `form-urlencoded` purposes; see [Appendix C](#appendix-c-using-rfc6570-based-serialization) for an example of handling `+` in form values. ### Percent-Encoding and `form-data` @@ -4516,7 +4436,7 @@ This specification normatively cites the following relevant standards: | [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 `+`. +See [Appendix C](#appendix-c-using-rfc6570-based-serialization) 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 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. @@ -4547,7 +4467,7 @@ However, care must be taken to use `form-urlencoded` decoding if `+` represents ### Percent-Encoding and Illegal or Reserved Delimiters -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]]. +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. @@ -4559,3 +4479,99 @@ Code that relies on leaving these delimiters unencoded, while using regular perc For maximum interoperability, it is RECOMMENDED to either define and document an additional escape convention while percent-encoding the delimiters for these styles, or to avoid these styles entirely. The exact method of additional encoding/escaping is left to the API designer, and is expected to be performed before serialization and encoding described in this specification, and reversed after this specification's encoding and serialization steps are reversed. This keeps it outside of the processes governed by this specification. + +## Appendix F: Resolving Security Requirements in a Referenced Document + +This appendix shows how to retrieve an HTTP-accessible multi-document OpenAPI Description (OAD) and resolve a [Security Requirement Object](#security-requirement-object) in the referenced (non-entry) document. See [Resolving Implicit Connections](#resolving-implicit-connections) for more information. + +First, the [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 +Host: www.example.com +Accept: application/openapi+json +``` + +```json +"components": { + "securitySchemes": { + "MySecurity": { + "type": "http", + "scheme": "bearer", + "bearerFormat": "JWT" + } + } +}, +"paths": { + "/foo": { + "$ref": "other#/components/pathItems/Foo" + } +} +``` + +```HTTP +GET /api/description/openapi HTTP/1.1 +Host: www.example.com +Accept: application/openapi+yaml +``` + +```yaml +components: + securitySchemes: + MySecurity: + type: http + scheme: bearer + bearerFormat: JWT +paths: + /foo: + $ref: 'other#/components/pathItems/Foo' +``` + +This entry document references another document, `other`, without using a file extension. This gives the client the flexibility to choose an acceptable format on a resource-by-resource basis, assuming both representations are available: + +```HTTP +GET /api/description/other HTTP/1.1 +Host: www.example.com +Accept: application/openapi+json +``` + +```json +"components": { + "securitySchemes": { + "MySecurity": { + "type": "http", + "scheme": "basic" + } + }, + "pathItems": { + "Foo": { + "get": { + "security": [ + "MySecurity": [] + ] + } + } + } +} +``` + +```HTTP +GET /api/description/other HTTP/1.1 +Host: www.example.com +Accept: application/openapi+yaml +``` + +```yaml +components: + securitySchemes: + MySecurity: + type: http + scheme: basic + pathItems: + Foo: + get: + security: + - MySecurity: [] +``` + +In the `other` document, the referenced path item has a Security Requirement for a Security Scheme, `MySecurity`. The same Security Scheme exists in the original entry document. As outlined in [Resolving Implicit Connections](#resolving-implicit-connections), `MySecurity` is resolved with an [implementation-defined behavior](#undefined-and-implementation-defined-behavior). However, documented in that section, it is RECOMMENDED that tools resolve component names from the [entry document](#openapi-description-structure). As with all implementation-defined behavior, it is important to check tool documentation to determine which behavior is supported.