Add support for OAS 3.2 nested tags via parent field in @tagMetadata by Copilot · Pull Request #9577 · microsoft/typespec

Copilot · 2026-02-04T14:54:48Z

Add support for OAS 3.2 Nested Tags

Update TypeSpec.OpenAPI.TagMetadata model to include parent field in decorators.tsp
Update generated TypeScript types for TagMetadata interface
Add parent field handling to resolveDocumentTags() in openapi.ts
- For OpenAPI 3.2: emit parent field natively
- For OpenAPI 3.0/3.1: drop the field entirely (not supported in these versions)
Add comprehensive tests for parent field in 3.0, 3.1, and 3.2
Update documentation with examples
Address review feedback to drop field instead of converting to x-parent
Run pnpm format to fix formatting issues
Add changeset for release notes

Summary

This PR adds support for OpenAPI 3.2 nested tags by introducing a parent field in the @tagMetadata decorator.

Changes: 8 files, 106 insertions, 8 deletions

The implementation correctly handles version differences:

OpenAPI 3.2: Emits parent field natively
OpenAPI 3.0/3.1: Drops the parent field entirely (not supported in these versions)

Original prompt

This section details on the original issue you should resolve

<issue_title>Add support for OAS 3.2 Nested Tags</issue_title>
<issue_description>### Clear and concise description of the problem

According to OAS 3.2 spec tags now can have parent field, allowing to create tags hierarchy.

https://spec.openapis.org/oas/v3.2.0.html#tag-object

I couldn't find any documentation around it and seems like it wasn't yet implemented.

I'm proposing to to extend default @tag decorator to accept now variadic amount of strings.
@tag("parent1", "parent2", "actual-tag")
op myop(): void
In this case all strings will represent hierarchy path.

Checklist

Follow our Code of Conduct

Read the docs.

Check that there isn't already an issue that request the same feature to avoid creating a duplicate.</issue_description>

<agent_instructions>we need to add support for parent in @tagMetadata decorator. Note that this property only is supported in openapi 3.2, when emitting 3.0 or 3.1 it should be dropped.</agent_instructions>

Comments on the Issue (you are @copilot in this section)
@timotheeguerin that might more be part of the `@tagMetadata`
Like this but without the x-
playground
@service
@tagMetadata("pet", #{
  description: "Pet"
})
@tagMetadata("cat", #{
  description: "Cat",
  `x-parent`: "pet",
})
namespace My;

