June 2023

Caution

This release contains breaking changes

New Features

• Json Schema Emitter
• New decimal types
• Support for using doc comments instead of the @doc decorator
• New valueof type constraint modifier for type literals
• Lazy evaluation of emitter configuration
• Signature Help for Template Arguments and other IDE improvements

New Decimal Types

Added support for decimal and decimal128 types

model Foo {
  price: decimal;
  shortPrice: decimal128;
}

These types represent values stored in decimal format which are often used in financial calculations to avoid rounding errors introduced by binary floating point formats. decimal can store values of any size and precision, while decimal128 corresponds to the 128 bit decimal floating point format described by IEEE 754.

Support for Doc Comments

Doc comments (/** */) will be treated as the documentation for types, unless there is an explicit @doc decorator

/** This will now be the documentation for model Foo */
model Foo {
  name: string;
}

New valueof type constraint modifier to require type literals

Templates and decorators can now constrain arguments to literal types. For example, the following template constraint:

model Foo<T extends valueof string> {
  @doc(T)
  name: string;
}

would match quoted literal strings, “this”, as well as references to enum values. Templates and decorators that require string values should change to using this new formulation.

Allow lazy evaluation of emitter config

• Validate linter configuration only for linters that are executing. This removes warnings for emitters that are configured but not available in a particular compilation.

Enable Signature Help for Template Arguments

• Template completion will now have similar help in IDE language server as decorators currently do.

Show documentation Comments on Aliases in IDE Language Tooling

• Documentation comments will show up in the IDE, just as documentation comments for other library types.

Ensure a dev release for all packages

• Packages with no changes will now release with a -dev.0 version in dev releases.

Json Schema Emitter

• Core packages now contain a Json Schema emitter @typespec/json-schema

Bug Fixes

-tspconfig.yaml should always get resolved relative to the entrypoint.

• Array and Record doc comments are treated as developer documentation.

• Fixed formatting of comment between decorator and op statement.

• Decorators on operations may reference the same operation, or may reference an operation that references this operation.

interface FooOperations {
  @nextPageOperation(getNextPage) // allowed
  getNextPage(pageLink: url): Page<Foo>;
}

• Fix validation for unixTimeStamp.

• Fix diagnostic for intrinsic type expected to not assume string as the required type.

• Fix error message for @encode errors.

• Fix error handling when template is missing or invalid in tsp init.

• Emitter framework: uppercase type argument type names when constructing a declaration name from a template instantiation.

• Add reference documentation for missing decorators.

• Remove dependency on node-fetch.

• Remove inaccurate output directory message from compilation success.

• Allow template resolution over http redirects for tsp init templates.

• Improve signature help for an unterminated argument list.

New Deprecations

• Templates that use decorators with the valueof constraint will receive a warning if their input types are not similarly constrained.

model Foo<T extends string> {
  @doc(T) // valueof constraint here will cause a warning
  id: uuid;
}

should be changed to apply the valueof constraint to their parameters that are passed to such decorators:

model Foo<T extends valueof string> {
  @doc(T) // no warning
  id: uuid;
}

• The object type is deprecated. Templates and decorators should use TypeSpec.Reflection.Model to indicate a model contraint. In specs, {} designates and empty model, unknown[] indicates and empty array, and Record<unknown> indicates a keyed type with unknown property types.

Breaking Changes

• Decorators that require literal type value marshalling MUST change to using the valueof keyword.

extern dec myDecorator(target: Type, name: string);

Must be changed to use the valueof decorator

extern dec myDecorator(target: Type, name: valueof string);

• Arrays are no longer assignable to an empty model (or object)

• Remove `@format(“url”) from url scalar. OpenAPI emitters will still emit the appropriate format, emitters should rely on the scalar type to determine how to process the url type, not the format string.