Protobuf Well-Known Types (Timestamp, Duration, Any)

Google's Well-Known Types

Protocol Buffers ships with a set of commonly needed message types in the google.protobuf package. These types have special JSON encoding and language-level support.

syntax = "proto3";

import "google/protobuf/timestamp.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/any.proto";
import "google/protobuf/struct.proto";
import "google/protobuf/wrappers.proto";
import "google/protobuf/field_mask.proto";

message Event {
  string id = 1;
  string name = 2;

  // Timestamp: represents a point in time
  google.protobuf.Timestamp created_at = 3;
  google.protobuf.Timestamp updated_at = 4;

  // Duration: represents a span of time
  google.protobuf.Duration ttl = 5;

  // Wrappers: nullable scalar types
  google.protobuf.StringValue description = 6;
  google.protobuf.Int32Value priority = 7;
  google.protobuf.BoolValue is_public = 8;

  // Any: holds any serialized message
  google.protobuf.Any payload = 9;

  // Struct: dynamic JSON-like structure
  google.protobuf.Struct metadata = 10;

  // FieldMask: specifies which fields to update
  google.protobuf.FieldMask update_mask = 11;
}

Type Reference

Type	JSON mapping	Purpose
Timestamp	RFC 3339 string ("2024-01-15T10:30:00Z")	Points in time
Duration	Seconds string ("3.5s")	Time spans
Any	Object with @type field	Arbitrary message types
Struct	JSON object	Dynamic/schema-less data
Value	Any JSON value	Dynamic single values
FieldMask	Comma-separated paths ("name,email")	Partial updates
StringValue	String or null	Nullable string
Int32Value	Number or null	Nullable int32
BoolValue	Boolean or null	Nullable boolean

Wrapper Types

In proto3, scalar fields cannot distinguish between "not set" and "set to default value." Wrapper types solve this by wrapping scalars in messages, which have a distinct null state. Use google.protobuf.StringValue instead of string when you need to differentiate between an empty string and an absent value.

FieldMask for Partial Updates

The FieldMask type specifies which fields should be updated in a PATCH-style operation. The client sends a field mask alongside the update data, and the server only modifies the listed fields, leaving others unchanged.