a bit of history

before protocol buffers

• sad Google developers :(
• explicitly formatted protocols
• versioning handled with if-ology

and then came proto...

• created for index server req-res
• easy introducing new fields
• passing unknown fields further
• semi self-describing format
• automatic generation of (de-)serialization code
• services descibed as proto

syntax & semantics

example message

message Presentation {
  required string author = 1;
  required string topic = 2;
  optional int32 attendees_count = 3 [default = 1]; // no of real attendees
  optional int32 attendees_registered = 4; // no of registered attendees
  repeated string tag = 5;
}
						

• message has a name
• each field has a tag assigned
• each field is defined as required, optional or repeated
• each field has its type defined
• a field can have a default value declared. Be aware that it depends on the compiled .proto and is not stored with message!

tags

message Presentation {
  required string author = 1;
  required string topic = 2;
  optional int32 attendees_count = 3 [default = 1]; // no of real attendees
  optional int32 attendees_registered = 4; // no of registered attendees
  repeated string tags = 5;
}
						

• field id
• unique per message
• smaller tag - smaller field overhead (choose smallest)

quantity

message Presentation {
  required string author = 1;
  required string topic = 2;
  optional int32 attendees_count = 3; // no of real attendees
  optional int32 attendees_registered = 4; // no of registered attendees
  repeated string tags = 5;
}
						

• optional - zero or one field per message
• required - one field per message (beware!)
• repeated - zero to infinity field values per message (can be replaced with optional)

multiple messages

.proto file can contain more than one message type

message Presentation {
  required string author = 1;
  required string topic = 2;
  optional int32 attendees_count = 3; // no of real attendees
  optional int32 attendees_registered = 4; // no of registered attendees
  repeated string tags = 5;
}

message Author {
  required string name = 1;
  repeated string tags = 2;
}
						

using your own types

a type declared can be used later

message Presentation {
  required Author author = 1; // this isn't compatible with earlier version!
  required string topic = 2;
  optional int32 attendees_count = 3; // no of real attendees
  optional int32 attendees_registered = 4; // no of registered attendees
  repeated string tags = 5;
}

message Author {
  required string name = 1;
  repeated string tags = 2;
}
						

nested types

one can nest types to provide a scope/namespaces of messages

message Presentation {
  message Author {
    required string name = 1;
    repeated string tags = 2;
  }

  required Author author = 1; // this isn't compatible with earlier version!
  required string topic = 2;
  optional int32 attendees_count = 3; // no of real attendees
  optional int32 attendees_registered = 4; // no of registered attendees
  repeated string tags = 5;
}
						

enumerations

enum PresentationLevel {
  option allow_alias = true;
  
  EASY = 100;
  MEDIUM = 200;
  EXPERT = 300;
  HARDCORE = 300; // alias, allowed by option above
}
						

extensions

some tools doesn't require to define extensions, but the standard does

message Presentation {
  // ...
  extensions 50 to 100;
}

extend Presentation {
  optional string address = 51;
}

						

extensions - convention

it's quite common to define a bag for your fields, to simplify future version changes

message Presentation {
  // ...
  extensions 50 to 100;
}

message Address {
  extend Presentation {
    optional Address address = 51;
  }
  
  optional string street = 1;
  optional string city = 2;
}
						

packages

package WGNET;
message Presentation {
  // ...
  extensions 50 to 100;
}

message Address {
  extend Presentation {
    optional Address address = 51;
  }
  
  optional string street = 1;
  optional string city = 2;
}
						

bytes structure & layout

performance

tooling

libraries for .NET

protobuf-linq