Skip to content

How to handle dates, times and time zones

A Planting takes a date and a watering time from a form, and every machine has to read them the same way.

With no format:, a date or time field reads a String through the standard library, and that is lenient. When you know what the input looks like, declare it. A preset such as :us or :eu is shorthand for a strptime String, and a String is used as given.

class Planting < FieldStruct::Base
required :crop, :string
required :day, :date, format: :eu
optional :watering, :time, format: '%H:%M', zone: 'UTC'
end
planting = Planting.new(crop: 'Tulips', day: '14/04/2026')
planting.day.iso8601 # => "2026-04-14"
Planting.new(crop: 'Tulips', day: '14/04/2026 ').valid? # => false
Planting.new(crop: 'Tulips', day: '31/04/2026').valid? # => false

A declared format must match the whole String, so a trailing space fails, and the day must exist on the calendar. as_json writes with the same format, which means a JSON round trip keeps it.

For timestamps that travel between systems, use format: :iso8601. That means RFC 3339, so a String without an offset is refused, not guessed at.

class Sample < FieldStruct::Base
required :rain_mm, :float
required :taken_at, :time, format: :iso8601
end
Sample.new(rain_mm: '4.5', taken_at: '2026-04-14T06:15:00-06:00').taken_at.utc_offset # => -21600
Sample.new(rain_mm: '4.5', taken_at: '2026-04-14T06:15:00').valid? # => false
Sample.new(rain_mm: '4.5', taken_at: '2026-04-14 06:15:00Z').valid? # => false

A wall-clock String with no offset is ambiguous. Without zone: it lands in whatever zone the process happens to run in. Declare the zone and the gem applies the offset that was in force on that date.

class Watering < FieldStruct::Base
required :starts, :time, zone: 'America/Chicago'
end
Watering.new(starts: '2026-07-01 10:00').starts.utc_offset # => -18000
Watering.new(starts: '2026-01-15 10:00').starts.utc_offset # => -21600
Watering.new(starts: '2026-07-01 10:00 +02:00').starts.utc_offset # => 7200

zone: accepts "UTC", a fixed offset like "-06:00" (the colon is required) or an IANA name with a slash. An abbreviation such as "CST" raises when the class is defined, which beats silently meaning something else. A String or object that carries its own offset keeps it.

With an IANA zone, a time the clock skips is refused. A time the clock repeats is read at the earlier, daylight offset.

Watering.new(starts: '2026-03-08 02:30').valid? # => false
Watering.new(starts: '2026-11-01 01:30').starts.utc_offset # => -18000

What you get back is a plain Time with the resolved offset. It doesn’t remember the zone, so adding days to it won’t follow daylight saving. If you need a fresh reading, assign the field again from the String.

In tests, use a fixed timestamp and a declared zone:. A format that covers only part of a day, like '%H:%M' above, fills in today’s date, so assert on hour and min rather than on the whole value.

Planting.new(crop: 'Tulips', day: '14/04/2026', watering: '07:45').watering.hour # => 7

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