---
title: 0.66 - March 2025
releaseDate: 2025-03-04
version: "0.66"
---

:::caution
This release contains deprecations that will be removed in the following version.
As we are preparing for 1.0-rc0, we are cleaning up the typespec language and some of the libraries.
:::

## Notable changes

### New Discriminated union with `@discriminated`

In order to simplify and provide a more intuitive discriminated union experience, we have introduced a new `@discriminated` decorator.
This decorators allows you to define a discriminated union that will use the variant names as the discriminator values.
The decorator allows customizing the serialization of the union(by default using an envelop object)

```tsp
@discriminated
union Pet {
  cat: Cat,
  dog: Dog,
}
```

Serialize as

```json
{
  "kind": "cat",
  "value": {
    "name": "Whiskers",
    "meow": true
  }
},
{
  "kind": "dog",
  "value": {
    "name": "Rex",
    "bark": false
  }
}
```

### New `tsp compile` progress indicator

```ansi
$ tsp compile .
TypeSpec compiler v0.65.3

[32m✔[0m Compiling
[33m⠙[0m @typespec/openapi3
```

```ansi
$ tsp compile .
TypeSpec compiler v0.65.3

[32m✔[0m Compiling
[32m✔[0m @typespec/openapi3

Compilation completed successfully.
```

## Breaking Changes

### @typespec/openapi3

