From 562befab85d3cdaec70710a4125d0039356d680f Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Mon, 5 Aug 2024 16:53:50 +0200 Subject: [PATCH 1/4] Improved links --- versions/3.1.1.md | 66 +++++++++++++++++++++++------------------------ 1 file changed, 33 insertions(+), 33 deletions(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 2cd4b69f8e..2331f56d60 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -12,7 +12,7 @@ The OpenAPI Specification (OAS) defines a standard, language-agnostic interface An OpenAPI description can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases. -For examples of OpenAPI usage and additional documentation, please visit [learn.openapis.org](https://learn.openapis.org/). +For examples of OpenAPI usage and additional documentation, please visit [[?OpenAPI-Learn]]. For extension registries and other specifications published by the OpenAPI Initiative, as well as the authoritative rendering of this specification, please visit [spec.openapis.org](https://spec.openapis.org/). @@ -110,7 +110,7 @@ Patterned fields MUST have unique names within the containing object. In order to preserve the ability to round-trip between YAML and JSON formats, YAML version [1.2](https://yaml.org/spec/1.2/spec.html) is RECOMMENDED along with some additional constraints: -* Tags MUST be limited to those allowed by [YAML's JSON schema ruleset](https://yaml.org/spec/1.2/spec.html#id2803231), which defines a subset of the YAML syntax and is unrelated to [JSON Schema](https://tools.ietf.org/html/draft-bhutton-json-schema-00). +* Tags MUST be limited to those allowed by [YAML's JSON schema ruleset](https://yaml.org/spec/1.2/spec.html#id2803231), which defines a subset of the YAML syntax and is unrelated to [[JSON-Schema-2020-12|JSON Schema]]. * Keys used in YAML maps MUST be limited to a scalar string, as defined by the [YAML Failsafe schema ruleset](https://yaml.org/spec/1.2/spec.html#id2802346). **Note:** While APIs may be described by OpenAPI documents in either YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML. @@ -126,7 +126,7 @@ It is RECOMMENDED that the entry OpenAPI document be named: `openapi.json` or `o #### Parsing Documents -In order to properly handle [Schema Objects](#schema-object), OAS 3.1 inherits the parsing requirements of [JSON Schema draft 2020-12 §9](https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00#section-9), with appropriate modifications regarding base URIs as specified in [Relative References In URIs](#relative-references-in-api-description-uris). +In order to properly handle [Schema Objects](#schema-object), OAS 3.1 inherits the parsing requirements of [JSON Schema Specification Draft 2020-12 Section 9](https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00#section-9), with appropriate modifications regarding base URIs as specified in [Relative References In URIs](#relative-references-in-api-description-uris). This includes a requirement to parse complete documents before deeming a Schema object reference to be unresolvable, in order to detect keywords that might provide the reference target or impact the determination of the appropriate base URI. @@ -267,7 +267,7 @@ OpenAPI Description authors SHOULD consider how text using such extensions will ### Relative References in API Description URIs URIs used as references within an OpenAPI Description, or to external documentation or other supplementary information such as a license, are resolved as _identifiers_, and described by this specification as **_URIs_**. -As noted under [Parsing Documents](#parsing-documents), this specification inherits JSON Schema draft 2020-12's requirements for loading documents and associating them with their expected URIs, which might not match their current location. +As noted under [Parsing Documents](#parsing-documents), this specification inherits JSON Schema Specification Draft 2020-12's requirements for loading documents and associating them with their expected URIs, which might not match their current location. This feature is used both for working in development or test environments without having to change the URIs, and for working within restrictive network configurations or security policies. Note that some URI fields are named `url` for historical reasons, but the descriptive text for those fields uses the correct "URI" terminology. @@ -276,7 +276,7 @@ Unless specified otherwise, all properties that are URIs MAY be relative referen Relative references in [Schema Objects](#schema-object), including any that appear as `$id` values, use the nearest parent `$id` as a Base URI, as described by [JSON Schema Specification Draft 2020-12](https://tools.ietf.org/html/draft-bhutton-json-schema-00#section-8.2). -Relative URI references in other Objects, and in Schema Objects where no parent schema contains an `$id`, MUST be resolved using the referring document's base URI, which is determined in accordance with [RFC3986 §5.1.2 – 5.1.4](https://tools.ietf.org/html/rfc3986#section-5.1.2). +Relative URI references in other Objects, and in Schema Objects where no parent schema contains an `$id`, MUST be resolved using the referring document's base URI, which is determined in accordance with [[RFC3986]] [Section 5.1.2 – 5.1.4](https://tools.ietf.org/html/rfc3986#section-5.1.2). In practice, this is usually the retrieval URI of the document, which MAY be determined based on either its current actual location or a user-supplied expected location. If a URI contains a fragment identifier, then the fragment should be resolved per the fragment resolution mechanism of the referenced document. If the representation of the referenced document is JSON or YAML, then the fragment identifier SHOULD be interpreted as a JSON-Pointer as per [RFC6901](https://tools.ietf.org/html/rfc6901). @@ -414,7 +414,7 @@ License information for the exposed API. | Field Name | Type | Description | | ------------------------------------------ | :------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | `string` | **REQUIRED**. The license name used for the API. | -| identifier | `string` | An [SPDX](https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60) license expression for the API. The `identifier` field is mutually exclusive of the `url` field. | +| identifier | `string` | An [SPDX](https://spdx.org/licenses/) license expression for the API. The `identifier` field is mutually exclusive of the `url` field. | | url | `string` | A URI for the license used for the API. This MUST be in the form of a URI. The `url` field is mutually exclusive of the `identifier` field. | This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -1118,7 +1118,7 @@ There are four possible parameter locations specified by the `in` field: * path - Used together with [Path Templating](#path-templating), where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example, in `/items/{itemId}`, the path parameter is `itemId`. * query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`. -* header - Custom headers that are expected as part of the request. Note that [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive. +* header - Custom headers that are expected as part of the request. Note that [RFC7230](https://tools.ietf.org/html/rfc7230#section-3.2) states header names are case insensitive. * cookie - Used to pass a specific cookie value to the API. ##### Fixed Fields @@ -1156,7 +1156,7 @@ Serializing with `schema` is NOT RECOMMENDED for `in: cookie` parameters, `in: h | -------------------------------------------------- | :--------------------------------------------------------------------------------------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | style | `string` | Describes how the parameter value will be serialized depending on the type of the parameter value. Default values (based on value of `in`): for `query` - `form`; for `path` - `simple`; for `header` - `simple`; for `cookie` - `form`. | | explode | `boolean` | When this is true, parameter values of type `array` or `object` generate separate parameters for each value of the array or key-value pair of the map. For other types of parameters this property has no effect. When [`style`](#parameter-style) is `form`, the default value is `true`. For all other styles, the default value is `false`. Note that despite `false` being the default for `deepObject`, the combination of `false` with `deepObject` is undefined. | -| allowReserved | `boolean` | When this is true, parameter values are serialized using reserved expansion, as defined by [RFC6570](https://datatracker.ietf.org/doc/html/rfc6570#autoid-20), which allows [RFC3986's reserved character set](https://datatracker.ietf.org/doc/html/rfc3986#autoid-13), as well as percent-encoded triples, to pass through unchanged, while still percent-encoding all other disallowed characters (including `%` outside of percent-encoded triples). Applications are still responsible for percent-encoding reserved characters that are [not allowed in the query string](https://datatracker.ietf.org/doc/html/rfc3986#autoid-24) (`[`, `]`, `#`), or have a special meaning in `application/x-www-form-urlencoded` (`-`, `&`, `+`); see Appendices [C](#appendix-c-using-rfc6570-implementations) and [E](#appendix-e-percent-encoding-and-form-media-types) for details. This property only applies to parameters with an `in` value of `query`. The default value is `false`. | +| allowReserved | `boolean` | When this is true, parameter values are serialized using reserved expansion, as defined by [RFC6570](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3), which allows [RFC3986's reserved character set](https://datatracker.ietf.org/doc/html/rfc3986#section-2.2), as well as percent-encoded triples, to pass through unchanged, while still percent-encoding all other disallowed characters (including `%` outside of percent-encoded triples). Applications are still responsible for percent-encoding reserved characters that are [not allowed in the query string](https://datatracker.ietf.org/doc/html/rfc3986#section-3.4) (`[`, `]`, `#`), or have a special meaning in `application/x-www-form-urlencoded` (`-`, `&`, `+`); see Appendices [C](#appendix-c-using-rfc6570-implementations) and [E](#appendix-e-percent-encoding-and-form-media-types) for details. This property only applies to parameters with an `in` value of `query`. The default value is `false`. | | schema | [Schema Object](#schema-object) | The schema defining the type used for the parameter. | | example | Any | Example of the parameter's potential value; see [Working With Examples](#working-with-examples). | | examples | Map[ `string`, [Example Object](#example-object) \| [Reference Object](#reference-object)] | Examples of the parameter's potential value; see [Working With Examples](#working-with-examples). | @@ -1202,7 +1202,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` replaces the `empty` column in previous versions of this specification in order to better align with [RFC6570 §2.3](https://www.rfc-editor.org/rfc/rfc6570.html#section-2.3) terminology, which describes certain values including but not limited to `null` as "undefined" values with special handling; notably, the empty string is _not_ undefined +* The `undefined` 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. @@ -1652,7 +1652,7 @@ See [Appendix B](#appendix-b-data-type-conversion) for a discussion of data type | ------------------------------------------------- | :-------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | style | `string` | Describes how a specific property value will be serialized depending on its type. See [Parameter Object](#parameter-object) for details on the [`style`](#parameter-style) property. The behavior follows the same values as `query` parameters, including default values. Note that the initial `?` used in query strings is not used in `application/x-www-form-urlencoded` message bodies, and MUST be removed (if using an RFC6570 implementation) or simply not added (if constructing the string manually). This property SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded` or `multipart/form-data`. If a value is explicitly defined, then the value of [`contentType`](#encoding-content-type) (implicit or explicit) SHALL be ignored. | | explode | `boolean` | When this is true, property values of type `array` or `object` generate separate parameters for each value of the array, or key-value-pair of the map. For other types of properties this property has no effect. When [`style`](#encoding-style) is `form`, the default value is `true`. For all other styles, the default value is `false`. Note that despite `false` being the default for `deepObject`, the combination of `false` with `deepObject` is undefined. This property SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded` or `multipart/form-data`. If a value is explicitly defined, then the value of [`contentType`](#encoding-content-type) (implicit or explicit) SHALL be ignored. | -| allowReserved | `boolean` | When this is true, parameter values are serialized using reserved expansion, as defined by [RFC6570](https://datatracker.ietf.org/doc/html/rfc6570#autoid-20), which allows [RFC3986's reserved character set](https://datatracker.ietf.org/doc/html/rfc3986#autoid-13), as well as percent-encoded triples, to pass through unchanged, while still percent-encoding all other disallowed characters (including `%` outside of percent-encoded triples). Applications are still responsible for percent-encoding reserved characters that are [not allowed in the query string](https://datatracker.ietf.org/doc/html/rfc3986#autoid-24) (`[`, `]`, `#`), or have a special meaning in `application/x-www-form-urlencoded` (`-`, `&`, `+`); see Appendices [C](#appendix-c-using-rfc6570-implementations) and [E](#appendix-e-percent-encoding-and-form-media-types) for details. The default value is `false`. This property SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded` or `multipart/form-data`. If a value is explicitly defined, then the value of [`contentType`](#encoding-content-type) (implicit or explicit) SHALL be ignored. | +| allowReserved | `boolean` | When this is true, parameter values are serialized using reserved expansion, as defined by [RFC6570](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3), which allows [RFC3986's reserved character set](https://datatracker.ietf.org/doc/html/rfc3986#section-2.2), as well as percent-encoded triples, to pass through unchanged, while still percent-encoding all other disallowed characters (including `%` outside of percent-encoded triples). Applications are still responsible for percent-encoding reserved characters that are [not allowed in the query string](https://datatracker.ietf.org/doc/html/rfc3986#section-3.4) (`[`, `]`, `#`), or have a special meaning in `application/x-www-form-urlencoded` (`-`, `&`, `+`); see Appendices [C](#appendix-c-using-rfc6570-implementations) and [E](#appendix-e-percent-encoding-and-form-media-types) for details. The default value is `false`. This property SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded` or `multipart/form-data`. If a value is explicitly defined, then the value of [`contentType`](#encoding-content-type) (implicit or explicit) SHALL be ignored. | See also [Appendix C: Using RFC6570 Implementations](#appendix-c-using-rfc6570-implementations) for additional guidance, including on difficulties caused by the interaction between RFC6570's percent-encoding rules and the `multipart/form-data` media type. @@ -1743,23 +1743,23 @@ name=example&icon=iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAIAAAD91JpzAAAABGdBTUEAALGPC_ ``` Note that the `=` padding characters at the end need to be percent-encoded, even with the "URL safe" `contentEncoding: base64url`. -Some base64-decoding implementations may be able to use the string without the padding per [RFC4648 §3.2](https://datatracker.ietf.org/doc/html/rfc4648#section-3.2). +Some base64-decoding implementations may be able to use the string without the padding per [RFC4648](https://datatracker.ietf.org/doc/html/rfc4648#section-3.2). However, this is not guaranteed, so it may be more interoperable to keep the padding and rely on percent-decoding. ##### Encoding `multipart` Media Types It is common to use `multipart/form-data` as a `Content-Type` when transferring forms as request bodies. In contrast to 2.0, a `schema` is REQUIRED to define the input parameters to the operation when using `multipart` content. This supports complex structures as well as supporting mechanisms for multiple file uploads. -The `form-data` disposition and its `name` parameter are mandatory for `multipart/form-data` ([RFC7578 §4.2](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.2)). -Array properties are handled by applying the same `name` to multiple parts, as is recommended by [RFC7578 §4.3](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.3) for supplying multiple values per form field. -See [RFC7578 §5](https://www.rfc-editor.org/rfc/rfc7578.html#section-5) for guidance regarding non-ASCII part names. +The `form-data` disposition and its `name` parameter are mandatory for `multipart/form-data` ([RFC7578](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.2)). +Array properties are handled by applying the same `name` to multiple parts, as is recommended by [RFC7578](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.3) for supplying multiple values per form field. +See [RFC7578](https://www.rfc-editor.org/rfc/rfc7578.html#section-5) for guidance regarding non-ASCII part names. -Various other `multipart` types, most notable `multipart/mixed` ([RFC2046 §5.1.3](https://www.rfc-editor.org/rfc/rfc2046.html#section-5.1.3)) neither require nor forbid specific `Content-Disposition` values, which means care must be taken to ensure that any values used are supported by all relevant software. +Various other `multipart` types, most notable `multipart/mixed` ([RFC2046](https://www.rfc-editor.org/rfc/rfc2046.html#section-5.1.3)) neither require nor forbid specific `Content-Disposition` values, which means care must be taken to ensure that any values used are supported by all relevant software. It is not currently possible to correlate schema properties with unnamed, ordered parts in media types such as `multipart/mixed`, but implementations MAY choose to support such types when `Content-Disposition: form-data` is used with a `name` parameter. -Note that there are significant restrictions on what headers can be used with `multipart` media types in general ([RFC2046 §5.1](https://www.rfc-editor.org/rfc/rfc2046.html#section-5.1)) and `multi-part/form-data` in particular ([RFC7578 §4.8](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.8)). +Note that there are significant restrictions on what headers can be used with `multipart` media types in general ([RFC2046](https://www.rfc-editor.org/rfc/rfc2046.html#section-5.1)) and `multi-part/form-data` in particular ([RFC7578](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.8)). -Note also that `Content-Transfer-Encoding` is deprecated for `multipart/form-data` ([RFC7578 §4.7](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.7)) where binary data is supported, as it is in HTTP. +Note also that `Content-Transfer-Encoding` is deprecated for `multipart/form-data` ([RFC7578](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.7)) where binary data is supported, as it is in HTTP. +Using `contentEncoding` for a multipart field is equivalent to specifying an [Encoding Object](#encoding-object) with a `headers` field containing `Content-Transfer-Encoding` with a schema that requires the value used in `contentEncoding`. +If `contentEncoding` is used for a multipart field that has an Encoding Object with a `headers` field containing `Content-Transfer-Encoding` with a schema that disallows the value from `contentEncoding`, the result is undefined for serialization and parsing. @@ -1843,7 +1843,7 @@ requestBody: ###### Example: Multipart Form with Multiple Files -In accordance with [RFC7578 §4.3](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.3), multiple files for a single form field are uploaded using the same name (`file` in this example) for each file's part: +In accordance with [RFC7578](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.3), multiple files for a single form field are uploaded using the same name (`file` in this example) for each file's part: ```yaml requestBody: @@ -1942,7 +1942,7 @@ Describes a single response from an API Operation, including design-time, static | Field Name | Type | Description | | --------------------------------------------- | :-----------------------------------------------------------------------------------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | description | `string` | **REQUIRED**. A description of the response. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. | -| headers | Map[`string`, [Header Object](#header-object) \| [Reference Object](#reference-object)] | Maps a header name to its definition. [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive. If a response header is defined with the name `"Content-Type"`, it SHALL be ignored. | +| headers | Map[`string`, [Header Object](#header-object) \| [Reference Object](#reference-object)] | Maps a header name to its definition. [RFC7230](https://tools.ietf.org/html/rfc7230#section-3.2) states header names are case insensitive. If a response header is defined with the name `"Content-Type"`, it SHALL be ignored. | | content | Map[`string`, [Media Type Object](#media-type-object)] | A map containing descriptions of potential response payloads. The key is a media type or [media type range](https://tools.ietf.org/html/rfc7231#appendix-D) and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/\* | | links | Map[`string`, [Link Object](#link-object) \| [Reference Object](#reference-object)] | A map of operations links that can be followed from the response. The key of the map is a short name for the link, following the naming constraints of the names for [Component Objects](#components-object). | @@ -2705,7 +2705,7 @@ Where JSON Schema indicates that behavior is defined by the application (e.g. fo ##### Properties -The OpenAPI Schema Object [dialect](https://tools.ietf.org/html/draft-bhutton-json-schema-00#section-4.3.3) is defined as requiring the [OAS base vocabulary](#base-vocabulary), in addition to the vocabularies as specified in the JSON Schema draft 2020-12 [general purpose meta-schema](https://tools.ietf.org/html/draft-bhutton-json-schema-00#section-8). +The OpenAPI Schema Object [dialect](https://tools.ietf.org/html/draft-bhutton-json-schema-00#section-4.3.3) is defined as requiring the [OAS base vocabulary](#base-vocabulary), in addition to the vocabularies as specified in the JSON Schema Specification Draft 2020-12 [general purpose meta-schema](https://tools.ietf.org/html/draft-bhutton-json-schema-00#section-8). The OpenAPI Schema Object dialect for this version of the specification is identified by the URI `https://spec.openapis.org/oas/3.1/dialect/base` (the "OAS dialect schema id"). @@ -3715,8 +3715,8 @@ animals: Defines a security scheme that can be used by the operations. -Supported schemes are HTTP authentication, an API key (either as a header, a cookie parameter or as a query parameter), mutual TLS (use of a client certificate), OAuth2's common flows (implicit, password, client credentials and authorization code) as defined in [RFC6749](https://tools.ietf.org/html/rfc6749), and [OpenID Connect Core](https://openid.net/specs/openid-connect-core-1_0.html). -Please note that as of 2020, the implicit flow is about to be deprecated by [OAuth 2.0 Security Best Current Practice](https://tools.ietf.org/html/draft-ietf-oauth-security-topics). Recommended for most use case is Authorization Code Grant flow with PKCE. +Supported schemes are HTTP authentication, an API key (either as a header, a cookie parameter or as a query parameter), mutual TLS (use of a client certificate), OAuth2's common flows (implicit, password, client credentials and authorization code) as defined in [RFC6749](https://tools.ietf.org/html/rfc6749), 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 @@ -3729,7 +3729,7 @@ Please note that as of 2020, the implicit flow is about to be deprecated by [OAu | scheme | `string` | `http` | **REQUIRED**. The name of the HTTP Authentication scheme to be used in the [Authorization header as defined in RFC7235](https://tools.ietf.org/html/rfc7235#section-5.1). The values used SHOULD be registered in the [IANA Authentication Scheme registry](https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml). The value is case-insensitive, as defined in [RFC7235](https://datatracker.ietf.org/doc/html/rfc7235#section-2.1). | | bearerFormat | `string` | `http` (`"bearer"`) | A hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes. | | flows | [OAuth Flows Object](#oauth-flows-object) | `oauth2` | **REQUIRED**. An object containing configuration information for the flow types supported. | -| openIdConnectUrl | `string` | `openIdConnect` | **REQUIRED**. [Well-known URL](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig) to discover the [OpenID provider metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). | +| openIdConnectUrl | `string` | `openIdConnect` | **REQUIRED**. [Well-known URL](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig) to discover the [[OpenID-Connect-Discovery]] [provider metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). | This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -4066,7 +4066,7 @@ The extensions properties are implemented as patterned fields that are always pr | ------------------------------------- | :--: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. Field names beginning `x-oai-` and `x-oas-` are reserved for uses defined by the [OpenAPI Initiative](https://www.openapis.org/). The value can be any valid JSON value (`null`, a primitive, an array or an object.) | -The OpenAPI Initiative maintains several [extension registries](https://spec.openapis.org/registry/index.html), including registries for [individual extension keywords](https://spec.openapis.org/registry/extension/) and [extension keyword namespaces](https://spec.openapis.org/registry/namespace/). +The OpenAPI Initiative maintains several [[OpenAPI-Registry|extension registries]], including registries for [individual extension keywords](https://spec.openapis.org/registry/extension/) and [extension keyword namespaces](https://spec.openapis.org/registry/namespace/). Extensions are one of the best ways to prove the viability of proposed additions to the specification. It is therefore RECOMMENDED that implementations be designed for extensibility to support community experimentation. @@ -4093,8 +4093,8 @@ OpenAPI description documents use JSON, YAML, and JSON Schema, and therefore sha * [JSON](https://www.iana.org/assignments/media-types/application/json) * [YAML](https://www.iana.org/assignments/media-types/application/yaml) -* [JSON Schema Core](https://json-schema.org/draft/2020-12/json-schema-core#section-13) -* [JSON Schema Validation](https://json-schema.org/draft/2020-12/json-schema-validation#name-security-considerations) +* [JSON Schema Core](https://tools.ietf.org/html/draft-bhutton-json-schema-00#section-13) +* [JSON Schema Validation](https://tools.ietf.org/html/draft-bhutton-json-schema-validation-00#section-10) ### Tooling and Usage Scenarios @@ -4137,7 +4137,7 @@ Certain properties allow the use of Markdown which can contain HTML including sc Serializing typed data to plain text, which can occur in `text/plain` message bodies or `multipart` parts, as well as in the `application/x-www-form-urlencoded` format in either URL query strings or message bodies, involves significant implementation- or application-defined behavior. -Schema Objects validate data based on the [JSON Schema data model](https://datatracker.ietf.org/doc/html/draft-wright-json-schema-00#section-4.2), which only recognizes four primitive data types: strings (which are [only broadly interoperable as UTF-8](https://datatracker.ietf.org/doc/html/rfc7159#section-8.1)), numbers, booleans, and `null`. +Schema Objects validate data based on the [JSON Schema data model](https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00#section-4.2.1), which only recognizes four primitive data types: strings (which are [only broadly interoperable as UTF-8](https://datatracker.ietf.org/doc/html/rfc7159#section-8.1)), numbers, booleans, and `null`. Notably, integers are not a distinct type from other numbers, with `type: integer` being a convenience defined mathematically, rather than based on the presence or absence of a decimal point in any string representation. The [Parameter Object](#parameter-object), [Header Object](#header-object) and [Encoding Object](#encoding-object) offer features to control how to arrange values from array or object types. @@ -4146,8 +4146,8 @@ However, there is no general-purpose specification for converting schema-validat Two cases do offer standards-based guidance: -* [RFC3987 §3.1](https://datatracker.ietf.org/doc/html/rfc3987#section-3.1) provides guidance for converting non-Unicode strings to UTF-8, particularly in the context of URIs (and by extension, the form media types which use the same encoding rules) -* [RFC6570 §2.3](https://www.rfc-editor.org/rfc/rfc6570#section-2.3) specifies which values, including but not limited to `null`, are considered _undefined_ and therefore treated specially in the expansion process when serializing based on that specification +* [RFC3987](https://datatracker.ietf.org/doc/html/rfc3987#section-3.1) provides guidance for converting non-Unicode strings to UTF-8, particularly in the context of URIs (and by extension, the form media types which use the same encoding rules) +* [RFC6570](https://www.rfc-editor.org/rfc/rfc6570#section-2.3) specifies which values, including but not limited to `null`, are considered _undefined_ and therefore treated specially in the expansion process when serializing based on that specification Implementations of RFC6570 often have their own conventions for converting non-string values, but these are implementation-specific and not defined by the RFC itself. This is one reason for the OpenAPI Specification to leave these conversions as implementation-defined: It allows using RFC6570 implementations regardless of how they choose to perform the conversions. @@ -4453,7 +4453,7 @@ This means that while these three characters are reserved-but-allowed in query s ### Percent-Encoding and `form-data` -[RFC7578 §2](https://datatracker.ietf.org/doc/html/rfc7578#section-2) suggests RFC3986-based percent-encoding as a mechanism to keep text-based per-part header data such as file names within the ASCII character set. +[RFC7578](https://datatracker.ietf.org/doc/html/rfc7578#section-2) suggests RFC3986-based percent-encoding as a mechanism to keep text-based per-part header data such as file names within the ASCII character set. This suggestion was not part of older (pre-2015) specifications for `form-data`, so care must be taken to ensure interoperability. The `form-data` media type allows arbitrary text or binary data in its parts, so percent-encoding is not needed and is likely to cause interoperability problems unless the `Content-Type` of the part is defined to require it. @@ -4468,9 +4468,9 @@ This specification normatively cites the following relevant standards: | Specification | Date | OAS Usage | Percent-Encoding | Notes | | -------------------------------------------------------------------------------------------------------- | ------- | --------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [RFC3986 URI Generic Syntax](https://datatracker.ietf.org/doc/html/rfc3986) | 01/2005 | URI/URL syntax | RFC3986 | obsoletes RFC1738, RFC2396 | -| [RFC6570 URI Template](https://datatracker.ietf.org/doc/html/rfc6570) | 03/2012 | style-based serialization | RFC3986 | does not use `+` for form‑urlencoded | -| [RFC1866 §8.2.1 form‑urlencoded](https://datatracker.ietf.org/doc/html/rfc1866#section-8.2.1) | 11/1995 | content-based serialization | RFC1738 | obsoleted by [HTML 4.01 §17.13.4.1](https://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1), [WHATWG URL §5](https://url.spec.whatwg.org/#urlencoded-serializing) | +| [RFC3986](https://datatracker.ietf.org/doc/html/rfc3986) | 01/2005 | URI/URL syntax | [[RFC3986]] | obsoletes [[RFC1738]], [[RFC2396]] | +| [RFC6570](https://datatracker.ietf.org/doc/html/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 `+`. From 5c2368c7eece20ccf421b3d857ce04c04a4edc6e Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Mon, 5 Aug 2024 17:41:16 +0200 Subject: [PATCH 2/4] Consistent formatting --- versions/3.1.1.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 2331f56d60..5bdc986e52 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -294,7 +294,7 @@ Relative references in CommonMark hyperlinks are resolved in their rendered cont This section describes the structure of the OpenAPI Description format. This text is the only normative description of the format. -A JSON Schema is hosted on [`spec.openapis.org`](https://spec.openapis.org) for informational purposes. +A JSON Schema is hosted on [spec.openapis.org](https://spec.openapis.org) for informational purposes. If the JSON Schema differs from this section, then this section MUST be considered authoritative. In the following description, if a field is not explicitly **REQUIRED** or described with a MUST or SHALL, it can be considered OPTIONAL. @@ -4516,4 +4516,3 @@ 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. - From c2fc43aefcb2819d0bf4f881be90e64acaecc980 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Wed, 7 Aug 2024 16:01:07 +0200 Subject: [PATCH 3/4] Update 3.1.1.md --- versions/3.1.1.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 5bdc986e52..8c42725bbb 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -2100,17 +2100,21 @@ For example, given the following HTTP request: POST /subscribe/myevent?queryUrl=https://clientdomain.com/stillrunning HTTP/1.1 Host: example.org Content-Type: application/json -Content-Length: 187 +Content-Length: 188 { - "failedUrl" : "https://clientdomain.com/failed", - "successUrls" : [ + "failedUrl": "https://clientdomain.com/failed", + "successUrls": [ "https://clientdomain.com/fast", "https://clientdomain.com/medium", "https://clientdomain.com/slow" ] } +``` + +resulting in: +```http 201 Created Location: https://example.org/subscription/1 ``` @@ -3149,7 +3153,7 @@ components: $id: fully_generic_array type: array items: - $dynamicRef: "#generic-array" + $dynamicRef: '#generic-array' $defs: allowAll: $dynamicAnchor: generic-array From b4394d5cd7c40fa2c6aef7aa5730c0949252cab9 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Wed, 7 Aug 2024 16:02:11 +0200 Subject: [PATCH 4/4] Revert "Update 3.1.1.md" This reverts commit c2fc43aefcb2819d0bf4f881be90e64acaecc980. --- versions/3.1.1.md | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 8c42725bbb..5bdc986e52 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -2100,21 +2100,17 @@ For example, given the following HTTP request: POST /subscribe/myevent?queryUrl=https://clientdomain.com/stillrunning HTTP/1.1 Host: example.org Content-Type: application/json -Content-Length: 188 +Content-Length: 187 { - "failedUrl": "https://clientdomain.com/failed", - "successUrls": [ + "failedUrl" : "https://clientdomain.com/failed", + "successUrls" : [ "https://clientdomain.com/fast", "https://clientdomain.com/medium", "https://clientdomain.com/slow" ] } -``` - -resulting in: -```http 201 Created Location: https://example.org/subscription/1 ``` @@ -3153,7 +3149,7 @@ components: $id: fully_generic_array type: array items: - $dynamicRef: '#generic-array' + $dynamicRef: "#generic-array" $defs: allowAll: $dynamicAnchor: generic-array