TypeSpec Authoring Docs: cover versioning an operation return type with @returnTypeChangedFrom

[haolingdong-msft]

Documentation gap: versioning a return type with @returnTypeChangedFrom

Summary

The Azure TypeSpec documentation does not cover how to change an operation's return type for a specific API version using the @returnTypeChangedFrom versioning decorator. The API versioning docs and the @typespec/versioning reference describe @added/@removed/@renamedFrom/@typeChangedFrom/@madeOptional, but there is no example showing @returnTypeChangedFrom for operations whose return type changes between versions.

Because the pattern is undocumented, an agent (and a human) asked to "change the return type only for version X" tends to either create a parallel duplicate operation or rename the existing version, instead of applying the version-scoped @returnTypeChangedFrom decorator.

Case / scenario

Change the return type of an existing operation from ExportResult to a richer DetailedExportResult only for a new preview API version, while older versions keep returning ExportResult.

Prompt

In the Widget project, change the return type of the `exportData` operation from
`ExportResult` to `DetailedExportResult` with additional optional properties
`format` (string) and `exportedAt` (utcDateTime) only for version `2025-05-04-preview`.

Input code

main.tsp (existing versions):

/** The available API versions. */
enum Versions {
  @armCommonTypesVersion(Azure.ResourceManager.CommonTypes.Versions.v5)
  v2021_11_01: "2021-11-01",

  /** 2024-10-01-preview version */
  @armCommonTypesVersion(Azure.ResourceManager.CommonTypes.Versions.v5)
  @previewVersion
  v2024_10_01_preview: "2024-10-01-preview",
}

employee.tsp (existing operation and return model):

/** Export result model */
model ExportResult {
  /** Exported data */
  data?: string;
}

@armResourceOperations
interface Employees {
  // ...
  /** Export employee data */
  exportData is ArmResourceActionSync<Employee, void, ExportResult>;
}

Expected code

Add the new preview version, define the new return model, change the declared return type, and version-scope the change so that before 2025-05-04-preview the return type was ExportResult:

// main.tsp — add the new preview version
enum Versions {
  @armCommonTypesVersion(Azure.ResourceManager.CommonTypes.Versions.v5)
  v2021_11_01: "2021-11-01",

  @armCommonTypesVersion(Azure.ResourceManager.CommonTypes.Versions.v5)
  @previewVersion
  v2024_10_01_preview: "2024-10-01-preview",

  /** 2025-05-04-preview version */
  @armCommonTypesVersion(Azure.ResourceManager.CommonTypes.Versions.v5)
  @previewVersion
  v2025_05_04_preview: "2025-05-04-preview",
}

// employee.tsp
/** Export result model */
model ExportResult {
  /** Exported data */
  data?: string;
}

/** Detailed export result model (added in 2025-05-04-preview) */
model DetailedExportResult {
  /** Exported data */
  data?: string;

  /** The export format */
  format?: string;

  /** When the data was exported */
  exportedAt?: utcDateTime;
}

@armResourceOperations
interface Employees {
  // ...
  /** Export employee data */
  @returnTypeChangedFrom(Versions.v2025_05_04_preview, ExportResult)
  exportData is ArmResourceActionSync<Employee, void, DetailedExportResult>;
}

Request

Please add documentation (with a worked example like the above) covering @returnTypeChangedFrom — i.e. how to change an operation's return type for a specific API version — alongside the existing @typeChangedFrom/@renamedFrom guidance in the Azure TypeSpec versioning docs.

[markcowl]

@haolingdong-msft

• We should discourage usage of this decorator
  • It is almost always a breaking change
• Most usages of the decorator will not work with complex templates, especially templates that add headers or have multiple success response status codes
• Usually what folks want to do here can be achieved by versioning the response type rather than the operation
• In the cases where they want to change the response type of a particular response, we could provide details on how to do this, but, again, this is a change we want to discourage in Azure apis.

[haolingdong-msft]

Thanks Mark! I've removed the benchmark case that uses this decorator.

[haolingdong-msft]

Hey @markcowl, instead of introducing returnTypeChangedFrom , do we want to add some guidance for users to know how to modify operation's return type?