JSContact 1.0 / 2.0 · vCard 4.0
Build contact cards that preserve your data
Read, validate, and build JSContact 1.0 and 2.0 contact cards in Ruby. Preserve valid extension fields and optionally convert vCard 4.0 through jcard_jcal.
require "jscontact"
card = JSContact::Card.build do |contact|
contact.name = { full: "Mina Sample" }
contact.add_email(address: "mina@example.test", contexts: { work: true })
contact["example.test:customer"] = { "number" => 42 }
end
card.name.full # => "Mina Sample"
card.emails["e1"].address # => "mina@example.test"
card.emails["e1"].label = "Desk" # updates the parent card
card.to_h # independent, deep copy
json = card.to_json # validates before serializing
copy = JSContact.parse(json)Work with typed cards
Build names, addresses, and contact methods with typed views and validated JSON serialization.
Preserve extensions
Keep unknown properties and map identifiers while applying patches and localized text.
Connect to vCard
Convert vCard 4.0 with optional jcard_jcal support and retain otherwise unmatched properties.
Installation
Add the gem to your Gemfile:
gem "jscontact"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
The optional converter requires jcard_jcal and accepts one vCard 4.0 at a time. vCard 2.1/3.0, CardDAV synchronization, and non-Gregorian calendar arithmetic are outside scope. Some values, including top-level extension nulls, cannot be converted and raise ConversionError.
Read the full documentation for supported formats, examples, and API details.