Protocol Buffer Types

Internal

• Protocol Buffer Concepts

String

string some_string = 1;

The default value is empty string (""). The field contains UTF-8 encoded or 7-bit ASCII text.

Boolean

bool some_bool = 1;

The default value is false.

Scalar Number Types

int32, sint32

Signed integers on 32 bits (4 bytes).

int32 some_int = 1;

The default value is 0.

It allows to represent -2,147,483,648 to 2,147,483,647.

int32 does not encode negative values efficiently. sint32 does.

uint32

uint32 allows to represent 0 to 4,294,967,295.

int64, sint64

Signed integers on 64 bits (8 bytes).

int64 some_int = 1;

The default value is 0.

It allows to represent -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807.

int64 does not encode negative values efficiently, sint64 does.

Bytes

bytes some_bytes = 1;

The default value is the empty byte array.

List (Array)

Use pluralized names for repeated fields.

repeated <some_other_type> <field_name> = <tag>;

Example:

repeated int32 sizes = 1;
repeated string names = 1;

The default value is the empty list.

map

message SomeMessage {
  int32 id = 1;
  map<string, Result> results = 2;
}

The keys can be scalars (except float/double) to values of any type.

Map fields cannot be repeated.

The order is undefined.

enum

The enum must start with the tag 0. The default value is the first value and it is a good practice to use that value with an "UNSPECIFIED" semantics, as shown below.

enums can be defined at the top level of a .proto file or they can be embedded.

Use PascalCase (with an initial capital) for enum type names and CAPITALS_WITH_UNDERSCORES for value names. Each enum value should end with a semicolon, not a comma. Prefer prefixing enum values instead of surrounding them in an enclosing message. Since some languages don’t support an enum being defined inside a “struct” type, this ensures a consistent approach across binding languages. The zero value enum should have the suffix UNSPECIFIED, because a server or application that gets an unexpected enum value will mark the field as unset in the proto instance. The field accessor will then return the default value, which for enum fields is the first enum value.

enum FooBar {
  FOO_BAR_UNSPECIFIED = 0;
  FOO_BAR_FIRST_VALUE = 1;
  FOO_BAR_SECOND_VALUE = 2;
}
message Something {
    FooBar foo_bar = 1;
}

To see what Go code is generated for an enum, go to:

Protocol Buffers Go Code Generation | enums

oneof

message SomeMessage {
  int32 id = 1;
  oneof something {
    string some_string = 2;
    int32 some_int = 3;
  }
}

oneof fields cannot be repeated with repeated.

oneof fields are complicated to evolve.

Well-Known Types

https://protobuf.dev/reference/protobuf/google.protobuf/

Protocol Buffers contains a set of Well Known Types, in the google.protobuf package.

Understand this better, and what and when to use.

Duration

https://protobuf.dev/reference/protobuf/google.protobuf/#duration

TODO

Timestamp

https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp

TODO

Other Common Types

Google Common Types

https://github.com/googleapis/googleapis/tree/master/google/type

date

https://github.com/googleapis/googleapis/blob/master/google/type/date.proto

dayofweek

https://github.com/googleapis/googleapis/blob/master/google/type/dayofweek.proto

money

https://github.com/googleapis/googleapis/blob/master/google/type/money.proto