- [#6182](https://github.com/microsoft/typespec/pull/6182) Using `{service-name}` in `tspconfig.yaml` will always interpolate the current service name. `{service-name-if-multiple}` can be used to get the previous behavior

## Deprecations

### @typespec/compiler

- [#6059](https://github.com/microsoft/typespec/pull/6059) Deprecate use of `@discriminator` on union. Migrate to `@discriminated`

  ```diff lang="tsp"
  -@discriminator("type")
  +@discriminated(#{envelope: "none", discriminatorPropertyName: "type"})
  union Pet;
  ```

- [#6088](https://github.com/microsoft/typespec/pull/6088) Deprecate use of string-based visibility modifiers using warnings.

  String-based visibilities can be replaced as follows:

  - `"create"`, `"read"`, `"update"`, `"delete"`, and `"query"` can be replaced with `Lifecycle.Create`, `Lifecycle.Read`, `Lifecycle.Update`, `Lifecycle.Delete`, and `Lifecycle.Query` respectively.
  - `@visibility("none")` can be replaced with `@invisible(Lifecycle)`.

  For example:

  ```tsp
  @visibility("create", "read")
  example: string;
  ```

  can be replaced with:

  ```tsp
  @visibility(Lifecycle.Create, Lifecycle.Read)
  example: string;
  ```

  ```tsp
  @visibility("none")
  example: string;
  ```

  can be replaced with:

  ```tsp
  @invisible(Lifecycle)
  example: string;
  ```

  Additionally, `@parameterVisibility` with no arguments is deprecated.

  ```tsp
  @parameterVisibility
  @patch
  op example(@bodyRoot resource: Resource): Resource;
  ```

  The effect of `@parameterVisibility` is to disable effective PATCH optionality. If you wish
  to disable effective PATCH optionality in `@typespec/http`, preventing it from treating all
  properties of the request body as effectively optional, you can now do so explicitly:

  ```tsp
  @patch(#{ implicitOptionality: false })
  op example(@bodyRoot resource: Resource): Resource;
  ```

- [#6108](https://github.com/microsoft/typespec/pull/6108) Migrate `@service` decorator options to take in a value

  ```diff lang="tsp"
  -@service({title: "My service"})
  +@service(#{title: "My service"})
  ```

### @typespec/http

- [#6130](https://github.com/microsoft/typespec/pull/6130) Updates `@header` decorator to accept values and adds the `explode` option.
  Note that using the model expression syntax to pass in arguments, or using the
  `format` field, are now deprecated.

  ```diff lang="tsp"
  op example1(
  -  @header({ name: "ETag" }) etag: string
  +  @header(#{ name: "ETag" }) etag: string
  ): void;

  op example2(
  -  @header({ format: "csv" }) list: string[]
  +  @header list: string[]
  ): void;
  ```

### @typespec/openapi

- [#6078](https://github.com/microsoft/typespec/pull/6078) Updates the `@extension` decorator with 3 changes:

  1. Removes the extension name starts with `x-` constraint.
  1. Adds support for passing in values to emit raw data.
  1. Adds a deprecation warning for passing in types. Passed in types will emit Open API schemas in a future release.

  Scalar literals (e.g. string, boolean, number values) are automatically treated as values.
  Model or tuple expression usage needs to be converted to values to retain current behavior in future releases.

  ```diff lang="tsp"
  -@extension("x-obj", { foo: true })
  +@extension("x-obj", #{ foo: true })
  -@extension("x-tuple", [ "foo" ])
  +@extension("x-tuple", #[ "foo" ])
  model Foo {}
  ```

- [#6108](https://github.com/microsoft/typespec/pull/6108) Migrate `@info` decorator to expect a value

  ```diff lang="tsp"
  -@info({ version: "1.0.0" })
  +@info(#{ version: "1.0.0" })
  ```

  ```diff lang="tsp"
  -@info({
  +@info(#{
    termsOfService: "http://example.com/terms/",
  -  contact: {
  +  contact: #{
      name: "API Support",
      url: "http://www.example.com/support",
      email: "support@example.com"
    },
  })
  ```

## Features

### @typespec/compiler

- [#5483](https://github.com/microsoft/typespec/pull/5483) Add autocomplete of model properties for union type
- [#5458](https://github.com/microsoft/typespec/pull/5458) Add codefix for for various triple quoted string syntax issues
- [#6082](https://github.com/microsoft/typespec/pull/6082) Introduced `list-files` flag to log all emitted files.
- [#6082](https://github.com/microsoft/typespec/pull/6082) Added a progress indicator to show the current stage of tsp compilation process.
- [#6059](https://github.com/microsoft/typespec/pull/6059) Add new `@discriminated` decorator to represent discriminated union with implicit envelopes
- [#5494](https://github.com/microsoft/typespec/pull/5494) Report unused template parameters in language server
- [#6045](https://github.com/microsoft/typespec/pull/6045) Redesign and simplification of `tsp init`
- [#5996](https://github.com/microsoft/typespec/pull/5996) Add Typekits to support EFV2
- [#5986](https://github.com/microsoft/typespec/pull/5986) Tsp init template with both config and emitters merge in tspconfig.yaml

- [#6047](https://github.com/microsoft/typespec/pull/6047) `--version` shows if tsp is running from the standalone version
- [#5453](https://github.com/microsoft/typespec/pull/5453) Report unused `using` in language server
- [#6164](https://github.com/microsoft/typespec/pull/6164) Renamed package `@typespec/http-server-javascript` to `@typespec/http-server-js`.

### @typespec/http

- [#5996](https://github.com/microsoft/typespec/pull/5996) Emitter Framework V2

### @typespec/openapi3

- [#6059](https://github.com/microsoft/typespec/pull/6059) Add support for new `@discriminated` unions
- [#5994](https://github.com/microsoft/typespec/pull/5994) Adds `seal-object-schemas` emitter option to automatically set additionalProperties/unevaluatedProperties to `{ not: {} }` wherever possible
- [#5961](https://github.com/microsoft/typespec/pull/5961) Updates JsonSchema and Open API 3.1 emitters to use unevaluatedProperties instead of additionalProperties, and updates Open API 3 emitters to match JsonSchema behavior of treating `Record<never>` as setting `additionalProperties: { not: {} }`
- [#6130](https://github.com/microsoft/typespec/pull/6130) updates openapi3 to respect `@headers` `explode` option and use value syntax
- [#6157](https://github.com/microsoft/typespec/pull/6157) Shared operations operationId can now be set if they all share the same value provided by `@operationId`
- [#6006](https://github.com/microsoft/typespec/pull/6006) Expose core library types in API surface.

### @typespec/html-program-viewer

- [#5996](https://github.com/microsoft/typespec/pull/5996) Emitter Framework V2

### @typespec/json-schema

- [#5994](https://github.com/microsoft/typespec/pull/5994) Adds `seal-object-schemas` emitter option to automatically set additionalProperties/unevaluatedProperties to `{ not: {} }` wherever possible
- [#5961](https://github.com/microsoft/typespec/pull/5961) Updates JsonSchema and Open API 3.1 emitters to use unevaluatedProperties instead of additionalProperties, and updates Open API 3 emitters to match JsonSchema behavior of treating `Record<never>` as setting `additionalProperties: { not: {} }`

### typespec-vs

- [#5968](https://github.com/microsoft/typespec/pull/5968) Support intellisense for tsconfig.yaml in visual studio

### typespec-vscode

- [#6014](https://github.com/microsoft/typespec/pull/6014) Add "Import TypeSpec from OpenApi3" menu item into explorer context menu
- [#6164](https://github.com/microsoft/typespec/pull/6164) Renamed package `@typespec/http-server-javascript` to `@typespec/http-server-js`.

## Bug Fixes

### @typespec/compiler

- [#4926](https://github.com/microsoft/typespec/pull/4926) Augmenting an expression will now report an error instead of silently failing to apply.
- [#5937](https://github.com/microsoft/typespec/pull/5937) Fix: StringTemplate type not supported in typespecValueToJson
- [#6204](https://github.com/microsoft/typespec/pull/6204) Fix `@example` reporting assignability error when using mix metadata(http) models
- [#6125](https://github.com/microsoft/typespec/pull/6125) Fix tmlanguage syntax highlighting when using decorator before escaped identifier
- [#6192](https://github.com/microsoft/typespec/pull/6192) Fix `tsp info` crash
- [#6203](https://github.com/microsoft/typespec/pull/6203) Fix mutator not mutating sourceModel(s)

### @typespec/openapi3

- [#5901](https://github.com/microsoft/typespec/pull/5901) Fix: `@typespec/openapi3/invalid-component-fixed-field-key` show on incorrect target

### typespec-vscode

- [#6137](https://github.com/microsoft/typespec/pull/6137) Fix code snippet for union in typespec-vscode
