Appendix C

Author: ralfhandl

versions/3.0.4.md

@@ -3950,10 +3950,10 @@ Certain properties allow the use of Markdown which can contain HTML including sc
 
 Serializing typed data to plain text, which can occur in `text/plain` message bodies or `multipart` parts, as well as in the `application/x-www-form-urlencoded` format in either URL query strings or message bodies, involves significant implementation- or application-defined behavior.
 
-Schema Objects validate data based on the [JSON Schema data model](https://tools.ietf.org/html/draft-wright-json-schema-00#section-4.2), which only recognizes four primitive data types: strings (which are [only broadly interoperable as UTF-8](https://datatracker.ietf.org/doc/html/rfc7159#section-8.1)), numbers, booleans, and `null`.
-Notably, integers are not a distinct type from other numbers, with `type: integer` being a convenience defined mathematically, rather than based on the presence or absence of a decimal point in any string representation.
+[Schema Objects](#schema-object) validate data based on the [JSON Schema data model](https://tools.ietf.org/html/draft-wright-json-schema-00#section-4.2), which only recognizes four primitive data types: strings (which are [only broadly interoperable as UTF-8](https://datatracker.ietf.org/doc/html/rfc7159#section-8.1)), numbers, booleans, and `null`.
+Notably, integers are not a distinct type from other numbers, with `type: "integer"` being a convenience defined mathematically, rather than based on the presence or absence of a decimal point in any string representation.
 
-The [Parameter Object](#parameter-object), [Header Object](#header-object) and [Encoding Object](#encoding-object) offer features to control how to arrange values from array or object types.
+The [Parameter Object](#parameter-object), [Header Object](#header-object), and [Encoding Object](#encoding-object) offer features to control how to arrange values from array or object types.
 They can also be used to control how strings are further encoded to avoid reserved or illegal characters.
 However, there is no general-purpose specification for converting schema-validated non-UTF-8 primitive data types (or entire arrays or objects) to strings.
 
@@ -3965,7 +3965,7 @@ Two cases do offer standards-based guidance:
 Implementations of RFC6570 often have their own conventions for converting non-string values, but these are implementation-specific and not defined by the RFC itself.
 This is one reason for the OpenAPI Specification to leave these conversions as implementation-defined: It allows using RFC6570 implementations regardless of how they choose to perform the conversions.
 
-To control the serialization of numbers, booleans, and `null` (or other values RFC6570 deems to be undefined) more precisely, schemas can be defined as `type: string` and constrained using `pattern`, `enum`, `format`, and other keywords to communicate how applications must pre-convert their data prior to schema validation.
+To control the serialization of numbers, booleans, and `null` (or other values RFC6570 deems to be undefined) more precisely, schemas can be defined as `type: "string"` and constrained using `pattern`, `enum`, `format`, and other keywords to communicate how applications must pre-convert their data prior to schema validation.
 The resulting strings would not require any further type conversion.
 
 The `format` keyword can assist in serialization.
@@ -3976,7 +3976,7 @@ Requiring input as pre-formatted, schema-validated strings also improves round-t
 
 ## Appendix C: Using RFC6570 Implementations
 
-Serialization is defined in terms of RFC6570 URI Templates in two scenarios:
+Serialization is defined in terms of [RFC6570](https://www.rfc-editor.org/rfc/rfc6570) URI Templates in two scenarios:
 
 | Object                               | Condition                                                                                                        |
 | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
@@ -3985,27 +3985,27 @@ Serialization is defined in terms of RFC6570 URI Templates in two scenarios:
 
 Implementations of this specification MAY use an implementation of RFC6570 to perform variable expansion, however, some caveats apply.
 
-Note that when using `style: form` RFC6570 expansion to produce an `application/x-www-form-urlencoded` HTTP message body, it is necessary to remove the `?` prefix that is produced to satisfy the URI query string syntax.
+Note that when using `style: "form"` RFC6570 expansion to produce an `application/x-www-form-urlencoded` HTTP message body, it is necessary to remove the `?` prefix that is produced to satisfy the URI query string syntax.
 
 Note also that not all RFC6570 implementations support all four levels of operators, all of which are needed to fully support the OpenAPI Specification's usage.
 Using an implementation with a lower level of support will require additional manual construction of URI Templates to work around the limitations.
 
 ### Equivalences Between Fields and RFC6570 Operators
 
-Certain field values translate to RFC6570 operators (or lack thereof):
+Certain field values translate to RFC6570 [operators](https://datatracker.ietf.org/doc/html/rfc6570#section-2.2) (or lack thereof):
 
-| field         | value   | equivalent          |
-| ------------- | ------- | ------------------- |
-| style         | simple  | _n/a_               |
-| style         | matrix  | `;` prefix operator |
-| style         | label   | `.` prefix operator |
-| style         | form    | `?` prefix operator |
-| allowReserved | `false` | _n/a_               |
-| allowReserved | `true`  | `+` prefix operator |
-| explode       | `false` | _n/a_               |
-| explode       | `true`  | `*` modifier suffix |
+| field         | value      | equivalent          |
+| ------------- | ---------- | ------------------- |
+| style         | `"simple"` | _n/a_               |
+| style         | `"matrix"` | `;` prefix operator |
+| style         | `"label"`  | `.` prefix operator |
+| style         | `"form"`   | `?` prefix operator |
+| allowReserved | `false`    | _n/a_               |
+| allowReserved | `true`     | `+` prefix operator |
+| explode       | `false`    | _n/a_               |
+| explode       | `true`     | `*` modifier suffix |
 
-Multiple `style: form` parameters are equivalent to a single RFC6570 [variable list](https://www.rfc-editor.org/rfc/rfc6570#section-2.2) using the `?` prefix operator:
+Multiple `style: "form"` parameters are equivalent to a single RFC6570 [variable list](https://www.rfc-editor.org/rfc/rfc6570#section-2.2) using the `?` prefix operator:
 
 ```YAML
 parameters:
@@ -4027,7 +4027,7 @@ Note that RFC6570 does not specify behavior for compound values beyond the singl
 
 ### Non-RFC6570 Field Values and Combinations
 
-Configurations with no direct RFC6570 equivalent SHOULD also be handled according to RFC6570.
+Configurations with no direct [RFC6570](https://datatracker.ietf.org/doc/html/rfc6570) equivalent SHOULD also be handled according to RFC6570.
 Implementations MAY create a properly delimited URI Template with variables for individual names and values using RFC6570 regular or reserved expansion (based on `allowReserved`).
 
 This includes:
@@ -4036,7 +4036,7 @@ This includes:
 * the combination of the style `form` with `allowReserved: true`, which is not allowed because only one prefix operator can be used at a time
 * any parameter name that is not a legal RFC6570 variable name
 
-The Parameter Object's `name` field has a much more permissive syntax than [RFC6570 variable name syntax](https://www.rfc-editor.org/rfc/rfc6570#section-2.3).
+The Parameter Object's `name` field has a much more permissive syntax than RFC6570 [variable name syntax](https://www.rfc-editor.org/rfc/rfc6570#section-2.3).
 A parameter name that includes characters outside of the allowed RFC6570 variable character set MUST be percent-encoded before it can be used in a URI Template.
 
 ### Examples
@@ -4056,7 +4056,7 @@ words:
 
 #### RFC6570-Equivalent Expansion
 
-This array of Parameter Objects uses regular `style: "form"` expansion, fully supported by RFC6570:
+This array of Parameter Objects uses regular `style: "form"` expansion, fully supported by [RFC6570](https://datatracker.ietf.org/doc/html/rfc6570):
 
 ```YAML
 parameters:
@@ -4090,7 +4090,7 @@ when expanded with the data given earlier, we get:
 #### Expansion With Non-RFC6570-Supported Options
 
 But now let's say that (for some reason), we really want that `/` in the `b` formula to show up as-is in the query string, and we want our words to be space-separated like in a written phrase.
-To do that, we'll add `allowReserved: true` to `formulas`, and change to `style: spaceDelimited` for `words`:
+To do that, we'll add `allowReserved: true` to `formulas`, and change to `style: "spaceDelimited"` for `words`:
 
 ```YAML
 parameters:
@@ -4111,7 +4111,7 @@ parameters:
       type: string
 ```
 
-We can't combine the `?` and `+` RFC6570 prefixes, and there's no way with RFC6570 to replace the `,` separator with a space character.
+We can't combine the `?` and `+` RFC6570 [prefixes](https://datatracker.ietf.org/doc/html/rfc6570#section-2.4.1), and there's no way with RFC6570 to replace the `,` separator with a space character.
 So we need to restructure the data to fit a manually constructed URI Template that passes all of the pieces through the right sort of expansion.
 
 Here is one such template, using a made-up convention of `words.0` for the first entry in the words value, `words.1` for the second, and `words.2` for the third:
@@ -4150,7 +4150,7 @@ The `/` and the pre-percent-encoded `%2B` have been left alone, but the disallow
 
 #### Undefined Values and Manual URI Template Construction
 
-Care must be taken when manually constructing templates to handle the values that [RFC6570 considers to be _undefined_](https://datatracker.ietf.org/doc/html/rfc6570#section-2.3) correctly:
+Care must be taken when manually constructing templates to handle the values that RFC6570 [considers to be _undefined_](https://datatracker.ietf.org/doc/html/rfc6570#section-2.3) correctly:
 
 ```YAML
 formulas: {}
@@ -4198,7 +4198,7 @@ parameters:
     type: string
 ```
 
-We can't just pass `❤️: love!` to an RFC6570 implementation.
+We can't just pass `❤️: "love!"` to an RFC6570 implementation.
 Instead, we have to pre-percent-encode the name (which is a six-octet UTF-8 sequence) in both the data and the URI Template:
 
 ```YAML