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
#suppress

#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
}

$ 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;
}

#suppress "@typespec/http/no-service-found" "standard library route"
namespace Lib {
  @route("/test") op get(): string;
}

Short diagnostic codes

Diagnostic codes from a library are prefixed with the package name (e.g. @typespec/http/no-service-found), which can get verbose. You can also reference a diagnostic using its short name, where the package scope is stripped:

@typespec/<name> → <name> (e.g. @typespec/http/no-service-found → http/no-service-found)
@<scope>/typespec-<name> → <name> (e.g. @azure-tools/typespec-autorest/no-foo → autorest/no-foo)
A library may also declare a custom alias (e.g. tcgc/no-foo).

#suppress "http/no-service-found" "standard library route"
namespace Lib {
  @route("/test") op get(): string;
}

The full name is always accepted. If two loaded libraries would resolve to the same short name, that short name becomes ambiguous and you must use the full name for those libraries.

Api

There is currently no exposed api to resolve suppresssions