Protocol Buffers v3

This chapter will discuss how to use Protocol Buffers with API design. To simplify developer experience and improve runtime efficiency, gRPC APIs should use Protocol Buffers version 3 (proto3) for API definition.

Protocol Buffers is a simple language-neutral and platform-neutral Interface Definition Language (IDL) for defining data structure schemas and programming interfaces. It supports both binary and text wire formats, and works with many different wire protocols on different platforms.

Proto3 is the latest version of Protocol Buffers and includes the following changes from proto2:

  • Field presence, also known as hasField, is removed by default for primitive fields. An unset primitive field has a language-defined default value.
    • Presence of a message field is still available, which can be tested using the compiler generated hasField method, or compare to null, or the sentinel value defined by the implementation.
    • Beginning in protobuf v3.14, primitive fields can distinguish between the default value and unset value by using the optional keyword, although this is generally discouraged.
  • User-defined default value for fields is no longer available.
  • Enum definitions must start with enum value zero.
  • Required fields are no longer available.
  • Extensions are no longer available. Use google.protobuf.Any instead.
    • Special exception is granted for google/protobuf/descriptor.proto for backward and runtime compatibility reasons.
  • Group syntax is removed.

The reason for removing these features is to make API designs simpler, more stable, and more performant. For example, it is often necessary to filter some fields before logging a message, such as removing sensitive information. This would not be possible if the fields are required.

See Protocol Buffers for more information.