Built in tags metadata

[timotheeguerin]

We currently define @tagMetadata in openapi library to map to openapi meaning. However it could be beneficial to define tags as a more core typespec feature. Current @tag is a core decorator that just take a string. We could expand to allow enum member which would allow defining available tags as enum(s)

import "@typespec/openapi";

@tags
enum Tags {
  /** Abc tag */
  @summary("Abc")
  @OpenAPI.externalDocs("")
  // parent
  // kind
  tagA,

  /** Abc tag */
  @tagParent(Tags.tagA)
  @tagKind("abc")
  tagB,
}

@tag(Tags.tagA)
op a(): void;

Playground Link

Category as separate enums

enum TagGroupA {
  a,
  b,
}
enum TagGroupB {
  a,
  b,
}

[github-actions]

🎯 Issue Triage

Feature request to promote tags from an OpenAPI-specific concept to a core TypeSpec feature, allowing enum members (with decorators) to represent named tags that can be referenced by @tag.

Category: Feature Request

Area: lib:http

🔗 [Playground Reproduction]((typespec.io/redacted)

🔍 Analysis

Currently the tag decorator in @typespec/http accepts only a plain string; metadata (description, external docs, hierarchy) is handled via tagMetadata in @typespec/openapi.

The proposal is to introduce a tags decorator on enums and allow tag to accept an enum member, so tag definitions and their metadata live in core TypeSpec rather than in OpenAPI-specific libraries.

This would enable emitters beyond OpenAPI (e.g., gRPC, JSON Schema) to consume structured tag information. A secondary proposal allows grouping tags via separate enums (categories).

Affected components: @typespec/http (tag decorator), potentially @typespec/openapi (tagMetadata migration path).

📝 Suggested next steps

• Design: define the tags decorator semantics and what properties an enum member can carry (summary, description, externalDocs, parent, kind).
• Decide whether tag should continue accepting plain strings alongside enum members for backwards compatibility.
• Update @typespec/http to support enum-member tags.
• Update @typespec/openapi3 emitter to consume the new tag metadata from enum definitions.
• Deprecate or remove tagMetadata once the core feature is available.

Generated by Agentic Triage