---
title: 0.58 - July 2024
---

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

## Examples in TypeSpec

This release introduce a new `@example` and `@opExample` decorator.

Those new decorators provide a way to specify some canonical examples for data types and operations. Each emitter is then able to serialize those examples in their own format.

```tsp
@example(#{
  id: "some",
  date: utcDateTime.fromISO("2020-01-01T00:00:00Z"),
  timeout: duration.fromISO("PT1M"),
})
model Foo {
  id: string;
  date: utcDateTime;
  @encode("seconds", int32) timeout: duration;
}
```

```tsp
@opExample(
  #{
    parameters: #{ pet: #{ id: "some", name: "Fluffy", dob: plainDate.fromISO("2020-01-01") } },
    returnType: #{ id: "some", name: "Fluffy", dob: plainDate.fromISO("2020-01-01") },
  },
  #{ title: "First", description: "Show creating a pet" }
)
op createPet(pet: Pet): Pet;
```

## Breaking Changes

### @typespec/compiler

- [#3793](https://github.com/microsoft/typespec/pull/3793) Do not carry over `@friendlyName` with `model is` or `op is`

  ```tsp
  @friendlyName("Abc{T}", T)
  model Foo<T> {}

  model Bar is Foo<string>;

  // This can be changed to
  model Abcstring is Foo<string>;
  ```

- [#3659](https://github.com/microsoft/typespec/pull/3659) Disallows overriding a required inherited property with an optional property.

In previous versions of TypeSpec, it was possible to override a required property with an optional property. This is no longer allowed. This change may result in errors in your code if you were relying on this bug, but specifications that used this behavior are likely to have been exposed to errors resulting from incoherent type checking behavior.

The following example demonstrates the behavior that is no longer allowed:

```tsp
model Base {
  example: string;
}

model Child extends Base {
  example?: string;
}
```

In this example, the `Child` model overrides the `example` property from the `Base` model with an optional property. This is no longer allowed.

### @typespec/http

- [#3737](https://github.com/microsoft/typespec/pull/3737) Keep trailing slash when building http routes, this is breaking if you used to have `@route()` ending with `/`.

  | TypeSpec                                                         | Before            | After              |
  | ---------------------------------------------------------------- | ----------------- | ------------------ |
  | `@route("users/")`                                               | `users`           | `users/`           |
  | `@route("users")`                                                | `users`           | `users`            |
  | on interface `@route("users/")` and on op `@route("addresses/")` | `users/addresses` | `users/addresses/` |
  | on interface `@route("users/")` and on op `@route("addresses")`  | `users/addresses` | `users/addresses`  |

## Features

### @typespec/compiler

- [#3699](https://github.com/microsoft/typespec/pull/3699) Moved compiler dependencies to peer and dev for scaffolded projects.
- [59daf90](https://github.com/microsoft/typespec/commit/59daf9054c709d3657e498b5f6dbe77492c98210) Add new `@example` and `@opExample` decorator to provide examples on types and operations.

  ```tsp
  @example(#{
    id: "some",
    date: utcDateTime.fromISO("2020-01-01T00:00:00Z"),
    timeout: duration.fromISO("PT1M"),
  })
  model Foo {
    id: string;
    date: utcDateTime;
    @encode("seconds", int32) timeout: duration;
  }
  ```

  ```tsp
  @opExample(
    #{
      parameters: #{ pet: #{ id: "some", name: "Fluffy", dob: plainDate.fromISO("2020-01-01") } },
      returnType: #{ id: "some", name: "Fluffy", dob: plainDate.fromISO("2020-01-01") },
    },
    #{ title: "First", description: "Show creating a pet" }
  )
  op createPet(pet: Pet): Pet;
  ```

- [#3751](https://github.com/microsoft/typespec/pull/3751) Adds option to `tsp init` to generate .gitignore file

### @typespec/http

- [#3717](https://github.com/microsoft/typespec/pull/3717) Allow overriding base operation verb
- [#3676](https://github.com/microsoft/typespec/pull/3676) Expose `getHttpPart` and types functions
- [#3732](https://github.com/microsoft/typespec/pull/3732) Expose `model` property on `HttpAuth` to retrieve original type used to define security scheme

### @typespec/openapi

- [#3626](https://github.com/microsoft/typespec/pull/3626) Adds public function for setting info object

### @typespec/openapi3

- [bd0b3df](https://github.com/microsoft/typespec/commit/bd0b3df225045a89d3d16c37828f24d84d154343) Add support for new `@example` and `@opExample` decorator
- [#3663](https://github.com/microsoft/typespec/pull/3663) Adds support for converting OpenAPI3 specs to TypeSpec via the new tsp-openapi3 CLI included in the `@typespec/openapi3` package.
- [#3732](https://github.com/microsoft/typespec/pull/3732) Apply openapi3 extension on Security schemes

### @typespec/html-program-viewer

- [#3713](https://github.com/microsoft/typespec/pull/3713) Complete new dynamic UI to navigate the TypeSpec type graph

## Bug Fixes

### @typespec/compiler

- [#3623](https://github.com/microsoft/typespec/pull/3623) Fix crash of language server on firefox
- [#3516](https://github.com/microsoft/typespec/pull/3516) Deprecate getAssetEmitter and recommend calling `createAssetEmitter` directly
- [#3767](https://github.com/microsoft/typespec/pull/3767) Fix semantic highlighting of using of single namespace
- [#3824](https://github.com/microsoft/typespec/pull/3824) Do not cast model expression to object value if the constraint is allowing the type
- [#3577](https://github.com/microsoft/typespec/pull/3577) Fix formatting of object and array literal in decorator to hug parenthesis
- [#3823](https://github.com/microsoft/typespec/pull/3823) Fix formatting of scalar constructor called with no args
- [#3743](https://github.com/microsoft/typespec/pull/3743) Fix 'typespec vs install' command on windows
- [#3605](https://github.com/microsoft/typespec/pull/3605) Fix templates initialized on node 22

### @typespec/openapi3

- [#3516](https://github.com/microsoft/typespec/pull/3516) Fix issue that could result in invalid document generation when running `tsp compile` from another directory
- [#3794](https://github.com/microsoft/typespec/pull/3794) Updates tsp-openapi3 to always emit main.tsp when formatting encounters an error.
- [#3839](https://github.com/microsoft/typespec/pull/3839) Updates tsp-openapi3 doc line wrapping to only automatically create newlines when they are present in the original documentation.

### @typespec/html-program-viewer

- [#3585](https://github.com/microsoft/typespec/pull/3585) Fix crash in program viewer when trying to display new value type

### @typespec/json-schema

- [#3516](https://github.com/microsoft/typespec/pull/3516) Fix issue that could result in invalid document generation when running `tsp compile` from another directory

```

```
