Clarify "URI" and "URL" meaning and usage (3.1.1) #3838
Merged
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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:
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:
operationRef
)mapping
field gets a URI description in PR Clarify discriminator "*Of" and "mapping" usage (3.0.4) #3822, so it's not in this PRFor 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:
$id
-based) behavior in the Schema Object, location behavior elsewhere, and pledges to "re-review this issue holistically"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 specMy 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.