Messages and Field Numbers

proto3 basics

A .proto file declares syntax = "proto3"; (or uses the newer editions syntax), a package, and messages with typed fields. Each field has a unique field number that identifies it in the binary encoding; names exist only in code. Scalar types include string, bytes, bool, int32, int64, uint64, double, float, and variants such as sint64 for negative numbers. In proto3, scalar fields have default zero values, and optional lets you detect whether a field was set.

The schema language

Protocol Buffers define messages and services with numbered fields that keep the wire format stable.

An order message

shop/v1/order.proto.

syntax = "proto3";

package shop.v1;

option go_package = "example.com/shop/gen/shop/v1;shopv1";

message Order {
  string id = 1;
  string customer_id = 2;
  repeated OrderItem items = 3;
  int64 total_cents = 4;        // money as integer minor units
  string currency = 5;          // ISO 4217 code, e.g. "INR"
  optional string coupon_code = 6;
}

message OrderItem {
  string product_id = 1;
  int32 quantity = 2;
  int64 unit_price_cents = 3;
}

Use numbers 1 to 15 for frequent fields

Field numbers 1 to 15 encode in one byte together with the wire type, so give them to the most common fields.

Quick check: What identifies a field in the protobuf binary encoding?

• Its name
• Its field number
• Its position in the file only
• Its comment