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

[handrews]

NOTE 1: This is not as long as it looks! After the first block, it's just a word here and a word there to make things consistent throughout the spec.

NOTE 2: This is not at all relevant to 3.0.4

NOTE 3: This does not address links in CommonMark text, which is being discussed in issue #1701

Fixes:

• Improve confusing "Relative References in URIs" / "Relative References in URLs" section titles and wording #3545

I went through many iterations on this, some of which went into much more detail. In the end I decided to do just a few things:

• State an overall criteria for URLs vs URIs rather than just mentioning a few fields or trying to include a complete list:
  • API interaction involves URLs (by definition, really)
  • Connecting pieces of the API description involves identifier-not-necessarily-locator URIs (because JSON Schema requires it, and the text mostly uses "URI" including for the Reference Object and operationRef)
• Make sure all fields with URI behavior are described as URIs and not URLs
  • This includes using less location-oriented phrasing in several places
  • The Discriminator Object's mapping field gets a URI description in PR Clarify discriminator "*Of" and "mapping" usage (3.0.4) #3822, so it's not in this PR
• Add minimal commentary on URI behavior
  • Reference the "Document Parsing" section which mentions configuration options for identifier-base loading
  • Briefly mention key use cases as this can feel like a puzzling or overly-academic requirement
  • It's worth noting that several tools actually allow "faking" the document location already

---

For those who want the full backstory (everyone else can skip the rest of this)

The most likely point of controversy would be removing "location of" from "identifies the location of the value being referenced" in the Reference Object. The "identifies the location" phrasing was copied over from the (not cited in 3.1) JSON Reference draft, and indicates location-based (URL) behavior. However, the new wording added in 3.1 calls the Reference Object's $ref a URI rather than a URL, and includes the Reference Object in the list in 3.1.0's URI section.

The history of this apparent contradiction is rather muddled:

• Jan 2020: I assert that reference objects can be treated as URIs rather than URLs and no one seems to object
• Feb 2020: Later in the same issue, the TSC states that "identifies the location" means URL behavior in 3.0, but in 3.1 that wording is no longer used
• March 2020: The TSC endorses URI ($id-based) behavior in the Schema Object, location behavior elsewhere, and pledges to "re-review this issue holistically"
• Jan. 2021: A TSC member introduces the distinction between document authoring and api operation, which I actually didn't notice until just now, although I did notice the discussion involving two TSC Members and a longtime contributor stating that externalValue is a URI and evaluated as an identifier rather than a locator; however, this is also where the "identifies the location" wording was pulled in from the no-longer-cited JSON Reference spec
• There are several issues (Define the scope of $id resolution  #2092, Remaining JSON Schema Tweaks for OAS 3.1 #2099, Figuring out $ref and $id in OAS v3.1 in general #2100) that might have been tracking the "holistic review" that never got resolved in a clear way - some were just closed for reasons that aren't clear, or are pointed to from elsewhere as tracking the solution but not actually saying anything about it. I really cannot figure out quite what happened.

My take on this is that the general URI/URL split, and the clear presence of the Reference Object in the URI section, means that it has URI behavior, and the "identifies the location" wording is something that never got taken out after that was resolved. So I'm taking it out now, because different parts of the spec treat it differently, and URI seems more consistent with more parts of the spec.

[ralfhandl]

Minor nits

[lornajane]

Thanks!