0Pricing
gRPC & High Performance APIs · Lesson

Oneof, Maps & Well-Known Types

Model flexible and evolving data with protobuf oneof fields, maps, and the standard well-known types like Timestamp, Duration, and Any.

Oneof, Maps & Well-Known Types is a free gRPC & High Performance APIs lesson on CoddyKit — lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the gRPC & High Performance APIs learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Beyond Plain Scalar Fields

Real schemas need more than strings and ints: mutually exclusive choices, key/value collections, and standard date/time types. Protobuf provides oneof, maps, and well-known types.

The oneof Construct

A oneof groups fields where at most one can be set at a time. Setting one clears the others, and only the active field is sent on the wire.

message Contact {
  oneof method {
    string email = 1;
    string phone = 2;
  }
}

Reading a oneof

Generated code gives a way to check which case is set, usually a case enum or accessor, so you branch on the active field.

switch c.Method.(type) {
case *Contact_Email: useEmail(c.GetEmail())
case *Contact_Phone: usePhone(c.GetPhone())
}

Map Fields

A map stores key/value pairs. Keys must be scalar (string/int); values can be any type except another map.

message Config {
  map<string, string> settings = 1;
}

How Maps Work on the Wire

Maps are sugar over a repeated message of key/value entries. Order is not guaranteed, and duplicate keys keep the last value — important when evolving schemas.

Well-Known Types

Protobuf ships standard types in google/protobuf/:

  • Timestamp — a point in time
  • Duration — a length of time
  • Any — a packed arbitrary message
  • Struct — dynamic JSON-like data

Timestamp and Duration

Prefer these over raw int seconds for clarity and tooling support. They map to native time types in most languages.

import 'google/protobuf/timestamp.proto';
message Event {
  google.protobuf.Timestamp created_at = 1;
}

Using Any

Any wraps any message plus a type URL, letting you carry heterogeneous payloads. The rich error model and reflection both use it.

import 'google/protobuf/any.proto';
message Envelope {
  google.protobuf.Any payload = 1;
}

FieldMask for Partial Updates

FieldMask lists which fields a request touches, enabling partial updates (PATCH-style) without ambiguity over unset vs default values.

// paths: ['name', 'email']

Wrappers for Nullability

Proto3 scalars cannot distinguish unset from zero. Wrapper types like Int32Value and StringValue add explicit nullability when you need it.

Evolution Tips

When evolving these constructs:

  • Add new fields to a oneof safely; do not reuse tag numbers
  • Maps: avoid changing value type
  • Well-known types are stable; prefer them over hand-rolled equivalents

Quick Check

Test your advanced protobuf knowledge.

Recap

You learned advanced protobuf constructs:

  • oneof models mutually exclusive fields
  • map stores key/value pairs (sugar over repeated entries)
  • Well-known types: Timestamp, Duration, Any, Struct
  • FieldMask enables partial updates; wrappers add nullability
  • Evolve carefully without reusing tag numbers

Frequently asked questions

Is the “Oneof, Maps & Well-Known Types” lesson free?

Yes — the full text of “Oneof, Maps & Well-Known Types” is free to read here on the web, and the gRPC & High Performance APIs course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the gRPC & High Performance APIs course, upgrade to CoddyKit PRO.

What will I learn in “Oneof, Maps & Well-Known Types”?

Model flexible and evolving data with protobuf oneof fields, maps, and the standard well-known types like Timestamp, Duration, and Any. You practise gRPC & High Performance APIs with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start gRPC & High Performance APIs?

No prior experience is required. gRPC & High Performance APIs on CoddyKit is structured for beginners through advanced learners; this is — lesson 4 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Oneof, Maps & Well-Known Types” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this gRPC & High Performance APIs lesson?

Yes. Every gRPC & High Performance APIs lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

  1. Protobuf Best Practices
  2. Schema Evolution Strategies
  3. Custom Protobuf Options
  4. Oneof, Maps & Well-Known Types
← Back to gRPC & High Performance APIs