Types

Every field in a schema needs a type. This reference lists the types available. Scalar types map directly to primitives your language already has. Well-known types cover common structures like timestamps. Every type, scalar or well-known, gets a defined JSON representation too, covered in the ProtoJSON mapping below.

Language mappings follow the generated code of each official runtime, with TypeScript from Protobuf-ES and Python from protobuf-py.

Non-Numeric Types

string

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

Language	Type	Literal
Go	string	"hi"
TypeScript	string	"hi"
Java	String	"hi"
Python	str	"hi"
C++	std::string	"hi"
ProtoJSON	string	"hi"

bytes

Raw bytes, no encoding assumed.

Language	Type	Literal
Go	[]byte	[]byte("hi")
TypeScript	Uint8Array	new Uint8Array([104, 105])
Java	ByteString	ByteString.copyFromUtf8("hi")
Python	bytes	b"hi"
C++	std::string	std::string("hi")
ProtoJSON	base64 string	"aGk="

bool

Encoded as a varint 0 or 1.

Language	Type	Literal
Go	bool	true
TypeScript	boolean	true
Java	boolean	true
Python	bool	True
C++	bool	true
ProtoJSON	true / false	true

enum

Predefined set of named integers. Defaults to 0.

Language	Type	Literal
Go	named int32	pb.Status_ACTIVE
TypeScript	enum	Status.ACTIVE
Java	enum	Status.ACTIVE
Python	IntEnum	Status.ACTIVE
C++	enum	ACTIVE
ProtoJSON	string (the value name)	"ACTIVE"

Numeric Types

int32

Signed 32-bit integer with variable-length (varint) encoding. Negative values always take 10 bytes, so prefer sint32 when they are common.

Language	Type	Literal
Go	int32	42
TypeScript	number	42
Java	int	42
Python	int	42
C++	int32_t	42
ProtoJSON	number	42

int64

Signed 64-bit integer with varint encoding. Use it for whole numbers unless you have a reason to pick another type.

Language	Type	Literal
Go	int64	42
TypeScript	bigint	42n
Java	long	42L
Python	int	42
C++	int64_t	42
ProtoJSON	string	"42"

uint32

Unsigned 32-bit integer with varint encoding. Ideal for counts and sizes that can never be negative.

Language	Type	Literal
Go	uint32	42
TypeScript	number	42
Java	int	42
Python	int	42
C++	uint32_t	42
ProtoJSON	number	42

uint64

Unsigned 64-bit integer with varint encoding. Ideal for large counts, sizes, and identifiers.

Language	Type	Literal
Go	uint64	42
TypeScript	bigint	42n
Java	long	42L
Python	int	42
C++	uint64_t	42
ProtoJSON	string	"42"

sint32

Signed 32-bit integer that uses ZigZag encoding to keep small negative numbers compact.

Language	Type	Literal
Go	int32	42
TypeScript	number	42
Java	int	42
Python	int	42
C++	int32_t	42
ProtoJSON	number	42

sint64

Signed 64-bit integer with ZigZag encoding. Use when values are frequently negative.

Language	Type	Literal
Go	int64	42
TypeScript	bigint	42n
Java	long	42L
Python	int	42
C++	int64_t	42
ProtoJSON	string	"42"

fixed32

Always 4 bytes, unsigned. Beats a varint only for values consistently above 2²⁸, like hashes.

Language	Type	Literal
Go	uint32	42
TypeScript	number	42
Java	int	42
Python	int	42
C++	uint32_t	42
ProtoJSON	number	42

fixed64

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

Language	Type	Literal
Go	uint64	42
TypeScript	bigint	42n
Java	long	42L
Python	int	42
C++	uint64_t	42
ProtoJSON	string	"42"

sfixed32

Always 4 bytes, signed. The fixed-width counterpart of int32.

Language	Type	Literal
Go	int32	42
TypeScript	number	42
Java	int	42
Python	int	42
C++	int32_t	42
ProtoJSON	number	42

sfixed64

Always 8 bytes, signed. The fixed-width counterpart of int64.

Language	Type	Literal
Go	int64	42
TypeScript	bigint	42n
Java	long	42L
Python	int	42
C++	int64_t	42
ProtoJSON	string	"42"

float

32-bit IEEE 754 floating point number.

Language	Type	Literal
Go	float32	3.14
TypeScript	number	3.14
Java	float	3.14f
Python	float	3.14
C++	float	3.14f
ProtoJSON	number, or "NaN" / "Infinity"	3.14

double

64-bit IEEE 754 floating point number.

Language	Type	Literal
Go	float64	3.14
TypeScript	number	3.14
Java	double	3.14
Python	float	3.14
C++	double	3.14
ProtoJSON	number, or "NaN" / "Infinity"	3.14

Well-Known Types

Every compiler ships a set of schemas already written for you, called well-known types, or WKTs for short. Google standardizes them, so you import google.protobuf.Timestamp or any other one without declaring a dependency yourself. Each WKT also gets its own JSON mapping, so a Timestamp, for example, appears in JSON as an RFC 3339 string. Full definitions are in the google.protobuf reference.

General

google.protobuf.Any

