Catalog My learning Blog
gRPC and Protobuf Tutorial: Fast Microservice APIs · Phase 1 · Lesson 3 · 4 min read

Protobuf Scalar Types, Enums and Nested Messages

On this page
  1. Choosing protobuf integer types: int32 vs sint32 vs fixed32
  2. Protobuf enums and the UNSPECIFIED zero value
  3. Nested messages, repeated fields and maps
  4. Default values and field presence with optional
  5. Check yourself

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):

Code
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 bytes
  • int32 / int64 use 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 / sint64 use 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 signed sfixed32 / sfixed64) always take 4 or 8 bytes: better for large values like hashes and IDs that are usually big.
  • uint32 / uint64 for 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

Protobuf
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 = 5 existed 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 PENDING in two enums in one package would clash.
Number types trade compactness for different value ranges; enums need an unspecified zero; messages nest, repeat and map to build structured data.
Number types trade compactness for different value ranges; enums need an unspecified zero; messages nest, repeat and map to build structured data.

Nested messages, repeated fields and maps

Protobuf
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:

Protobuf
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.