// service.proto — field numbers are forever
syntax = "proto3";
message User {
uint64 id = 1; // never reuse this number
string email = 2;
string name = 3;
reserved 4; // old "phone" field — safely reserved
}Protocol Buffers: The Language Behind gRPC
Protocol Buffers (protobuf) is the interface definition language and serialization format that powers gRPC. Understanding it deeply is the key to designing gRPC APIs that are correct today and maintainable as requirements evolve over months and years.
Field Numbers Are Sacred
Every field in a protobuf message has a name and a number. The name is used in your code; the number is what appears on the wire. Once a field number is assigned and deployed, it must never be reassigned to a different field, even if the original field is removed. Reusing a field number causes silent data corruption when old clients or old data is deserialized by new code. The convention is to reserve removed field numbers explicitly, which causes protoc to emit a compile error if anyone tries to reuse them.
Designing for Evolution
The most important constraint in protobuf schema design is backward and forward compatibility. Adding a new field with a new field number is always safe. Removing a field (and reserving its number) is safe. Changing a field's type is usually not safe. Renaming a field is safe at the wire level but breaks generated code for all consumers. These rules mean your initial schema design carries long-term consequences, and getting field semantics right before the first deployment avoids painful migrations later.
Message Composition and Nesting
Complex data models map naturally onto nested message types. A UserProfile might contain an Address message, which contains a Country message with a currency code field. Deep nesting is readable in proto files but incurs serialization overhead proportional to nesting depth. For very hot paths, flattening frequently accessed fields to the top level measurably reduces serialization cost. Prefer composition over inheritance; protobuf has no inheritance concept, and trying to simulate it leads to awkward designs.
Well-Known Types
The protobuf standard library includes well-known types that handle common needs: Timestamp for time values (prefer this over raw int64 epoch milliseconds), Duration for time intervals, FieldMask for partial updates, Any for polymorphic payloads, and Struct for dynamic JSON-like data. Using well-known types instead of reinventing them improves interoperability and means your schemas communicate intent to other developers instantly.
Enums and Default Values
Every protobuf field has a default value when absent from a message: zero for numeric types, empty string for strings, false for booleans, and the zero-value enum variant for enums. This means your first enum variant should always represent an unknown or unspecified state, not a meaningful business value. A Status enum that starts with STATUS_UNSPECIFIED = 0 communicates clearly when a field is absent versus explicitly set to a known state, and prevents subtle bugs when old code deserializes new messages.
Schema Governance at Scale
When many teams share a proto repository, governance becomes critical. Enforce backward compatibility automatically in CI using buf lint and buf breaking. Organize protos by service domain with clear ownership. Use buf.yaml to configure style linting that catches common mistakes like mutable singletons, unclear field names, and missing documentation comments before they reach production.