What Problem Does oneof Solve?
A oneof groups several fields of any type such that at most one of them can be set at a time; setting any member automatically clears whichever other member was previously set. This models a tagged union (also called a sum type or discriminated union) rather than a plain struct, which is exactly the right shape for data like 'a payment method that is either a credit card OR a bank transfer OR a wallet ID, never more than one at once.'
Cricket analogy: A match result field that's either WIN, LOSS, TIE, or NO_RESULT can never be two of those simultaneously, exactly the mutual exclusivity a oneof enforces between its member fields.
Wire Format, Presence, and Generated Code
On the wire, a oneof is not a distinct encoding, each member field is encoded exactly as it would be outside a oneof; the union behavior is purely a client-side/generated-code discipline enforced by the runtime library, which tracks which case is currently active and clears the others in the setter. Because of this, all oneof member fields effectively get explicit presence tracking even in proto3 (unlike ordinary singular scalar fields), so checking 'which oneof case is set' also tells you whether a scalar member like an int32 was explicitly sent, even if its value happens to be zero.
Cricket analogy: The umpire's signal (four, six, wide, no-ball) is communicated the same physical way, a hand gesture, regardless of which one is chosen, similar to how a oneof member is wire-encoded normally, with the 'which one' logic living in the runtime, not the bytes.
syntax = "proto3";
message PaymentMethod {
string customer_id = 1;
oneof method {
CreditCard credit_card = 2;
BankTransfer bank_transfer = 3;
string wallet_id = 4;
}
}
message CreditCard {
string number_last4 = 1;
string expiry = 2;
}
message BankTransfer {
string iban = 1;
string bic = 2;
}Generated code exposes a case accessor, e.g. Go's GetMethod().(type) switch, Java's getMethodCase(), or C++'s method_case(), that tells you which oneof member (if any) is currently set, functioning as a lightweight discriminant without you needing a separate enum tag field.
You cannot use the repeated keyword on a field inside a oneof; if you need a mutually-exclusive choice between multiple repeated lists, wrap each list in its own single message type and put those messages inside the oneof instead.
oneof vs Optional Fields
A single-member oneof is actually how proto3's optional keyword is implemented under the hood, the compiler synthesizes a hidden one-field oneof for every optional scalar field, which is why explicit presence tracking becomes available for that field. This means you rarely need to hand-roll a oneof just to get presence-detection on a single field; reach for oneof explicitly when you have two or more genuinely mutually-exclusive alternatives, and use optional when you simply need presence tracking on one field.
Cricket analogy: A DRS review outcome being tracked as 'reviewed: yes/no' plus a separate result is really just a lightweight single-choice flag, similar to how proto3's optional is secretly a one-member oneof under the hood.
- oneof groups fields so that at most one member can be set; setting one clears any previously set member.
- Wire encoding of a oneof member is identical to a normal field; exclusivity is enforced entirely by generated code, not the wire format.
- oneof members effectively gain explicit presence tracking, letting you distinguish 'unset' from 'set to the type's zero value'.
- repeated fields cannot be placed directly inside a oneof; wrap them in a message type instead.
- proto3's optional keyword is implemented as a synthesized single-member oneof under the hood.
- Use oneof for genuine multi-way mutually exclusive alternatives; use optional for simple single-field presence tracking.
- Adding/removing/reordering oneof membership after deployment should be treated as a breaking API change.
Practice what you learned
1. What happens when you set a second field inside a oneof after already setting a different member?
2. How is a oneof member field encoded differently from a normal field on the wire?
3. Which of these is NOT allowed inside a oneof declaration?
4. How is proto3's optional keyword implemented under the hood by protoc?
5. Why do oneof member fields get explicit presence tracking even in proto3?
Was this page helpful?
You May Also Like
Protobuf Data Types
A tour of Protocol Buffers' scalar, composite, and byte-oriented field types, and how each is encoded on the wire.
Nested Messages and Enums
How to model hierarchical data and closed sets of values in Protocol Buffers using nested message types and enums.
Well-Known Types in Protobuf
The standard library of reusable protobuf message types, like Timestamp, Duration, Any, and wrapper types, and when to use them.
Related Reading
Related Study Notes in Web Development
Browse all study notesWebSockets Study Notes
Web Development · 30 topics
Web DevelopmentWebAssembly Study Notes
WebAssembly · 30 topics
Web DevelopmentSpring Boot Study Notes
Java · 30 topics
Web DevelopmentFlask Study Notes
Python · 30 topics
Web DevelopmentDjango Study Notes
Python · 30 topics
Web DevelopmentNext.js Study Notes
JavaScript · 30 topics