OpenAPI has always had support for simple tags, but the OpenAPI 3.2 release brought in some serious tag upgrades including a summary field, a “kind” field with registry, – and the ability to nest tags which is the focus of today’s post. If one level of organisation isn’t enough for your API (and on bigger APIs I’d argue it shouldn’t be) then the ability to indicate which tag is the parent of this tag will be a good feature to adopt when you upgrade your OpenAPI descriptions.

The basic premise is: each tag has a ‘parent’ field which contains the name of a tag for this tag to belong to. Let’s quickly look at an example:

tags:
  - name: account
    summary: Account Details
    description: Operations relating to the customer's account
  - name: accVerification
    summary: Verification
    description: Operations for verify a new user or user detail change
    parent: account

The parent tag does not have awareness of its children, but the child tag indicates the parent that it belongs to. This works well for APIs that are composed of smaller APIs such as in a miroservices context.

There are no rules in the specification itself about the matching parent must exist – there are also no restrictions on creating structures that clearly won’t work such as loops. The tools that implement the tag structures will probably point out the error of your ways though, if you try to use something like that!

APIs that have previously used extensions to group tags, such as x-tagGroups (which I see fairly frequently), will find this approach gives an OpenAPI official way to do the same thing. The major benefit is that all tools now use the same syntax to describe the same thing and your API descriptions should be more portable across different contexts.

For more details on nesting tags in OpenAPI, see the OpenAPI learn site – then come back here and leave me a comment on what your structure looks like!