---
title: "1.0.0-rc.0"
releaseDate: 2025-04-02
version: "1.0.0-rc.0"
---

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

## TypeSpec 1.0 Release Candidate

We're excited to announce the TypeSpec 1.0 Release Candidate, marking a significant milestone for the TypeSpec project. TypeSpec accelerates your initial API development while providing a sustainable approach to evolving your APIs over time. Design faster today by defining your APIs in a concise, human-readable format and generating all the artifacts you need from a single source of truth – OpenAPI specifications, client libraries, and server code scaffolding. Scale easier tomorrow with an API-first approach that keeps everything in sync as your API grows and requirements change.

- `@typespec/compiler`
- `@typespec/http`
- `@typespec/openapi`
- `@typespec/openapi3`
- `@typespec/json-schema`

All the other typespec libraries remain in preview, beta or alpha stage.

[See our blog post](https://typespec.io/blog/2025-03-31-typespec-1-0-release/)

## Breaking Changes

### @typespec/compiler

- [#6678](https://github.com/microsoft/typespec/pull/6678) Moved `TypeSpecPrettierPlugin` type to internal. If wanting to use the prettier pluging programmatically, use it from the `@typespec/prettier-plugin-typespec` package
- [#6544](https://github.com/microsoft/typespec/pull/6544) Remove deprecated `@typespec/compiler/emitter-framework` export in favor of a new package `@typespec/asset-emitter`

  ```diff lang=json title=package.json
  "dependencies": {
  +   "@typespec/asset-emitter": "^1.0.0-rc.0"
  }
  ```

  ```diff lang=ts
  -import { TypeEmitter, ... } from "@typespec/compiler/emitter-framework";
  +import { TypeEmitter, ... } from "@typespec/asset-emitter";
  ```

- [#6754](https://github.com/microsoft/typespec/pull/6754) Reserve additional keywords:
  - `context`
  - `sym`
  - `prop`
  - `property`
  - `scenario`

### @typespec/http

- [#6557](https://github.com/microsoft/typespec/pull/6557) Remove support for deprecated implicit multipart, migrate to explicit part with `@multipartBody` and `HttpPart<T>`

  ```diff lang=tsp
  op upload(
    @header contentType: "multipart/form-data",
  -  @body body: {
  +  @multipartBody body: {
  -    name: string;
  +    name: HttpPart<string>;
  -    avatar: bytes;
  +    avatar: HttpPart<bytes>;
    }
  ): void;
  ```

- [#6563](https://github.com/microsoft/typespec/pull/6563) Separate file bodies into their own `bodyKind`.

  The HTTP library will now return a body with `bodyKind: "file"` in all cases where emitters should treat the body as a file upload or download. Emitters that previously attempted to recognize File bodies by checking the `type` of an HTTP `"single"` body may now simply check if the `bodyKind` is `"file"`. This applies to all HTTP payloads where an `HttpOperationBody` can appear, including requests, responses, and multipart parts.

### @typespec/openapi3

- [#6557](https://github.com/microsoft/typespec/pull/6557) Remove support for removed feature implicit multipart.
- [#6563](https://github.com/microsoft/typespec/pull/6563) Separate file bodies into their own `bodyKind`.

  The HTTP library will now return a body with `bodyKind: "file"` in all cases where emitters should treat the body as a file upload or download. Emitters that previously attempted to recognize File bodies by checking the `type` of an HTTP `"single"` body may now simply check if the `bodyKind` is `"file"`. This applies to all HTTP payloads where an `HttpOperationBody` can appear, including requests, responses, and multipart parts.

## Features

### @typespec/http

- [#6559](https://github.com/microsoft/typespec/pull/6559) [API] Expose `property?` on `HttpOperationPart`
- [#6652](https://github.com/microsoft/typespec/pull/6652) Add validation when using path or query options with the default value while the parameter is referenced in the uri template

### @typespec/prettier-plugin-typespec

- [#6678](https://github.com/microsoft/typespec/pull/6678) Migrate to ESM. This shouldn't be breaking as we didn't support prettier < 3.

## Bug Fixes

### @typespec/compiler

- [#6197](https://github.com/microsoft/typespec/pull/6197) Show emitter internal error message in tspconfig
- [#6710](https://github.com/microsoft/typespec/pull/6710) Updates to scaffolding script and scaffold commands for consistency
- [#6826](https://github.com/microsoft/typespec/pull/6826) Fix new reserved keywords were not allowed in augment decorator expression
- [#6697](https://github.com/microsoft/typespec/pull/6697) Fix crash that would happen when a type was mutated while using null in a decorator(e.g. when using versioning library with `@example(null)`)
- [#6711](https://github.com/microsoft/typespec/pull/6711) Fix extra properties not validated in nested entries of the config
- [#6711](https://github.com/microsoft/typespec/pull/6711) Fix passing nested emitter options with `--option`

### @typespec/http

- [#6542](https://github.com/microsoft/typespec/pull/6542) Query parameter with `-` will be correctly represented in the resulting uri template
- [#6472](https://github.com/microsoft/typespec/pull/6472) Path parameters can now be optional under specific circumstances. This fix updates the validation to ensure it doesn't trigger in these scenarios.

  An optional parameter should have a leading `/` inside the `{}`.

  For example:

  ```tsp
  @route("optional{/param}/list")
  op optional(@path param?: string): void;
  ```

  Another supported scenario is using `@autoRoute`:

  ```tsp
  @autoRoute
  op optional(@path param?: string): void;
  ```

### @typespec/openapi

- [#6651](https://github.com/microsoft/typespec/pull/6651) Adds diagnostic when passing in a `Type` to the `$extension` decorator function directly

### @typespec/openapi3

- [#6559](https://github.com/microsoft/typespec/pull/6559) Fix missing application of description on multipart properties
- [#6729](https://github.com/microsoft/typespec/pull/6729) Fix duplicate name error when using named union inside multipart part.
- [#6506](https://github.com/microsoft/typespec/pull/6506) Fix union of custom scalar with `null` creating an `object` with `allOf` reference

### typespec-vscode

- [#6668](https://github.com/microsoft/typespec/pull/6668) Fix error when upgrading to use latest telemetry library
- [#6690](https://github.com/microsoft/typespec/pull/6690) Fix the issue to log compiler information as an error. And remove PREVIEW prefix for server code emitter
- [#6694](https://github.com/microsoft/typespec/pull/6694) compiler can be resolved automatically when it's not installed in the root folder of the first opened workspace.
- [#6620](https://github.com/microsoft/typespec/pull/6620) Update menu item and command text for "Show OpenAPI3 Documentation" and "Import TypeSpec from OpenApi3"
