Guide
Formatting .proto files and catching field-number mistakes
Protocol Buffers describe messages for gRPC services, event streams and storage formats in .proto files. The format is forgiving about layout, so files from different authors drift into different styles, and it is unforgiving about field numbers, where a single reused number can corrupt data between versions. This tool reformats a .proto file and checks the numbering and naming rules.
Field numbers are the contract
On the wire, a message does not contain field names, only each field’s number and wire type followed by the value. That makes protobuf compact and lets old and new code interoperate, but it means the numbers are the real interface. Changing a field’s number, or giving a removed field’s number to a new field, makes old clients read data as the wrong field. The checker therefore treats numbering mistakes as errors.
Rules protoc enforces
Field numbers must be between 1 and 536,870,911, and the range 19000 to 19999 is reserved for the protobuf implementation itself. A number may be used only once per message, and so may a name. Fields inside a oneof share the numbering of the enclosing message. In proto3, the first value of every enum must be 0, because 0 is the default when a value is missing. The checker reports each of these with its line number.
Reserved numbers and names
When you delete a field, mark its number and name as reserved, for example reserved 5, 9 to 11; and reserved "coupon";. protoc then refuses any new field that reuses them. The checker reads reserved lists, including ranges ending in max, and flags fields that collide with them.
Style guide checks
The Protocol Buffers style guide asks for PascalCase message names, lower_snake_case field names and UPPER_SNAKE_CASE enum values, and these are reported as warnings. A further warning notes fields numbered above 15 while lower numbers are still free: numbers 1 to 15 encode their tag in one byte and 16 to 2047 in two, so frequently set fields should get the small numbers. A file without a syntax or edition line is compiled as proto2 by protoc, so that is flagged too.
Formatting
The formatter re-indents every block, messages, nested messages, enums, oneofs and services, with two spaces per level as in Google’s style, or four if you prefer. It normalises the spaces around =, puts a single space before opening braces and collapses runs of blank lines, while leaving comments and the order of declarations alone.
A worked example
The Sample shop.v1 schema reformats so that message Order { is followed by string id = 1;. It reports four errors: number 2 is already used on line 6 in Order (by the labels map), number 9 is reserved, 19001 is inside the implementation range, and the enum’s first value must be 0 in proto3. Three warnings cover the field Note, which should be lower_snake_case, the enum value shipped, which should be upper case, and the placed_at field numbered 19001 while low numbers are still free.
What a single file cannot show
The checker reads one file and does not resolve imports, so it cannot tell whether google.protobuf.Timestamp or other message types exist, whether a change breaks compatibility with the previous version, or how extensions are numbered. For those, run protoc or buf lint and buf breaking in CI.
Related tools
- GraphQL Formatter formats the other popular API schema language.
- JSON Formatter checks the JSON mapping of messages.
- Bitmask Calculator designs flag fields packed into integers.
- XML Formatter tidies older SOAP and WSDL schemas.
Checked against the current version of the Protobuf Formatter on .