0.66 - March 2025

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)

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

Serialize as

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

New tsp compile progress indicator

$ tsp compile .
TypeSpec compiler v0.65.3

✔ Compiling
⠙ @typespec/openapi3

$ tsp compile .
TypeSpec compiler v0.65.3

✔ Compiling
✔ @typespec/openapi3

Compilation completed successfully.

Breaking Changes

@typespec/openapi3

• #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 Deprecate use of @discriminator on union. Migrate to @discriminated

  @discriminator("type")
  @discriminated(#{envelope: "none", discriminatorPropertyName: "type"})
  union Pet;

• #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:

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

  can be replaced with:

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

  @visibility("none")
  example: string;

  can be replaced with:

  @invisible(Lifecycle)
  example: string;

  Additionally, @parameterVisibility with no arguments is deprecated.

  @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:

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

• #6108 Migrate @service decorator options to take in a value

  @service({title: "My service"})
  @service(#{title: "My service"})

@typespec/http

• #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.

  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 Updates the @extension decorator with 3 changes:

  1. Removes the extension name starts with x- constraint.
  2. Adds support for passing in values to emit raw data.
  3. 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.

  @extension("x-obj", { foo: true })
  @extension("x-obj", #{ foo: true })
  @extension("x-tuple", [ "foo" ])
  @extension("x-tuple", #[ "foo" ])
  model Foo {}

• #6108 Migrate @info decorator to expect a value

  @info({ version: "1.0.0" })
  @info(#{ version: "1.0.0" })

  @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 Add autocomplete of model properties for union type

• #5458 Add codefix for for various triple quoted string syntax issues

• #6082 Introduced list-files flag to log all emitted files.

• #6082 Added a progress indicator to show the current stage of tsp compilation process.

• #6059 Add new @discriminated decorator to represent discriminated union with implicit envelopes

• #5494 Report unused template parameters in language server

• #6045 Redesign and simplification of tsp init

• #5996 Add Typekits to support EFV2

• #5986 Tsp init template with both config and emitters merge in tspconfig.yaml

• #6047 --version shows if tsp is running from the standalone version

• #5453 Report unused using in language server

• #6164 Renamed package @typespec/http-server-javascript to @typespec/http-server-js.

@typespec/http

• #5996 Emitter Framework V2

@typespec/openapi3

• #6059 Add support for new @discriminated unions
• #5994 Adds seal-object-schemas emitter option to automatically set additionalProperties/unevaluatedProperties to { not: {} } wherever possible
• #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 updates openapi3 to respect @headers explode option and use value syntax
• #6157 Shared operations operationId can now be set if they all share the same value provided by @operationId
• #6006 Expose core library types in API surface.

@typespec/html-program-viewer

• #5996 Emitter Framework V2

@typespec/json-schema

• #5994 Adds seal-object-schemas emitter option to automatically set additionalProperties/unevaluatedProperties to { not: {} } wherever possible
• #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 Support intellisense for tsconfig.yaml in visual studio

typespec-vscode

• #6014 Add “Import TypeSpec from OpenApi3” menu item into explorer context menu
• #6164 Renamed package @typespec/http-server-javascript to @typespec/http-server-js.

Bug Fixes

@typespec/compiler

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

@typespec/openapi3

• #5901 Fix: @typespec/openapi3/invalid-component-fixed-field-key show on incorrect target

typespec-vscode

• #6137 Fix code snippet for union in typespec-vscode