---
title: 0.59 - August 2024
---

:::caution
This release contains deprecations breaking changes
:::

## Breaking Changes

### @typespec/compiler

- [#4050](https://github.com/microsoft/typespec/pull/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.

  ```tsp
  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:

  ```tsp
  namespace MyOrg.MyProject;

  namespace MyArea {
    model A {}
  }

  namespace MyArea2 {
    model B {}
  }
  ```

### @typespec/json-schema

- [#3558](https://github.com/microsoft/typespec/pull/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:

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

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

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

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

## Deprecations

### @typespec/http

- [#3932](https://github.com/microsoft/typespec/pull/3932) API deprecation: `HttpOperation#pathSegments` is deprecated. Use `HttpOperation#uriTemplate` instead.
- [#3932](https://github.com/microsoft/typespec/pull/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.

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

## Features

### @typespec/compiler

- [#3906](https://github.com/microsoft/typespec/pull/3906) Support completion for template parameter extending model or object value

  Example

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

- [#4020](https://github.com/microsoft/typespec/pull/4020) Add support for encoding numeric types as string
- [#4023](https://github.com/microsoft/typespec/pull/4023) Warn when using `\` in config file field that expect a path.
- [#3932](https://github.com/microsoft/typespec/pull/3932) Add `ArrayEncoding` enum to define simple serialization of arrays

### @typespec/http

- [#4046](https://github.com/microsoft/typespec/pull/4046) API: Expose `properties: HttpProperty[]` on operation parameter and response which reference all the properties of interest(Body, statusCode, contentType, implicitBodyProperty, etc.)
- [#3932](https://github.com/microsoft/typespec/pull/3932) `@route` can now take a uri template as defined by [RFC-6570](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3)

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

### @typespec/rest

- [#3932](https://github.com/microsoft/typespec/pull/3932) Add support for URI templates in routes

### @typespec/openapi3

- [#3894](https://github.com/microsoft/typespec/pull/3894) Add support for `@useRef` on responses
- [#4020](https://github.com/microsoft/typespec/pull/4020) Add support for encoding numeric types as string
- [#3890](https://github.com/microsoft/typespec/pull/3890) `@extension` used on the service namespace will set extension at the root of the document
- [#3932](https://github.com/microsoft/typespec/pull/3932) Add support for URI templates in routes

## Bug Fixes

### @typespec/compiler

- [#3881](https://github.com/microsoft/typespec/pull/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](https://github.com/microsoft/typespec/pull/4050) Allow using compact namespace form `Foo.Bar` when inside another namespace

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

    }
  }
  ```

- [#3898](https://github.com/microsoft/typespec/pull/3898) Fix decimal numeric with leading zeros
- [#4046](https://github.com/microsoft/typespec/pull/4046) Fix type comparison of literal and scalar when in projection context
- [#4022](https://github.com/microsoft/typespec/pull/4022) `tsp compile --watch` will not stop when a crash happens during compilation
- [#3933](https://github.com/microsoft/typespec/pull/3933) Add `const` template parameter to get the precise lib type

### @typespec/http

- [#3909](https://github.com/microsoft/typespec/pull/3909) Fix `HttpPart` not respecting explicit part name by always using the property name
- [#3933](https://github.com/microsoft/typespec/pull/3933) Fix some diagnostic not showing the right message

### @typespec/versioning

- [#3911](https://github.com/microsoft/typespec/pull/3911) Allow spreading a model that has props added in previous version
- [#3951](https://github.com/microsoft/typespec/pull/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](https://github.com/microsoft/typespec/pull/4046) Fix issue where operation example would produce an empty object when `@body`/`@bodyRoot` was used
- [#4046](https://github.com/microsoft/typespec/pull/4046) Fix operation response body examples showing up for each response.
- [#3912](https://github.com/microsoft/typespec/pull/3912) Fixes bug where union documentation was being applied to each union member in emitted output.
- [#3908](https://github.com/microsoft/typespec/pull/3908) Fixes bug where circular references in unions caused an empty object to be emitted instead of a ref.

### @typespec/protobuf

- [#3933](https://github.com/microsoft/typespec/pull/3933) Fix some diagnostic not showing the right message
