Skip to content

February 2023

New Features

Emitter Framework

The new emitter framework makes it simpler to build emitters from TypeSpec to other assets. It provides an easy way to handle TypeSpec types and provides a template for asset emitters to spell out the emitter tasks. It provides helpers to solve many difficult problems, including:

  • Constructing references between types
  • Handling circular references
  • Propagating type context based on containers or references
  • Class-based inheritance to encourage reuse and specialization of existing emitters

Details are available on the documentation website or in the [repository documentation] (https://github.com/microsoft/typespec/blob/main/docs/extending-typespec/emitter-framework.md).

Cli support for emitters in development

Use the path to the emitter to specify emitter options, rather than the emitter name.

Allow @autoroute and @route to be used together

Provide standard rules for combining @route and @autoroute decorators

  • Allow @route applied to an operation to override route settings from the interface
  • Allow @route on an operation to prepend the paths provided by @autoroute

Simplified versioning dependencies

Introduced the @useDependency decorator to replace @versionedDependency decorator. Simplify dependencies between versioned namespaces, by allowing each version to be decorated with the appropriate versioned dependency, rather than requiring the user to construct a dependency map.

Breaking Changes

Breaking changes in this release resulted from removal of previously decorated types and functions, including:

  • uri scalar removed. Use the url scalar instead.
  • Removed deprecated metadata types with the ‘type’ suffix.
    • Use Enum instead of EnumType
    • Use EnumMember instead of EnumMemberType
    • Use Interface instead of InterfaceType
    • Use Model instead of ModelType
    • Use ModelProperty instead of ModelTypeProperty
    • Use Namespace instead of NamespaceType
    • Use Operation instead of OperationType
    • Use Tuple instead of TupleType
    • Use Union instead of UnionType
  • Removed Map<K, V> type, use Record<V> instead
  • Removed @serviceTitle and @serviceVersion decorators. Use the @service decorator instead.
  • Removed helper and accessor functions associated with @serviceTitle and @serviceVersion decorators
    • Replace getServiceNamespace, getServiceTitle, getServiceVersion, and getServiceNamespaceString with getService or listServices
    • Replace setServiceNamespace with addService
  • Removed @segmentSeparator, use @actionSeparator instead
  • Removed @produces and @consumes decorators. Use @header contentType: <ContentType> instead in the operation return type
  • Removed getSegmentSeparator function. Use getActionSeparator instead
  • Removed getProduces and getConsumes functions. Use getContentTypes instead

Deprecations

Deprecates the @versionedDependency decorator in favor of the @useDependency decorator

For versioned libraries, @useDependency is applied to the version enum members

Before (versioned namespace)

@armProviderNamespace
@service({
  title: "Microsoft.Observability",
})
@versionedDependency(
  [
    [Microsoft.Observability.Versions.v2021_06_13_preview, Azure.Core.Versions.v1_0_Preview_2],
    [Microsoft.Observability.Versions.v2022_04_30_preview, Azure.Core.Versions.v1_0_Preview_2]
  ]
)
@versionedDependency(
  [
    [
      Microsoft.Observability.Versions.v2021_06_13_preview,
      Azure.ResourceManager.Versions.v1_0_Preview_1
    ],
    [
      Microsoft.Observability.Versions.v2022_04_30_preview,
      Azure.ResourceManager.Versions.v1_0_Preview_1
    ]
  ]
)
@versioned(Versions)
namespace Microsoft.Observability;


interface Operations extends Azure.ResourceManager.Operations {}


enum Versions {
  v2021_06_13_preview: "2021-06-13-preview",
  v2022_04_30_preview: "2022-04-30-preview",
}

After (Versioned namespace)

@armProviderNamespace
@service({
  title: "Microsoft.Observability",
})
@versioned(Versions)
namespace Microsoft.Observability;


interface Operations extends Azure.ResourceManager.Operations {}


enum Versions {
  @useDependency(Azure.Core.Versions.v1_0_Preview_2, Azure.ResourceManager.Versions.v1_0_Preview_1)
  v2021_06_13_preview: "2021-06-13-preview",


  @useDependency(Azure.Core.Versions.v1_0_Preview_2, Azure.ResourceManager.Versions.v1_0_Preview_1)
  v2022_04_30_preview: "2022-04-30-preview",
}

For unversioned libraries that reference versioned libraries, simply replace @versionedDependency with @useDependency

Before (unversioned namespace using versioned library)

@service({
  title: "Microsoft.EnvelopeTest",
  version: "2021-09-21-preview",
})
@versionedDependency(Azure.ResourceManager.Versions.v1_0_Preview_1)
@armProviderNamespace
namespace Microsoft.EnvelopeTest;

After (unversioned namespace using versioned library)

@service({
  title: "Microsoft.EnvelopeTest",
  version: "2021-09-21-preview",
})
@useDependency(Azure.ResourceManager.Versions.v1_0_Preview_1)
@armProviderNamespace
namespace Microsoft.EnvelopeTest;