Protobuf
field_struct-protobuf gives a struct a Protocol Buffers form without a protoc run. It prints .proto source for other teams, registers a message class with google-protobuf, and converts instances to messages, to binary and back.
gem 'field_struct-protobuf'require 'field_struct/protobuf'You choose the field numbers. Each field carries proto: {number: n} and the gem never guesses one. require 'field_struct/protobuf' registers proto: as a field option (with FieldStruct.register_option), so require it before those classes; until then the option raises and says which file to require. An unknown key inside proto: raises when the schema or message is built, with a did-you-mean: proto: has no key numbr: (did you mean number:?). If it numbered by declaration order, moving two lines around in a class would quietly change the wire format.
The schema of a struct
Section titled “The schema of a struct”FieldStruct::Protobuf.proto prints the file for a single class. It prints from the descriptor that gets registered, so the text and the registered message can’t drift apart.
require 'field_struct/protobuf'
module Fleet class Depot < FieldStruct::Base required :name, :string, proto: { number: 1 } end
class Trip < FieldStruct::Base required :route, :string, proto: { number: 1 } optional :meters, :integer, proto: { number: 2 } optional :origin, Depot, proto: { number: 3 } optional :waypoints, :array, of: :string, proto: { number: 4 } optional :battery, :big_decimal, proto: { number: 5 } optional :departed, :time, zone: 'America/Denver', proto: { number: 6 } endend
text = FieldStruct::Protobuf.proto(Fleet::Trip)text.lines.grep(/\A(message| )/).map(&:strip)# => ["message Trip {", "optional string route = 1;", "optional int64 meters = 2;", ".fleet.Depot origin = 3;", "repeated string waypoints = 4;", "optional string battery = 5;", ".google.protobuf.Timestamp departed = 6;"]FieldStruct::Protobuf.file_name(Fleet::Trip) # => "field_struct/fleet/trip.proto"FieldStruct::Protobuf.full_name(Fleet::Trip) # => ".fleet.Trip"Here is the whole file for Fleet::Trip:
// field_struct/fleet/trip.proto: generated by field_struct-protobuf from Fleet::Trip.// Field numbers come from each field's proto: {number:} option.
syntax = "proto3";
package fleet;
import "field_struct/fleet/depot.proto";import "google/protobuf/timestamp.proto";
message Trip { optional string route = 1; optional int64 meters = 2; .fleet.Depot origin = 3; repeated string waypoints = 4; optional string battery = 5; .google.protobuf.Timestamp departed = 6;}The module Fleet turns into the package. Each class gets its own file with one message in it. A file imports the files of whatever structs it refers to. A struct can refer to itself, but two structs can’t point at each other.
Type mapping
Section titled “Type mapping”| FieldStruct type | Protobuf |
|---|---|
:binary |
bytes |
:string, :immutable_string, :uuid, :email, :url, :symbol |
string |
:big_decimal, :decimal |
string, so 19.9 stays exact |
:date |
string, as 2026-11-01 |
:boolean |
bool |
:integer |
int64 |
:float |
double |
:time, :datetime |
.google.protobuf.Timestamp; the zone: offset is restored on decode |
:value |
.google.protobuf.Value; numbers come back as Floats |
| a struct class | its message |
:array, of: X |
repeated X |
:hash, of: X |
map<string, X> |
Singular scalars are all optional, so presence is explicit: a field nobody set reads back as nil, not 0 or an empty string. Arrays and maps differ. Empty and unset look the same on the wire, so an unset array reads back as [] and an unset map as {}.
A map’s keys are Strings, as field_struct keeps them. proto3 has no repeated or map values, so a :hash of arrays or maps is refused, and since a map entry can’t hold null either, encoding a nil value raises "<key>: protobuf map values can't be nil".
class Locker < FieldStruct::Base required :dock, :string, proto: { number: 1 } optional :bikes_by_bay, :hash, of: :integer, proto: { number: 2 }end
FieldStruct::Protobuf.proto(Locker).lines.map(&:strip).grep(/map/) # => ["map<string, int64> bikes_by_bay = 2;"]bytes = FieldStruct::Protobuf.encode(Locker.new(dock: 'Quay', bikes_by_bay: {east: 4}))FieldStruct::Protobuf.decode(Locker, bytes).bikes_by_bay # => {"east" => 4}Use case: encode and decode
Section titled “Use case: encode and decode”Take a trip that starts at the north depot and carries a battery reading.
trip = Fleet::Trip.new(route: 'Riverside loop', meters: '5400', origin: { name: 'North depot' }, waypoints: %w[dock-12 dock-31], battery: '87.5', departed: Time.utc(2026, 10, 27, 15, 30))
bytes = FieldStruct::Protobuf.encode(trip)bytes.encoding # => #<Encoding:BINARY (ASCII-8BIT)>
back = FieldStruct::Protobuf.decode(Fleet::Trip, bytes)back == trip # => trueback.battery == BigDecimal("87.5") # => trueback.departed.utc_offset # => -21600back.origin.name # => "North depot"Code that protoc generates from the printed .proto can read these bytes. The adapter’s own specs prove it by compiling the text with protoc, so this page relies on that claim and does not run it.
Use case: messages
Section titled “Use case: messages”message_class builds the message for a class one time and registers it in google-protobuf’s generated pool. to_message and from_message convert a single instance.
depot = Fleet::Depot.new(name: 'Harbour depot')
message = FieldStruct::Protobuf.to_message(depot)message.name # => "Harbour depot"FieldStruct::Protobuf.message_class(Fleet::Depot).equal?(message.class) # => trueFieldStruct::Protobuf.from_message(Fleet::Depot, message) == depot # => trueMessage field names are the serialize :protobuf names, as given. Pass serialization: when you want the names of another format.
Unset stays unset
Section titled “Unset stays unset”sparse = Fleet::Trip.new(route: 'Riverside loop')message = FieldStruct::Protobuf.to_message(sparse)
message.has_meters? # => falseFieldStruct::Protobuf.decode(Fleet::Trip, FieldStruct::Protobuf.encode(sparse)).meters # => nilFieldStruct::Protobuf.decode(Fleet::Trip, FieldStruct::Protobuf.encode(sparse)).waypoints # => []It raises rather than guess
Section titled “It raises rather than guess”When there is no exact mapping, the call raises ArgumentError and names the class and field. Cases are a field with no number, a number used twice, a union, an array of arrays, a map of arrays or maps and a custom type.
class Unnumbered < FieldStruct::Base required :dock, :stringend
class Twice < FieldStruct::Base required :dock, :string, proto: { number: 2 } required :slot, :string, proto: { number: 2 }end
class Either < FieldStruct::Base required :dock, :union, of: %i[integer string], proto: { number: 1 }end
refusals = [Unnumbered, Twice, Either].map do |klass| FieldStruct::Protobuf.proto(klass)rescue ArgumentError => e e.messageendrefusals# => ["Unnumbered: give every field a protobuf field number, e.g. `proto: {number: 1}`; missing on dock", "Twice: field numbers 2 are used twice", "Either#dock is a union, which field_struct-protobuf can't map yet; split it into one field per member type, or declare it :value (a google.protobuf.Value)"]Module functions
Section titled “Module functions”| Call | Returns |
|---|---|
proto(klass) |
the .proto text |
file_name(klass), full_name(klass), package(klass), message_name(klass) |
the names given to the file and message |
file_descriptor(klass) |
the registered descriptor |
message_class(klass) |
the google-protobuf message class |
to_message(struct), from_message(klass, message) |
one instance, to a message and back |
encode(struct), decode(klass, bytes) |
binary |
Limits
Section titled “Limits”- Output is proto3 only. There is no
oneof, enum, service or option. - Registration lasts for the process and cannot be undone. If a class gains a field after its message was built, nothing notices, and the stale message rejects the new field. Reloading code means restarting.
- Each class registers under one
serialization:. Asking for a second one raises. - For malformed bytes,
decodeletsGoogle::Protobuf::ParseErrorpass through. - An integer past 64 bits raises
RangeError. format:andin:are not checked here. The struct does that.
See also
Section titled “See also”- Introspection reference
- Avro: the other binary format
- How adapters work
FieldStruct, Actionable and their adapters are open source under the MIT license.