Type
Every `field` has an associated type (e.g., string, int32, bool). The Types reference lists every scalar and well-known type you can put here.
Because Protobuf is strictly typed, it catches many of the data type errors that would otherwise only show up at runtime with formats like JSON. Each target programming language has a mapping to/from each protobuf type.
Name
`Names` are used in your code for readability, and are ignored entirely in the binary encoding. They are, however, used in generated code and for the ProtoJSON serialization format. That means you can rename a field without breaking binary compatibility, though it may break JSON consumers and code using generated code.
Number
The `number` is the most critical part of the three, which may be a confusing statement for those unfamiliar. Instead of sending long string names (like "username") over the wire, Protobuf identifies each field by this integer ID. On the wire it is packed together with the field's wire type into a single value called the tag to save on space (the Binary section shows exactly how this is done). Because field numbers identify which field the data is for, you should never change them once a message type is in use. Reusing a number for a different field will cause data corruption.
Tip: Numbers 1 through 15 take 1 byte to encode (including the field number and wire type). Use 1-15 for your most frequently sent fields.
message User {
string username = 1;
}
{
"username": "hiro"
}Each case pairs a different schema with a message that fits it. Switch between them to see how the type and the number shape what lands on the wire.
Numbers 1 through 15 pack into a single tag byte; field 16 needs two. Open the Bytes tab and compare the two tags.
edition = "2024"; package demo.v1; message Metrics { int32 low_number = 1; int32 high_number = 16; }
Compiling the schema...
Further Reading
- Tip of the week #1: Field names are forever
Why renaming a field is safe on the wire but still a breaking change almost everywhere else.
- Tip of the week #9: Some numbers are more equal than others
How field numbers pack into tags, and why 1 through 15 are worth rationing.
Next
Enums
Defining enums in Protobuf: the required zero value, open enums, naming conventions, and how unknown enum values behave across versions.