Skip to content

July 2023

New Features

Section titled “New Features”

@typespec/compiler and core language

Section titled “@typespec/compiler and core language”
  • New built-in linter system. Typespec libraries are able to define linting rules which can be configured in tspconfig.yaml. See documentation for configuring a linter and writing a linter
  • Allow decorators, directives and doc comments to be specified in any order
  • Format doc comments above decorators and directives
  • Improve formatting for properties with comments and decorators
  • Support for new Unicode 15.0 identifier characters

Emitter framework

Section titled “Emitter framework”
  • Add writeOutput to TypeEmitter for additional customization in writing generated files
  • Add meta property to source files and declarations to store arbitrary metadata
  • Add support for emitting enum member references
  • Add new TypeEmitter methods for scalar instantiation

@typespec/http library

Section titled “@typespec/http library”
  • Add documentation on automatic header name resolution from property name for @header decorator

@typespec/json-schema emitter

Section titled “@typespec/json-schema emitter”
  • Support @extension for adding arbitrary vendor extensions into the output
  • Add support for Record<T>
  • Support templates instantiated with intrinsic types and type expressions
  • Export emitter and related types from the npm package
  • By default, types that are not marked with @jsonSchema or are within a namespace with @jsonSchema are bundled into the schemas that reference them. Set the emitAllRefs option to true to get the previous behavior of emitting all types referenced as JSON Schema

@typespec/openapi3 emitter

Section titled “@typespec/openapi3 emitter”
  • Omit x-typespec-name extension by default from openapi3 output. A new configuration and command line option include-x-typespec-name: \"inline-only\" | \"never\" has been added to get previous behavior

@typespec/rest library

Section titled “@typespec/rest library”
  • Add isListOperation function migrated from @typespec/compiler

Bug Fixes

Section titled “Bug Fixes”

@typespec/compiler and core language bug fixes

Section titled “@typespec/compiler and core language bug fixes”
  • Add support for UTF-8 with bom for other files loaded by TypeSpec compiler. .tsp files already had support, this make it more available for any library/emitter using the compiler api to load a file.
  • Fix signature help after comment with no closing parenthesis or angle bracket
  • Doc comment /** */ should override base type doc in model is or op is
  • Formatter incorrectly formatting :: to .
  • Fix formatting issue with comment between decorator and scalar or interface
  • Fix stack overflow when a circular reference with op is exists inside an interface.
  • Clean up handling of non-standard entrypoints in language server
  • Fix stack overflow when referencing decorator target in checker and projections

@typespec/openapi3 emitter bug fixes

Section titled “@typespec/openapi3 emitter bug fixes”
  • OpenAPI emitters: treat union namespaces like namespaces for other types

Emitter framework bug fixes

Section titled “Emitter framework bug fixes”
  • Fix that some context methods were not being passed the expected parameters
  • Fix that context was set incorrectly for some TypeEmitter methods, and add missing context methods for model properties, enum members, and union variants

@typespec/json-schema emitter bug fixes

Section titled “@typespec/json-schema emitter bug fixes”
  • Fix a bug that could result in a schema being bundled more than once

Breaking Changes

Section titled “Breaking Changes”

For Specification Authors

Section titled “For Specification Authors”
  • Update tsp init template schema for future extensibility. Older tsp version will fail validation when trying to initialize a project with a new template definition.
  • Json Schema Emitter: the namespace has been corrected to TypeSpec.JsonSchema. Update any using statements from JsonSchema to TypeSpec.JsonSchema, and any references from JsonSchema.[Type] to TypeSpec.JsonSchema.[Type].

For Emitters and Libraries

Section titled “For Emitters and Libraries”
  • Minimum version of TypeScript updated to 5.0. TypeSpec is using new features available in TypeScript 5.0 which result in a definition file not parsable by older version. Note that this only affect compiling TypeScript code and is not breaking any JS or TypeSpec code. See more information on typescript 5.0
  • Emitter Framework: Add support for templates instantiated with types without declared names. In such cases, TypeEmitter’s declarationName method may return undefined, and so the various *Instantiation methods might be called with an undefined name, and AssetEmitter’s emitDeclarationName method might return undefined.
  • Make internal @resourceTypeForKeyParam decorator in @typespec/rest library private

Deprecations

Section titled “Deprecations”
  • @list decorator from TypeSpec core is deprecated. Use @listsResource from @typespec/http instead
  • isListOperation function from TypeSpec core is deprecated. Use isListOperation from @typespec/http instead
  • getListOperationType from TypeSpec core is deprecated
  • @typespec/linter Package is deprecated in favor of built-in linter system