TCGC versioning

tcgc-api-design.md

Overview

TCGC common models need to support TypeSpec versioning. The support should be separated into two parts:

1. Support to get common models from specific version/latest version. This should be applied to all TCGC APIs.
2. Support to provide all versioning information for common models that languages' emitter could leverage to generate SDK with version resilency.

Support to get specific/latest version info for all TCGC APIs

Config

1. A new option api-version will be added to the TCGC context and should be configed in languages' tspconfig.yaml file.
2. If the api-version is not set or set to latest, then all returns of TCGC APIs will be the information of latest API version.
3. If the api-version is set to a specific version, then all returns of TCGC APIs will be the information of that API version. If the version is not existed, then a diagnostic warning will be passed to emitter and will fallback to latest version.
4. If the api-version is set to all, then the returns of TCGC APIs will be the information of all API versions. Next part will describe how the versioning infomation is included in TCGC common models.

Related interfaces and APIs

• createSdkContext and experimental_sdkPackage in SdkContext
• getSdkPackage
• getAllModels, getClientType and other type conversion functions
• getClient, listClients, listOperationGroups, listOperationsInOperationGroup
• getHttpOperationWithCache

---

NOT GOAL FOR DT

Support to get all versions info for TCGC common models

Goal

1. Provide enought versioning info for emitter to generate version resiliency clients.
2. Cover all TypeSpec versioning decorators: @added, @madeOptional, @removed, @renamedFrom, @returnTypeChangedFrom, @typeChangedFrom.
3. Only apply to TCGC common models, not decorator/util APIs.

Design

1. apiVersions property It could cover @added and @removed decorators. This property is added to TCGC types according to different TypeSpec types:

• Model -> SdkModelType
• ModelProperty -> SdkModelPropertyType
• Operation -> SdkServiceMethod // TODO: how about SdkServiceOperation
• Enum -> SdkEnumType
• EnumMember -> SdkEnumValueType
• Union -> SdkUnionType // TODO: how about union as enum
• UnionVariant -> SdkType
• Scalar -> SdkType
• Interface -> SdkClientType

TCGC common models will contain the universal set of types in all the versions. Through apiVersions, emitter could know which version contains which type.

• @added example
• @removed example
• ABA example

2. nameByVersions property It could cover @renamedFrom decorator. This property is added to TCGC types according to different TypeSpec types just like apiVersions. For all TCGC types, this property will show all the name in the versioning history.

• @renamedFrom example
• ABA example

3. optionalByVersions property It could cover @madeOptional decorator. This property is added to TCGC types according to different TypeSpec types:

• ModelProperty -> SdkModelPropertyType

Model property or method parameter could change optional flag.

• @madeOptional example
• ABA example

4. typesByVersions property It could cover @typeChangedFrom and @returnTypeChangedFrom decorators. This property is added to TCGC types according to different TypeSpec types:

• ModelProperty -> SdkModelPropertyType
• Operation -> SdkServiceMethod

Model proprety, method parameter or operation response could change types.

• @typeChangedFrom example
• ABA example