Consolidated $ref-to-Some Object feature request

[handrews]

This issure consolidates and replaces the numerous "can the OAS allow $ref for..." issues:

• Security Requirement: Add security to the components object #1850
• Security Scheme: How do I refer to external securitySchema object ? #1972 (but see also Use URI references for Security Requirements in 3.2 #3776 for an alternative)
• Server: change specification to permit $ref of server objects #2338
• Tags: Allow the use of $ref and json pointer in tags #2905
• Operation: Feature Request: $ref for Operation Object  #2922 (but note that there are impacts on finding and resolving operationId)
• Media Type: Allow $ref in request body and response content objects #3056 (closed because the specific use case is handled by overriding description with a Reference Object); also Reusable media types #2845 although there is more to that one)
• Contact: [feature] support of $ref in contact fields  #3552
• License: [feature] support of $ref in licence fields #3569

[handrews]

It's worth noting that all of these are at least a bit more complex than they initially seem:

• [NOTE: URI references of some sort were considered and rejected for 3.2, and we are unlikely to revisit them without new motivation] Tag Objects are in an array, and JSON Pointer fragments to an array are confusing and fragile
• Added in 3.2! Security Requirement Objects involve an unusual lookup to Security Scheme Objects (although see Use URI references for Security Requirements in 3.2 #3776)
• Server Objects are looked up based on their parent Object – I think that wouldn't be too much of a problem because you'd look up based on the $ref source and not on the actual location of the Server Object, but that would be a new complication to resolving things
• Operation Objects require context from parent Path Item and Paths Objects to function, which is already a problem for Link Objects (see Link Object (and Arazzo?): require referencing operation with unambiguous path template #4084 for more information)
• Added in 3.2! Media Type Objects require the media type from the parent field - while it is possible that the same Media Type Object could be used for different Media Types, this pattern would be a bit unusual and would require some thought
• It's not all that clear to me how $ref for Contact and License would be used. If we just want to avoid having to repeat these objects in each document in a multi-document OAD, I'd probably rather just relax the requirement that they be present in non-entry documents

[baywet]

@handrews was #2697 meant to be on this list as well?

[handrews]

@baywet no, because that's a $ref-to-string which is a completely different approach.

[LasneF]

what about spliting this ticket into manageable problem , if tag or security are a problem , what about handling $ref for "easy" point like contact , and license . Those are relatively stable , often shared among several APIs , and here (at least for contact) $ref can just applies as include

[handrews]

@LasneF I consolidated this because we need to think more holistically about what we do and don't do with references. It is only worth splitting something out if we decide we want to do something with it, as we did with the Media Type Object in 3.2. Otherwise, it is much more manageable to be able to look at the full set here than to chase a bunch of individual tickets that we do not, currently, have any intention of doing anything with right now. But (as with the Media Type Object in 3.2) might decide to pick up in the future.

[handrews]

@LasneF that said, if there's one (or a few) that you actively want to pursue separately, I am not standing in the way of that! I just don't want to split this for the sake of splitting it, as I found it frustrating to have to track all of the separate issues that all basically said the same thing.

[handrews]

@LasneF what do you think of my proposal that we not require the contact and license fields in documents that can't be used as entry documents (e.g. because they do not have paths or webhooks, only components. Would that solve your use case? I am reluctant to endorse $ref for these, in part because if you have a components-only document, it makes sense that it would be treated based on the referring entry document, and there might be multiple such documents and you can't know which one to $ref.

Unlike other reference targets, there cannot be any benefit to $ref-ing these within a single document. It only works for multiple documents, and the direction of reference that makes the most sense (components to entry) isn't suited to $ref.

[handrews]

The only one here that really seems both viable and well-justified by use cases is Server Objects (see #2338 for use cases).

As noted above (with no replies), I don't see the use case for Contact and Licenses, and think that the complaint with them could be solved in other ways. We've already formally decided (during 3.2) not to support URI-based referencing for tags. Referencing for Operations is complicated in ways we don't want to touch anytime soon- we ought to solve those same problems at the path item level first. And we already did Security Scheme Objects and Media Type Objects.

My inclination is to just re-open the Server issue (it has renewed relevance with SAFs (#5310, #5314) and the need to support authorization servers (#5304, OAI/sig-security#33, OAI/sig-security#31) and close this one. @LasneF @OAI/tsc objections?