A map field is shorthand for a repeated message of key/value pairs.
map<string, int32> items = 1;
message Entry { string key = 1; int32 value = 2; } repeated Entry items = 1;
On the wire, each entry is an ordinary length-delimited sub-message, with the key in field 1 and the value in field 2. A decoder written before maps existed still parses the data correctly, as a repeated field, so maps stay compatible with older Protobuf implementations.
This representation explains why entries carry no defined order, and why the last entry wins when the same key shows up twice in a payload. A repeated field would keep both entries; a map keeps one value per key.
Further Reading
- Maps in the language guide
The official maps documentation, including the backwards-compatibility note behind the repeated-entry representation on this page.
Next
Presence
Why unset and default-valued Protobuf fields take zero bytes on the wire, and how that interacts with field presence semantics when decoding.