Why does protobuf's FieldMask use field names instead of field numbers?

Question

In the docs for FieldMask the paths use the field names (e.g., foo.bar.buzz), which means renaming the message field names can result in a breaking change.

Why doesn't FieldMask use the field numbers to define the path?

Something like 1.3.1?

Answer 1

You may want to consider filing an issue on the GitHub protocolbuffers repo for a definitive answer from the code's authors.

Your proposal seems logical. Using names may be a historical artifact. There's a possibly relevant comment on an issue thread in that repo:

https://github.com/protocolbuffers/protobuf/issues/3793#issuecomment-339734117

"You are right that if you use FieldMasks then you can't safely rename fields. But for that matter, if you use the JSON format or text format then you have the same issue that field names are significant and can't be changed easily. Changing field names really only works if you use the binary format only and avoid FieldMasks."

Answer 2

The answer for your question lies in the fact FieldMasks are a convention/utility developed on top of the proto3 schema definition language, and not a feature of it (and that utility is not present in all of the language bindings)

While you’re right in your observation that it can break easily (as schemas tend evolve and change), you need to consider this design choice from a user friendliness POV:

If you’re building an API and want to allow the user to select the field set present inside the response payload (the common use case for field masks), it’ll be much more convenient for you to allow that using field paths, rather then binary fields indices, as the latter would force the user of the gRPC/protocol generated code to be “aware” of the schema. That’s not always the desired case when providing API as a code software packages.

While implementing this as a proto schema feature can allow the user to have the best of both worlds (specify field paths, have them encoded as binary indices) for binary encoding, it would also:

• Complicate code generation requirements
• Still be an issue for plain text encoding.

So, you can understand why it was left as an “external utility”.