JSCalendar / RFC 8984 JSON
Build calendars with time zones and recurrence
Read, validate, build, and expand RFC 8984 calendar events and tasks in Ruby. Typed models keep JSON extensions while supporting patches, localizations, and time zone handling.
require "jscalendar"
meeting = JSCalendar::Event.build do |event|
event.title = "Weekly review"
event.start = "2026-10-12T10:00:00"
event.time_zone = "Asia/Tokyo"
event.duration = "PT1H"
event.add_recurrence_rule(frequency: "weekly", by_day: [{ day: "mo" }])
end
json = meeting.to_json
copy = JSCalendar.parse(json)
copy.start_time # => 2026-10-12 01:00:00 UTC
instances = copy.occurrences(from: Time.utc(2026, 10, 1), to: Time.utc(2026, 11, 1), limit: 100)
instances.each { |instance| puts [instance.recurrence_id, instance.start_time, instance.event.title] }
instances.truncated?Model calendar data
Build events, tasks, and groups with typed accessors while preserving unknown and vendor fields.
Expand recurrence
Generate Gregorian occurrences with time zones, exclusions, additions, and per-instance overrides.
Apply changes
Use validated object patches and language-specific localizations with configurable resource bounds.
Installation
Add the gem to your Gemfile:
gem "jscalendar"Run bundle install, then try the quick start. Requires Ruby 3.3 or later.
For supported dependencies and optional integrations, see the installation guide.
Scope & documentation
Recurrence expansion supports Gregorian calendars; non-Gregorian rules, backward/forward skip behavior, and leap-second recurrence raise UnsupportedError. iCalendar conversion, invitations, free/busy services, and alert delivery are outside scope.
Read the full documentation for supported formats, examples, and API details.