This document provides a style guide for .proto files. By following these conventions, you’ll make your protocol buffer message definitions and their corresponding classes consistent and easy to read.

Note that protocol buffer style has evolved over time, so it is likely that you will see .proto files written in different conventions or styles. Please respect the existing style when you modify these files. Consistency is key. However, it is best to adopt the current best style when you are creating a new .proto file.

Standard File Formatting

• Keep the line length to 80 characters.
• Use an indent of 2 spaces.

File Structure

Files should be named lower_snake_case.proto

All files should be ordered in the following manner:

1. License header (if applicable)
2. File overview
3. Syntax
4. Package
5. Imports (sorted)
6. File options
7. Everything else

Packages

Package name should be in lowercase, and should correspond to the directory hierarchy. e.g., if a file is in my/package/, then the package name should be my.package.

Package Names

Package names declared in the API .proto files should be consistent with Product Names and Service Names. Package names should use singular component names to avoid mixed singular and plural component names. Package names must not use underscores. Package names for versioned APIs must end with the version. For example:

// Google Calendar API
package google.calendar.v3;

An abstract API that isn’t directly associated with a service, such as Google Watcher API, should use proto package names consistent with the Product name:

// Google Watcher API
package google.watcher.v1;

Java package names specified in the API .proto files must match the proto package names with standard Java package name prefix (com., edu., net., etc). For example:

package google.calendar.v3;

// Specifies Java package name, using the standard prefix "com."
option java_package = "com.google.calendar.v3";

Message and Field Names

Use CamelCase (with an initial capital) for message names – for example, SongServerRequest. Use underscore_separated_names for field names (including oneof field and extension names) – for example, song_name.

message SongServerRequest {
  required string song_name = 1;
}

Using this naming convention for field names gives you accessors like the following:

C++:
  const string& song_name() { ... }
  void set_song_name(const string& x) { ... }

Java:
  public String getSongName() { ... }
  public Builder setSongName(String v) { ... }

If your field name contains a number, the number should appear after the letter instead of after the underscore. e.g., use song_name1 instead of song_name_1

Message Names

Message names should be short and concise. Avoid unnecessary or redundant words. Adjectives can often be omitted if there is no corresponding message without the adjective. For example, the Shared in SharedProxySettings is unnecessary if there are no unshared proxy settings.

Message names should not include prepositions (e.g. “With”, “For”). Generally, message names with prepositions are better represented with optional fields on the message.

Field Names

Field definitions in the .proto files must use lower_case_underscore_separated_names. These names will be mapped to the native naming convention in generated code for each programming language.

Field names should not include prepositions (e.g. “for”, “during”, “at”), for example:

• reason_for_error should instead be error_reason
• cpu_usage_at_time_of_failure should instead be failure_time_cpu_usage

Field names should not use postpositive adjectives (modifiers placed after the noun), for example:

• items_collected should instead be collected_items
• objects_imported should instead be imported_objects

Repeated Field Names

Repeated fields in APIs must use proper plural forms. This matches the convention of existing Google APIs, and the common expectation of external developers.

Time and Duration

To represent a point in time independent of any time zone or calendar, google.protobuf.Timestamp should be used, and the field name should end with time, such as start_time and end_time.

If the time refers to an activity, the field name should have the form of verb_time, such as create_time, update_time. Avoid using past tense for the verb, such as created_time or last_updated_time.

To represent a span of time between two points in time independent of any calendar and concepts like “day” or “month”, google.protobuf.Duration should be used.

message FlightRecord {
  google.protobuf.Timestamp takeoff_time = 1;
  google.protobuf.Duration flight_duration = 2;
}

If you have to represent time-related fields using an integer type for legacy or compatibility reasons, including wall-clock time, duration, delay and latency, the field names must have the following form:

xxx_{time|duration|delay|latency}_{seconds|millis|micros|nanos}
message Email {
  int64 send_time_millis = 1;
  int64 receive_time_millis = 2;
}

If you have to represent timestamp using string type for legacy or compatibility reasons, the field names should not include any unit suffix. The string representation should use RFC 3339 format, e.g. “2014-07-30T10:43:17Z”.

Date and Time of Day

