Adapters
An adapter is an optional gem on top of field_struct or actionable, and it handles one format. Every gem here is a prerelease, at 1.0.0.pre1, and CI runs each example on these pages against that code.
Choose an adapter
Section titled “Choose an adapter”| You want to | Adapter | Gem | Status |
|---|---|---|---|
| publish a struct’s JSON as a schema, for docs or other services | JSON Schema | field_struct-json_schema |
prerelease |
| write structs as Avro binary and read old events | Avro | field_struct-avro |
prerelease |
| encode Avro faster, with an optional Rust encoder | Avro native encoder | field_struct-avro-native |
prerelease |
print a .proto and encode structs with Protobuf |
Protobuf | field_struct-protobuf |
API may change |
| trace action runs | OpenTelemetry | actionable-otel |
prerelease |
| let a language model call an action | LLM and MCP tools | actionable-tools |
API may change |
| write a readable page and flowchart for each action | Process pages | actionable-docs |
API may change |
Install
Section titled “Install”Every adapter is a separate gem, and you load it with an explicit require.
gem 'field_struct-json_schema' # require 'field_struct/json_schema'gem 'field_struct-avro' # require 'field_struct/avro'gem 'field_struct-avro-native' # require 'field_struct/avro/native'gem 'field_struct-protobuf' # require 'field_struct/protobuf'gem 'actionable-otel' # require 'actionable/otel'gem 'actionable-tools' # require 'actionable/tools'gem 'actionable-docs' # require 'actionable/docs'Some pull in a library and some leave that to you. Avro depends on avro and Protobuf on google-protobuf. OpenTelemetry depends on opentelemetry-api alone, so the SDK and the exporter are your choice. The tools adapter needs mcp or ruby_llm only for the wrapper you require.
How they behave
Section titled “How they behave”- Module functions first. Each adapter works as plain functions, like
FieldStruct::Avro.schema(Hut). The Avro and JSON Schema adapters also have an opt-inMethodsmodule for when you wantHut.to_avro_schemaon the class. - Requiring leaves your classes alone. OpenTelemetry is the exception:
require 'actionable/otel'turns tracing on. - One shape, many formats. The three format adapters share a single walk over a struct’s fields,
FieldStruct::Introspection. Output names come fromserialize, so one declaration can call a field something different in:json,:avroand:protobuf. - They refuse rather than approximate. If a format can’t hold something exactly, the adapter raises, or leaves it out and documents that.
require 'field_struct/json_schema'
class Hut < FieldStruct::Base required :name, :stringend
Hut.respond_to?(:to_json_schema) # => falseFieldStruct::JSONSchema.generate(Hut)['required'] # => ["name"]
class Hut include FieldStruct::JSONSchema::Methodsend
Hut.respond_to?(:to_json_schema) # => trueGo further
Section titled “Go further”- How adapters work: why they are separate gems, and why they never approximate
- Introspection reference: the walk all the format adapters share
- Build your own adapter: a generator for another format in about 60 lines
See also
Section titled “See also”FieldStruct, Actionable and their adapters are open source under the MIT license.