JSON and serialization
A struct goes out to JSON through as_json and to_json and comes back in through from_json. Reading runs through new, so JSON input gets the same coercion and validation as a Hash would. All JSON work uses Oj, never the standard library.
| Member | Returns |
|---|---|
#as_json |
a Hash with Symbol keys, one entry per field |
#to_json |
a JSON String |
.from_json(string) |
an instance |
.serialize(format, **mapping) |
the class, see serialize |
as_json
Section titled “as_json”as_json builds a Hash with Symbol keys in declaration order, one entry per field, and unset optionals show up as nil. The :json mapping supplies the key names. It reads one option, describe_foreign: (below), and ignores any other, so there is no only: or except:. Each value comes from the field’s reader, so overriding a reader changes the output, but overriding attributes does not.
Values convert as follows:
| Value | Written as |
|---|---|
nil, true, false, String, Integer, Float |
itself |
| Symbol | its String |
| BigDecimal | a plain decimal String, so digits are never lost. BigDecimal('1234567890123.4567') becomes "1234567890123.4567". to_json writes a number instead (below) |
| Date, DateTime, Time | by the field’s format:: an RFC 3339 preset as its rule says, a strftime String as given, and with no format the object’s iso8601. For an array field the element’s format: is used |
| Array | each element, by the same rules |
| Hash | its values, by the same rules |
| a struct | its own as_json, so its own mapping applies |
| anything else | as_json of the object if it responds to it, else the object itself |
Only :value fields reach the last row. Dates, times and zones covers the formats.
as_json(describe_foreign: true) changes that last row: each such object is written as a short description, "#<Lantern id=4>", or "#<Lantern>" when it has no id. Nothing is called on the object except class and id, so a record’s own as_json (which might query, or write fields you didn’t mean to share) never runs. Numbers and nested structs are written as usual, and the mode ends with the call.
class Lantern attr_reader :id def initialize(id) = @id = id def as_json(*) = { 'id' => id, 'wick_code' => 'w-9' }end
class Watch < FieldStruct::Base optional :lantern, :valueend
watch = Watch.new(lantern: Lantern.new(4))watch.as_json # => {lantern: {"id" => 4, "wick_code" => "w-9"}}watch.as_json(describe_foreign: true) # => {lantern: "#<Lantern id=4>"}Leaving out what wasn’t sent
Section titled “Leaving out what wasn’t sent”A class with json_omit :unset leaves a field out of as_json and to_json when the caller didn’t give it and it’s nil. A default is still written, since the model chose to say it, and a nil the caller gave is written as nil, since that’s a null they sent. A nested struct follows its own class’s setting. Class macros has the macro itself.
class BalloonLaunch < FieldStruct::Base json_omit :unset optional :station, :string optional :tethered, :boolean, default: true optional :burst_m, :integer optional :notes, :stringend
BalloonLaunch.new(station: 'Ridge').as_json # => {station: "Ridge", tethered: true}BalloonLaunch.new(station: 'Ridge', notes: nil).as_json # => {station: "Ridge", tethered: true, notes: nil}BalloonLaunch.new(burst_m: 31_000).to_json # => "{\"tethered\":true,\"burst_m\":31000}"to_json
Section titled “to_json”to_json writes the same tree as as_json with Oj in :compat mode, with one difference: a BigDecimal goes out as a JSON number with its exact digits, at any depth, so 3.25 stays 3.25 and from_json reads it back exactly. Its argument is ignored too, so to_json(only: [:species]) still writes every field. Symbol keys become JSON strings.
A decimal that a JavaScript client must not parse into a float can keep the string: declare it json: :string, or element: { json: :string } on an array or map of decimals. A type of your own can make that its default by answering json_default with :string. as_json always gives Strings, so a struct inside a Hash that some other encoder writes, such as a Rails render json: of a Hash, still gets strings.
require 'bigdecimal'
class Invoice < FieldStruct::Base required :total, :decimal optional :display_total, :decimal, json: :stringend
invoice = Invoice.new(total: '1234.50', display_total: '1234.50')invoice.to_json # => '{"total":1234.5,"display_total":"1234.5"}'invoice.as_json[:total] # => "1234.5"Invoice.from_json(invoice.to_json).total # => BigDecimal('1234.5')from_json
Section titled “from_json”Klass.from_json(json_string)The string is parsed with Oj.load(string, mode: :compat, decimal_class: BigDecimal): numbers with a fraction or exponent arrive as BigDecimal, whole numbers as Integer. Keys map back to Ruby names and the Hash goes to Klass.new, so coercion, nested construction, unknown_attributes and coercion_policy act just as they do for direct construction.
What the BigDecimal parse means for each type:
- a
:decimalfield receives exactly the digits that were sent - a
:floatfield still ends up a Float - an
:integerfield cuts3.7down to3 - a
:valuefield, along with numbers inside its Hashes and Arrays, holds a BigDecimal, whichto_jsonwrites as a number andas_jsonas a String - JSON
1e400is a finite BigDecimal. Decimal and integer fields read it and a float field refuses it
Errors:
| Input | Raises |
|---|---|
| a root that is not an object | ArgumentError: from_json expects a JSON object root, got Array |
null |
the same, with got NilClass |
| malformed JSON, including an empty or blank String | EncodingError: from_json could not parse its input as JSON (<description> at line L, column C) |
EncodingError is what Oj raises in this mode, and FieldStruct has no class of its own for it. It is re-raised with no cause and no piece of the input, so a secret inside a bad payload never reaches a log.
require 'bigdecimal'
class Plant < FieldStruct::Base required :species, :string optional :yield_kg, :decimal optional :sown, :date, format: :us optional :last_watered, :time, format: :iso8601 optional :leaves, :integer optional :humidity, :float optional :notes, :valueend
json = '{"species":"Fern","yield_kg":3.250,"sown":"03/14/2026","last_watered":"2026-05-02T06:00:00Z","leaves":88.9,"humidity":5e1}'plant = Plant.from_json(json)plant.yield_kg # => BigDecimal('3.25')plant.leaves # => 88plant.humidity # => 50.0plant.as_json[:yield_kg] # => "3.25"plant.as_json[:sown] # => "03/14/2026"plant.as_json[:last_watered] # => "2026-05-02T06:00:00Z"plant.as_json[:notes] # => nilplant.to_json.include?('"yield_kg":3.25') # => truePlant.new(species: 'x').to_json(only: [:species]) == Plant.new(species: 'x').to_json # => truePlant.from_json('{"species":"x","notes":{"depth":0.75}}').notes # => {"depth" => BigDecimal('0.75')}
begin Plant.from_json('[1]')rescue ArgumentError => e e.message # => "from_json expects a JSON object root, got Array"end
begin Plant.from_json('null')rescue ArgumentError => e e.message # => "from_json expects a JSON object root, got NilClass"end
begin Plant.from_json('{oops')rescue EncodingError => e e.message.start_with?('from_json could not parse its input as JSON') # => trueendRound trip
Section titled “Round trip”Klass.from_json(x.to_json) == x holds for any struct, with one exception. A :value field comes back equal only when its content is plain JSON, since from_json returns numbers as BigDecimal while to_json writes them as Strings. Nested structs, arrays of structs, unions of structs (each member reverse-maps through its own mapping), temporal fields with any declared format:, and decimals all round-trip.
class Sample < FieldStruct::Base required :label, :string optional :rainfall_mm, :decimal optional :collected_at, :datetime, format: :iso8601 optional :season_start, :date, format: '%d/%m/%Y' serialize :json, collected_at: 'collectedAt'end
sample = Sample.new(label: 'gauge-7', rainfall_mm: '14.5', collected_at: '2026-09-21T18:30:00Z', season_start: '01/09/2026')sample.to_json == Sample.from_json(sample.to_json).to_json # => trueSample.from_json(sample.to_json) == sample # => truesample.as_json # => {label: "gauge-7", rainfall_mm: "14.5", collectedAt: "2026-09-21T18:30:00Z", season_start: "01/09/2026"}serialize
Section titled “serialize”serialize :json, internal_name: 'externalName'serialize(format, **mapping) renames keys for one format. The mapping keys are Ruby field names and must be declared already. Values turn into Strings, so first: :firstName stores "firstName". The mapping is kept frozen and metadata.serialization(format) returns it.
The gem itself uses only :json. Other names, like :csv, are stored for other gems to read. Declaring a format again swaps out its whole mapping, and fields left out of the mapping keep their own names. A subclass starts with its parent’s mappings and may map inherited fields, replace a format or add a new one. Replacing is total: a subclass that calls serialize :json again drops the parent’s :json entries unless it repeats them.
The mapping works in both directions and recursively:
as_jsonwrites the external names, with nested structs using their own mappingsfrom_jsonreads the external name and also takes the Ruby name. A key matching neither is unknown and followsunknown_attributes- a nested struct given a Hash, and each Hash in an array of structs, goes through the nested class’s own mapping
- a
:uniongiven a Hash tries its members in declared order. A struct member maps the keys through its own mapping and builds, and the first one that accepts wins. A non-struct member such as:valuethat accepts the raw Hash wins as is. If none accepts, the raw Hash moves on and the field’s coercion policy decides - arrays of unions, and unions inside arrays, are not reverse-mapped
attributes, to_h, deconstruct_keys and deconstruct always use Ruby names, whatever serialize says. Changing a mapping after a class has been read takes effect on the next call.
class Bed < FieldStruct::Base required :plot_no, :string serialize :json, plot_no: 'plotNo'end
class Gardener < FieldStruct::Base required :nickname, :string optional :border, Bed optional :extras, :array, of: Bed serialize :json, nickname: :nickName, extras: 'extraBeds'end
json = '{"nickName":"Moss","border":{"plotNo":"C-14"},"extraBeds":[{"plot_no":"C-15"}]}'gardener = Gardener.from_json(json)gardener.nickname # => "Moss"gardener.border.plot_no # => "C-14"gardener.extras.first.plot_no # => "C-15"gardener.as_json # => {nickName: "Moss", border: {plotNo: "C-14"}, extraBeds: [{plotNo: "C-15"}]}gardener.attributes.keys # => [:nickname, :border, :extras]Gardener.from_json('{"nickname":"Fen"}').nickname # => "Fen"Gardener.metadata.serialization(:json) # => {nickname: "nickName", extras: "extraBeds"}Gardener.metadata.serialization(:csv) # => {}You can’t declare a field named after a reserved method such as errors. Declare it under another name and map it, like serialize :json, errors_field: 'errors'. See Fields and options.
See also
Section titled “See also”FieldStruct, Actionable and their adapters are open source under the MIT license.