Nested Messages in Protobuf

Composing Data with Nested Messages

Protobuf messages can contain other messages as field types, creating hierarchical data structures. Messages can also be defined inside other messages (nested definitions) to scope them logically.

syntax = "proto3";

message Order {
  int64 order_id = 1;
  Customer customer = 2;
  repeated LineItem items = 3;
  ShippingInfo shipping = 4;

  // Nested message definitions
  message LineItem {
    string product_id = 1;
    string name = 2;
    int32 quantity = 3;
    double unit_price = 4;
  }

  message ShippingInfo {
    Address address = 1;
    string carrier = 2;
    string tracking_number = 3;
  }
}

message Customer {
  int64 id = 1;
  string name = 2;
  string email = 3;
}

message Address {
  string line1 = 1;
  string line2 = 2;
  string city = 3;
  string state = 4;
  string postal_code = 5;
  string country = 6;
}

Nested vs. Top-Level Messages

Nested messages (defined inside another message) are scoped to their parent. From outside, they are referenced as Order.LineItem. This is useful when a type is logically owned by its parent and not reused elsewhere.

Top-level messages (like Address above) are defined at the file level and can be referenced by any message. Use top-level definitions when a type is shared across multiple messages.

Null Semantics

Message-typed fields have a distinct "not set" state (null). This differs from scalar fields, which always have a default value. In proto3, you can check whether a message field has been set using the generated has_* methods in most languages.

Depth and Complexity

There is no hard limit on nesting depth, but deeply nested structures increase serialization overhead and reduce readability. Aim for 2-3 levels of nesting at most.