fix(swagger): type Tag Object kind as a free-form string#3925
Merged
kamilmysliwiec merged 1 commit intoMay 20, 2026
Conversation
The OpenAPI 3.2 Tag Object defines `kind` as a machine-readable, free-form string; the spec only lists `nav`, `badge` and `audience` as conventional values, none of which are mandated. The type was `'navigation' | 'reference'`, a closed union of two values that do not appear in the spec. This rejects every conventional value and any custom one a user might choose. Widen `kind` to `string` on `TagObject`, `ApiTagOptions` and the `DocumentBuilder.addTag()` options, with a JSDoc note pointing to the conventional values.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
PR Type
What is the current behavior?
TagObject.kind,ApiTagOptions.kindand theDocumentBuilder.addTag()options.kindparameter are all typed as:This closed union was introduced in #3725 (v11.4.0). However, the OpenAPI 3.2 Tag Object defines
kindas a machine-readable, free-form string. The spec lists onlynav,badgeandaudienceas conventional values, and explicitly does not mandate them.As a result the current type:
nav,badge,audience);navigation,reference) that do not appear in the spec at all;Spec references: OpenAPI 3.2 Tag Object, learn.openapis.org — Enhanced Tags.
What is the new behavior?
kindis widened tostringonTagObject,ApiTagOptionsandDocumentBuilder.addTag(), with a JSDoc note pointing to the conventional values (nav,badge,audience). Any spec-conventional or custom value is now accepted.Does this PR introduce a breaking change?
The type is widened, not narrowed — every value that compiled before still compiles. Existing
addTagtests were updated to use spec-conventional values, and a test for a free-form custom value was added.Other information
Part of the OpenAPI 3.2 tag-hierarchy support added in #3725.