@tag("cat")
op test(): string;
```</body></comment_new>
<comment_new><author>@timotheeguerin</author><body>
Oh I wouldn't say it's done, we still need to allow putting parent directly without `x-`. And what does that mean for 3.1 and 3.0. One option is to add the x- if someone try to use it but emit 3.0 or 3.1</body></comment_new>
</comments>

Fixes Add support for OAS 3.2 Nested Tags #9510

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

- Updated TagMetadata model to include parent field - Modified openapi.ts to convert parent to x-parent for 3.0/3.1 - Added comprehensive tests for all OpenAPI versions - Tests passing for parent field in 3.2, x-parent in 3.0/3.1 Co-authored-by: timotheeguerin <1031227+timotheeguerin@users.noreply.github.com>

- Added example of nested tags using parent field - Rebuilt packages to update generated types Co-authored-by: timotheeguerin <1031227+timotheeguerin@users.noreply.github.com>

timotheeguerin · 2026-02-04T16:34:49Z

@copilot need to make sure you do a full build and commit the generated files. ANd run pnpm format to format the files

pkg-pr-new · 2026-02-04T16:37:28Z

Open in StackBlitz

npm i https://pkg.pr.new/@typespec/openapi@9577

npm i https://pkg.pr.new/@typespec/openapi3@9577

commit: 90e2f11

- Changed from using 'as any' to a more type-safe approach - Use tag.parent from source TagMetadata to check parent existence - Only use type assertion on delete operation with explicit type Co-authored-by: timotheeguerin <1031227+timotheeguerin@users.noreply.github.com>

- Updated README.md with parent field example - Updated decorators.md with parent field example - Generated files from full build Co-authored-by: timotheeguerin <1031227+timotheeguerin@users.noreply.github.com>

Copilot · 2026-02-04T16:51:55Z

@copilot need to make sure you do a full build and commit the generated files. ANd run pnpm format to format the files

Done in c831ac7. Ran full build and pnpm format, committed the generated documentation files.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

telemetry.astro.build
- Triggering command: /usr/local/bin/node node /home/REDACTED/work/typespec/typespec/website/node_modules/.bin/../astro/astro.js build sh sion�� ebsite/src/content/docs/docs/emitters/openapi3/reference node ules/.bin/sh n --local --verbsh . node node tool�� lmstxt --output-dir ../../website/src/content/docs/docs/libraries/http/reference ./specs e signature && tscsh node st/node-gyp-bin/tsx ./.scripts/regen-compiler-docs.ts node (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

timotheeguerin · 2026-02-05T00:33:58Z

@copilot pull latest change from main and resolve merge conflicts

- Integrated parent field conversion logic into refactored resolveDocumentTags function - Updated test imports to match main branch changes - Preserved parent field tests for all OpenAPI versions Co-authored-by: timotheeguerin <1031227+timotheeguerin@users.noreply.github.com>

Copilot · 2026-02-05T00:39:12Z

@copilot pull latest change from main and resolve merge conflicts

Merged main branch in 2cd4f77. Resolved conflicts by integrating the parent field conversion logic into the refactored resolveDocumentTags function that was added in main.

timotheeguerin · 2026-02-05T20:46:54Z

@copilot run pnpm format exactly the format check is failing

- Removed extra blank line in tagmetadata.test.ts Co-authored-by: timotheeguerin <1031227+timotheeguerin@users.noreply.github.com>

Copilot · 2026-02-05T20:56:59Z

@copilot run pnpm format exactly the format check is failing

Done in 6facdb9. Ran pnpm format after doing a full build, fixed formatting issue (removed extra blank line).

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

telemetry.astro.build
- Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node /home/REDACTED/work/typespec/typespec/website/node_modules/.bin/../astro/astro.js build node tool�� ebsite/src/conte--llmstxt . /.bin/node --import @typespec/librar/home/REDACTED/work/typespec/typespec/packages/http-specs/node_modules�� --no-emit node /nod�� gen-extern-signature node de/node/bin/sh --no-emit l/reference (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

timotheeguerin · 2026-03-01T17:35:03Z

@copilot please add changelog

- Added feature changeset for @typespec/openapi and @typespec/openapi3 - Describes support for parent field in @tagMetadata decorator Co-authored-by: timotheeguerin <1031227+timotheeguerin@users.noreply.github.com>

Copilot · 2026-03-01T17:39:04Z

@copilot please add changelog

Done in d87c38c. Added feature changeset for @typespec/openapi and @typespec/openapi3 packages.

azure-sdk · 2026-03-02T16:02:12Z

You can try these changes here

🛝 Playground	🌐 Website	🛝 VSCode Extension

Initial plan

b69828a

Copilot AI assigned Copilot and timotheeguerin Feb 4, 2026

Copilot started work on behalf of timotheeguerin February 4, 2026 14:55 View session

microsoft-github-policy-service Bot added lib:openapi meta:website TypeSpec.io updates emitter:openapi3 Issues for @typespec/openapi3 emitter labels Feb 4, 2026

Update documentation with parent field example

4aaaef7

- Added example of nested tags using parent field - Rebuilt packages to update generated types Co-authored-by: timotheeguerin <1031227+timotheeguerin@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Add support for OAS 3.2 nested tags feature~~ Add support for OAS 3.2 nested tags via parent field in @tagMetadata Feb 4, 2026

Copilot AI requested a review from timotheeguerin February 4, 2026 15:19

Copilot finished work on behalf of timotheeguerin February 4, 2026 15:19

timotheeguerin reviewed Feb 4, 2026

View reviewed changes

Comment thread packages/openapi3/src/openapi.ts Outdated

Copilot started work on behalf of timotheeguerin February 4, 2026 16:34 View session

Copilot AI requested a review from timotheeguerin February 4, 2026 16:40

Copilot finished work on behalf of timotheeguerin February 4, 2026 16:40

Copilot started work on behalf of timotheeguerin February 4, 2026 16:41 View session

Add generated documentation files for parent field

c831ac7

- Updated README.md with parent field example - Updated decorators.md with parent field example - Generated files from full build Co-authored-by: timotheeguerin <1031227+timotheeguerin@users.noreply.github.com>

Copilot finished work on behalf of timotheeguerin February 4, 2026 16:52

Copilot started work on behalf of timotheeguerin February 5, 2026 00:34 View session

microsoft-github-policy-service Bot added emitter:client:csharp Issue for the C# client emitter: @typespec/http-client-csharp emitter:client:python Issue for the Python client emitter: @typespec/http-client-python eng labels Feb 5, 2026

Copilot AI requested a review from timotheeguerin February 5, 2026 01:10

Copilot finished work on behalf of timotheeguerin February 5, 2026 01:10

markcowl reviewed Feb 5, 2026

View reviewed changes

Comment thread packages/openapi3/test/tagmetadata.test.ts

Comment thread packages/openapi3/test/tagmetadata.test.ts

Update tagmetadata.test.ts

d9d851c

Copilot started work on behalf of timotheeguerin February 5, 2026 20:47 View session

Run pnpm format to fix formatting issues

6facdb9

- Removed extra blank line in tagmetadata.test.ts Co-authored-by: timotheeguerin <1031227+timotheeguerin@users.noreply.github.com>

Copilot finished work on behalf of timotheeguerin February 5, 2026 20:57

timotheeguerin added 3 commits February 24, 2026 14:52

Merge branch 'main' into copilot/add-oas-32-nested-tags-support

ef1a120

Merge branch 'main' into copilot/add-oas-32-nested-tags-support

10d0345

Merge branch 'main' into copilot/add-oas-32-nested-tags-support

c5fe742

Copilot started work on behalf of timotheeguerin March 1, 2026 17:35 View session

Add changeset for OpenAPI 3.2 nested tags feature

d87c38c

- Added feature changeset for @typespec/openapi and @typespec/openapi3 - Describes support for parent field in @tagMetadata decorator Co-authored-by: timotheeguerin <1031227+timotheeguerin@users.noreply.github.com>

Copilot finished work on behalf of timotheeguerin March 1, 2026 17:40

timotheeguerin marked this pull request as ready for review March 2, 2026 15:37

timotheeguerin requested review from AlitzelMendez, bterlson, chrisradek and witemple-msft as code owners March 2, 2026 15:37

timotheeguerin added 2 commits March 2, 2026 12:06

Merge branch 'main' into copilot/add-oas-32-nested-tags-support

79783a7

Merge branch 'main' into copilot/add-oas-32-nested-tags-support

9a678ab

markcowl approved these changes Mar 2, 2026

View reviewed changes

timotheeguerin added this pull request to the merge queue Mar 2, 2026

Merged via the queue into main with commit 4fd384a Mar 2, 2026
24 checks passed

timotheeguerin deleted the copilot/add-oas-32-nested-tags-support branch March 2, 2026 20:53

Conversation

Copilot AI commented Feb 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!