Skip to content

Validation and errors

A field setter coerces the value, stores it, and validates that one field. Problems go onto obj.errors and aren’t raised unless you ask for :raise. Building an object and asking whether it is valid are two different things: new always hands back an instance, and valid? reports the outcome.

The macros that set policies live on Class macros.

name=(value) runs these steps in order, and new, assign_attributes and with run the same ones for every key.

  1. If the instance is initialized and the class is immutable!, raise ImmutableError.
  2. Coerce with the field’s type. A failure (ArgumentError, TypeError or RangeError) is handed to the coercion policy and the pipeline stops.
  3. Store the coerced value.
  4. Validate the field (below).

Any other exception, like NoMethodError or a FieldStruct::Error, propagates. The setter returns the coerced value. Assigning a field again reruns the whole pipeline and rewrites that field’s errors while leaving the other fields’ errors alone. Under :keep_raw, a later good value clears an earlier coercion error.

Once coercion succeeds, validation goes in this order and stops at the first step that applies:

  1. Clear that field’s errors.
  2. If the type calls the value missing, add "is required" when the field is required and stop. A missing optional value is fine, and so is a given nil on a field declared nullable: true.
  3. Otherwise, when a string-family value is outside its length:, or an array holds more than its max_items:, add that size message and stop.
  4. Otherwise, when the value fails format: (a Regexp only), enum: or in:, or is an invalid nested struct or holds one, add "is invalid". It is added once, however many checks fail.
  5. For an array with element: options, add the element-index message, and for a map with them the entry-count message (see Types).
Message When
"is required" a required field is missing: nil, a blank String, an empty Array or Hash
"is too short (minimum is 3)", "is too long (maximum is 40)" a string-family value is outside its length:
"is invalid" format:, enum: or in: failed, or a nested struct inside is invalid
"element at index 1 is invalid" an element of an array failed an element: check
"1 entry is invalid", "2 entries are invalid" values of a map failed an element: check; the message names no key
"has too many items (maximum is 3)" an array holds more elements than its max_items:
"could not be coerced: <reason>" the type couldn’t read the value
anything you add from validate or errors.add

format:, enum: and in: can be combined, and any failure gives a single "is invalid". nil never fails them. A Symbol or String format: (temporal presets and strftime strings) only drives parsing and adds no error. Coercion goes first, so '10' is already 10 when in: looks at it.

length: takes a Range of whole numbers (3..40, ..40, 3..) and counts characters, or bytes on :binary. It runs before format: and enum:, and a value that breaks it gets only the length message, which names the limit and never the value. A blank String is missing, so it skips length: the way it skips every check: '' passes length: 3.. on an optional field, and is "is required" on a required one.

class Burrow < FieldStruct::Base
required :name, :string, length: 3..12
optional :entrance, :string, length: 2..
end
Burrow.new(name: 'Ox').errors[:name] # => ["is too short (minimum is 3)"]
Burrow.new(name: 'Underhill-East').errors[:name] # => ["is too long (maximum is 12)"]
Burrow.new(name: 'Sett', entrance: '').valid? # => true

When coercion fails on a required field, only the coercion error is recorded, never "is required" as well, even if :replace stored nil. Defaults satisfy required, because the check looks at the stored value.

Messages carry the class of the input, never the value. That covers coercion errors, CoercionError, union and array messages, from_json errors and the cause chain, so it is safe to log them. Custom types write their own messages, and those should name the class as well.

class Seedling < FieldStruct::Base
required :tag, :string, format: /\A[A-Z]{2}-\d+\z/
optional :count, :integer, in: 1..40
optional :stage, :symbol, enum: %i[sprout potted hardened]
end
seedling = Seedling.new(tag: 'zz', count: 'a dozen')
seedling.valid? # => false
seedling.errors[:tag] # => ["is invalid"]
seedling.errors[:count].first.start_with?('could not be coerced') # => true
seedling.errors.full_messages.first # => "Tag is invalid"
Seedling.new.errors[:tag] # => ["is required"]
Seedling.new(tag: 'FE-7', count: 400).errors[:count] # => ["is invalid"]
Seedling.new(tag: 'FE-7', count: nil, stage: nil).valid? # => true

