How do you evolve a Protocol Buffers message without breaking old clients?

Protobuf's binary wire format is designed so many schema changes are backward- and forward-compatible when field numbers are treated as immutable identifiers. The proto3 language guide splits changes into wire-safe, wire-unsafe, and conditionally compatible.

Binary wire-safe:

• Adding new fields is safe. Old binaries ignore unknown fields; new binaries see default values when old senders omit the field. Proto3 preserves unknown fields and writes them back out.
• Removing a field is safe if its number is never reused. Reserve the deleted number, and preferably the name, for JSON and text formats:

message Foo {
  reserved 2, 15, 9 to 11;
  reserved "foo", "bar";
}

• Adding values to an enum is safe, with the usual caution that exhaustive switches in application code may need updating.

Not safe: changing a field's number; reusing a deleted number; moving fields into an existing oneof. Reusing a number makes decoding ambiguous and can corrupt data, because the wire format has no way to tell that the definition changed.

Conditionally compatible means the same bytes may parse before and after the change, but the change can be lossy. Examples include widening int32 to int64 if a value later exceeds what the old type can hold; string and bytes when the bytes are valid UTF-8; and enum with integer types. These need a carefully managed rollout, and they are a poor idea if you cannot control every reader and writer.

JSON encoding of protobuf has a narrower set of safe changes than the binary wire format. The official guide treats the binary format as the preferred form for compatibility-sensitive interchange.

Alternate interview scenarios