Decorators

TypeSpec.Protobuf

@field

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

When applied to the variants of a named union, the union can be used as the type of a message field:

• If the model property has no @field decorator, the union is emitted inline as a oneof named after the property, and the variant field indices share the field index space of the containing message. The property must be optional.
• If the model property has a @field decorator, the union is emitted as a wrapper message (named after the union) that contains a oneof value, and the variant field indices belong to the wrapper message.

Union variants used in a oneof cannot be arrays or maps.

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.
• not be used by any other field of the same message, including members of a oneof.

API Compatibility Note

Fields are accessed by index, so changing the index of a field is an API breaking change.

Encoding

Field indices between 1 and 15 are encoded using a single byte, while field indices from 16 through 2047 require two bytes, so those indices between 1 and 15 should be preferred and reserved for elements that are frequently or always set in the message. See the Protobuf binary format.

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

Target

ModelProperty | UnionVariant

Parameters

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

Examples

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

union Payment {
  @field(10) card: CardPayment,
  @field(11) bank_transfer: BankTransfer,
}

model Order {
  @field(1) id: string;

  // Emitted inline as `oneof payment { CardPayment card = 10; BankTransfer bank_transfer = 11; }`
  payment?: Payment;
}

@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. A named union annotated with this decorator is emitted as a wrapper message containing a oneof value.

@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;