Working with Well-Known Types

1. Using Timestamp Type

Example: Timestamp in a message

import "google/protobuf/timestamp.proto";
message Event {
  string id = 1;
  google.protobuf.Timestamp occurred_at = 2;
}
PropertyDetail
Fieldsseconds (int64) + nanos (int32)
Range0001-01-01 to 9999-12-31 (UTC)
JSONRFC 3339 string e.g. "2026-05-18T10:00:00Z"
Go helpertimestamppb.Now() / .AsTime()

2. Using Duration Type

PropertyDetail
Importgoogle/protobuf/duration.proto
Fieldsseconds + nanos (signed)
JSON"3.5s"
Go helperdurationpb.New(time.Second)

3. Using Any Type

Example: Packing/unpacking Any

import "google.golang.org/protobuf/types/known/anypb"

a, _ := anypb.New(&User{Id: "u1"})
var u User
_ = a.UnmarshalTo(&u)
FieldPurpose
type_urlFully-qualified type URL (type.googleapis.com/pkg.Name)
valueSerialized message bytes

4. Using Struct Type

FieldDetail
fieldsmap<string, Value> — arbitrary JSON-like data
Use caseSchema-less payload, dynamic config
JSONNative JSON object

5. Using Empty Type

Example: RPC with no input or output

import "google/protobuf/empty.proto";
service Health {
  rpc Ping(google.protobuf.Empty) returns (google.protobuf.Empty);
}
NoteDetail
Future-proof altUse a dedicated PingRequest{} so you can add fields later

6. Using FieldMask Type

Example: Partial update with FieldMask

import "google/protobuf/field_mask.proto";
message UpdateUserRequest {
  User user = 1;
  google.protobuf.FieldMask update_mask = 2;   // e.g. paths="email,profile.name"
}
FieldPurpose
pathsList of field paths to update
ConventionUpdate only listed paths; ignore others

7. Using Wrapper Types

WrapperWrapsPurpose
StringValue / BytesValuestring / bytesPresence tracking
Int32/64Value, UInt32/64ValueintegersDistinguish 0 from unset
FloatValue / DoubleValuefloat / doubleDistinguish 0.0 from unset
BoolValueboolDistinguish false from unset
Note: Prefer optional over wrappers in proto3 — wrappers exist for legacy and JSON interop.

8. Importing Well-Known Types

Import PathProvides
google/protobuf/timestamp.protoTimestamp
google/protobuf/duration.protoDuration
google/protobuf/any.protoAny
google/protobuf/struct.protoStruct, Value, ListValue
google/protobuf/empty.protoEmpty
google/protobuf/field_mask.protoFieldMask
google/protobuf/wrappers.proto*Value wrappers

9. Converting Between Native and Proto Types

Native (Go)ProtoConversion
time.TimeTimestamptimestamppb.New(t) / ts.AsTime()
time.DurationDurationdurationpb.New(d) / d.AsDuration()
map[string]anyStructstructpb.NewStruct(m)

10. Using Value Type

Variant (oneof)Maps To
null_valuenull
number_valuedouble
string_valuestring
bool_valuebool
struct_valueStruct
list_valueListValue