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.

Co-authored-by: Ralf Handl <[email protected]>

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

🤦 thanks for catching this, @ralfhandl

Co-authored-by: Ralf Handl <[email protected]>

Encoding Object content and header clarifications (3.0.4)

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.

"serialization" matches other discussions, "rendering" does not.

Co-authored-by: Ralf Handl <[email protected]>

This is to make sure PR checks pass even though the PR adding
Appendix C has not yet been merged.

Thanks @notEthan!

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.

This was confusing, and my initial use of _e/s_ was too novel.
Switch the column heading to "undefined" to align with RFC6570
and make clear that it is not about `allowEmptyValue`

That style is not usable for the Header Object anyway.

Appendix for percent-encoding concerns (3.0.4)

This clarifies how to handle resolving implicit (non-URI-based)
connections in multi-document OpenAPI Descriptions.

While the behavior is implementation-defined overall, this
RECOMMENDS a single approach based on how things behaved going
back to the 2.0 referencing model.  This allows Security Schemes
and Tags to (like the top-level Server Objects) define
a deployment-specific interface for referenced documents to access.

This entry document interface approach makes less sense for the
Discriminator Object, but it can use the URI syntax of `mapping`
to keep things within the local document.

This also aligns the search for matching `operationId`s with
3.1's full-document parsing requirements.

Note that the term "complete OpenAPI document" has been defined
in another change pending approval on the 3.0.4 branch.

Co-authored-by: Ralf Handl <[email protected]>

Co-authored-by: Jeremy Fiel <[email protected]>

Co-authored-by: Ralf Handl <[email protected]>

Co-authored-by: Ralf Handl <[email protected]>

Co-authored-by: Jeremy Fiel <[email protected]>

An off-by-one caused respec to change all subsequent heading levels.

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.

This tries to be consistent about using "describe" rather than "define"
and using "description" for the entire potentially-multi-document
thing, and "document" (or sometimes "description document") to
refer to individual documents in the description.

Fix heading levels

Encoding Object and Header Object descriptions had a few
incorrect usages of "parameter" or related text left in.

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.

Include Header Object in data serialization list

Fix XML namespace syntax

Resolving implicit connections (3.0.4 port of OAI#3856)

Clarify discriminator non-impact on validation

Fix stray mentions of parameters in Encoding / Header Objects (3.0.4)

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.

Consisent x- Param/Encoding/Header wording (3.0.4)

* 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

Minor editiorial and link target fixes (3.0.4)

The description of defaults in the `contentType` fixed fields
table in 3.0.3 did not match the description in the Media Type Object's
"Considerations for multipart" section.

The "considerations for multipart" section appears to be more complete
and correct in both 3.0.3 and 3.1.1, so this adjusts that table
that replaced the fixed field defaults description to match the
"considerations for multipart" section.

This just moves (and occasionally copies) blocks of text and/or
examples in preparation form more substantial streamlining.
No modifications were made to any block.

Make the Parameter, Encoding, and Header Object fixed fields
section organization the same in all three places, with the
same levels of indentation.

Add more headings under the Encoding Object for guidance on
each form media type, and sub-headings for each example in
each of those sections.

This will make the diff for the next commit much more legible.

This puts the useful part of the "An encoding attribute..."
text into the fixed fields table, and removes the duplication.

It also links the remaining stub or truncated sections to the
information's new location under the Encoding Object.

This re-organizes and streamlines the form-urlencoded guidance
that was consolidated from the Media Type Object.

It also adds an example of a base64-encoded URL query parameter.

Use document/description/definition consistently (3.0.4)

3.0.4 dev: typo "paramter"

This organizes and streamlines the guidance on multipart
that was incorporated from the Media Type Object.

Lots of duplication has been removed, and the examples
reworked to show distinct use cases.

I forgot to run the example through URL quoting, which is necessary.

I did not mean to remove this.

This adds a note about the authoritative HTML rendering and adds
a definition for "Schema" to explain the three ways the term
is used in or with the specification.

Reorganize and streamline form media type guidance (3.0.4)

Authoritative rendering; "schema" usage (3.0.4)

format: byte also defaults to octet-stream (3.0.4)

…der definition

Co-authored-by: Ralf Handl <[email protected]>

…encies

3.0.4 formatting: don't monospace "Xxx Object"

Clarify interaction of format: byte and Content-Transfer-Encoding header definition

3.0.4: sync with 3.1.1

Align 3.0.4 with 3.1.1

Sync 3.0.4 with 3.1.1

…n-links

3.0.4: improved RFC section links

- heading levels aren't continuous MD001
- code fences need a language MD040
- table has the wrong number of cells MD056

Markdown updates for 3.0.4

3.0.4: Improved request-response example

and two other uses of it in this document