Types

A reference for what a field can hold. Scalar types map directly to standard primitives in your programming language, well-known types cover common structures like timestamps, and every type has a defined JSON representation.

Numeric Types

int32 / int64

Signed integers with variable-length (varint) encoding. The default choice; when in doubt, int64 is the safe pick.

uint32 / uint64

Unsigned integers. Ideal for counts and sizes that can never be negative.

sint32 / sint64

Signed integers that use ZigZag encoding to keep small negative numbers compact. Use when values are frequently negative.

fixed32 / fixed64

Always 4/8 bytes. Beats a varint only for values consistently above 2²⁸ / 2⁵⁶, like hashes and large constants.

float / double

32-bit and 64-bit IEEE 754 floating point numbers.

Other Scalar Types

string

Always UTF-8 encoded text. Limited to 2GB.

bytes

Raw byte sequences for arbitrary binary data.

bool

Encoded as a varint 0 or 1.

enum

Predefined set of named integers. Defaults to 0.

Well-Known Types

Well-Known Types (WKTs) are schemas standardized by Google, with dedicated JSON mappings for clean integration with web APIs. Every WKT ships with every compiler, so you can import them without declaring a dependency. Full definitions are in the google.protobuf reference.

General

google.protobuf.Any

Holds an arbitrary serialized message plus a type URL identifying it, so payloads can vary at runtime.

google.protobuf.Timestamp

A point in time, independent of timezone. Maps to RFC 3339 in JSON.

google.protobuf.Duration

A span of time. Maps to a string ending in 's' in JSON (e.g. '1.5s').

google.protobuf.Empty

Used to indicate an API takes no parameters or returns nothing.

google.protobuf.FieldMask

A set of symbolic field paths specifying which fields a read or update should touch.

Dynamic JSON

google.protobuf.Struct

Maps directly to a free-form JSON object.

google.protobuf.Value

Represents a dynamically typed value, equivalent to any JSON type.

Like every well-known type, these are ordinary messages defined in plain .proto files you can read: struct.proto defines Struct and Value, and wrappers.proto defines the wrapper types, which are rarely needed now that optional provides explicit presence.

One more family of WKTs describes APIs and types themselves, powering runtime reflection and API tooling; they rarely appear in hand-written schemas. The most interesting are Method in api.proto, Type in type.proto, and SourceContext in source_context.proto.

ProtoJSON Mapping

While Protobuf is primarily binary, it defines a canonical ProtoJSON mapping. This ensures that every binary payload has a deterministic representation in JSON.

JSON mapping rules

Protobuf to JSON Type Mapping Rules
Protobuf Type	JSON Type(s)	JSON Value Example	Notes
`message`	JSONObject	Example`{"userName": "hiro"}`	Serialized as a JSON object. Field names are mapped to lowerCamelCase by default, or the json_name option if set.
`repeated`	JSONArray	Example`["a", "b"]`	Serialized as a JSON array.
`map<K, V>`	JSONObject	Example`{"k": "v"}`	Serialized as a JSON object.
`int32, uint32`	JSONNumber	Example`42`	Standard JSON numbers.
`float, double`	JSONNumber	Example`123.45`	Standard JSON numbers.
`bool`	JSONBoolean	Example`true`	Standard JSON booleans.
`int64, uint64`	JSONString	Example`"9007199254740993"`	Strings prevent precision loss in JS.
`enum`	JSONString	Example`"ROLE_ADMIN"`	Uses the string name of the enum value.
`bytes`	JSONString	Example`"NDI="`	Base64 encoded string.
`google.protobuf.Timestamp`	JSONString	Example`"2023-10-01T12:00:00Z"`	RFC 3339 formatted timestamp string.
`google.protobuf.Duration`	JSONString	Example`"1.000340012s"`	Seconds with up to 9 fractional digits.
`google.protobuf.FieldMask`	JSONString	Example`"f.a,f.b"`	Comma-separated paths as a single string.
`google.protobuf.Struct`	JSONObject	Example`{"foo": "bar"}`	Standard representation for a generic JSON object.
`google.protobuf.Value`	JSONAny	Example`"foo" or 123`	Can be any valid JSON value (null, number, string, boolean, struct, or list).
`google.protobuf.NullValue`	JSONnull	Example`null`	The JSON null value.
`google.protobuf.Empty`	JSONObject	Example`{}`	An empty JSON object.

64-bit Precision

JavaScript numbers are 64-bit floats, which lose precision for integers above 2⁵³ - 1.

To prevent data loss, 64-bit integer types (int64, fixed64, uint64, sint64, and sfixed64) are encoded as strings in JSON.

Basics

Advanced