[PROPOSAL] Add summary, parent and kind as optional fields for tags #4063
Conversation
|
I used 3.1.0 as a basis so probably will need to update/reformat after a 3.1.1 release, try not to get hung up on the formatting as I'm not making the main PR quite yet. |
|
|
||
| The existing tags implementation is also quite limiting, so users/tools feel they "cannot" use tags, because they are so widely implemented for documentation navigation and required exactly one tag per operation, to be used only for this single purpose or to be opted out using extensions such as `x-traitTag`. The result is that we see lots of extensions that add arbitrary metadata to operations, some of them even become part of the specification officially (looking at you, `deprecated: true`) or being so widely used that we should probably adopt them (`x-internal`, `x-experimental`). The specification does have a way of tagging operations, but it's too limited and the result is that everything has to be added as an extension field. | ||
|
|
||
| On a personal note, I work for a tool vendor and was proposing these changes internally; but the problems affect all OpenAPI users so I brought it to the main project. |
There was a problem hiding this comment.
Thank you!!! We need more of this kind of tool to spec feedback loop.
|
|
||
| * Tags get a `summary` alongside `name` and `description`. In keeping with our existing practices: name is the identifier, summary is the short display content, and description is available in contexts where more information is appropriate. | ||
| * A `parent` field is added to support a hierarchy without adding either separators or a new data type. Your tag can belong to another tag. | ||
| * A `kind` field to explain which family of tags this tag belongs to (previously proposed as `type`). We'd expecting these to be `nav`, `badge`, `internal` and probably some other things that other tooling types would find useful. |
There was a problem hiding this comment.
(Warning: bikeshedding ahead, feel free to ignore). As "kind" has two meanings would "category" be more clear for non-native speakers? I agree on avoiding "type" as it usually means data type.
There was a problem hiding this comment.
"Category" has its own heap of baggage, I find "kind" less overloaded and easier to understand here.
There was a problem hiding this comment.
@ralfhandl I'm fine with not using "category" but I am curious as to what baggage it has in this context?
There was a problem hiding this comment.
I don't love or hate any of the options
There was a problem hiding this comment.
@handrews It's probably only my experience with "Foo category" being a coarse-grained grouping of Foos, and "Foo type" being a refinement of "Foo category" 😄
handrews
added
draft:proposal
metadata
Co-authored-by: Ralf Handl <ralf.handl@sap.com>
There was a problem hiding this comment.
I'm approving this in its current form because I'd be OK with kind and, as noted in today's TDC call, this is just the proposal and we can continue to discuss the field name as it moves to reality.
More importantly, while I'm open to alternative proposals if someone comes up with one, I emphatically support adding the simple parent hierarchy. In the Moonwalk discussion I advocated for a more thorough and flexible relational system, but I was convinced (and remain convinced) that a simple hierarchy is what is most requested, and is something that has more-or-less been implemented as extensions already.
So while I'd personally be inclined to a more complex knowledge management approach, I think this is the right step in the spirit of incremental progress that really should define the 3.x line.
|
I'll try to recap in a more intelligible way what I mentioned. What we have today are effectively labels/a list of terms. They only allow for a simple (one level/node) grouping of of operations and carry very little structure, let alone semantic meaning. This proposal effectively "upgrades" things to a classification / hierarchy. It's really nice because:
We probably don't want to required anybody working with OpenAPI to have a background in information management, although that might bring interoperability with tooling from that industry. Enabling a more semantic classification of the operation could also better enable "autonomous agents" (i.e. AI orchestrators) to discover the operation. I believe we should at least consider additional scenarios: matrix organizations. Think of the traditional insurance company that can offer packages for both auto and housing. Let's say they have dedicated quotes endpoints for each. Their taxonomy might look something like that. Each of the quotes operations being tied to its respective tag. But there's no reason why I shouldn't be able to discover that Housing_propects and Auto_propects are related mechanically, and without having to require an LLM. Hence why I'm suggesting that in addition to the parent property, we should also at the very least introduce a "relatesTo" property (multi-value, one way). An very short article on the topic Thoughts? |
|
@baywet Could you please formulate your addition in a new PR? I'm merging this now as everyone seems to be ok with it. |
After lots of discussion (and some lively issues that have been open for YEARS), I've put together a proposal for enhancing tags in a future version of OpenAPI (targeting 3.2 as the next minor release). Please take a look, identify problems/gaps/mistakes, identify any use cases of your own where this could help, and let's try to put together something great for a future release.