Clarifies that there can be multiple complete OpenAPI documents,
only one of which is an entry OpenAPI document.

Clarify entry/complete document terminology (3.0.4)

Co-authored-by: Mike Kistler <mikekistler@microsoft.com>

Clarify discriminator "*Of" and "mapping" usage (3.0.4)

This acknowledges the ambiguity in the key and value syntax of the
Link Object's `parameter` field, and provides a bit of guidance
on how to implement it.  Sadly it is not possible to fully solve
in a point release.

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

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 is the 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.

Note that they are resolved in their rendered context.

RFC6570-based serialization will not go beyond what is specified
to unpack arrays and objects.

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

Co-authored-by: Darrel <darrmi@microsoft.com>

* Paramter names don't need to be modeled as template variables.
* Include an example of a parameter name that needs encoding.
* Add more details to the fixed field entries for allowReserved

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

* 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.

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

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

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.

...to placate the PR checks in GitHub.

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

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

This backports changes made to the Discriminator Object
in 3.1.1 and merges them with the changes  made on this branch.

Note that the previouc changes incorporated reworked ideas from
@jdesrosiers regarding the ambiguous `mapping` syntax submitted
in the 3.1.1 changes but not accepted at that time due to
compatibility concerns.  This commit merges in the parts of
that 3.1.1 change that were accepted.

For the same compatibility reasons, the MUST wording for
requiring the named discriminator property in the schema
was (regrettably) weakened to a "SHOULD but otherwise undefined",
as we have done for other problematic ambiguities.

Co-authored-by: Jason Desrosiers <jdesrosi@gmail.com>

I found the "discriminator value" language confusing, because
`discriminator` is the field name, and in most cases the value
of a field is the value in the OpenAPI Description.

Reviewers did not like "discriminator property value", but
"discriminating value" makes it clear that this is about the
value that actually causes schema selection, and not about
the value of the discriminator keyword.

Also removed placeholder in favor of just having the headings,
as has been done in several other PRs that overlap with
new section PRs for internal linking.

Clarify Link Obj parameters as best we can (3.0.4)

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

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

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

Thanks to @lornajane for the review feedback.

Backport (3.0.4) of merge resolution from #3846

OpenID Connect Discovery URL fix (3.0.4 port of #3718)

Resolution of relative URLs in CommonMark text (3.0.4)

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

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

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.

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

* Consolidate guidance around examples

The three (four in 3.1) ways of specifying parameter or media type
examples are confusing. There is a lot of guidance that is repeated,
making it harder to see the essentials.  Some of that guidance is
also contradictory, with most saying that the examples SHOULD
match various conditions, but one saying that they MUST.

Research shows that SHOULD was repeatedly advocated, and instances
of MUST corrected back to SHOULD, except for one final commit
where MUST was introduced, and the subsequent commit to revert
to SHOULD seems to have simply missed one instance.  So this
change takes the position that the MUST was an error and weakens
it to SHOULD to match the other four or five places where the
requirement was specified.

* Fix typo in examples changes

Verbose Header Object documentation (3.0.4)

Improve media type serialization examples (3.0.4)

Appendix on RFC6570-derived behavior + `allowReserved` (3.0.4)

So that additional PRs can avoid merge conflicts.

Stub out all appendix headers (3.0.4)

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.

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

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

JSON Schema was accidentally the draft for 3.1, while this spec
uses the older 7159 for JSON instead of 8259, so I have matched
that rather than change it or cite both.

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.

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

Appendix on converting data types to strings (3.0.4)

Warnings for header and cookie serialization (3.0.4)

Add Security Considerations (3.0.4)

Various minor editorial improvements (3.0.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.

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

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 <ralf.handl@sap.com>

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 <ralf.handl@sap.com>

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 <ralf.handl@sap.com>

Co-authored-by: Jeremy Fiel <32110157+jeremyfiel@users.noreply.github.com>

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

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

Co-authored-by: Jeremy Fiel <32110157+jeremyfiel@users.noreply.github.com>