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 jdesrosi@gmail.com