Protobuf Scalar Types, Enums and Nested Messages
On this page
Choosing protobuf integer types: int32 vs sint32 vs fixed32
Protobuf has several integer types that look interchangeable but encode differently. Encoding the same values with each (sizes include the 1-byte field tag):
value int32 sint32 fixed32
1 2 bytes 2 bytes 5 bytes
300 3 bytes 3 bytes 5 bytes
-1 11 bytes 2 bytes (unsigned only)
-300 11 bytes 3 bytes (unsigned only)
2000000000 6 bytes 6 bytes 5 bytesint32/int64use variable-length encoding (varints): small positive numbers are tiny, but negative numbers always take 10 bytes, because they're encoded as huge unsigned values.sint32/sint64use ZigZag encoding, which maps small negatives to small positives: -1 takes the same space as 1. It interleaves the two signs: 0 becomes 0, -1 becomes 1, 1 becomes 2, -2 becomes 3, 2 becomes 4, so a number close to zero stays small whichever side of zero it's on. Use them for values that are often negative (temperature deltas, offsets).fixed32/fixed64(and signedsfixed32/sfixed64) always take 4 or 8 bytes: better for large values like hashes and IDs that are usually big.uint32/uint64for counts that can't be negative.
Other scalars: double, float, bool, string (must be valid UTF-8) and bytes (anything). Money belongs in an integer of minor units (int64 total_cents) or a dedicated money message, never a float.
Protobuf enums and the UNSPECIFIED zero value
message Order {
enum Status {
STATUS_UNSPECIFIED = 0;
STATUS_PENDING = 1;
STATUS_PAID = 2;
STATUS_SHIPPED = 3;
STATUS_DELIVERED = 4;
}
Status status = 3;
}- The first value must be 0, and 0 is the default when nothing is set, so make it
..._UNSPECIFIED. - Proto3 enums are open: a client compiled before
STATUS_REFUNDED = 5existed receives the number 5 and keeps it as an unknown value. Code must handle values it doesn't recognize, typically treating them as "other". - Prefix values with the enum name; enum values share a namespace with their siblings in C++ rules, so
PENDINGin two enums in one package would clash.
Nested messages, repeated fields and maps
message Order {
repeated LineItem items = 5; // an ordered list
map<string, string> attributes = 7; // key-value pairs, no ordering guarantee
message LineItem { // nested type, referenced as Order.LineItem
string sku = 1;
int32 quantity = 2;
int64 unit_price_cents = 3;
}
}Nest types that only make sense inside their parent; give shared types (like Money or Address) their own top-level message so other messages can reuse them.
Default values and field presence with optional
In proto3, scalar fields have default values (0, "", false), and defaults aren't sent on the wire. Encoding a message with an empty name and age 0 produced zero bytes (Day 11). The consequence: by default, the receiver can't tell "age is 0" from "age wasn't set".
When the difference matters, ask for presence tracking:
message UpdateProfileRequest {
optional int32 age = 1; // generated code gets HasAge()
google.protobuf.Int32Value retries = 2; // a wrapper type: null versus 0
}optional on proto3 scalars gives generated Has...() methods. Message fields always have presence (they can be nil). Wrapper types (Day 21) are the older approach and also show up as null versus 0 in JSON.
Check yourself
int32 encodes negatives as large unsigned varints of 10 bytes; sint32 uses ZigZag encoding, mapping -1 to a small number.
Proto3 enums are open: the value is kept as an unknown number, and the client's code should handle it as an unrecognized value.
Mark the field optional, so the generated code tracks presence with a has method or pointer, or use a wrapper type like google.protobuf.Int32Value. Plain proto3 scalars can't distinguish zero from unset.
repeated for ordered lists. map for lookups by a unique key, keeping in mind map ordering isn't guaranteed on the wire.
For values that are usually large, like hashes or random ids, where a fixed 8 bytes is smaller than a varint that would need 9 or 10.