valid? runs the cross-field validators when the class has any, then reports errors.empty?. invalid? says the opposite. Per-field errors are set at assignment and never recomputed afterwards. Changing a nested struct, or an element of an array, in place doesn’t refresh the parent in either direction, and pushing onto an array in place stores the raw element without coercion. To rerun coercion and validation, assign the field again or use with or assign_attributes.

An invalid nested struct gives the parent field "is invalid" when it is assigned. So does an Array containing at least one invalid struct, and so does a bare struct assigned to a :value field. Only the value itself and the elements of an Array are inspected, so a struct inside a Hash value goes unchecked.

class Tray < FieldStruct::Base
required :cells, :integer
end
class Nursery < FieldStruct::Base
optional :tray, Tray
end
nursery = Nursery.new(tray: {cells: 24})
nursery.valid? # => true
nursery.tray.cells = 'plenty'
nursery.valid? # => true
nursery.tray = nursery.tray
nursery.errors[:tray] # => ["is invalid"]
seedling = Seedling.new(tag: 'zz')
seedling.tag = 'FE-7'
seedling.valid? # => true

When a type refuses a value, the policy in force is the field’s coercion_policy: if it has one, otherwise the class’s, which defaults to :keep_raw.

Policy What happens
:keep_raw the raw input is stored and a single "could not be coerced: ..." message is recorded
:replace the field becomes nil and the same message is recorded
:raise the setter raises FieldStruct::CoercionError and the old value stays

:keep_raw and :replace skip the validation steps, so the coercion message never comes with "is required" or "is invalid". An invalid object under :keep_raw can thus hold a value of the wrong class, so check valid? before trusting a value.

For arrays, a single refused element fails the whole array under the policy. The message lists zero-based indexes, never values: element at index 1: <reason>, or elements at index 1, 4 (index 1 shown): <reason>, with at most five indexes before and N more.

CoercionError has field_name (a Symbol) and original, the coercion exception, which is also its cause. The message reads could not coerce Integer input for fruit: <reason>. A field-level coercion_policy: is inherited along with the field, and a subclass that redeclares the field without it loses the override.

class Trial < FieldStruct::Base
optional :sprouts, :integer
optional :buds, :integer, coercion_policy: :replace
optional :fruit, :integer, coercion_policy: :raise
required :stems, :integer, coercion_policy: :replace
end
trial = Trial.new(sprouts: 'few', buds: 'many', stems: 'tall')
trial.sprouts # => "few"
trial.buds # => nil
trial.errors[:stems].size # => 1
trial.errors[:stems].first.start_with?('could not be coerced:') # => true
begin
Trial.new(fruit: 'ripe')
rescue FieldStruct::CoercionError => e
e.field_name # => :fruit
e.original.class # => ArgumentError
e.message.start_with?('could not coerce String input for fruit:') # => true
end

validate takes method names, which are called on the record with no arguments, or a block, which is called with the record. Every name and every block is a validator of its own. You can mix the two forms and stack calls, and validators run in declaration order. validate returns the class.

Validators run after the per-field checks: once at the end of new and with (only when the class declares any), and again on every valid?. errors[:base] is cleared before each run, so cross-field messages belong under :base. Per-field errors are left alone, which means a validator writing to a named field must clean that entry up itself. A subclass gets a copy of its parent’s validators and adds its own. An inherited one can’t be removed.

Validators have to cope with nil fields, since the record may be invalid. The library doesn’t guard against an exception raised inside a validator. assign_attributes doesn’t rerun validators, but valid? does.

class Band < FieldStruct::Base
required :coldest, :integer
required :warmest, :integer
validate :ordered
validate { |band| band.errors.add(:base, 'no variation') if band.coldest == 0 && band.warmest == 0 }
def ordered
errors.add(:base, 'warmest must exceed coldest') if coldest && warmest && warmest <= coldest
end
end
Band.new(coldest: 9, warmest: 4).errors[:base] # => ["warmest must exceed coldest"]
Band.new(coldest: 0, warmest: 0).errors[:base] # => ["warmest must exceed coldest", "no variation"]
Band.new(coldest: -2, warmest: 11).valid? # => true
band = Band.new(coldest: -2, warmest: 11)
band.warmest = -5
band.errors[:base] # => []
band.valid? # => false
band.errors[:base] # => ["warmest must exceed coldest"]

