jcard_jcal

vCard ↔ jCard / iCalendar ↔ jCal

Convert contact and calendar formats in Ruby

Convert vCard 4.0 and iCalendar text to and from jCard and jCal. Handle structured values, nested calendar components, escaping, and line folding through a Ruby API.

Get started Read the documentation

Ruby 3.3+MIT licenseRubyGems

Quick startRuby
require "jcard_jcal" # or require "jcard" / require "jcal"

card = JCard.from_vcard("BEGIN:VCARD\nVERSION:4.0\nFN:Alice\nEND:VCARD\n").first
card.properties("fn").first.values # => ["Alice"]
card.to_json                       # => '["vcard",[["version",{},"text","4.0"],["fn",{},"text","Alice"]]]'
card.to_vcard                      # CRLF line endings, UTF-8 safe folding

calendar = JCal.from_ical(<<~ICAL)
  BEGIN:VCALENDAR
  VERSION:2.0
  PRODID:-//Example//Calendar//EN
  BEGIN:VEVENT
  UID:review@example.test
  DTSTAMP:20261001T090000Z
  DTSTART:20261012T010000Z
  SUMMARY:Weekly review
  END:VEVENT
  END:VCALENDAR
ICAL
calendar.components("vevent").each do |event|
  puts event.property("dtstart")&.values
end
JCal.parse(calendar.to_json).to_ical

Installation

Add the gem to your Gemfile:

gem "jcard_jcal"

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

vCard support is limited to version 4.0. Calendar semantic rules, time zone conversion, recurrence expansion, and CardDAV/CalDAV transport are outside scope. Text serialization normalizes equivalent representations rather than preserving identical bytes.

Read the full documentation for supported formats, examples, and API details.