Skip to content

GlidersFieldStruct and Actionable

Typed plain-Ruby objects (FieldStruct) and typed service objects built on them (Actionable), with adapters for JSON Schema, Avro, Protobuf, OpenTelemetry and LLM tools.

Open source under the MIT license: free to use, change and ship, commercial work included.

reserve_places.rb
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")  endend
calls.rb
  1. ReservePlaces.run(hut_code: 'KR12', places: '4')

    success "Holding 4 places"

  2. ReservePlaces.run(hut_code: 'KR12', places: 9)

    failure :fully_booked

  3. ReservePlaces.run(places: '2')

    failure :invalid_input ["Hut code is required"]

Three calls, one result each. Every line here runs in CI.

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.

hut.rb
class Hut < FieldStruct::Base
required :name, :string
optional :places, :integer
end
hut = Hut.new(name: 'Larch Col', places: '24')
hut.places # => 24
hut.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.

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.

start_firing.rb
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}")
end
end
StartFiring.run(kiln: 'K2', pieces: 0).status # => :skipped

Each 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.

studio.rb
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(', ')}"
end
end
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.

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.

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.