obj.errors is a FieldStruct::Errors, a plain value object that doesn’t depend on ActiveModel. Keys are Symbols, though a String key works anywhere you read one.

Member Returns
#[](field) the field’s messages, or a throwaway [] that is not stored
#add(field, message) appends a message, creating the entry if needed
#clear(field) removes the field’s entry and returns nil
#empty? true when no field has a message
#to_h, #messages {field => [messages]} for fields that have messages, a new Hash on each call, ordered by when each field first got a message
#paths {"slats[1].width" => ["is required"]}: where each message comes from, nested structs included. See below
#full_messages "Name is required": the humanized field name, a space, the message. :base gets no prefix
#inspect #<FieldStruct::Errors empty> or #<FieldStruct::Errors name=["is required"]>
#freeze freezes the message arrays too, so add and clear raise FrozenError
dup, clone a deep copy of the message arrays; a dup of frozen errors can be changed again

Humanizing swaps underscores for spaces and upcases the first character, nothing more. The inspect prefix follows use_alias!.

Error keys appear in this order: first those from the defaults pass, in declaration order, then those from the input, in input order. Take three required fields genus, species and cultivar and the input {cultivar: nil, genus: nil}: the keys are [:species, :cultivar, :genus].

errors = FieldStruct::Errors.new
errors.empty? # => true
errors.add(:leaf_color, 'is required')
errors.add(:base, 'Needs a second look')
errors['leaf_color'] # => ["is required"]
errors.full_messages # => ["Leaf color is required", "Needs a second look"]
errors.to_h # => {leaf_color: ["is required"], base: ["Needs a second look"]}
errors.inspect # => '#<FieldStruct::Errors leaf_color=["is required"] base=["Needs a second look"]>'
copy = errors.dup
copy.clear(:leaf_color)
errors.empty? # => false
errors[:missing] # => []
class Label < FieldStruct::Base
required :genus, :string
required :species, :string
required :cultivar, :string
end
Label.new(cultivar: nil, genus: nil).errors.to_h.keys # => [:species, :cultivar, :genus]

Once an instance’s errors are frozen, valid? reads them as they are and runs no validator, since a validator could no longer record anything. The errors on a frozen Actionable result are frozen this way.

class Hedge < FieldStruct::Base
required :species, :string
end
hedge = Hedge.new(species: nil)
hedge.errors.freeze
hedge.valid? # => false
begin
hedge.errors.add(:species, 'try again')
rescue FrozenError
hedge.errors[:species] # => ["is required"]
end
hedge.dup.errors.frozen? # => false

An invalid nested struct shows in to_h as one "is invalid" on the parent field. paths says which part was wrong: a nested field adds .name, an array element adds [index], a map value adds {"key"}, and a top-level field is just its name. to_h doesn’t change.

class Slat < FieldStruct::Base
required :width, :integer
end
class Trellis < FieldStruct::Base
required :bed, :string
optional :slats, :array, of: Slat
end
trellis = Trellis.new(bed: 'east', slats: [{ width: 4 }, {}])
trellis.errors.to_h # => {slats: ["is invalid"]}
trellis.errors.paths # => {"slats[1].width" => ["is required"]}
Trellis.new(slats: []).errors.paths # => {"bed" => ["is required"]}
class Arbor < FieldStruct::Base
optional :slats_by_side, :hash, of: Slat
end
Arbor.new(slats_by_side: { north: { width: 3 }, south: {} }).errors.paths
# => {"slats_by_side{\"south\"}.width" => ["is required"]}

paths reads the nested structs as they are when you call it and runs no validators. If you fix a nested struct in place, the parent still says "is invalid" (validity is computed on assignment), and since no child explains it any more, paths keeps the parent’s own entry. A failed :invalid_input run in Actionable answers paths for its input the same way.

When there are errors, inspect appends them as errors: {field: ["message"]}. It reads them as they stand and never reruns validation or validators. Sensitive values can’t show up, since messages hold no values. See Instance API.

Seedling.new(tag: 'zz').inspect # => '#<Seedling tag: "zz", count: nil, stage: nil errors: {tag: ["is invalid"]}>'

FieldStruct, Actionable and their adapters are open source under the MIT license.