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

<p>One of the most underrated additions in OpenAPI 3.2 is the new support for structured, hierarchical tags.</p><p>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.</p><h3 id="the-problem-with-flat-tags">The Problem With Flat Tags</h3><p>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.</p><p>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:</p><pre>users users-profile users-notifications payments payments-webhooks analytics analytics-metrics analytics-reports</pre><p>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.</p><h3 id="what-changes-in-3-2">What Changes in 3.2</h3><p>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.</p><p>An example might look like this:</p><pre>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</code></pre><p>Docs tools can then visualise these relationships as nested menus, collapsible sections, or grouped navigation trees.</p><p>Tags are still used the same way as before:</p><pre>paths: /users/{id}/profile: get: summary: Get user profile tags: [profile] responses: '200': description: Returns a user profile</pre><p>View the Tag Object full details in OpenAPI 3.2 Specification.</p><h3 id="why-it-matters">Why It Matters</h3><p>For large organisations, this change brings real clarity.</p><ul><li>Better navigation: You can now organize endpoints by domain, feature, or business area, not just alphabetically.</li><li>Cleaner docs: Readers get a structured hierarchy that mirrors how the product is built.</li><li>Smarter SDKs: Code generators can use tag structure to create namespaces or class groupings automatically.</li></ul><p>Fewer naming hacks: No more manual prefixing to simulate folders or sections.</p><p>It’s a small spec change with a big downstream effect — especially for teams maintaining large or modular APIs.</p><h3 id="a-small-step-toward-more-maintainable-apis">A Small Step Toward More Maintainable APIs</h3><p>Structured tags don’t change how your API behaves — they change how it’s understood.</p><p>That’s an equally important part of API design.</p><p>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.</p><h3 id="comparison-with-x-taggroups">Comparison with x-tagGroups</h3><p>Before OpenAPI 3.2, the only way to organise tags hierarchically was through the x-tagGroups extension, an unofficial convention popularised by tools.</p><p>While it worked well in some ecosystems, it was never part of the OpenAPI standard.</p><p>That meant support was inconsistent: some documentation tools rendered tag groups beautifully, while others ignored them entirely.</p><p>With structured tags now built into OpenAPI 3.2, this kind of grouping is finally standardised and portable.</p><p>You no longer have to rely on vendor-specific extensions or risk losing structure when switching tools.</p><p>For API designers and documentation teams, that means one thing: your tag hierarchy will now look the same everywhere.</p>