For dates that are independent of time zone and time of day, google.type.Date should be used and it should have the suffix _date. If a date must be represented as a string, it should be in the ISO 8601 date format YYYY-MM-DD, e.g. 2014-07-30.

For times of day that are independent of time zone and date, google.type.TimeOfDay should be used and should have the suffix _time. If a time of day must be represented as a string, it should be in the ISO 8601 24-hour time format HH:MM:SS[.FFF], e.g. 14:55:01.672.

message StoreOpening {
  google.type.Date opening_date = 1;
  google.type.TimeOfDay opening_time = 2;
}

Quantities

Quantities represented by an integer type must include the unit of measurement.

xxx_{bytes|width_pixels|meters}

If the quantity is a number of items, then the field should have the suffix _count, for example node_count.

Repeated Fields

Use pluralized names for repeated fields.

  repeated string keys = 1;
  ...
  repeated MyMessage accounts = 17;

Enums

Naming

Use CamelCase (with an initial capital) for enum type names and CAPITALS_WITH_UNDERSCORES for value names:

enum Foo {
  FOO_UNSPECIFIED = 0;
  FOO_FIRST_VALUE = 1;
  FOO_SECOND_VALUE = 2;
}

• Each enum value should end with a semicolon, not a comma.
• Prefer prefixing enum values instead of surrounding them in an enclosing message.
• The first value should be named ENUM_TYPE_UNSPECIFIED as it is returned when an enum value is not explicitly specified.

Values

• Enum definitions must start with enum value zero.

Methods

Method Names

A service may, in its IDL specification, define one or more RPC methods that correspond to methods on collections and resources. The method names should follow the naming convention of VerbNoun in upper camel case, where the noun is typically the resource type.

The verb portion of the method name should use the imperative mood, which is for orders or commands rather than the indicative mood which is for questions.

For standard methods, the noun portion of the method name must be singular for all methods except List, and must be plural for List. For custom methods, the noun may be singular or plural as appropriate. Batch methods must use the plural noun.

Note: The case above refers to the RPC name in protocol buffers; the HTTP/JSON URI suffixes use :lowerCamelCase.

This is easily confused when the verb is asking a question about a sub-resource in the API, which is often expressed in the indicative mood. For example, ordering the API to create a book is clearly CreateBook (in the imperative mood), but asking the API about the state of the book’s publisher might use the indicative mood, such as IsBookPublisherApproved or NeedsPublisherApproval. To remain in the imperative mood in situations like this, rely on commands such as “check” (CheckBookPublisherApproved) and “validate” (ValidateBookPublisher).

Method names should not include prepositions (e.g. “For”, “With”, “At”, “To”). Generally, method names with prepositions indicate that a new method is being used where a field should instead be added to an existing method, or the method should use a distinct verb.

For example, if a CreateBook message already exists and you are considering adding CreateBookFromDictation, consider a TranscribeBook method instead.

Services

If your .proto defines an RPC service, you should use CamelCase (with an initial capital) for both the service name and any RPC method names:

service FooService {
  rpc GetSomething(FooRequest) returns (FooResponse);
}

Service Names

Service names should be syntactically valid DNS names (as per RFC 1035) which can be resolved to one or more network addresses. The service names of public Google APIs follow the pattern: xxx.googleapis.com. For example, the service name of the Google Calendar is calendar.googleapis.com.

If an API is composed of several services they should be named in a way to help discoverability. One way to do this is for the Service Names to share a common prefix. For example the services build.googleapis.com and buildresults.googleapis.com are both services that are part of the Google Build API.

Things to avoid

• Required fields (only for proto2)
• Groups (only for proto2)

Misc

Camel Case

Except for field names and enum values, all definitions inside .proto files must use UpperCamelCase names, as defined by Google Java Style.

Name Abbreviation

For well known name abbreviations among software developers, such as config and spec, the abbreviations should be used in API definitions instead of the full spelling. This will make the source code easy to read and write. In formal documentations, the full spelling should be used. Examples:

• config (configuration)
• id (identifier)
• spec (specification)
• stats (statistics)

Reference

• https://developers.google.com/protocol-buffers/docs/style
• https://cloud.google.com/apis/design/proto3
• https://cloud.google.com/apis/design/naming_convention

• ← Previous Post
• Next Post →