OpenAPI tags have always been annoying: user-supplied arbitrary data for endpoints should be a fabulous feature – but the documentation tools seem to think that tags are only for them so it becomes more difficult to use tags for other purposes. In fact it is very useful to be able to tag endpoints with lots of different categories of data and so in OpenAPI 3.2, tags were enhanced to include an additional “kind” field so that different kinds of tag could be used.

Being grumpy about documentation tools using tags for themselves is silly (especially as I built some of those tools!), and I’m really pleased there’s a better way now. Tags might be useful for:
– tagging endpoints that are only for an exclusive group of users
– tagging endpoints to show something is “new” in an API, or relates to a particular version
– tagging endpoints to indicate their lifecycle status such as being in beta, or being deprecated
– tagging endpoints to say whether they are included in the published documentation or SDKs
– tagging if this endpoint follows a particular pattern or exception to a pattern
– tagging for some other tool to pick up and use the tag for more information later

… you get the idea, tags can be used for anything now.

Declare the kind of tag it is

Tags are declared in their own tags section, and it’s here that you can say what sort of tags they are. Here’s an example:

tags:
 - name: product
   summary: Products
   description: Product operations
 - name: partner
   summary: Partner
   description: Operations available only to partner organisations, or other privileged accounts.
   kind: audience
 - name: v2
   summary: Version 2
   description: Available in API v2 or later
   kind: version

Tags without a “kind” default to type “nav” – meaning the navigation tags which is the pre-3.2 standard behaviour. This default setting means that you can upgrade an OpenAPI description from 3.1 to 3.2 without needing to make changes, but when you want to introduce new tags you can do so by including the “kind” of tag that they are.

Apply the tag

Applying tags is done the same way as before – again, no changes needed on upgrade and the additional data is applied in the tags entry rather than at the operation level. So it looks something like the example below if I apply a v2 tag:

paths:
  "/v2/products/":
    operationId: getProductsV2
    summary: Get all products
    tags:
      - v2
      - products

Applying multiple different kinds of tag is expected and doesn’t need any special setup – the tags have their own properties, and you can apply as many as you like.

Tags Registry

The kind field is an open string – you can define your own kinds of tag and that’s intentional so that this feature can be used in different ways in different contexts. That said, there are some common use cases and for those we’ll get much better experiences if we collaborate on the tags we use and how we use them. That way, we can all align and have the tools support our use cases and give us seamless interoperability as we send our OpenAPI descriptions through all sorts of different pipelines.

The OpenAPI tag kinds registry has already been set up with some basic entries: nav (default), badge, and audience. Please check out the list for new entries and open pull requests to add tag kinds you’re using yourself.

Tags are not just for docs any more

Tell your friends, your colleagues, and your AI assistants: tags are not a docs feature. They’re an arbitrary user-supplied data feature, and I can’t wait to see what you build!

For more information about tags, read the tag kinds documentation on the OpenAPI Learn site.