Holds an arbitrary serialized message and a type URL that identifies it. The payload can vary at runtime.

Language	Type	Literal
Go	*anypb.Any	anypb.New(msg)
TypeScript	Any	anyPack(UserSchema, user)
Java	com.google.protobuf.Any	Any.pack(msg)
Python	protobuf.wkt.Any	Any.pack(msg)
C++	google::protobuf::Any	any.PackFrom(msg)
ProtoJSON	object with "@type"	{"@type": "...", ...}

google.protobuf.Timestamp

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

Language	Type	Literal
Go	*timestamppb.Timestamp	timestamppb.Now()
TypeScript	Timestamp	timestampNow()
Java	com.google.protobuf.Timestamp	Timestamps.fromMillis(ms)
Python	protobuf.wkt.Timestamp	Timestamp.now()
C++	google::protobuf::Timestamp	TimeUtil::GetCurrentTime()
ProtoJSON	RFC 3339 string	"2026-01-15T10:00:00Z"

google.protobuf.Duration

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

Language	Type	Literal
Go	*durationpb.Duration	durationpb.New(30 * time.Second)
TypeScript	Duration	create(DurationSchema, { seconds: 30n })
Java	com.google.protobuf.Duration	Durations.fromSeconds(30)
Python	protobuf.wkt.Duration	Duration.from_seconds(30)
C++	google::protobuf::Duration	TimeUtil::SecondsToDuration(30)
ProtoJSON	string ending in "s"	"30s"

google.protobuf.Empty

Marks an API that takes no parameters, or returns nothing.

Language	Type	Literal
Go	*emptypb.Empty	&emptypb.Empty{}
TypeScript	Empty	create(EmptySchema)
Java	com.google.protobuf.Empty	Empty.getDefaultInstance()
Python	protobuf.wkt.Empty	Empty()
C++	google::protobuf::Empty	Empty()
ProtoJSON	{}	{}

google.protobuf.FieldMask

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

Language	Type	Literal
Go	*fieldmaskpb.FieldMask	fieldmaskpb.New(msg, "name")
TypeScript	FieldMask	create(FieldMaskSchema, { paths: ["name"] })
Java	com.google.protobuf.FieldMask	FieldMaskUtil.fromString("name")
Python	protobuf.wkt.FieldMask	FieldMask(paths=["name"])
C++	google::protobuf::FieldMask	FieldMaskUtil::FromString("name", &mask)
ProtoJSON	comma-separated string	"name"

Dynamic JSON

google.protobuf.Struct

Maps directly to a free-form JSON object.

Language	Type	Literal
Go	*structpb.Struct	structpb.NewStruct(m)
TypeScript	Struct	fromJson(StructSchema, { k: "v" })
Java	com.google.protobuf.Struct	Struct.newBuilder().putFields(…)
Python	protobuf.wkt.Struct	Struct.from_python({"k": "v"})
C++	google::protobuf::Struct	(*s.mutable_fields())["k"]
ProtoJSON	object	{"k": "v"}

google.protobuf.Value

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

Language	Type	Literal
Go	*structpb.Value	structpb.NewStringValue("x")
TypeScript	Value	fromJson(ValueSchema, "x")
Java	com.google.protobuf.Value	Values.of("x")
Python	protobuf.wkt.Value	Value.from_python("x")
C++	google::protobuf::Value	v.set_string_value("x")
ProtoJSON	any JSON value	"x"

Like every well-known type, these are ordinary messages, defined in plain .proto files. struct.proto defines Struct and Value. wrappers.proto defines the wrapper types, though you rarely need those now that scalar fields track presence by default.

One more family of WKTs describes APIs and types themselves. They power runtime reflection and API tooling, and application code seldom uses them directly. The main ones are Method in api.proto, Type in type.proto, and SourceContext in source_context.proto.

JSON shows RFC 3339 and a seconds string; the bytes are just seconds and nanos fields encoded as varints.

schema.proto

edition = "2024";

package demo.v1;

import "google/protobuf/timestamp.proto";
import "google/protobuf/duration.proto";

message Job {
  google.protobuf.Timestamp scheduled_at = 1;
  google.protobuf.Duration timeout = 2;
}

Input JSON (editable)

{
  "scheduledAt": "2026-01-15T10:00:00Z",
  "timeout": "30s"
}

ProtoJSON

Compiling the schema...

ProtoJSON Mapping

Protobuf's wire format is binary, but it also defines a standard ProtoJSON mapping: the rules for how each type appears in JSON, so JSON written by one library can be read by any other. It does not pin down the exact output. Whitespace, field order, and serializer options can differ between libraries and versions, so don't hash, sign, or byte-compare ProtoJSON.

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

Every number in JavaScript is a 64-bit float, which can only represent integers exactly up to 2⁵³ - 1. Past that, values get rounded. Parsing 9007199254740993 as a JSON number rounds it to 9007199254740992.

That is why 64-bit integer types (int64, fixed64, uint64, sint64, and sfixed64) are encoded as strings in JSON, not numbers.

64-bit values are strings in JSON so JavaScript's floats can't corrupt them. The canonical output keeps the quotes.