Replies: 8 comments 22 replies
-
|
Nice proposal!
|
Beta Was this translation helpful? Give feedback.
-
|
I agree that we should try to avoid loops, good point. One parent is what I'm proposing here, but if we get feedback in other directions we should definitely explore them. |
Beta Was this translation helpful? Give feedback.
-
|
@lornajane thanks for writing this up! I think this is an interesting complement to #30 – that discussion is something of a top-down approach starting from design concerns where tags could be part of the solution, while this proposal is bottom-up, proposing a more feature-rich tagging system. I brought up in the other discussion that we seem to have some disconnect between features/outcomes for documentation vs SDKs (and other code generation). So my question here is: Should tags be a purely documentation-oriented feature, or should they support all generative use cases? Or are there potentially two mechanisms that we need in place of the current tags, which as you note are typically used poorly anyway. Getting into @baywet 's comment a bit, and thinking about #30's questioning of hierarchy, would a more general "related" field, rather than a strict "parent" field, be more useful? I'm a strong proponent of embracing the graph-like reality of APIs. Strict hierarchical trees only work well with a subset of modeling problems. For example, "accounting" and "legal" do not have parent-child relationships with "collection" (or with each other). |
Beta Was this translation helpful? Give feedback.
-
|
We could go the "related" way as well and represent tags as a graph, and not a tree. I think it might make things harder for documentation generation tooling which might want to represent things as a tree due to navigation patterns (breadcrumbs, TOCs, etc...) and URL segmentation of the documentation pages. (the eternal ontology vs taxonomy debate). |
Beta Was this translation helpful? Give feedback.
-
|
@handrews tags should be an everything solution. I currently work for a docs tools vendor, and I think the tags have been more used/misused in the documentation space so far, but I think they apply to all the generative workflows and some degenerative(?) ones as well. Examples beyond docsgen and codegen that I've already thought of: tags should be used for filtering so that an OpenAPI can be maintained as a whole, and then only the partner endpoints, or all endpoints except the internal ones, or something can be filtered out and published. There will also be use cases that I haven't thought of, which is why I'm keeping this open approach. I have seen requests for tags as a hierarchy and I'm clear on the use cases for that model. I also think it is well understood and can be used successfully by both tool builders and end users. I'm less clear on either the use case or the success chances of the other options mentioned. |
Beta Was this translation helpful? Give feedback.
-
|
@baywet nothing here requires any API producer to do anything. Use cases that are represented by trees should be represented by trees, and nothing I said makes that inherently harder to do. @lornajane I can definitely understand hierarchy having more clear uses cases, especially in terms of documentation UI layout. Having options other than hierarchy becomes more important in the context of things being discussed in #30. But it may be that there are other ways to solve that. (also... LOL degenerative workflows... arguably among the more common types!) |
Beta Was this translation helpful? Give feedback.
-
|
I'm very conscious that this proposal does not solve all the problems, it's "better tags" rather than "perfect tags". I'm aiming for a balance between the features that a simple API needs and the majority of users can understand, and solving 80% of the problems we see already being solved in one way or another. |
Beta Was this translation helpful? Give feedback.
-
What purposes tags do fit? Honest question. I only seen them used for grouping operations in UI or in a client library, and it doesn't seem like the right purpose. |
Beta Was this translation helpful? Give feedback.
-
|
Tags are a generic taxonomy feature, so you can categorise operations by ... whatever scheme makes sense to you. Grouping operations is one, and I think that's a really valid use case. Tags might also be useful for marking internal operations, or endpoints with restricted access. We have a Does that help a bit? |
Beta Was this translation helpful? Give feedback.
-
By 'you', you mean author of the API, the tool that API is implemented in, the author of the client, or a client library? The specification should be a contract between all the parties. 'whatever scheme makes sense to you' isn't.
Internal to whom? to the team, department, institution? Security requirements answer this clearly. Also the tag of type BTW, this gives me idea for my client generator: it should be able to filter operations by security requirements. See? No need for any tags or flags.
But why tags? If we want properties with clear semantics, they're added as properties or flags -
Yeah it helps a lot - now I think tags in OAS are useless and should be deprecated ;) |
Beta Was this translation helpful? Give feedback.
-
|
@rafalkrupinski it's not clear if your comment is serious, but I'll pick out a couple of points as part of a wider discussion that others might find useful or want to constructively progress. It seems like you expect that a tag like "internal" has some special meaning, and that we pre-define some list tags can be used - and all the tools know what that means. That's not how tags work now, and I'm not proposing that they should. Instead, users can categorise tags as appropriate for their use case. A docs tool might offer use of tags for navigation - the user says which tags to use (or adopts the proposed type field). A client code generator might offer to include/exclude endpoints by tag - the user says which tag that should be. For one API that might mean excluding something tagged as a prototype; for another API that might mean only including endpoints tagged as "partner" - or probably a whole lot of other options. It's also likely that some tools will use pre-chosen tags that users can apply to API descriptions, and of course that's fine, but it's probably not part of the spec. Even defining "type" seems like possible overreach, but I think it will help us to get the most common use cases that we already know to be easily adopted without limiting anything else that could be built with this approach. |
Beta Was this translation helpful? Give feedback.
-
|
The last sentence was meant a half-joke. Probably it shouldn't. I still don't see a solid reason to use tags. If we're discussing changing the spec, why not add something that can work as a contract between authors and users?
So, if I understand you correctly, you're proposing a double hierarchy, through parent, and (a flat hierarchy) through type. Does seem
OK, lets say we write an API server. We want to group operations by subject or resource and then we want to configure our UI to display operations in groups. Is it something you had in mind?
If I had an API that's so large that I wanted to split client into separate libraries (as I understand you're suggesting), then I'd rather separate the server and/or spec first. And I don't think anyone cares about size of a generated client library. If I had a subset of operations intended for a specific user or groups of users, I'd use security requirements, since just tagging wouldn't stop anyone from using other operations. I'd also consider having separate server. If I had a prototype operations, then I had a dedicated server for them. I might generate a prototype client for it, I'd distribute it only to interested parties, and the prototype operations would be marked as such in the documentation, since I'm unaware of any mechanism analogous to I think the only thing a tool can do with prototype operations is adding a badge in a API UI, so lets have a
Why would they use tags instead of extended properties? Seems to me that any use case we might have for tags would be served better by other means. |
Beta Was this translation helpful? Give feedback.
-
|
This thread wasn't especially constructive in its tone but I wanted to circle back and recognise that there's a good question here. Should we be looking at everything that tags get used for, and adding those fields to the specification instead of allowing conventions to develop organically? My personal opinion is that tags opens the door to niche and novel usages (and that's a Good Thing (TM) ), they're flexible and are a useful tool for anything where user-supplied data has value. Plenty of use cases would be better served with more specific |
Beta Was this translation helpful? Give feedback.
-
|
It's correct that this is how tags are predominantly used. However, I'm wondering if we've just always used the wrong capability! I've written converters to turn OpenAPI into Postman collections and vice-versa. It's always felt off and been lossy. Tags do not make good organization hierarchy pointers. I would actually propose going in the opposite direction: lean into tagging, allow tags to have an optional |
Beta Was this translation helpful? Give feedback.
-
|
Thinking about this again. I'd like to put some more thought into grouping and hierarchy. We run into a lot of issues trying to use tags for this purpose today. I guess one question is... How else are tags actually being used in the wild? Is anyone actually querying and filtering operations based on tags? It seems like a legitimate use case. I've done this using CLI-based JSON query tools and using JSON-based document data store queries... but I don't know if I've ever seen it explicitly productized. |
Beta Was this translation helpful? Give feedback.
-
|
aiopenapi3 - a dynamic client library in python lets you invoke operations with |
Beta Was this translation helpful? Give feedback.
-
|
I've seen a few uses of tags for filtering - but it's more common (which I believe is because so many tools misuse tags) to add extra fields that can then be used for filtering. For example, I think the point about whether this is even a "tag" at some point is a very good one. Some blogging platforms use categories for a structured containment of content where a single item can only be in one category, and the categories can nest - and they same platforms have an additional tags feature. I think tags could easily cover our needs, but I'm open to other ideas! The key thing is that I'm hearing some common use cases or problems to solve, which is good. |
Beta Was this translation helpful? Give feedback.
-
|
We use tags for grouping operations in the (interactive) API documentation. Tag values are typically the "resource type" that the operation acts on or returns, and operations that "follow a relationship" are tagged with both the source and target resource type, see for example https://api.sap.com/api/CE_BANK_0003/resource/Bank.
|
Beta Was this translation helpful? Give feedback.
-
|
Same use case here and with many other shops that I have met and shared ideas with. |
Beta Was this translation helpful? Give feedback.
-
|
I like the idea of hierarchical tags, but (This assumes each tag can have only one parent tag.) tags:
- name: deprecated
type: internal
summary: Deprecated
description: This operation has been deprecated and will be removed in the future. Avoid using items with this tag.
- name: shop
type: nav
summary: Order Online
description: Operations relating to the retail operations behind the [online shopping site](https://example.com/shopping).
subtags: # or 'children', or similar
- name: products
type: nav
summary: Products
description: View and manage the product catalog.
- name: orders
type: nav
summary: Online Orders
description: Place, fulfil and invoice orders for the online shop. |
Beta Was this translation helpful? Give feedback.
-
|
I thought we fixed that with the upcoming addition to section OpenAPI Description Structure:
Maybe we should add there that only the entry document's OpenAPI Object is used and OpenAPI objects in non-entry documents are disregarded. This is kind of implied by not defining a "merge" algorithm for OpenAPI Objects in the multi-document case, which implies that only the |
Beta Was this translation helpful? Give feedback.
-
|
@ralfhandl As seen in Resolving Implicit Connections, there are problems no matter what rule you set for implicit tag resolution. The solution is to make it (or at least allow it to be) explicit. I am vehemently opposed to any kind of merge algorithm outside of an overlays concept. What we need is clarity and intuitive control over connections among different parts of the spec. Not more magic that may or may not work for a given scenario because it makes a bunch of assumptions. Almost all of the really thorny reference-ish problems in 3.x are due to attempts at that sort of magic. |
Beta Was this translation helpful? Give feedback.
-
|
What I tried to say:
|
Beta Was this translation helpful? Give feedback.
-
|
@ralfhandl since we're talking about a major revision (this being the moonwalk repo), let's solve the problem consistently and not have weird special casing with entry documents. If you want to talk about 3.2, let's use: |
Beta Was this translation helpful? Give feedback.
-
|
I assume that we again are on the same page and confused by different ways of expressing the same thing. We'll probably have to pause this discussion until we have a "skeleton" for Moonwalk on which to anchor it, and then flesh out the details. |
Beta Was this translation helpful? Give feedback.
-
|
@lornajane 1st and foremost thanks for sharing your ideas in the form of this proposal. Having grokked everyone's opinion here (to get some perspective), are you then proposing a taxonomic approach to docgen and codegen ? I think this is a good opportunity to go beyond the current status quo of how tags have been traditionally used (misused ? - although to be honest like @ralfhandl I just have the same resource-oriented use case, which then is leveraged by whatever tool works for me). I do understand that in your space you have deeper use cases. I am trying to get there. Looking at your example: |
Beta Was this translation helpful? Give feedback.
-
|
The pet store isn't a great example, but here's an "in the wild" use of x-tagGroups from Docker: https://github.com/APIs-guru/openapi-directory/blob/433a94f3e9e268f2b000b0b497785ede34332a7f/APIs/docker.com/hub/beta/openapi.yaml (thanks, apis.guru!) Existing 3.x tags sections from that description(note:
tags:
- name: resources
x-displayName: Resources
- name: rate-limiting
x-displayName: Rate Limiting
- name: authentication
x-displayName: Authentication
- name: access-tokens
x-displayName: Personal Access Tokens
- name: images
x-displayName: Advanced Image Management
- name: audit-logs
x-displayName: Audit Logs
- name: org-settings
x-displayName: Org Settings
- name: repositories
x-displayName: Repositories
- name: scim
x-displayName: SCIM
x-tagGroups:
- name: General
tags:
- resources
- rate-limiting
- name: API
tags:
- authentication
- access-tokens
- images
- audit-logs
- org-settings
- repositories
- scimCompare with the proposed replacement: The same tags in the proposed new style structure (doesn't include `type/kind` examples)
tags:
- name: General
- name: API
- name: resources
summary: Resources
parent: General
- name: rate-limiting
summary: Rate Limiting
parent: General
- name: authentication
summary: Authentication
parent: API
- name: access-tokens
summary: Personal Access Tokens
parent: API
- name: images
summary: Advanced Image Management
parent: API
- name: audit-logs
summary: Audit Logs
parent: API
- name: org-settings
summary: Org Settings
parent: API
- name: repositories
summary: Repositories
parent: API
- name: scim
summary: SCIM
parent: APIThanks for prompting me to make a more concrete example for us to look at! |
Beta Was this translation helpful? Give feedback.
-
|
After discussion in the SIG meeting (Moonwalk) today, there are some agreements on what we should do next.
|
Beta Was this translation helpful? Give feedback.
-
Tags in OpenAPI 3.x are fit for many purposes, sadly they're not really fit for the purposes that they actually get used for. Having seen a bunch of discussions about how to work around the tags situation, and a number of other feature requests that would be solved with tags if we were not already using them incorrectly, I'd like to propose that we level up our tags game for the next generation.
Tags are mostly used in a one-tag-per-operation format, to group operations for display in reference documentation. This is very limiting because:
x-tagGroupsis a good example - and there's a very active open issue on OpenAPI as wellx-internalas a tag-alike since if we could add arbitrary tags to endpoints, it could be tagged in that fashionProposed changes
I think we can achieve these changes by enriching the existing top-level tags declaration to add more metadata, that the various tools can use as they please.
summaryalongsidenameanddescription. 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.parentfield is added to support a hierarchy without adding either separators or a new data type. Your tag can belong to another tag.kindfield to explain which family of tags this tag belongs to (previously proposed astype). We'd expecting these to benav,badge,internaland probably some other things that other tooling types would find useful. I'm very open-minded on the values we should use here, and it definitely needs to be extensible, but offering some suggested values that would get tooling vendors to be on the same page for the use cases we already know about is my goal. And leaving this open for all the other use cases I haven't thought of - and making it clear that more use cases are expected and tools should respect that. (update: we'll use a registry rather than set these out in the spec itself)Example
I work for a tools vendor, and I originally started writing this as an internal feature proposal - but I realised that there's a lot of other tools with the same discussions happening, so I'm proposing it here.
Beta Was this translation helpful? Give feedback.
All reactions