Decorators

TypeSpec.Protobuf

@field

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)

Target

ModelProperty

Parameters

Name	Type	Description
index	valueof uint32	The whole-number index of the field.

Examples

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

@message

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

Target

{}

Parameters

None

@package

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)

Target

Namespace

Parameters

Name	Type	Description
details	PackageDetails	the optional details of the package

@reserve

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.

API Compatibility Note

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[])

Target

{}

Parameters

Name	Type	Description
reservations	valueof string | [uint32, uint32] | uint32[]	a list of field reservations

Examples

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

@service

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

Target

Interface

Parameters

None

@stream

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

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

Target

Operation

Parameters

Name	Type	Description
mode	StreamMode	The streaming mode to apply to this operation.

Examples

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

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