TypeSpec language style guide

This guide offers a recommended set of naming conventions to follow when drafting a TypeSpec specification.

info

The guidelines in this article are used in TypeSpec Core libraries. You can use them, or adapt them to your needs. The primary objectives are consistency and readability within your project, team, organization, or company source code.

Naming convention

Type	Naming	Example
scalar	camelCase	scalar uuid extends string;
model	PascalCase	model Pet {}
model property	camelCase	model Pet {furColor: string}
enum	PascalCase	enum Direction {}
enum member	camelCase	enum Direction {up, down}
namespace	PascalCase	namespace Org.PetStore
interface	PascalCase	interface Stores {}
operation	camelCase	op listPets(): Pet[];
operation params	camelCase	op getPet(petId: string): Pet;
unions	PascalCase	union Pet {cat: Cat, dog: Dog}
unions variants	camelCase	union Pet {cat: Cat, dog: Dog}
alias	camelCase or PascalCase depending on context	alias myString = string or alias MyPet = Pet
decorators	camelCase	@format, @resourceCollection
functions	camelCase	addedAfter
file name	kebab-case	my-lib.tsp
template parameter	PascalCase	<ExampleParameter>

note

In some languages, particularly object-oriented programming languages, it's conventional to prefix certain names with a letter to indicate what kind of thing they are. For example, prefixing interface names with I (as in IPet) or prefixing template parameter names with T (as in TResponse). This is not conventional in TypeSpec.

Layout convention

TypeSpec has a built-in formatter. See formatter section for more information on how to use it.

• Use 2 space indenting

// bad
model Pet {
    name: string;
}

// good
model Pet {
  name: string;
}

• Place a space before an opening curly brace

// bad
model Pet{
  name: string;
}

// good
model Pet {
  name: string;
}

• Block opening curly brace { should be on the same line

// bad
model Pet 
{
  name: string;
}

// good
model Pet {
  name: string;
}

• Add a newline after blocks

// bad
model Pet {
  name: string;
}
model Cat extends Pet {}

// good
model Pet {
  name: string;
}

model Cat extends Pet {}

• Place no space between an operation/decorator/function name and the parameter list

// bad
op list (filter: string): Pet[];

// bad
@doc ("This is a pet")

// good
op list(filter: string): Pet[];

// good
@doc("This is a pet")

• Do not add spaces inside parentheses

// bad
op list( filter: string ): Pet[];

// good
op list(filter: string): Pet[];

• Add spaces inside curly braces.

// bad
alias foo = {type: "cat"};

// good
alias foo = { type: "cat" };

• Do not add space inside square brackets

// bad
alias foo = [ 1, 2, 3 ];

// good
alias foo = [1, 2, 3];

• Start all comments with a space

//bad

// good

• Avoid trailing spaces at the end of lines.

Model layout

• Properties should hug each other unless they have decorators or comments

// bad
model Foo {
  one: string;

  two: string;

  three: string;
}

// good
model Foo {
  one: string;
  two: string;
  three: string;
}

• Wrap properties in new lines if they have leading comments or decorators

// bad
model Foo {
  one: string;
  @doc("Foo")
  two: string;
  // line comment
  three: string;
  /**
   *  Block comment
   */
  four: string;
  five: string;
}

// good
model Foo {
  one: string;

  @doc("Foo")
  two: string;

  // line comment
  three: string;

  /**
   *  Block comment
   */
  four: string;
  
  five: string;
}