TCGC common models need to support TypeSpec versioning. The support should be separated into two parts:
- Support to get common models from specific version/latest version. This should be applied to all TCGC APIs.
- Support to provide all versioning information for common models that languages' emitter could leverage to generate SDK with version resilency.
- A new option
api-version
will be added to the TCGC context and should be configed in languages'tspconfig.yaml
file. - If the
api-version
is not set or set tolatest
, then all returns of TCGC APIs will be the information of latest API version. - 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. - If the
api-version
is set toall
, 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.
createSdkContext
andexperimental_sdkPackage
inSdkContext
getSdkPackage
getAllModels
,getClientType
and other type conversion functionsgetClient
,listClients
,listOperationGroups
,listOperationsInOperationGroup
getHttpOperationWithCache
NOT GOAL FOR DT
- Provide enought versioning info for emitter to generate version resiliency clients.
- Cover all TypeSpec versioning decorators:
@added
,@madeOptional
,@removed
,@renamedFrom
,@returnTypeChangedFrom
,@typeChangedFrom
. - Only apply to TCGC common models, not decorator/util APIs.
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 aboutSdkServiceOperation
Enum
->SdkEnumType
EnumMember
->SdkEnumValueType
Union
->SdkUnionType
// TODO: how about union as enumUnionVariant
->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
nameByVersions
property It could cover@renamedFrom
decorator. This property is added to TCGC types according to different TypeSpec types just likeapiVersions
. For all TCGC types, this property will show all the name in the versioning history.
@renamedFrom
example- ABA example
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
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