Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 39 ยท Protobuf Language

Protobuf Messages and Scalar Types

Learn how to define protobuf messages, the scalar types (int32, sint64, string, bytes and more), default values, and how they map to Go, Java and Python types.

A message is the basic unit of data in Protocol Buffers: a named group of typed fields, similar to a struct or a class with only data. Everything that goes in or out of a gRPC call is a message. In this lesson you will learn the syntax of messages, every scalar type, how defaults work in proto3, and how the types map to real programming languages.

The real compiler cannot run on this site, so .proto snippets are read-only. The Go programs are stand-ins that model protobuf behavior with ordinary structs. Run them to see the effects.

A first message

PROTO
syntax = "proto3";

package shop.v1;

message Product {
  int64  id          = 1;
  string name        = 2;
  double price       = 3;
  bool   in_stock    = 4;
  bytes  thumbnail   = 5;
}

Reading it line by line:

  • syntax = "proto3"; must come first. Without it the compiler assumes the old proto2 and prints a warning. (Newer "editions" exist, but proto3 is still the common starting point.)
  • package prevents name clashes between different .proto files. See packages, imports and options.
  • Each field has a type, a name and a unique field number. Field numbers matter more than names on the wire; see field numbers and the wire format.
  • Field names are written in snake_case. Generators convert them to the style of each language (inStock in Java, InStock in Go).

The scalar types

Whole numbers

int32 / int64 Varint, poor for negatives
sint32 / sint64 ZigZag, good for negatives
uint32 / uint64 Unsigned varint
fixed32 / fixed64 Always 4 or 8 bytes
1 / 2
Proto type Go Java Python Notes
double float64 double float 64-bit IEEE 754
float float32 float float 32-bit IEEE 754
int32 int32 int int Negative values take 10 bytes; prefer sint32 if often negative
int64 int64 long int Same caveat
uint32, uint64 uint32, uint64 int, long int Unsigned varint
sint32, sint64 int32, int64 int, long int ZigZag encoding for negatives
fixed32, fixed64 uint32, uint64 int, long int Fixed width, faster for huge values
sfixed32, sfixed64 int32, int64 int, long int Signed fixed width
bool bool boolean bool
string string String str Must be UTF-8 and under 2 GB
bytes []byte ByteString bytes Any binary data

How to choose a number type:

  1. Most numbers: int32 or int64.
  2. Values that are often negative: sint32 or sint64.
  3. Values that are never negative: uint32 or uint64.
  4. Values that are usually huge (hashes, ids from a random 64-bit space): fixed64.
  5. Money: do not use double. Use an int64 of the smallest unit (cents) or a message with units and nanos, as in the Google Money type.

Default values

In proto3, a field you never set reads as its type's zero value:

  • numbers: 0
  • bool: false
  • string: ""
  • bytes: empty
  • enums: the first value, which must be 0
  • message fields: unset (nil in Go, null or a default instance in other languages)

Important consequence: for plain scalar fields, the zero value is not sent on the wire, and the receiver cannot tell "set to 0" from "never set". The next lesson shows how optional and wrapper types solve this: oneof, optional and well-known types.

Stand-in 1: zero values hide "not set"

This stand-in models a proto3 message with a plain Go struct. Both requests below look identical to the receiver, even though the sender meant different things.

Go Stand-in: proto3 zero values

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

If the first request means "sold out" and the second means "leave the stock alone", a plain int32 cannot express the difference. Real protobuf offers optional int32 stock, which tracks presence.

Stand-in 2: how zero values are skipped

This stand-in writes a message the way protobuf does: only non-default fields appear. The format is simplified (field number and a decimal value), but the skipping rule is the real one.

Go Stand-in: skipping defaults

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

An empty message encodes to zero bytes. That is perfectly valid: a request like GetStatus that needs no input can use an empty message (often google.protobuf.Empty).

Strings and bytes

  • string must contain valid UTF-8. Libraries reject or replace invalid data, so use bytes for arbitrary binary content (images, encrypted blobs, hashes).
  • There is no built-in limit shorter than 2 GB, but gRPC limits a single message to 4 MB by default on the receiving side. Large files belong in a stream of chunks, not one giant message.

Naming rules and style

  • Message names: UpperCamelCase, such as CreateOrderRequest.
  • Field names: lower_snake_case, such as created_at.
  • Do not start a field name with a digit, and avoid names that clash with keywords in your target language where you can.
  • Name request and response messages after the method: GetBookRequest and GetBookResponse. Even when a method takes one id, a dedicated request message lets you add fields later without breaking callers.

Reserved and unknown fields

If a receiver sees a field number it does not know (because the sender is newer), it keeps the field as an unknown field instead of failing. This is the foundation of safe evolution and is explored in field numbers.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does a proto3 int32 field read as when it was never set?

    Scalars have zero defaults: 0, false, empty string, empty bytes.
  2. 2. Which type is best for a number that is frequently negative?

    sint32 uses ZigZag encoding, so small negatives stay small. A negative int32 always uses 10 bytes.
  3. 3. Which type should hold arbitrary binary data such as an image?

    string must be valid UTF-8; bytes is for anything else.
  4. 4. Why use a dedicated GetBookRequest message even for a single id?

    RPC methods take a message. Wrapping inputs lets the contract grow safely.
  5. 5. Why is a plain scalar zero value a problem for partial updates?

    Default values are not transmitted, so presence is lost unless you use optional or wrappers.

Summary

  • A message is a set of typed, numbered fields.
  • Scalar types: integers (variable, zigzag, fixed), floats, bool, string, bytes.
  • Unset scalars read as zero values and are not sent on the wire.
  • Choose sint* for negatives, fixed* for huge values, and never use floating point for money.
  • Give every RPC its own request and response messages.

Next: Field Numbers and the Wire Format