Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Clarify discriminator + oneOf/anyOf/allOf usage (3.2.0 port of #3846) #3885

Merged
merged 2 commits into from
Jun 6, 2024
Merged

Clarify discriminator + oneOf/anyOf/allOf usage (3.2.0 port of #3846) #3885

merged 2 commits into from
Jun 6, 2024

Conversation

handrews
Copy link
Member

@handrews handrews commented Jun 4, 2024

handrews and others added 2 commits June 4, 2024 13:39
@handrews @jdesrosiers
Clarify discriminator + oneOf/anyOf/allOf usage (3.2.0)
cda2ba7 
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 <jdesrosi@gmail.com>
@handrews
Use "discriminating value" consistently
cccd70b 
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.
@handrews handrews added discriminator clarification requests to clarify, but not change, part of the spec labels Jun 4, 2024
@handrews handrews added this to the v3.2.0 milestone Jun 4, 2024
@handrews handrews requested a review from a team June 4, 2024 20:41
@handrews handrews added the approved pr port PRs that just port an approved PR to another version label Jun 5, 2024
@miqui miqui merged commit 218b970 into OAI:v3.2.0-dev Jun 6, 2024
1 check passed
@handrews handrews deleted the disc-of-320 branch June 6, 2024 18:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@miqui miqui miqui approved these changes

@ralfhandl ralfhandl ralfhandl approved these changes

Assignees
No one assigned
Labels
approved pr port PRs that just port an approved PR to another version clarification requests to clarify, but not change, part of the spec discriminator
Projects
None yet
Milestone
v3.2.0
Development

Successfully merging this pull request may close these issues.
3 participants
@handrews @ralfhandl @miqui