feat(openapi): add array form for @tagMetadata to control tag declaration order (#10770)

Adds a new array form for the `@tagMetadata` decorator that lets authors
explicitly specify tags and their order in a single decorator call,
rather than relying on the bottom-up decorator execution order.

## Changes

- **`packages/openapi/lib/decorators.tsp`**: Added `TagMetadataWithName`
model; updated `@tagMetadata` signature to accept `string |
TagMetadataWithName[]` with the second parameter optional (only used in
inline form).
- **`packages/openapi/generated-defs/TypeSpec.OpenAPI.ts`**: Regenerated
with new `TagMetadataWithName` interface (including `summary` and `kind`
fields) and updated `TagMetadataDecorator` type.
- **`packages/openapi/src/lib.ts`**: Added `mixed-tag-metadata-form`
diagnostic — emitted when mixing the array form and inline form on the
same namespace. Added `tag-metadata-array-with-metadata-arg` diagnostic
— emitted when the second `tagMetadata` argument is provided alongside
the array form.
- **`packages/openapi/src/types.ts`**: Added publicly documented
`TagMetadataWithName` interface (with `summary` and `kind` fields).
- **`packages/openapi/src/index.ts`**: Exported new public type.
- **`packages/openapi/src/decorators.ts`**: State storage changed from
`{ [name: string]: TagMetadata }` to `TagMetadataWithName[]`; handles
both inline and array forms; reports error on mixing or on using the
second argument with the array form.
- **`packages/openapi3/src/openapi.ts`**: Updated `resolveDocumentTags`
to iterate the new array-based state.
-
**`packages/openapi3/src/cli/actions/convert/generators/generate-tags.ts`**:
Updated the OpenAPI→TypeSpec converter to emit `@tagMetadata(#[...])`
(array form) instead of multiple inline calls, ensuring import/export
order symmetry. Emits `parent`, `summary`, and `kind` fields natively
for OpenAPI 3.2.0 tags.
-
**`packages/openapi3/src/cli/actions/convert/transforms/transform-tags.ts`**:
Passes through `parent`, `summary`, and `kind` fields from
`OpenAPITag3_2`; reads `summary` and `kind` from
`x-oai-summary`/`x-oai-kind` extensions as fallbacks for OpenAPI 3.0/3.1
documents.
- **`packages/openapi3/src/cli/actions/convert/interfaces.ts`**: Added
`parent`, `summary`, and `kind` fields to `TypeSpecTagMetadata`.
- **`packages/openapi/test/decorators.test.ts`**: Updated existing tests
for the new array return type; added tests for array form, mixing error,
and second-argument-with-array-form error.
- **`packages/openapi3/test/tagmetadata.test.ts`**: Added tests for
array form ordering, operation-tag insertion behavior, and parent/child
tag scenarios.
-
**`packages/openapi3/test/tsp-openapi3/convert-openapi3-doc.test.ts`**:
Added unit tests verifying converter handling of OpenAPI 3.2.0 `parent`,
`summary`, and `kind` tag fields, and `x-oai-` extension fallbacks for
3.0/3.1 documents.
- **Converter snapshot outputs** (`tag-metadata`,
`playground-http-service`, `petstore-swagger`, `tag-metadata-3-2`):
Updated to reflect the new array form emitted by the converter.

### Array form example

```typespec
@service
@tagMetadata(#[
  #{ name: "First Tag", description: "First tag description" },
  #{ name: "Second Tag", description: "Second tag description" },
  #{ name: "Third Tag", description: "Third tag description" },
])
namespace PetStore {}
```

Tags are emitted in the exact order specified in the array.

### Mixing forms is an error

Using both forms on the same namespace reports a
`mixed-tag-metadata-form` diagnostic:

```typespec
@service
@tagMetadata(#[#{ name: "tag1" }])
@tagMetadata("tag2", #{})  // error: cannot mix array and inline form
namespace PetStore {}
```

### Passing the second argument with the array form is an error

```typespec
@service
@tagMetadata(#[#{ name: "tag1" }], #{description: "not allowed"})  // error: tag-metadata-array-with-metadata-arg
namespace PetStore {}
```

### Converter output

The OpenAPI→TypeSpec converter now emits the array form so that tag
order in the source OpenAPI document is preserved in the output
TypeSpec. OpenAPI 3.2.0 `parent`, `summary`, and `kind` tag fields are
emitted natively. For OpenAPI 3.0/3.1 documents, `summary` and `kind`
are also read from `x-oai-summary` and `x-oai-kind` extensions:

```typespec
@tagMetadata(#[
  #{ name: "pet", description: "Everything about your Pets", externalDocs: #{ url: "...", description: "Find out more" } },
  #{ name: "store", description: "Access to Petstore orders", externalDocs: #{ url: "...", description: "Find out more about our store" } },
  #{ name: "user", description: "Operations about user" },
  #{ name: "extensive", description: "A tag with all 3.2 fields", summary: "Short summary", kind: "OperationGroup", parent: "parent-tag" },
])
namespace SwaggerPetstoreOpenAPI30;
```

### Tag insertion behavior (unchanged)

- Tags used only at the operation level (via `@tag`) and **not**
declared with `@tagMetadata` appear first in the output.
- Tags declared with `@tagMetadata` follow in their stored order.
- A tag used at both the operation level and in `@tagMetadata` is
emitted exactly once, at its `@tagMetadata`-declared position with its
metadata.

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: baywet <7905502+baywet@users.noreply.github.com>
Co-authored-by: Vincent Biret <vibiret@microsoft.com>
Co-authored-by: Timothee Guerin <tiguerin@microsoft.com>

Author: 3 people

.chronus/changes/copilot-tagmetadata-array-form-2026-5-25-17-0-0.md

@@ -0,0 +1,19 @@
+---
+changeKind: feature
+packages:
+  - "@typespec/openapi"
+  - "@typespec/openapi3"
+---
+
+Add array form for `@tagMetadata` decorator to allow explicit control of tag declaration order.
+
+```typespec
+@service
+@tagMetadata(#[
+  #{ name: "First Tag", description: "First tag description" },
+  #{ name: "Second Tag", description: "Second tag description" },
+])
+namespace PetStore {}
+```
+
+Using `@tagMetadata(#[...])` and `@tagMetadata("name", #{...})` on the same namespace is a diagnostic error.

packages/openapi/README.md

@@ -147,10 +147,13 @@ op read(): string;
 
 #### `@tagMetadata`
 
-Specify OpenAPI additional information.
+Specify OpenAPI tag metadata. Can be used in two forms:
+
+- Inline form: specify a single tag by name with optional metadata.
+- Array form: specify an ordered list of tags with their metadata in a single decorator call.
 
 ```typespec
-@TypeSpec.OpenAPI.tagMetadata(name: valueof string, tagMetadata: valueof TypeSpec.OpenAPI.TagMetadata)
+@TypeSpec.OpenAPI.tagMetadata(name: valueof string | TypeSpec.OpenAPI.TagMetadataWithName[], tagMetadata?: valueof TypeSpec.OpenAPI.TagMetadata)
 ```
 
 ##### Target
@@ -159,13 +162,15 @@ Specify OpenAPI additional information.
 
 ##### Parameters
 
-| Name        | Type                                  | Description            |
-| ----------- | ------------------------------------- | ---------------------- |
-| name        | `valueof string`                      | tag name               |
-| tagMetadata | [valueof `TagMetadata`](#tagmetadata) | Additional information |
+| Name        | Type                                                       | Description                                                         |
+| ----------- | ---------------------------------------------------------- | ------------------------------------------------------------------- |
+| name        | `valueof string \| TypeSpec.OpenAPI.TagMetadataWithName[]` | Tag name (inline form) or array of tags with metadata (array form). |
+| tagMetadata | [valueof `TagMetadata`](#tagmetadata)                      | Additional information for the tag. Only used in inline form.       |
 
 ##### Examples
 
+###### Inline form
+
 ```typespec
 @service
 @tagMetadata(
@@ -181,3 +186,16 @@ namespace PetStore {
 
 }
 ```
+
+###### Array form (preserves explicit tag order)
+
+```typespec
+@service
+@tagMetadata(#[
+  #{ name: "First Tag", description: "First tag description" },
+  #{ name: "Second Tag", description: "Second tag description" }
+])
+namespace PetStore {
+
+}
+```

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

@@ -17,6 +17,16 @@ export interface AdditionalInfo {
   readonly license?: License;
 }
 
+export interface TagMetadataWithName {
+  readonly [key: string]: unknown;
+  readonly name: string;
+  readonly description?: string;
+  readonly externalDocs?: ExternalDocs;
+  readonly parent?: string;
+  readonly summary?: string;
+  readonly kind?: string;
+}
+
 export interface TagMetadata {
   readonly [key: string]: unknown;
   readonly description?: string;
@@ -128,23 +138,34 @@ export type InfoDecorator = (
 ) => DecoratorValidatorCallbacks | void;
 
 /**
- * Specify OpenAPI additional information.
+ * Specify OpenAPI tag metadata. Can be used in two forms:
+ * - Inline form: specify a single tag by name with optional metadata.
+ * - Array form: specify an ordered list of tags with their metadata in a single decorator call.
  *
- * @param name tag name
- * @param tagMetadata Additional information
- * @example
+ * @param name Tag name (inline form) or array of tags with metadata (array form).
+ * @param tagMetadata Additional information for the tag. Only used in inline form.
+ * @example Inline form
  * ```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 {}
  * ```
+ * @example Array form (preserves explicit tag order)
+ * ```typespec
+ * @service()
+ * @tagMetadata(#[
+ *   #{ name: "First Tag", description: "First tag description" },
+ *   #{ name: "Second Tag", description: "Second tag description" },
+ * ])
+ * namespace PetStore {}
+ * ```
  */
 export type TagMetadataDecorator = (
   context: DecoratorContext,
   target: Namespace,
-  name: string,
-  tagMetadata: TagMetadata,
+  name: string | readonly TagMetadataWithName[],
+  tagMetadata?: TagMetadata,
 ) => DecoratorValidatorCallbacks | void;
 
 export type TypeSpecOpenAPIDecorators = {

packages/openapi/lib/decorators.tsp

@@ -118,10 +118,10 @@ extern dec info(target: Namespace, additionalInfo: valueof AdditionalInfo);
 
 /** Metadata to a single tag that is used by operations. */
 model TagMetadata {
-  /** A description of the API. */
+  /** A description of the tag. */
   description?: string;
 
-  /** An external Docs information of the API. */
+  /** External documentation information for the tag. */
   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`. */
@@ -137,6 +137,14 @@ model TagMetadata {
   ...Record<unknown>;
 }
 
+/** Metadata for a tag that includes the name of the tag. Used with the array form of `@tagMetadata`. */
+model TagMetadataWithName {
+  /** The name of the tag. */
+  name: string;
+
+  ...TagMetadata;
+}
+
 /** External Docs information. */
 model ExternalDocs {
   /** Documentation url */
@@ -150,16 +158,33 @@ model ExternalDocs {
 }
 
 /**
- * Specify OpenAPI additional information.
- * @param name tag name
- * @param tagMetadata Additional information
+ * Specify OpenAPI tag metadata. Can be used in two forms:
+ * - Inline form: specify a single tag by name with optional metadata.
+ * - Array form: specify an ordered list of tags with their metadata in a single decorator call.
  *
- * @example
+ * @param name Tag name (inline form) or array of tags with metadata (array form).
+ * @param tagMetadata Additional information for the tag. Only used in inline form.
+ *
+ * @example Inline form
  * ```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 {}
  * ```
+ *
+ * @example Array form (preserves explicit tag order)
+ * ```typespec
+ * @service()
+ * @tagMetadata(#[
+ *   #{ name: "First Tag", description: "First tag description" },
+ *   #{ name: "Second Tag", description: "Second tag description" },
+ * ])
+ * namespace PetStore {}
+ * ```
  */
-extern dec tagMetadata(target: Namespace, name: valueof string, tagMetadata: valueof TagMetadata);
+extern dec tagMetadata(
+  target: Namespace,
+  name: valueof string | TagMetadataWithName[],
+  tagMetadata?: valueof TagMetadata
+);