Recursive AI

Convert vCard to jCard and xCard in C#

OneMail is a free, open-source email library for .NET from Recursive AI. MIT or Apache-2.0, no native dependencies.

jCard and xCard represent vCard contacts as JSON and XML. contact.vcf is in the download and shown below.

Terminal
dotnet add package RecursiveAI.OneMail.Calendar

Requires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.

C#
using RecursiveAI.OneMail.Calendar;
using RecursiveAI.OneMail.Calendar.Forms;
 
var doc = ContentDocument.Parse(
    File.ReadAllBytes("contact.vcf"));
File.WriteAllBytes("contact.json",
    JsonForms.ToJson(doc).Bytes);
File.WriteAllBytes("contact.xml",
    XmlForms.ToXCard(doc).Bytes);
Console.WriteLine("Wrote JSON and XML.");

Unzip the example, then dotnet run.

The snippet at the top prints:

Text
Wrote JSON and XML.

The full program

The download’s Program.cs also lists conversion losses.

C#
using RecursiveAI.OneMail.Calendar;
using RecursiveAI.OneMail.Calendar.Forms;
 
var doc = ContentDocument.Parse(File.ReadAllBytes("contact.vcf"));
var json = JsonForms.ToJson(doc);
var xml = XmlForms.ToXCard(doc);
File.WriteAllBytes("contact.json", json.Bytes);
File.WriteAllBytes("contact.xml", xml.Bytes);
Console.WriteLine("Wrote contact.json and contact.xml");
Console.WriteLine($"JSON losses: {json.Losses.Count}; XML losses: {xml.Losses.Count}");
foreach (var loss in json.Losses)
    Console.WriteLine($"JSON: {loss.Kind}");
foreach (var loss in xml.Losses)
    Console.WriteLine($"XML: {loss.Kind}");
Text
Wrote contact.json and contact.xml
JSON losses: 0; XML losses: 0

contact.json contains this formatted-name property (excerpt):

JSON
["fn",{},"text","Alex Example"]

The corresponding property in contact.xml (excerpt):

XML
<fn>
  <text>Alex Example</text>
</fn>

Writing reports what the destination cannot carry in Losses; reading reports repairs in Defects rather than throwing on content.

The input, contact.vcf, is a synthetic example included in the zip. It uses CRLF line endings.

Text
BEGIN:VCARD
VERSION:4.0
FN:Alex Example
N:Example;Alex;;;
EMAIL:alex@example.org
END:VCARD

Variations

Append this to the full program to read both forms back and save the reconstructed text files:

C#
var fromJson = JsonForms.FromJson(json.Bytes);
var fromXml = XmlForms.FromXml(xml.Bytes);
File.WriteAllBytes("from-json.vcf", fromJson.Document.ToArray());
File.WriteAllBytes("from-xml.vcf", fromXml.Document.ToArray());
Console.WriteLine($"Read defects: {fromJson.Defects.Count}, {fromXml.Defects.Count}");

Additional output:

Text
Read defects: 0, 0

The short answer

Parse the VCF text into a ContentDocument, call JsonForms.ToJson to produce jCard and XmlForms.ToXCard to produce xCard, then write the returned bytes. Both write results include Losses. Read the forms back with FromJson or FromXml and inspect their Defects before using the reconstructed contact tree.

The example converts an invented vCard contact. It does not extract contacts from a mailbox, access an address-book account or define a custom JSON schema. The files it writes follow the standard JSON and XML forms linked above.

How can I convert a vCard file?

Use the downloaded program with contact.vcf, then replace that input with your own card. Keep the loss-report loops: a conversion can write a file even when the destination cannot represent every source detail. The synthetic card uses VERSION:4.0, a formatted name, a structured name and an email address. It produces no reported losses in either form.

jCard maps contact properties into typed JSON arrays. It is not the same thing as serializing an object with name and email keys. Structured values such as N and ADR become arrays; TYPE and related multi-value parameters have their standard array forms. A grouped property name becomes a group parameter. See the mapping reference for the exact choices.

xCard uses the XML namespace and property forms defined by RFC 6351. Use it when the receiver explicitly asks for xCard, not simply because it accepts XML. The receiver still needs to understand the same contact representation.

Are VCF and vCard the same?

VCF is the usual filename extension for a vCard file; vCard names the contact format. RFC 6350 section 10.1 registers the vcf extension for text/vcard. Renaming contact.vcf to contact.json does not convert its contents. The JSON and XML writers do that conversion by mapping the parsed properties.

OneMail reads vCard 2.1, 3.0 and 4.0, but xCard is the 4.0 representation. The XML writer does not carry the VERSION property. A 3.0 card is written using the 4.0 forms of properties that differ, such as a geo URI for GEO and PREF=1 for TYPE=pref. The writer reports version-related transformations through its loss model. A 3.0 card converted through xCard comes back as vCard 4.0.

Inline binary fields in older cards become data URIs because jCard and xCard have no binary type. A contact with photos or encoded legacy fields therefore deserves inspection beyond checking that the output exists.

Can VCF files be converted back from JSON or XML?

Yes, when the input is jCard or xCard. The variation reads each output into a new ContentDocument and writes from-json.vcf and from-xml.vcf. Both reads have zero reported defects for the synthetic card. That result applies to this contact, not to every possible vCard.

Reading and writing have separate reports. FormLoss describes something not carried into a form; FormDefect describes a repair while reading one. Reading back cannot restore discarded folding, stray lines or an XML-incompatible name. Keep the original VCF if you need its exact source bytes.

For a value that cannot be parsed as its declared type, OneMail can carry the raw text as unknown and report ValueNotRepresentable. Decide whether your contact importer permits that result. A writable contact tree is not a promise that every downstream address book will accept all its properties.

All onemail recipes