Skip to content

Directives

Directives are predefined annotations that attach to the syntax nodes unlike decorators which will cary over with model is, op is, etc. This means any syntax node is able to have a directive(e.g alias).

These are the available directives:

#deprecated

The deprecated directive allows marking a node and through it its type as deprecated. It takes a single argument which is the deprecation message.

#deprecated "Use NewUser instead"
model LegacyUser {}

Using that type will result in a deprecation warning:

model Post {
  author: LegacyUser;
  //      ^ warning: Deprecated: Use NewUser instead
}
Terminal window
$ tsp compile .


Diagnostics were reported during compilation:


main.tsp:5:11 - warning deprecated: Deprecated: Use NewUser instead
> 5 |   author: LegacyUser;
    |           ^^^^^^^^^^


Found  1 warning.

Adding another #suppress on a node that reports a deprecation warning will suppress the warning automatically.

model Post {
  #suppress "Use newAuthor property instead"
  author: LegacyUser; // no need to also suppress the deprecated diagnostic about usage of LegacyUser
}

Api

A library or emitter can check if a type was annotated with the deprecated directive using the isDeprecated method and/or get the message using getDeprecationDetails.

import { getDeprecationDetails, isDeprecated } from "@typespec/compiler";
const isDeprecated = isDeprecated(program, type);
const details = getDeprecationDetails(program, type);

#suppress

Suppress directive allows suppressing a specific warning diagnostic. It takes 2 arguments:

  • The diagnostic code to suppress
  • A message to justify the suppression
model Post {
  #suppress "deprecated" "We are not ready to migrate yet"
  author: LegacyUser;
}

Api

There is currently no exposed api to resolve suppresssions