TypeSpec library and emitter for Protobuf (gRPC)

npm install @typespec/protobuf

1. Via the command line

tsp compile . --emit=@typespec/protobuf

2. Via the config

emit:
  - "@typespec/protobuf"

Type: boolean

If set to true, this emitter will not write any files. It will still validate the TypeSpec sources to ensure they are compatible with Protobuf, but the files will simply not be written to the output directory.

Type: boolean

By default, the emitter will create message declarations for any models in a namespace decorated with @package that have an @field decorator on every property. If this option is set to true, this behavior will be disabled, and only messages that are explicitly decorated with @message or that are reachable from a service operation will be emitted.

• @field
• @message
• @package
• @reserve
• @service
• @stream

Defines the field index of a model property for conversion to a Protobuf message.

The field index of a Protobuf message must:

• fall between 1 and 2²⁹ - 1, inclusive.
• not fall within the implementation reserved range of 19000 to 19999, inclusive.
• not fall within any range that was [marked reserved](#

@TypeSpec.Protobuf.field(index: valueof uint32)

ModelProperty

model ExampleMessage {
  @field(1)
  test: string;
}

Declares that a model is a Protobuf message.

Messages can be detected automatically if either of the following two conditions are met:

• The model has a @field annotation on all of its properties.
• The model is referenced by any service operation.

This decorator will force the emitter to check and emit a model.

@TypeSpec.Protobuf.message

{}

None

Declares that a TypeSpec namespace constitutes a Protobuf package. The contents of the namespace will be emitted to a single Protobuf file.

@TypeSpec.Protobuf.package(details?: TypeSpec.Protobuf.PackageDetails)

Namespace

Reserve a field index, range, or name. If a field definition collides with a reservation, the emitter will produce an error.

This decorator accepts multiple reservations. Each reservation is one of the following:

• a string, in which case the reservation refers to a field name.
• a uint32, in which case the reservation refers to a field index.
• a tuple [uint32, uint32], in which case the reservation refers to a field range that is inclusive of both ends.

Unlike in Protobuf, where field name and index reservations must be separated, you can mix string and numeric field reservations in a single @reserve call in TypeSpec.

Field reservations prevent users of your Protobuf specification from using the given field names or indices. This can be useful if a field is removed, as it will further prevent adding a new, incompatible field and will prevent users from utilizing the field index at runtime in a way that may break compatibility with users of older specifications.

See Protobuf Language Guide - Reserved Fields for more information.

@TypeSpec.Protobuf.reserve(...reservations: valueof string | [uint32, uint32] | uint32[])

{}

// Reserve the fields 8-15 inclusive, 100, and the field name "test" within a model.
@reserve([8, 15], 100, "test")
model Example {
  // ...
}

Declares that a TypeSpec interface constitutes a Protobuf service. The contents of the interface will be converted to a service declaration in the resulting Protobuf file.

@TypeSpec.Protobuf.service

Interface

None

Set the streaming mode of an operation. See StreamMode for more information.

@TypeSpec.Protobuf.stream(mode: TypeSpec.Protobuf.StreamMode)

Operation

@stream(StreamMode.Out)
op logs(...LogsRequest): LogEvent;

@stream(StreamMode.Duplex)
op connectToMessageService(...Message): Message;