Add support for OAS 3.2 nested tags via parent field in @tagMetadata

.chronus/changes/copilot-add-oas-32-nested-tags-support-2026-2-1-17-38-24.md

@@ -0,0 +1,8 @@
+---
+changeKind: feature
+packages:
+  - "@typespec/openapi"
+  - "@typespec/openapi3"
+---
+
+Add support for OpenAPI 3.2 nested tags via `parent` field in `@tagMetadata` decorator

packages/openapi/README.md

@@ -176,6 +176,7 @@ Specify OpenAPI additional information.
     `x-custom`: "string",
   }
 )
+@tagMetadata("Child Tag", #{ description: "Child tag description", parent: "Tag Name" })
 namespace PetStore {
 
 }

packages/openapi/generated-defs/TypeSpec.OpenAPI.ts

@@ -21,6 +21,7 @@ export interface TagMetadata {
   readonly [key: string]: unknown;
   readonly description?: string;
   readonly externalDocs?: ExternalDocs;
+  readonly parent?: string;
 }
 
 export interface Contact {
@@ -133,6 +134,7 @@ export type InfoDecorator = (
  * ```typespec
  * @service()
  * @tagMetadata("Tag Name", #{description: "Tag description", externalDocs: #{url: "https://example.com", description: "More info.", `x-custom`: "string"}, `x-custom`: "string"})
+ * @tagMetadata("Child Tag", #{description: "Child tag description", parent: "Tag Name"})
  * namespace PetStore {}
  * ```
  */

packages/openapi/lib/decorators.tsp

@@ -124,6 +124,9 @@ model TagMetadata {
   /** An external Docs information of the API. */
   externalDocs?: ExternalDocs;
 
+  /** The name of a tag that this tag is nested under. Only supported in OpenAPI 3.2. For 3.0 and 3.1, this will be converted to `x-parent`. */
+  parent?: string;
+
   /** Attach some custom data, The extension key must start with `x-`. */
   ...Record<unknown>;
 }
@@ -149,6 +152,7 @@ model ExternalDocs {
  * ```typespec
  * @service()
  * @tagMetadata("Tag Name", #{description: "Tag description", externalDocs: #{url: "https://example.com", description: "More info.", `x-custom`: "string"}, `x-custom`: "string"})
+ * @tagMetadata("Child Tag", #{description: "Child tag description", parent: "Tag Name"})
  * namespace PetStore {}
  * ```
  */

packages/openapi3/src/openapi.ts

@@ -1798,7 +1798,12 @@ function createOAPIEmitter(
     }
 
     for (const [name, tag] of Object.entries(metadata || {})) {
-      tags.push({ name: name, ...tag });
+      const tagData: OpenAPI3Tag = { name: name, ...tag };
+      // For OpenAPI 3.0 and 3.1, drop the 'parent' field (only supported in 3.2)
+      if (specVersion !== "3.2.0" && tag.parent) {
+        delete (tagData as { parent?: string }).parent;
+      }
+      tags.push(tagData);
     }
 
     return tags;

packages/openapi3/test/tagmetadata.test.ts

@@ -1,6 +1,6 @@
 import { deepStrictEqual } from "assert";
-import { expect, it } from "vitest";
-import { supportedVersions, worksFor } from "./works-for.js";
+import { describe, expect, it } from "vitest";
+import { OpenAPISpecHelpers, supportedVersions, worksFor } from "./works-for.js";
 
 worksFor(supportedVersions, ({ openApiFor, openapisFor }) => {
   const testCases: [string, string, string, any][] = [
@@ -150,3 +150,79 @@ worksFor(supportedVersions, ({ openApiFor, openapisFor }) => {
     ]);
   });
 });
+
+// Test for parent field - version specific behavior
+describe("tag metadata with parent field", () => {
+  it("OpenAPI 3.2 should emit parent field as-is", async () => {
+    const res = await OpenAPISpecHelpers["3.2.0"].openApiFor(
+      `
+      @service
+      @tagMetadata("ParentTag", #{description: "Parent tag"})
+      @tagMetadata("ChildTag", #{description: "Child tag", parent: "ParentTag"})
+      namespace PetStore {
+        @tag("ChildTag") op test(): string;
+      }
+      `,
+    );
+
+    deepStrictEqual(res.tags, [
+      {
+        name: "ChildTag",
+        description: "Child tag",
+        parent: "ParentTag",
+      },
+      {
+        name: "ParentTag",
+        description: "Parent tag",
+      },
+    ]);
+  });
+
+  it("OpenAPI 3.1 should drop parent field", async () => {
+    const res = await OpenAPISpecHelpers["3.1.0"].openApiFor(
+      `
+      @service
+      @tagMetadata("ParentTag", #{description: "Parent tag"})
+      @tagMetadata("ChildTag", #{description: "Child tag", parent: "ParentTag"})
+      namespace PetStore {
+        @tag("ChildTag") op test(): string;
+      }
+      `,
+    );
+
+    deepStrictEqual(res.tags, [
+      {
+        name: "ChildTag",
+        description: "Child tag",
+      },
+      {
+        name: "ParentTag",
+        description: "Parent tag",
+      },
+    ]);
+  });
+
+  it("OpenAPI 3.0 should drop parent field", async () => {
+    const res = await OpenAPISpecHelpers["3.0.0"].openApiFor(
+      `
+      @service
+      @tagMetadata("ParentTag", #{description: "Parent tag"})
+      @tagMetadata("ChildTag", #{description: "Child tag", parent: "ParentTag"})
+      namespace PetStore {
+        @tag("ChildTag") op test(): string;
+      }
+      `,
+    );
+
+    deepStrictEqual(res.tags, [
+      {
+        name: "ChildTag",
+        description: "Child tag",
+      },
+      {
+        name: "ParentTag",
+        description: "Parent tag",
+      },
+    ]);
+  });
+});

website/src/content/docs/docs/libraries/openapi/reference/data-types.md

@@ -85,8 +85,9 @@ model TypeSpec.OpenAPI.TagMetadata
 
 #### Properties
 
-| Name          | Type                                                            | Description                              |
-| ------------- | --------------------------------------------------------------- | ---------------------------------------- |
-| description?  | `string`                                                        | A description of the API.                |
-| externalDocs? | [`ExternalDocs`](./data-types.md#TypeSpec.OpenAPI.ExternalDocs) | An external Docs information of the API. |
-|               | `unknown`                                                       | Additional properties                    |
+| Name          | Type                                                            | Description                                                                                                                            |
+| ------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| description?  | `string`                                                        | A description of the API.                                                                                                              |
+| externalDocs? | [`ExternalDocs`](./data-types.md#TypeSpec.OpenAPI.ExternalDocs) | An external Docs information of the API.                                                                                               |
+| parent?       | `string`                                                        | The name of a tag that this tag is nested under. Only supported in OpenAPI 3.2. For 3.0 and 3.1, this will be converted to `x-parent`. |
+|               | `unknown`                                                       | Additional properties                                                                                                                  |

website/src/content/docs/docs/libraries/openapi/reference/decorators.md

@@ -165,6 +165,7 @@ Specify OpenAPI additional information.
     `x-custom`: "string",
   }
 )
+@tagMetadata("Child Tag", #{ description: "Child tag description", parent: "Tag Name" })
 namespace PetStore {
 
 }