Align RFC links, show all RFCs in Normative References

ralfhandl · ralfhandl · commit 7d7f69d783c8 · 2024-07-29T09:52:53.000+02:00
diff --git a/versions/3.0.4.md b/versions/3.0.4.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/).
 
@@ -154,7 +154,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-wright-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-05|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.
@@ -1189,7 +1189,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](#usingRFC6570Implementations) for more information on constructing query strings from multiple parameters, and [Appendix D](#serializingHeadersAndCookies) 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](#encodingObject) for more information
 * The examples are percent-encoded as required by RFC6570 and RFC3986; see [Appendix E](#percentEncodingAndFormMediaTypes) 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.
@@ -1736,23 +1736,23 @@ name=example&icon=iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAIAAAD91JpzAAAABGdBTUEAALGPC%
 ```
 
 Note that this base64-encoded value had to be futher percent-encoded, replacing `/` with `%2F` and each of two final `=` padding characters with `%3D`.
-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 and the value would still need to be percent-decoded due to the `%2F`.
 
 ##### 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 `format: byte` for a multipart field is equivalent to specifying an [Encoding Object](#encodingObject) with a `headers` field containing `Content-Transfer-Encoding` with a schema that requires the value `base64`.
 If `format: byte` is used for a multipart field that has an Encoding Object with a `headers` field containing `Content-Transfer-Encoding` with a schema that disallows `base64`, the result is undefined for serialization and parsing.
@@ -1835,7 +1835,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:
@@ -3606,8 +3606,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), 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), 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
 Field Name | Type | Applies To | Description
@@ -3619,7 +3619,7 @@ Field Name | Type | Applies To | Description
 <a name="securitySchemeScheme"></a>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).
 <a name="securitySchemeBearerFormat"></a>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.
 <a name="securitySchemeFlows"></a>flows | [OAuth Flows Object](#oauthFlowsObject) | `oauth2` | **REQUIRED**. An object containing configuration information for the flow types supported.
-<a name="securitySchemeOpenIdConnectUrl"></a>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).
+<a name="securitySchemeOpenIdConnectUrl"></a>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](#specificationExtensions).
 
@@ -3946,7 +3946,7 @@ Field Pattern | Type | Description
 ---|:---:|---
 <a name="infoExtensions"></a>^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be any valid JSON value (`null`, a primitive, an array or an object.)
 
-The OpenAPI Initiative maintains several [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.
@@ -3972,8 +3972,8 @@ Two examples of this:
 OpenAPI description documents use JSON, YAML, and JSON Schema, and therefore share their security considerations:
 - [JSON](https://www.iana.org/assignments/media-types/application/json)
 - [YAML](https://www.iana.org/assignments/media-types/application/yaml)
-- [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://datatracker.ietf.org/doc/html/draft-wright-json-schema-00#section-10)
+- [JSON Schema Validation](https://datatracker.ietf.org/doc/html/draft-wright-json-schema-validation-00#section-8)
 
 ### Tooling and Usage Scenarios
 
@@ -4022,8 +4022,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.
@@ -4322,7 +4322,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.
@@ -4337,9 +4337,9 @@ This specification normatively cites the following relevant standards:
 
 Specification | Date | OAS Usage | Percent-Encoding | Notes
 ------------- | ---- | --------- | ----- | -----
-[RFC3986 URI&nbsp;Generic&nbsp;Syntax](https://datatracker.ietf.org/doc/html/rfc3986) | 01/2005 | URI/URL syntax | RFC3986 | obsoletes RFC1738, RFC2396
-[RFC6570 URI&nbsp;Template](https://datatracker.ietf.org/doc/html/rfc6570) | 03/2012 | style-based serialization | RFC3986 | does not use `+` for <code>form&#8209;urlencoded</code>
-[RFC1866&nbsp;§8.2.1 form&#8209;urlencoded](https://datatracker.ietf.org/doc/html/rfc1866#section-8.2.1) | 11/1995 | content-based serialization | RFC1738 | obsoleted by [HTML&nbsp;4.01&nbsp;§17.13.4.1](https://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1), [WHATWG&nbsp;URL&nbsp;§5](https://url.spec.whatwg.org/#urlencoded-serializing)
+[[RFC3986]] | 01/2005 | URI/URL syntax | [[RFC3986]] | obsoletes [[RFC1738]], [[RFC2396]]
+[[RFC6570]] | 03/2012 | style-based serialization | [[RFC3986]] | does not use `+` for <code>form&#8209;urlencoded</code>
+[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](#parameterObject) when `schema` is present, and in the [Encoding Object](#encodingObject) when at least one of `style`, `explode`, or `allowReserved` is present.
 See [Appendix C](#usingRFC6570Implementations) for more details of RFC6570's two different approaches to percent-encoding, including an example involving `+`.
