Add diagnostic metadata to @experimental

[JoshLove-msft]

Motivation

@experimental currently records only that a TypeSpec declaration is experimental. That is enough for emitters that need a boolean lifecycle flag, but it does not describe how an emitter should identify the experiment or whether the generated implementation relies on other experimental features.

A generated API can be a distinct public experiment while being composed from several lower-level experiments. For example, an operation tracked as experiment C may internally use experimental features A and B. Consumers should see C, while an emitter may need A and B to generate warning suppressions around implementation code.

Usage

@experimental(#{
  emitterScope: "@typespec/http-client-csharp",
  diagnosticId: "C",
  dependsOn: #["A", "B"]
})
op bar(): void;

Scenarios

• Direct experiment: specify only diagnosticId when an emitter needs a stable identifier for the experimental API.
• Composed experiment: use dependsOn when the generated implementation consumes other independently experimental features.
• Emitter-specific diagnostics: use emitterScope when identifiers are meaningful only to a particular emitter or target language.
• Lifecycle tooling: emitters and tooling can query the complete lifecycle details without parsing decorator syntax.
• Explicit graduation: dependencies becoming generally available does not silently graduate the public API. The declaration remains experimental until its decorator is explicitly removed.

API changes

• Add optional diagnosticId and dependsOn fields to FeatureLifecycleOptions.
• Add getFeatureLifecycleDetails, returning:

{
  stage: "Experimental";
  diagnosticId?: string;
  dependsOn: readonly string[];
}

• Preserve the existing getFeatureLifecycle API and its "Experimental" | undefined behavior for compatibility.
• Apply existing emitter-scope filtering to all lifecycle details.

Emitter behavior

The metadata is descriptive rather than prescriptive. Each emitter decides how to represent it. The C# companion implementation in #11685 maps diagnosticId to ExperimentalAttribute and dependsOn to scoped warning suppressions.

Related work

• C# emitter implementation: Emit experimental diagnostics in C# clients #11685
• Design issue: Enhance @experimental with diagnostic IDs and dependencies #11690

Validation

• @typespec/http-client build and full test suite
• Affected-package lint and formatting checks

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/microsoft/typespec/@typespec/http-client@11684

commit: d301a81

[github-actions]

All changed packages have been documented.

• ✅ @typespec/http-client

Show changes

@typespec/http-client - feature ✏️

Add diagnostic and dependency metadata to @experimental.,> ,> typespec,> @experimental(#{ diagnosticId: "C", dependsOn: #["A", "B"] }),> op bar(): void;,>

[azure-sdk-automation]

You can try these changes here

🛝 Playground	🌐 Website	🛝 VSCode Extension