Structured Tags in OpenAPI 3.2: Organising APIs the Way They Deserve

One of the most underrated additions in OpenAPI 3.2 is the new support for structured, hierarchical tags.

It doesn’t sound like much at first — tags have existed since the earliest OpenAPI versions. But this change quietly solves one of the most persistent pain points in large-scale API documentation: structure.

The Problem With Flat Tags

Before 3.2, OpenAPI only supported a flat list of tags. Each operation could reference one or more tags, and documentation tools would group endpoints accordingly.

That was fine for small APIs. But as soon as you had dozens or hundreds of operations, the tag list turned into a scrollable wall of names:

users
users-profile
users-notifications
payments
payments-webhooks
analytics
analytics-metrics
analytics-reports

Developers ended up overloading tag names to imply hierarchy — adding hyphens, prefixes, or categories — and relying on their doc viewer to make sense of it. The spec didn’t help you structure it; you just hoped your conventions held up.

What Changes in 3.2

With OpenAPI 3.2, the Tag Object can now be nested and grouped. Tags can belong to categories, subcategories, or other tags — allowing documentation tools and SDK generators to represent APIs in logical hierarchies.

An example might look like this:

tags:
  - name: users
    description: Endpoints related to user management
    summary: Users
  - name: profile
    description: Profile operations
    summary: Profile
    parent: users # <--- Makes profile a child of users
  - name notifications
    description: User notifications
    summary: Notifications
    parent: users
    
  - name: payments
    description: Payment processing and billing

Docs tools can then visualise these relationships as nested menus, collapsible sections, or grouped navigation trees.

Tags are still used the same way as before:

paths:
  /users/{id}/profile:
    get:
      summary: Get user profile
      tags: [profile]
      responses:
        '200':
          description: Returns a user profile

View the Tag Object full details in OpenAPI 3.2 Specification.

Why It Matters

For large organisations, this change brings real clarity.

• Better navigation: You can now organize endpoints by domain, feature, or business area, not just alphabetically.
• Cleaner docs: Readers get a structured hierarchy that mirrors how the product is built.
• Smarter SDKs: Code generators can use tag structure to create namespaces or class groupings automatically.

Fewer naming hacks: No more manual prefixing to simulate folders or sections.

It’s a small spec change with a big downstream effect — especially for teams maintaining large or modular APIs.

A Small Step Toward More Maintainable APIs

Structured tags don’t change how your API behaves — they change how it’s understood.

That’s an equally important part of API design.

This update is about clarity at scale. And for teams that manage complex platforms or multiple product areas, that clarity can make all the difference.

Comparison with x-tagGroups

Before OpenAPI 3.2, the only way to organise tags hierarchically was through the x-tagGroups extension, an unofficial convention popularised by tools.

While it worked well in some ecosystems, it was never part of the OpenAPI standard.

That meant support was inconsistent: some documentation tools rendered tag groups beautifully, while others ignored them entirely.

With structured tags now built into OpenAPI 3.2, this kind of grouping is finally standardised and portable.

You no longer have to rely on vendor-specific extensions or risk losing structure when switching tools.

For API designers and documentation teams, that means one thing: your tag hierarchy will now look the same everywhere.