0.59 - August 2024

warning

This release contains deprecations breaking changes

Breaking Changes

@typespec/compiler

• #4050 Fix issue where naming a namespace with the same name as the blockless namespace would merge with it instead of creating a subnamespace like any other name would.

  namespace MyOrg.MyProject;
  
  namespace MyOrg.MyProject.MyArea {
    model A {}
  }
  
  namespace MyArea2 {
    model B {}
  }

  Previously model A would end-up in namespace MyOrg.MyProject.MyArea and model B in MyOrg.MyProject.MyArea2. With this change model A will now be in MyOrg.MyProject.MyOrg.MyProject.MyArea. To achieve the previous behavior the above code should be written as:

  namespace MyOrg.MyProject;
  
  namespace MyArea {
    model A {}
  }
  
  namespace MyArea2 {
    model B {}
  }

@typespec/json-schema

• #3558 Updates @extension decorator to support TypeSpec values in addition to types.

In previous versions of the json-schema emitter, the @extension decorator only accepted types as the value. These are emitted as JSON schemas. In order to add extensions as raw values, types had to be wrapped in the Json<> template when being passed to the @extension decorator.

This change allows setting TypeSpec values (introduced in TypeSpec 0.57.0) directly instead.

The following example demonstrates using values directly:

@extension("x-example", #{ foo: "bar" })
model Foo {}

This change results in scalars being treated as values instead of types. This will result in the @extension decorator emitting raw values for scalar types instead of JSON schema. To preserve the previous behavior, use typeof when passing in a scalar value.

The following example demonstrates how to pass a scalar value that emits a JSON schema:

@extension("x-example", "foo")
model Foo {}

To preserve this same behavior, the above example can be updated to the following:

@extension("x-example", typeof "foo")
model Foo {}

Deprecations

@typespec/http

• #3932 API deprecation: HttpOperation#pathSegments is deprecated. Use HttpOperation#uriTemplate instead.

• #3932 Deprecated @query({format: }) option. Use @query(#{explode: true}) instead of form or multi format. Previously csv/simple is the default now. Decorator is also expecting an object value now instead of a model. A deprecation warning with a codefix will help migrating.

  - @query({format: "form"}) select: string[];
  + @query(#{explode: true}) select: string[];

Features

@typespec/compiler

• #3906 Support completion for template parameter extending model or object value

  Example

  model User<T extends {name: string;age: int16}> {}
  alias user = User<{
    ┆: [age] | [name];
  }>;

• #4020 Add support for encoding numeric types as string

• #4023 Warn when using \ in config file field that expect a path.

• #3932 Add ArrayEncoding enum to define simple serialization of arrays

@typespec/http

• #4046 API: Expose properties: HttpProperty[] on operation parameter and response which reference all the properties of interest(Body, statusCode, contentType, implicitBodyProperty, etc.)

• #3932 @route can now take a uri template as defined by RFC-6570

  @route("files{+path}") download(path: string): void;

@typespec/rest

• #3932 Add support for URI templates in routes

@typespec/openapi3

• #3894 Add support for @useRef on responses
• #4020 Add support for encoding numeric types as string
• #3890 @extension used on the service namespace will set extension at the root of the document
• #3932 Add support for URI templates in routes

Bug Fixes

@typespec/compiler

• #3881 Fixes a bug where ending a non-terminal line in a multi-line comment with a backslash caused the next star to show up in the parsed doc string.

• #4050 Allow using compact namespace form Foo.Bar when inside another namespace

  namespace MyOrg.MyProject {
    namespace MyModule.MySubmodule { // <-- this used to emit an error
    // ...
  
    }
  }

• #3898 Fix decimal numeric with leading zeros

• #4046 Fix type comparison of literal and scalar when in projection context

• #4022 tsp compile --watch will not stop when a crash happens during compilation

• #3933 Add const template parameter to get the precise lib type

@typespec/http

• #3909 Fix HttpPart not respecting explicit part name by always using the property name
• #3933 Fix some diagnostic not showing the right message

@typespec/versioning

• #3911 Allow spreading a model that has props added in previous version
• #3951 Fixes issue where spreading a versioned model as a parameter to an incompatible versioned operation would cause the compiler to crash.

@typespec/openapi3

• #4046 Fix issue where operation example would produce an empty object when @body/@bodyRoot was used
• #4046 Fix operation response body examples showing up for each response.
• #3912 Fixes bug where union documentation was being applied to each union member in emitted output.
• #3908 Fixes bug where circular references in unions caused an empty object to be emitted instead of a ref.

@typespec/protobuf

• #3933 Fix some diagnostic not showing the right message