Use URI references for Security Requirements in 3.2

[handrews]

Resolving component names used in referenced (as opposed to entry) documents is ambiguous, particularly in 3.1 where we advertise the ability to have a components-only document to use as a shared component library. Historically, component names were resolved from the entry document, as reference targets were extracted from the document in which they were found without regard for the contents of the rest of the document.

In 3.1, whole-document parsing is required to properly implement the Schema Object, and there is a reasonable intuition that component names should be resolved within the document in which they appear. This is at odds with the historical behavior, and one could argue that for Security Schemes in particular, it makes sense to treat them as part of the "deployment" aspect of things, which is arguably more relevant to the entry document.

For the Discriminator Object, the ambiguity can avoided by using the mapping keyword with unambiguous URI-references (meaning URI-references that are not syntactically valid as component names). There is no similar workaround for the Security Requirement Object.

Adding a URI-reference mechanism for Security Requirements, whether by allowing $ref somewhere, or just allowing URI-references as keys in place of the current component names, will make it possible to write unambiguous security requirements.

[handrews]

[NOTE: tags are no longer covered by this issue, see comments below]

There is a similar issue with tags. While a tag doesn't need to connect to a Tag Object, it is similarly ambiguos as to which Tag Objects are "in scope", and any choice made makes it impossible to connect to whichever Tag Objects (or Security Scheme Objects) are deemed "out of scope."

I'm going to write a proposal on this to consider a couple of options holistically.

[kevinswiber]

@handrews Security Requirement Objects could definitely use this. I'm actually okay with tags working this way in the 3.x release lines. We could be more explicit that Tag Objects will be resolved in the order that all documents are resolved in the description and may be overwritten upon duplicate declarations. Linting can check for duplicates. I'd suggest revisiting tags in Moonwalk.

[handrews]

I'm going to take tags out of this, because they have challenges that Security Requirements do not, and (as @kevinswiber notes) are not as much of a problem. See issue #3853 (Consolidated $ref-to-Some Object feature request) to track further thoughts on URI-references to Tag Objects (among others).