---
title: "Convert vCard to jCard and xCard in C#"
url: https://recursiveai.org/onemail/cookbook/convert-vcard-to-jcard-and-xcard/
description: "Convert a vCard contact to jCard JSON and xCard XML in C#. Inspect conversion losses and read both outputs back into a vCard component tree."
version: "1.0.1"
---

# 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.

[NuGet](https://www.nuget.org/packages/RecursiveAI.OneMail.Calendar) · [GitHub](https://github.com/recursive-ai-oss/onemail-csharp) · [Docs](https://recursiveai.org/onemail/docs/) · [Download example (.zip)](https://recursiveai.org/onemail/cookbook/convert-vcard-to-jcard-and-xcard/convert-vcard-to-jcard-and-xcard.zip)

[jCard](https://www.rfc-editor.org/rfc/rfc7095.html) and [xCard](https://www.rfc-editor.org/rfc/rfc6351.html) represent vCard contacts as JSON and XML. `contact.vcf` is in the download and shown below.

```shell
dotnet add package RecursiveAI.OneMail.Calendar
```

Requires [.NET 10](https://dotnet.microsoft.com/download/dotnet/10.0) (net10.0); .NET 9 and earlier aren’t supported.

```csharp
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](https://recursiveai.org/onemail/cookbook/convert-vcard-to-jcard-and-xcard/convert-vcard-to-jcard-and-xcard.zip), 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.

```csharp
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:

```csharp
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
```

## Related recipes

- [Expand recurring iCalendar events in C#](https://recursiveai.org/onemail/cookbook/expand-recurring-calendar-events/)
- [Convert ICS to jCal and xCal in C#](https://recursiveai.org/onemail/cookbook/convert-ics-to-jcal-and-xcal/)
- [Parse email bounce delivery status in C#](https://recursiveai.org/onemail/cookbook/parse-delivery-status-notification/)

## 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](https://recursiveai.org/onemail/docs/jcal-xcal/) for the exact choices.

xCard uses the XML namespace and property forms defined by [RFC 6351](https://www.rfc-editor.org/rfc/rfc6351.html). 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](https://www.rfc-editor.org/rfc/rfc6350.html#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.
