Skip to content

Adding a Stable Version when the Last Version was a Preview

When the last api-version in your TypeSpec spec is a preview, adding a new stable version means

This includes the followign steps:

Making Changes to your TypeSpec spec

Section titled “Making Changes to your TypeSpec spec”

  • Add a new entry to the versions enum for the new stable version

  • Update any version documentation to use the new version

  • Change the name of the examples version folder for the latest preview to match the new stable version

  • Determine which type changes from the latest preview are now stable

    • Update the versioning decorators for those changes to reference the new stable version
    • For changes in the latest preview (p) that are not in the new stable version

      • For any type with an @added(p) decorator, delete the type

      • For any property or parameter with a @typeChangedFrom(p, Type) decorator, replace the property type with the Type argument, and then remove the decorator, for example

        @typeChangedFrom(Versions.2025-12-01-preview, string)
        property: int32;

        should be changed to:

        property: string;

      • For any operation with an @returnTypeChangedFrom(p, ReturnType) decorator, replace the return type with the ReturnType argument and then remove the decorator, for example:

        @returnTypeChangedFrom(Versions.2025-12-01-preview, void)
        move is ArmResourceActionSync(Widget, MoveOptions, MoveResult);

        should be changed to:

        move is ArmResourceActionSync(Widget, MoveOptions, void);

      • For any type with an @renamedFrom(p, Name) decorator, replace the name of the type with the Name argument in the decorator and remove the decorator, for example:

        @renamedFrom(Versions.2025-12-01-preview, "oldProperty")
        newProperty: int32;

        should be changed to:

        oldProperty: int32;

      • For any property or parameter with a @madeOptional(p) decorator, remove the decorator, and make the property required, for example:

        @madeOptional(Versions.2025-12-01-preview)
        property?: int32;

        should be changed to:

        property: int32;

      • For any type with an @removed(p) decorator, remove the decorator

  • Model any additional changes in the new stable version and mark with the appropriate versioning decorator, referencing the new stable version

  • Add and modify examples to match the api changes in the new stable version

Preparing a PR into the azure-rest-api-specs repo

Section titled “Preparing a PR into the azure-rest-api-specs repo”

  • Navigate to the root directory of the repo in your local fork or clone

    Terminal window
    C:\repos\azure-rest-api-specs\specifications\myRp > cd \repos\azure-rest-api-specs
    C:\repos\azure-rest-api-specs >

  • Pull the latest version from the repo

    Terminal window
    C:\repos\azure-rest-api-specs > git fetch upstream main
    C:\repos\azure-rest-api-specs > git pull upstream main

  • Reinstall dependencies

    Terminal window
    C:\repos\azure-rest-api-specs > npm install

  • Compile your spec

    Terminal window
    C:\repos\azure-rest-api-specs > cd specification\myRpShortname\resource-manager\Microsoft.MyRP
    C:\repos\azure-rest-api-specs\specification\myRpShortname\resource-manager\Microsoft.MyRP > npx tsp compile .

  • If you don’t need the older preview version, remove the OpenAPI directory for that version and update the README.md file to use the new version instead.

    Terminal window
    C:\repos\azure-rest-api-specsC:\repos\azure-rest-api-specs\specification\myRpShortname\resource-manager\Microsoft.MyRP > rm -r 2025-12-01-preview

  • If you do need the older preview version, update README.md to include a new entry for the new stable version.