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

[handrews]

This is not a direct port of #3822 (although it is close), for two reasons:

1. Full-document parsing (Clarify how Schema Objects require full-document parsing (3.1.1) #3758) and 3.1.1-specific implicit component resolution (PR Clarify resolving implicit connections (3.1.1) #3823) means that the 3.0.4 guidance on finding allOf-using schemas is not needed in 3.1.1
2. @jdesrosiers made some improvements and bug-fixes to the Discriminator Object language in 3.1.1 (PR 3.1.1 discriminator improvements #2618) but not 3.0.4 (because when he submitted the PR, we hadn't decided to do a 3.0.4 yet)

I have tried to merge the improvements as best I can. There were two notable changes to the improved text:

• A paragraph at the beginning was dropped because it's points are now all addressed elsewhere:
  • The definition of "name" is superseded by the definition of the term "component name" in PR Clarify resolving implicit connections (3.1.1) #3823, which we've been using consistently in several PRs now; I added an example in PR Clarify resolving implicit connections (3.1.1) #3823 to ensure that it is as clear as what @jdesrosiers wrote in the removed paragraph
  • The bit about implicit schemas not being considered (which might not have been changed in the previous 3.1.1 PR) moved down into text that I rewrote substantially in PR Clarify discriminator "*Of" and "mapping" usage (3.0.4) #3822
• The MUST wording on requiring the propertyName property sadly has to be weakened to a "SHOULD but the behavior is otherwise undefined" due to our tightened compatibility requirements for patch releases - this is how we have handled other problematic ambiguities – in practice, this is essentially as strong since disregarding the SHOULD is clearly not interoperable (see PR Define "undefined" and "implementation-defined" (3.1.1 port of #3449) #3805 for the meaning of "undefined" and "implementation-defined"

I also revived some of @jdesrosiers 's ideas that were taken out for compatibility reasons and included a co-author credit; see the commit message below.

Once this PR is accepted, I will backport @jdesrosiers 's changes, as merged here, to 3.0.4 and include a co-author credit (unless you'd rather do it yourself, Jason).

Fixes:

• Discriminator: how properly detect valid reference #2520
• Clarification on discriminator usage on allOf schemas. #3424
• How to find discriminator targets #3591

---

Commit message:

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]

[ralfhandl]

+1, minor nits

[jdesrosiers]

unless you'd rather do it yourself, Jason

No thanks, you go ahead. But, I appreciate you asking and the recognition. Thanks for getting this work over the finish line.

[miqui]

Looks good

[mikekistler]

Looks good. 👍

I commented on an empty H4. If that was not intended it should be fixed but everything else looked fine.

[mikekistler]

This looks like an empty H4 ... is that what was intended? It looks very odd.

[handrews]

It's to keep the markdown validator from complaining about broken links. That section is being added in another PR. I have like 6 different PRs that cross-reference each other and there's no good way to do this. Of the three ways I've tried, this was the only one that @ralfhandl didn't object to.

It will all get sorted as we merge and resolve conflicts.

[ralfhandl]

@handrews Do you want to merge now?