Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 39 ยท Protobuf Language

Protobuf Enums, Repeated Fields and Maps

Define enums with a safe zero value, repeated lists with packed encoding, and map fields in proto3, with runnable Go stand-ins for unknown values and packing.

Real data is rarely a flat list of numbers and strings. Orders have statuses, users have many emails, and products have attributes keyed by name. Protobuf covers these with three constructs: enums (a fixed set of named values), repeated fields (lists) and map fields (key-value pairs). This lesson explains each one, the traps to avoid, and how they look on the wire.

The .proto code is read-only here. The Go programs are stand-ins that model the behavior; the encoding in the packed-repeated example is the real protobuf layout.

Enums

PROTO
enum OrderStatus {
  ORDER_STATUS_UNSPECIFIED = 0;
  ORDER_STATUS_PENDING     = 1;
  ORDER_STATUS_SHIPPED     = 2;
  ORDER_STATUS_DELIVERED   = 3;
}

message Order {
  int64 id = 1;
  OrderStatus status = 2;
}

Rules and conventions:

  • The first value must be zero in proto3. Because zero is the default, make it a neutral ..._UNSPECIFIED value. A forgotten field then reads as "unspecified" rather than as a real business state like PENDING.
  • Enum value names are scoped to the package, not to the enum, so two enums in one package cannot both contain PENDING. Prefix every value with the enum name in UPPER_SNAKE_CASE as above.
  • Enums are encoded as varints, using the numeric value.
  • Do not reorder or reuse numbers. Retire values with reserved.
PROTO
enum Color {
  reserved 2, 15 to 20;
  reserved "COLOR_PURPLE";
  COLOR_UNSPECIFIED = 0;
  COLOR_RED = 1;
}

Aliases

If two names should share one number, you must enable option allow_alias = true; inside the enum. Aliases are mainly useful when renaming a value without breaking existing code.

Unknown enum values

If a newer server sends ORDER_STATUS_RETURNED = 4 and your older client does not know it, proto3 enums are open: the numeric value is kept as-is. In Go the field simply holds 4. Your code must have a default branch.

Stand-in 1: handling an unknown enum value

Go Stand-in: open enums need a default branch

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Repeated fields

repeated means "zero or more", an ordered list:

PROTO
message User {
  int64 id = 1;
  repeated string emails = 2;
  repeated int32 favorite_numbers = 3;
  repeated Address addresses = 4;
}
  • In generated code it becomes a slice or list. An empty list and an unset list are the same thing.
  • Order is preserved.
  • Scalar repeated fields in proto3 are packed by default: one tag, one length, then all values back to back. Strings, bytes and messages cannot be packed, so each element gets its own tag.

Packed encoding in action

Take repeated int32 d = 4; with values 3, 270 and 86942. Packed, they become one length-delimited field. Unpacked they would be three separate tag/value pairs.

Go Stand-in: packed versus unpacked repeated

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Decoders accept both forms, so you can change a field between packed and unpacked without breaking anyone.

Do not nest lists directly

You cannot write repeated repeated int32. Wrap the inner list in a message:

PROTO
message Row { repeated double cells = 1; }
message Matrix { repeated Row rows = 1; }

Maps

PROTO
message Product {
  int64 id = 1;
  map<string, string> attributes = 2;
  map<int32, Price> prices_by_region = 3;
}

Key types can be any integer or string (and bool), but never float, double, bytes, enums or messages. Values can be anything except another map or a repeated field.

Things to know:

  • A map is syntactic sugar. On the wire it is a repeated field of small messages with key = 1 and value = 2, so maps are compatible with plain repeated entries.
  • Iteration order is undefined. Two serializations of the same map may list keys differently, and generated Go code iterates in random order like any Go map. Sort the keys if you need stable output.
  • Maps cannot be repeated, and a duplicate key keeps the last value.

Stand-in 2: map entries as repeated messages, with sorted output

Go Stand-in: map as key/value entries

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Design tips

  1. Prefer enums over free-form strings for states, so clients can switch exhaustively.
  2. Always keep an UNSPECIFIED zero value and treat it as "not provided".
  3. Use repeated for ordered lists; use map for lookups by key. If you need ordered key-value pairs, use a repeated message instead of a map.
  4. Avoid huge repeated fields in one message. For thousands of items, stream them or paginate.
  5. Name repeated fields in the plural (emails, not email).

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why should the first (zero) enum value be something like UNSPECIFIED?

    An unset field reads as 0. If 0 meant PENDING, forgotten data would look valid.
  2. 2. How are repeated scalar fields encoded in proto3 by default?

    Scalar repeated fields are packed, which saves a tag per element.
  3. 3. Which type cannot be a map key?

    Floating-point types, bytes, enums and messages are not allowed as keys.
  4. 4. What guarantee does protobuf give about map iteration order?

    Sort keys yourself when you need deterministic output.
  5. 5. What happens when an old client receives an enum number it does not know?

    proto3 enums are open; unknown numbers are kept.

Summary

  • Enums are named numbers; the first value must be zero and should mean "unspecified".
  • repeated fields are ordered lists; scalar lists are packed on the wire.
  • map<K, V> is a repeated key/value message with undefined iteration order.
  • Handle unknown enum values with a default case.
  • Retire enum values and numbers with reserved.

Next: oneof, optional and Well-Known Types