This copies the relevant Parameter Object fields to the Header Object
instead of relying on implicit guidance.  The text for the fields
has been edited to reflect that only headers are being described.

This also include an example of describing a header using the
`content` field, and explaining why it is necessary to do so.

Co-authored-by: Ralf Handl <ralf.handl@sap.com>

* Replace the outdated "model" terminology with "schema"
* Remove the outdated `text/plain` array example, which does not correlate with current OAS requirements
* Rather than replacing the `text/plain` example direclty, enhance the example of serializing `application/json` content in `application/x-www-form-urlencoeded` request bodies.

This aligns allowReserved with style by similarly correlating it
with RFC6570 operators.  This will make it easier to write a more
in-depth explanation of the process in an appendix.

This also adds one of several appendixes to be added to clarify
the most obscure details of Parameter Object and Encoding Object
serialization.

This clarifies the correspondence between OAS fields and RFC6570
operators, and acknowledges that some field values and combinations
do not have analogues.  It provides further guidance for how to
use RFC6570 implementations to support these configurations.

This includes a SHOULD directive regarding using RFC6570 expansion
with the non-RFC6570 styles, as the use of "explode" and
"allowReserved" does not otherwise make any sense.  It perhaps
could be a MUST.

Examples are included to show both typical usage, and how to
work around the lack of exact RFC6570 equivalences for certain
configurations.

It's very unclear how numbers, booleans, and other non-UTF-8-string
values are converted to strings, particularly for the form media types.
This adds a brief appendix that acknowledges the lack of standardization,
and points to resources for the few cases that do have specifications.

It highlights concerns with relying on certain JSON Schema keywords
or values for serialization, and suggests defining schemas of
type string and requiring applications to perform the conversion
prior to schema validation as a way to control the results.

This also clarifies that schema validation occurs before serialization.

Also add note about RFC6570 type conversions.  The spec doesn't
address it, but implementations often have their own rules.

This makes serializing cookie paramters and most header parameters
with `schema` and `style` NOT RECOMMENDED.
It is not clear that any `schema`-based serialization for cookies
will produce a correct value (although the reason is sufficiently
obscure that many implementations might ignore it and produce
cookie-compliant output anyway).
With headers, there are numerous pitfalls and only the simplest
scenarios will work properly, although perhaps the warning
here could be reworded to emphasize the safe scenarios more clearly.

The details are relegated to an appendix, because truly, most
people will not want to know.  But recommending against syntactically
legal configurations really does need to be explained in the spec.

Also, don't use

- in: header
  name: Cookie

Because... yeah.

This adds the previously standalone security considerations
document as a top-level section just before the appendices.

Guide readers to supplemental documentation, examples, related
specificatioins, and extension registries.  These sites answer
many questions that otherwise get raised as GitHub issues.

Co-authored-by: Lorna Jane Mitchell <github@lornajane.net>

…3861 7/11)

Co-authored-by: Ralf Handl <ralf.handl@sap.com>

Thanks to @lornajane for the review feedback.

When we mention YAML's "Failsafe schema" we give it a lower-case
"schem", as the YAML documentatio does.  We also prefix it with
"YAML".

However, we capitalize "Schema" in "JSON Schema ruleset",
which (given how much JSON Schema is used in the OAS) is a jarring
overlap with "JSON Schema".

This change aligns "YAML JSON schema ruleset" with
"YAML Failsafe ruleset" and explicitly calls out that it is
unrelated to JSON Schema.

… 1/4)

The Encoding Object's `contentType` field takes a comma-separated
list of either regular or wildcared media types.  These are the
"two types" mentioned in the previous wording – "two" here did
*not* refer to a limit on the number of entries in the list.

These are not exactly media-type or media-range values, as both
of those include parameters.

This change also moves the hard-to-follow list of default values
out of the individual field cell and into its own table.

It takes `Content-Disposition` out of the header field's cell
and instead explains limitations on header usage, and explains
how `Content-Disposition` is used for encoding.

This explanation includes a suggestion on how other `multipart`
formats could be used with an Encoding Object, since their
unnamed parts otherwise cannot be supported.

Finally, it clarifies the interaction between `contentType`
and the three fields imported from the Parameter Object, by
aligning the recommended (but not, for compatibility reasons,
required) behavior with guidance added in 3.1.0.

Thanks to @notEthan for the comments!

This splits the Encoding Object's fixed fields table
to make the usage more clear, and closer to how it is presented
for the Parameter and Header Objects

Percent-encoding is a minefield, although in practice it mostly works.

This appendix attempts to acknowledge the concerns and then define enough
terminology and link to enough other specifications that interested
readers will be able to research further details.

This aligns all examples with RFC6570 operator prefixing behavior,
which was previously only shown for `matrix` and `label`.  The
non-RFC6570 styles (`spaceDelimited`, `pipeDelimited`, and
`deepObject`) are treated as analogues of `form` and therefore
prefixed with a `?`.  The lack of suitablity of this for
cookie parameters has been addressed with an appendix in
another change, and the appendix has been stubbed out here to
ensure that the link is valid.

Switch the "empty" column heading to "undefined" to align with
RFC6570 and make clear that it is not about `allowEmptyValue`

…911 2/2)

The PR adding Appendix B pre-dated giving the Header Object
its own field tables.  This adds "Header Object" to the list
of relevant Objects along with the Paramter Object and the
Encoding Object.

The XML Object's namespace field was changed from "URL"
to "absolute URI" because relative references in a namespace
are deprecated by XML, and the base URI to use for resolving
them in the context of an OpenAPI Description is unclear.

However, XML namespaces can include fragments, and the
correct term is "non-relative URI" rather than "absolute URI"
which forbids fragments.

This change includes additional guidance on how XML usage and
the requirements of this specification do not quite align.

Be very explicit that discriminator MUST NOT change the validation
outcome, and explain the implication for the "allOf" use case.

It was a bit challenging to figure out where to put the wording
about allowing extension parameters when there are multiple
fixed fields tables, each in their own subsection.

For the Parameter Object (the only one with multiple tables in
past releases), it had been after the last table, but that got
further and further away from what felt like the main part of
the Object description.

I thought I had put it consistently after the initial
"Common Fixed Fields" table, but I put it even before that in
one place (which we don't do anywhere), and I forgot to include
it in the Header Object at all.

This change puts it after the Common Fixed Fields table for
all three, which means that for all Objects it is immediately
after the first Fixed Fields table.

* Fix a copy-paste error that broke a link in an appendix
* Fix a sentence that just kind of... wandered off
* Prevent line breaks after the `?` in the form examples

These lines were added to clarify in 3.0 what was already fixed
properly in 3.1.  Remove most of them, but keep (and reword) the
explanation of how they correlate with how the Parameter Object
fields are used.

OAS 3.1 allows using RFC6570-style serialization with
`multipart/form-data`, but this can interact with the requirements
of the media type in unexpected and arguably incorrect ways.

In the link to Appendix C, call out that multipart/form-data
encoding with `style`, etc. can have problematic interactions
with `multipart/form-data`.

Various updates ported over from 3.0.4 mention using the `format`
values `byte` or `binary`, which have been replaced by the
`contentMediaType` and `contentEncoding` keywords.  This change
updates those ported chagnes accordingly.

Co-authored-by: Ralf Handl <ralf.handl@sap.com>

Co-authored-by: Ralf Handl <ralf.handl@sap.com>