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.

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

Clarify discriminator + oneOf/anyOf/allOf usage (3.1.1 modified port of #3822) #3846

Merged
merged 2 commits into from
Jun 4, 2024

Commits on May 23, 2024

  1. Clarify discriminator + oneOf/anyOf/allOf usage (3.1.1)

    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 and jdesrosiers committed May 23, 2024
    Configuration menu
    Copy the full SHA
    52bdba7 View commit details
    Browse the repository at this point in the history

Commits on May 31, 2024

  1. Use "discriminating value" consistently

    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 committed May 31, 2024
    Configuration menu
    Copy the full SHA
    dd44da9 View commit details
    Browse the repository at this point in the history