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

Protobuf Any, Oneof and Well-Known Types

On this page
  1. Modeling choices in protobuf
  2. oneof: exactly one of several fields
  3. google.protobuf.Any: a message of any type
  4. Well-known types: Timestamp, Duration, wrappers, FieldMask
  5. Protobuf JSON mapping rules to know
  6. Check yourself

Modeling choices in protobuf

A payment is made by card or bank transfer, never both. An event log carries events of many types. A timestamp needs a standard representation. Protobuf has tools for each.

oneof: exactly one of several fields

Protobuf
message PaymentEvent {
  string payment_id = 1;
  google.protobuf.Timestamp occurred_at = 2;
  google.protobuf.Duration processing_time = 3;
  google.protobuf.Int32Value retries = 4;   // distinguishes "0 retries" from "not reported"
  oneof method {
    Card card = 10;
    BankTransfer bank_transfer = 11;
  }
}

At most one member of method is set; setting another clears the first. Generated code lets you switch on which one is present. protoc's text parser refuses to set both:

Code
Field "bank_transfer" is specified along with field "card", another member of oneof "method".

On the wire, though, the rule is "last one wins". Concatenating an encoded message containing card with one containing bank_transfer (protobuf merges concatenated messages, Day 11) decodes as:

Code
payment_id: "pay_1"
bank_transfer {
  iban_suffix: "3000"
}

The card was silently replaced. Don't rely on merge behavior with oneofs, and never move existing fields into or out of a oneof (Day 12).

oneof holds at most one member, Any wraps a message with its type URL, and well-known types give standard encodings for time, durations, nullable values and field masks.
oneof holds at most one member, Any wraps a message with its type URL, and well-known types give standard encodings for time, durations, nullable values and field masks.

google.protobuf.Any: a message of any type

google.protobuf.Any holds serialized bytes plus a type URL naming the message type. In JSON:

JSON
{"@type":"type.googleapis.com/shop.v1.GetOrderRequest", "orderId":"ord_42"}

The receiver checks the type and unpacks it (anypb.UnmarshalTo in Go). gRPC's own error details use Any (Day 14). Elsewhere, prefer a oneof of known types: it's typed, self-documenting and validated at compile time. Use Any only when the set of types is unknown in advance, such as plugin payloads. A simple way to choose: oneof is a form with a fixed set of checkboxes, pick exactly one; Any is a sealed envelope with a label on the front saying what's inside, which the receiver has to read before opening it.

Well-known types: Timestamp, Duration, wrappers, FieldMask

Import them from google/protobuf/ instead of inventing your own. Their JSON forms, produced by Go's protojson:

Code
Timestamp    "2026-10-11T14:30:00Z"
Duration     "1.500s"
Int32Value   0
FieldMask    "displayName,address.city"
  • Timestamp: a point in time (seconds and nanoseconds since the epoch, always UTC), RFC 3339 in JSON.
  • Duration: a span of time.
  • Wrappers (Int32Value, StringValue, BoolValue...): nullable scalars. Int32Value of 0 is serialized as 0, distinct from an absent field. Proto3 optional (Day 3) is now usually preferred for this.
  • FieldMask: which fields an update touches, for partial updates: UpdateUserRequest { User user = 1; google.protobuf.FieldMask update_mask = 2; }.
  • Struct / Value: arbitrary JSON-like data, for when the shape really is dynamic.
  • Empty: no fields; but prefer your own empty request and response messages so you can add fields later (Day 2).

Protobuf JSON mapping rules to know

From the same run:

Code
int64 field  {"id":"ord_42", "totalCents":"4999"}
defaults     {"status":"STATUS_UNSPECIFIED", "at":null}      (with EmitUnpopulated)

64-bit integers become strings, names become lowerCamelCase, enums become names, and default values are omitted unless you ask for them.

Check yourself

The last one wins: setting a oneof member clears the others, so the earlier member is silently dropped. Merging partial updates can therefore lose data unexpectedly.

When the set of possible types is open-ended and can't be listed in the schema; otherwise oneof is typed and clearer.

It says exactly which fields to change. Without it, an unset field is indistinguishable from "clear this value", so a partial update could wipe fields the client didn't mean to touch.

It's unambiguous about units and epoch, maps to native date types in generated code, and serializes to RFC 3339 strings in JSON.

A typed length of time with seconds and nanoseconds, avoiding confusion over whether a plain number means milliseconds or seconds. Generated code maps it to native types like Go's time.Duration, and JSON shows it as "1.5s".