Proposal for referencing Tag Objects with URIs. #4480
Conversation
|
Thanks for putting this together, good structure and good starting point for getting input on the idea! |
There was a problem hiding this comment.
I am not in favour of these additions for the 3.x branch. I wish that we'd implemented tags differently in the first place, and I'm sure that all the constructive discussion around the tags feature will help us a lot in future major releases.
I believe that the limitations of the current tag situation can be overcome with helper tooling and that this change (while solving a narrow but valid use case) adds complexity to the specification that is unnecessary and does not benefit the majority of users. As custodians of a widely-used standard, we have a responsibility to maintain something that is appropriate for its audience, and we should be "reluctant" in all our changes unless we see that they are really needed.
I propose that users would be equally well served by leaving the requirement to resolve tags from the entry document. Organisations can either maintain an extensive list of tags in all OpenAPI documents, and then remove any that aren't used before publishing (tooling exists for this use case), or alternatively if a tool wants to include tags found in the wider context of referenced OpenAPI documents by adding them to the top-level tags array during processing, that would work well too.
The tags array is a list of strings. It isn't an ID like the Operation uses, and it's not a named entry like the security schemes, so it is appropriate to approach the limitations of it differently. My proposal is to offer some advice or documentation on approaching this problem, but not to bring it in scope of the specification for 3.x since other options are available.
(I've marked this as "request changes" so that my review isn't missed/ignored - but please feel free to dismiss it if we reach consensus as a group that this proposal should go forward anyway).
ralfhandl
dismissed
their stale review
Convinced by @lornajane's arguments I remove my approval
|
@lornajane @ralfhandl I have updated the proposal to document the rejected status so we can point to the file in the repo (and not an old PR) in issues where the feature is requested. |
|
I'd like to leave this open a week or two longer if that's okay - a proposal isn't a minor thing and I don't want to move so quickly we don't hear input from others if they want to give it. |
| However, in [3.0.4](https://spec.openapis.org/oas/v3.0.4#resolving-implicit-connections) and [3.1.1](https://spec.openapis.org/oas/v3.1.1#resolving-implicit-connections) we RECOMMEND (== SHOULD) that tag names are resolved to Tag Objects in the _entry document_. | ||
| This means that there is no way to resolve them from the current document, which is the mirror image of the problem as that encountered by @SandroG. | ||
|
|
||
| In today's TDC call, @lornajane stated that she expects tag names to be resolved from the entry document, and @kevinswiber expressed doubt that anyone implements anything else (sadly @SandroG does not mention their tool, which presumably resolves from the current document or else they would not have explained the issue in this way). |
There was a problem hiding this comment.
I'm sorry I missed this discussion in the TDC call. I can easily imagine scenarios where tags should be resolved to the current document. Consider an API that is actually implemented as a collection of microservices that each implement the CRUD operations for one or more resources. The API description might be structured as an entry document that $ref's in groups of path items from separate documents for each microservice. Now suppose we want one tag per resource -- these tags would naturally be defined in the document for a micro service and not the entry document.
There was a problem hiding this comment.
@mikekistler yes, that's exactly the sort of scenario I feel we should support using the same mechanisms we use for everything else.
I'm a little curious why you see this scenario but reject solving it?
There was a problem hiding this comment.
I agreed with rejecting solving this in 3.2. I think we should solve this in 4.0.
There was a problem hiding this comment.
@mikekistler got it. yeah in 4.0 we need to have just one mechanism. Or at least one mechanism per use case (e.g. one magic "look in the entry document" mechanism, and one explicit "look exactly where I say" mechanism). Note that in JSON Schema, $dynamicRef is the (more flexible but also more complex) equivalent of the magic entry document mechanism.
|
@lornajane That's fine with me, if somehow things change it's still valuable to document your rationale- under "alternatives" if we end up finding a version of this to accept. |
This proposal replaces draft PR #4390 based on today's TDC call.