These should have the parameter name in the resulting string (see issue #3737).

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

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

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

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

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

Limit interoperable parsing expectations (avoid type conflicts)

Be more clear about `format` support (3.1.1)

The "undefined" wording was chosen to allow implementations
that make a good-faith effort to accommodate non-string values
to remain compliant.  However, new implementations are not
expected to implement any sort of type coersion, and this
guides API designers away from that expectation.

The previous wording could be read to only restrict what sort
of request bodies could use an Encoding Object, while allowing that
it could be used with other entities that use a Media Type Object.

This emphasizes that it is only relevant to Request Body Objects,
and within that, only for specific media types.

The OAS does not define how to avoid collisions between parameter
values and style delimiters.  Mostly, this is straightforward,
but the need to URL encode space characters introduces extra
confusion.  Make it clear that managing this occurs outside
of the use of style, and is the responsibility of users.

JSON Schema draft 2020-12 includes numerous keywords that require
parsing the entire document prior to deeming a reference unresolvable.
This makes that more clear and outlines several approaches.

The practice of embedding OpenAPI fragments in other formats is
deemed to have implementation-defined (non-interoperable) behavior,
as the potential complications that might arise are not predictable.

Also, remove the example that goes against the advice in the
updated binary-handling section.

Clarify how to model binary data in 3.1

 Clarify `openIdConnectUrl` #3630

Correctly escape example operationRef URLs (3.1.1 port of #3731)

Non-string discriminator values (3.1.1 port of #3728)

Clarify spaceDelimited with spaces in values (3.1.1 port of #3723)

Clarify wording on encoding field (3.1.1 port of #3724)

If no Encoding Object is provided, the behavior is the same as
an empty Encoding Object, as none of its fields are required.

Also make the translation from 3.0 binary modeling a subsection,
as otherwise the line about streaming either feels randomly inserted
into the middle of the section, or feels disconnected when placed
after the conversion table.

fix style=form examples (3.1.1)

This goes into more detail and uses "undefined" instead of
"implementation-defined" as the behavior is likely to be
incorrect (rather than just a different interpretationof an
ambiguous requirement), and may result in security concerns
as well.

Fix 3.1.1 .gitignore

Explain that dynamic refs can implement generics

This makes the relational requirements of `content` vs `schema`
and associated fields more clear.  The mutual exclusivity requirement
is moved up to the top of the Fixed Fields section, and each table
table is given a subsection clarifying its meaning.  This makes it
easier to follow the multi-table format, which is unusual within the OAS.

The commentary on `example` and `examples` is moved to the section
on `schema` and related parameters as it appears to only apply
in that case.

Thanks to Bellangelo

Co-authored-by: Aggelos Bellos <[email protected]>

Clarify constraints on Param Obj fields (3.1.1 port of #3760)

Clarify how Schema Objects require full-document parsing (3.1.1)

Undefined means "don't use this even if it seems to work, as there
are cases where it won't."  Implementation-defined means "this isn't
portable or interoperable, but it is still correct."

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

Define "undefined" and "implementation-defined" (3.1.1 port of #3449)

This clarifies the meaning of `allowEmptyValue` as discussed in
today'd TDC call.  It is intended to indicate an agreement between
the client and server to use zero-length string values as an
indicator of unused fields.

This clarifies that using the APIs involves URLs, while describing
the API involves URIs.  It ensures that all URIs involved in
the API description are called "URIs", and briefly mentions
how using URIs is different from URLs.

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

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

It's not entirely clear how these should resolve.

…vity-note

3.1.1 upport of #3801: Link for case insensitivity of auth scheme

Clarify entry/complete document terminology (3.1.1 port of #3820)

Clarify allowEmptyValue -> disregard empty values (3.1.1 port of #3812)

This moves some guidance up to the fixed fields section where
it is more obvious, and explicitly designates other configurations
as having undefined behavior.

It also creates subsections to organize the different topics, pulls
key guidance out of the examples and up into those sections,
and provides clarification on the ambiguity of names and URIs.

Finally, it incorporates ideas from @jdesrosiers regarding
the ambiguous `mapping` syntax submitted in a prior PR, but
does so in a way that meets our compatibility requirements
for patch releases.
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 <[email protected]>

Previously we deprecated the special $ref behavior entirely, but
doing so violates the compatibility guidelines that we have
re-established for ourselves within 3.x.  This wording allows
changes in 3.2, but emphasizes convergence rather than
discouraging the usage.

Not only do we not capitalize the "h" elsewhere, this example,
which pre-dated 3.1 webhooks, used the term in a confusinglty
not-quite-the-same way.

3.1 deprecates the OAS extension `example` schema keyword
in favor of the draft 2020-12 `examples` standard schema keyword.

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

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 discriminator + oneOf/anyOf/allOf usage (3.1.1 modified port of #3822)

Fixes #3152

Signed-off-by: Henry H. Andrews <[email protected]>

Signed-off-by: Henry H. Andrews <[email protected]>

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.

OpenID Connect Core URL fix (3.1.1 port of #3607)

Clarify Link Obj parameters as best we can (3.1.1 port of #3824)

Clarify "URI" and "URL" meaning and usage (3.1.1)

Path Item $ref change warning (3.1.1)

Note that they are resolved in their rendered context.

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

The four 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.

Consolidate guidance around examples (modified 3.1.1 port of #3893)

Resolution of relative URLs in CommonMark text (3.1.1 port of #3858)

Minor webhooks/callbacks and schema `examples` improvements (3.1.1)

To avoid complex merge conflicts

Stub out appendix headers (3.1.1)

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]>

Alternative: Clarify resolving implicit connections (3.1.1- alternative to #3823)

This makes it more clear that jsonSchemaDialect, like $schema,
is per document, and provides guidance for incomplete OAS documents
and using $schema in standalone schema documents.

It also clarifies the nature of "requiring" the OAS extension
vocabulary.

Co-authored-by: Karen Etheridge <[email protected]>

More guidance on schema dialects.