GlidersFieldStruct and Actionable
Open source under the MIT license: free to use, change and ship, commercial work included.
class ReservePlaces < Actionable::Action input do required :hut_code, :string required :places, :integer end fails :fully_booked, 'not enough free places' step :check_room step :hold def check_room fail!(:fully_booked) if input.places > 6 end def hold succeed("Holding #{input.places} places") endendReservePlaces.run(hut_code: 'KR12', places: '4')success
"Holding 4 places"ReservePlaces.run(hut_code: 'KR12', places: 9)failure
:fully_bookedReservePlaces.run(places: '2')failure
:invalid_input["Hut code is required"]
A glider has no engine. It stays up on the air that is already there. These gems try to work the same way: with your data and your system, not against them.
Why the name: the Gliders idea →FieldStruct: typed POROs
Section titled “FieldStruct: typed POROs”Declare typed fields on a plain Ruby class and you get an object that coerces what it is given and knows whether it is valid. There is no database in the picture, and no Rails.
class Hut < FieldStruct::Base required :name, :string optional :places, :integerend
hut = Hut.new(name: 'Larch Col', places: '24')hut.places # => 24hut.valid? # => true
unnamed = Hut.new(name: ' ')unnamed.errors.full_messages # => ["Name is required"]The places count came in as a string and is an integer now. A blank name didn’t raise. It was recorded, and the message is waiting when you ask for it.
Actionable: service objects
Section titled “Actionable: service objects”An action is a handful of plain methods, one per step, and every run ends in exactly one result: success, failure or skip. The input is a FieldStruct, so a step never sees bad input.
Above, the hero shows a success and two failures. The third outcome is a skip: the action had nothing to do, which is neither an error nor a success. A pottery studio’s kiln makes one.
class StartFiring < Actionable::Action input do required :kiln, :string required :pieces, :integer end
skips :nothing_to_fire, 'the kiln is empty' fails :overloaded, 'a kiln holds 30 pieces'
step :check_load step :fire
private
def check_load skip!(:nothing_to_fire) if input.pieces.zero? fail!(:overloaded) if input.pieces > 30 end
def fire succeed("Firing #{input.pieces} pieces in #{input.kiln}") endend
StartFiring.run(kiln: 'K2', pieces: 0).status # => :skippedEach result is a Success, a Failure or a Skipped, and each is a FieldStruct, so case ... in can branch on its class and its code in one line.
def notice(result) case result in Actionable::Success(message:) then message in Actionable::Skipped(code: :nothing_to_fire) then 'Nothing in the kiln today' in Actionable::Failure(code: :overloaded) then 'Split the load across two firings' in Actionable::Failure(code: :invalid_input) then "Check the form: #{result.errors.full_messages.join(', ')}" endend
notice(StartFiring.run(kiln: 'K2', pieces: '12')) # => "Firing 12 pieces in K2"notice(StartFiring.run(kiln: 'K2', pieces: 0)) # => "Nothing in the kiln today"notice(StartFiring.run(kiln: 'K2', pieces: 45)) # => "Split the load across two firings"notice(StartFiring.run(pieces: 3)) # => "Check the form: Kiln is required"A skip stops the run like fail! does, so fire never runs for an empty kiln. Every declared code is plain data, so the branches read like the declarations.
Install
Section titled “Install”Both gems go in your Gemfile. They are pre-releases for now, so the constraint names the pre-release version.
gem 'field_struct', '~> 1.0.0.pre1'gem 'actionable-rb', '~> 2.0.0.pre1'The second gem is actionable-rb because another project owns the short name, but you still require 'actionable'. Both need Ruby 3.3 or newer. This site documents field_struct 1.0.0.pre1 and actionable-rb 2.0.0.pre1, and CI executes every runnable example on it, the two above included, against those versions. A wrong # => comment fails the build.
Adapters
Section titled “Adapters”A set of optional gems reads the same field metadata and writes other formats: JSON Schema, Avro, OpenTelemetry, Protobuf, plus actions exposed as LLM and MCP tools, and process pages for actions (Markdown with a Mermaid flowchart). Each is a prerelease, like the two gems. Start at the adapters overview, or jump to building your own adapter.
FieldStruct, Actionable and their adapters are open source under the MIT license.