1.0.0-rc.0

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

Breaking Changes

@typespec/compiler

#6678 Moved TypeSpecPrettierPlugin type to internal. If wanting to use the prettier pluging programmatically, use it from the @typespec/prettier-plugin-typespec package

#6544 Remove deprecated @typespec/compiler/emitter-framework export in favor of a new package @typespec/asset-emitter

"dependencies": {
   "@typespec/asset-emitter": "^1.0.0-rc.0"
}

import { TypeEmitter, ... } from "@typespec/compiler/emitter-framework";
import { TypeEmitter, ... } from "@typespec/asset-emitter";

#6754 Reserve additional keywords:
- context
- sym
- prop
- property
- scenario

@typespec/http

#6557 Remove support for deprecated implicit multipart, migrate to explicit part with @multipartBody and HttpPart<T>

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

#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 Remove support for removed feature implicit multipart.
#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 [API] Expose property? on HttpOperationPart
#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 Migrate to ESM. This shouldn’t be breaking as we didn’t support prettier < 3.

Bug Fixes

@typespec/compiler

#6197 Show emitter internal error message in tspconfig
#6710 Updates to scaffolding script and scaffold commands for consistency
#6826 Fix new reserved keywords were not allowed in augment decorator expression
#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 Fix extra properties not validated in nested entries of the config
#6711 Fix passing nested emitter options with --option

@typespec/http

#6542 Query parameter with - will be correctly represented in the resulting uri template
#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:
```
@route("optional{/param}/list")
op optional(@path param?: string): void;
```
Another supported scenario is using @autoRoute:
```
@autoRoute
op optional(@path param?: string): void;
```

@typespec/openapi

#6651 Adds diagnostic when passing in a Type to the $extension decorator function directly

@typespec/openapi3

#6559 Fix missing application of description on multipart properties
#6729 Fix duplicate name error when using named union inside multipart part.
#6506 Fix union of custom scalar with null creating an object with allOf reference

typespec-vscode

#6668 Fix error when upgrading to use latest telemetry library
#6690 Fix the issue to log compiler information as an error. And remove PREVIEW prefix for server code emitter
#6694 compiler can be resolved automatically when it’s not installed in the root folder of the first opened workspace.
#6620 Update menu item and command text for “Show OpenAPI3 Documentation” and “Import TypeSpec from OpenApi3”