Skip to content

version-progression

Id
@azure-tools/typespec-azure-resource-manager/version-progression

Validate that ARM service versions all use unique dates and are declared in strictly increasing chronological order.

Use this rule to catch ordering mistakes across otherwise well-formed service versions. It complements arm-resource-invalid-version-format, which validates the format of each individual version string; arm-version-progression does not flag malformed version strings because those are reported by the format rule.

Impact

Section titled “Impact”
  • Area: API, SDK, Tooling

Out-of-order versions, or versions with matching dates, make specs unmaintainable and cause SDK problems.

❌ Incorrect

Section titled “❌ Incorrect”

A preview and a stable version share the same date:

@versioned(Versions)
@armProviderNamespace
namespace Microsoft.Contoso;


enum Versions {
  v2026_04_28: "2026-04-28",
  v2026_04_28_preview: "2026-04-28-preview",
}

Versions are declared out of chronological order:

@versioned(Versions)
@armProviderNamespace
namespace Microsoft.Contoso;


enum Versions {
  v2024_06_01: "2024-06-01",
  v2024_01_01: "2024-01-01",
}

✅ Correct

Section titled “✅ Correct”
@versioned(Versions)
@armProviderNamespace
namespace Microsoft.Contoso;


enum Versions {
  v2024_01_01: "2024-01-01",
  v2024_03_01: "2024-03-01",
  v2024_06_01_preview: "2024-06-01-preview",
}

A stable version followed by a preview that is chronologically later (one day after) is also valid — previews must come chronologically after the most recent stable version:

@versioned(Versions)
@armProviderNamespace
namespace Microsoft.Contoso;


enum Versions {
  v2024_03_01: "2024-03-01",
  v2024_06_01: "2024-06-01",
  v2024_06_02_preview: "2024-06-02-preview",
}

Suppression

Section titled “Suppression”

Do not suppress. Ensure new api-versions are unique and monotonically increasing from top to bottom in the Versions enum.