Protocol Buffers Syntax Examples
Basic Syntax Declaration
Example:
syntax = "proto3";
package example;
Simple Message
Example:
message Person {
string name = 1;
int32 id = 2;
string email = 3;
}
Message with All Basic Types
Example:
message DataTypes {
// Integer types
int32 integer32 = 1;
int64 integer64 = 2;
uint32 unsigned32 = 3;
uint64 unsigned64 = 4;
sint32 signed32 = 5;
sint64 signed64 = 6;
// Fixed-size types
fixed32 fixed_unsigned32 = 7;
fixed64 fixed_unsigned64 = 8;
sfixed32 fixed_signed32 = 9;
sfixed64 fixed_signed64 = 10;
// Floating point
float single_precision = 11;
double double_precision = 12;
// Boolean
bool is_active = 13;
// Text and binary
string text = 14;
bytes binary_data = 15;
}
Nested Messages
Example:
message Person {
string name = 1;
int32 id = 2;
message PhoneNumber {
string number = 1;
PhoneType type = 2;
}
repeated PhoneNumber phones = 4;
}
enum PhoneType {
MOBILE = 0;
HOME = 1;
WORK = 2;
}
Enumerations
Example:
enum Status {
UNKNOWN = 0;
ACTIVE = 1;
INACTIVE = 2;
DELETED = 3;
}
enum Priority {
option allow_alias = true;
LOW = 0;
NORMAL = 1;
HIGH = 2;
URGENT = 2; // Alias for HIGH
}
Field Rules (Proto2)
Example:
// Proto2 syntax with field rules
syntax = "proto2";
message User {
required string username = 1;
required string email = 2;
optional string full_name = 3;
repeated string roles = 4;
}
Repeated Fields
Example:
message SearchResults {
repeated string results = 1;
int32 total_count = 2;
}
message Matrix {
repeated int32 values = 1;
int32 rows = 2;
int32 cols = 3;
}
Maps
Example:
message Project {
string name = 1;
map<string, string> labels = 2;
map<int32, User> contributors = 3;
}
Imports
Example:
syntax = "proto3";
import "google/protobuf/timestamp.proto";
import "google/protobuf/duration.proto";
import public "other.proto";
message Event {
string name = 1;
google.protobuf.Timestamp created_at = 2;
google.protobuf.Duration duration = 3;
}
Options
Example:
option java_package = "com.example.tutorial";
option java_outer_classname = "AddressBookProtos";
option java_multiple_files = true;
option go_package = "example.com/tutorial";
message MyMessage {
option message_set_wire_format = true;
int32 id = 1 [deprecated = true];
string name = 2 [(my_option) = "value"];
}
Services and RPC
Example:
service UserService {
// Get a user by ID
rpc GetUser(GetUserRequest) returns (User);
// List all users
rpc ListUsers(ListUsersRequest) returns (ListUsersResponse);
// Create a new user
rpc CreateUser(CreateUserRequest) returns (User);
// Update an existing user
rpc UpdateUser(UpdateUserRequest) returns (User);
// Delete a user
rpc DeleteUser(DeleteUserRequest) returns (Empty);
}
message GetUserRequest {
int32 user_id = 1;
}
message ListUsersRequest {
int32 page_size = 1;
string page_token = 2;
}
message ListUsersResponse {
repeated User users = 1;
string next_page_token = 2;
}
message CreateUserRequest {
User user = 1;
}
message UpdateUserRequest {
User user = 1;
google.protobuf.FieldMask update_mask = 2;
}
message DeleteUserRequest {
int32 user_id = 1;
}
message Empty {}
Streaming RPC
Example:
service ChatService {
// Client sends a message, server responds
rpc SendMessage(Message) returns (Ack);
// Server-side streaming
rpc ReceiveMessages(SubscribeRequest) returns (stream Message);
// Client-side streaming
rpc UploadFile(stream FileChunk) returns (FileInfo);
// Bidirectional streaming
rpc Chat(stream Message) returns (stream Message);
}
Oneof Fields
Example:
message SampleMessage {
oneof test_oneof {
string name = 4;
int32 id = 5;
bytes raw_data = 6;
}
}
message Shape {
oneof shape {
Circle circle = 1;
Rectangle rectangle = 2;
Triangle triangle = 3;
}
}
Any Type
Example:
import "google/protobuf/any.proto";
message ErrorStatus {
string message = 1;
repeated google.protobuf.Any details = 2;
}
Reserved Fields
Example:
message Foo {
reserved 2, 15, 9 to 11;
reserved "foo", "bar";
string name = 1;
int32 id = 3;
}
Extensions (Proto2)
Example:
syntax = "proto2";
message Foo {
extensions 100 to 199;
}
extend Foo {
optional int32 bar = 126;
}
message Baz {
optional Foo foo = 1;
}
Packages and Namespaces
Example:
syntax = "proto3";
package com.example.project.v1;
message Request {
string query = 1;
}
message Response {
repeated Result results = 1;
}
message Result {
string title = 1;
string url = 2;
}
Default Values
Example:
syntax = "proto2";
message Config {
optional int32 timeout = 1 [default = 30];
optional bool enabled = 2 [default = true];
optional string mode = 3 [default = "production"];
optional Priority priority = 4 [default = NORMAL];
}
Well-Known Types
Example:
import "google/protobuf/timestamp.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/struct.proto";
import "google/protobuf/wrappers.proto";
message Event {
string name = 1;
google.protobuf.Timestamp timestamp = 2;
google.protobuf.Duration timeout = 3;
google.protobuf.Struct metadata = 4;
google.protobuf.Int32Value optional_count = 5;
}
Complete Example: Address Book
Example:
syntax = "proto3";
package tutorial;
option java_multiple_files = true;
option java_package = "com.example.tutorial.protos";
option java_outer_classname = "AddressBookProtos";
message Person {
string name = 1;
int32 id = 2;
string email = 3;
enum PhoneType {
MOBILE = 0;
HOME = 1;
WORK = 2;
}
message PhoneNumber {
string number = 1;
PhoneType type = 2;
}
repeated PhoneNumber phones = 4;
google.protobuf.Timestamp last_updated = 5;
}
message AddressBook {
repeated Person people = 1;
}