jCal and xCal represent iCalendar data as JSON and XML. events.ics is in the download and shown below.
dotnet add package RecursiveAI.OneMail.CalendarRequires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.
using RecursiveAI.OneMail.Calendar; using RecursiveAI.OneMail.Calendar.Forms; var doc = ContentDocument.Parse( File.ReadAllBytes("events.ics")); File.WriteAllBytes("calendar.json", JsonForms.ToJson(doc).Bytes); File.WriteAllBytes("calendar.xml", XmlForms.ToXCal(doc).Bytes); Console.WriteLine("Wrote JSON and XML.");
Unzip the example, then dotnet run.
The snippet at the top prints:
Wrote JSON and XML.The full program
The download’s Program.cs also lists conversion losses.
using RecursiveAI.OneMail.Calendar; using RecursiveAI.OneMail.Calendar.Forms; var doc = ContentDocument.Parse(File.ReadAllBytes("events.ics")); var json = JsonForms.ToJson(doc); var xml = XmlForms.ToXCal(doc); File.WriteAllBytes("calendar.json", json.Bytes); File.WriteAllBytes("calendar.xml", xml.Bytes); Console.WriteLine("Wrote calendar.json and calendar.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}");
Wrote calendar.json and calendar.xml JSON losses: 0; XML losses: 0
calendar.json contains this start-time property (excerpt):
["dtstart",{"tzid":"America/New_York"},"date-time","2026-03-02T09:00:00"]The corresponding property in calendar.xml (excerpt):
<dtstart> <parameters> <tzid> <text>America/New_York</text> </tzid> </parameters> <date-time>2026-03-02T09:00:00</date-time> </dtstart>
Writing reports what the destination cannot carry in Losses; reading reports repairs in Defects rather than throwing on content.
The input, events.ics, is a synthetic example included in the zip. It uses CRLF line endings.
BEGIN:VCALENDAR VERSION:2.0 PRODID:-//Example//Calendar//EN BEGIN:VEVENT UID:meeting@example.org DTSTAMP:20260301T000000Z DTSTART;TZID=America/New_York:20260302T090000 DTEND;TZID=America/New_York:20260302T100000 RRULE:FREQ=WEEKLY;COUNT=4 EXDATE;TZID=America/New_York:20260309T090000 SUMMARY:Planning END:VEVENT END:VCALENDAR
Variations
Append this to the full program to read both forms back and save the reconstructed text files:
var fromJson = JsonForms.FromJson(json.Bytes); var fromXml = XmlForms.FromXml(xml.Bytes); File.WriteAllBytes("from-json.ics", fromJson.Document.ToArray()); File.WriteAllBytes("from-xml.ics", fromXml.Document.ToArray()); Console.WriteLine($"Read defects: {fromJson.Defects.Count}, {fromXml.Defects.Count}");
Additional output:
Read defects: 0, 0Related recipes
- Expand recurring iCalendar events in C#
- Convert vCard to jCard and xCard in C#
- Parse email bounce delivery status in C#
The short answer
Use JsonForms.ToJson for jCal and XmlForms.ToXCal for xCal after parsing the ICS into a ContentDocument. Save each result’s Bytes and inspect its Losses. Reading goes in the opposite direction through JsonForms.FromJson and XmlForms.FromXml, which return a document and a list of FormDefect entries.
The sample converts a whole calendar rather than inventing a JSON object from selected event fields. Its recurrence, exclusion and time-zone identifier remain calendar properties. Conversion does not expand the recurring event or fetch appointments from a calendar service.
What is the ICS format?
ICS is the text form of iCalendar: a VCALENDAR component can contain VEVENTs, time-zone definitions and other components. Property lines hold names, parameters and values. The sample’s DTSTART has a TZID parameter; its RRULE and EXDATE together describe a weekly series with a removed date. RFC 5545 defines the calendar format.
jCal is its standardized JSON representation, not an arbitrary event DTO. Component and property names become lower case, values carry a type, and structured values retain their structure. Recurrence rules become objects with lower-case part names. Dates and times use the extended spelling in the JSON and XML forms. Those mappings are documented in OneMail’s forms reference.
Use jCal when the receiving system expects RFC 7265 JSON and xCal when it expects RFC 6321 XML. If an endpoint expects its own fields such as a provider-specific event ID or attendee object, sending jCal just because the endpoint accepts JSON is not enough. The format contract must agree on both ends.
How do you convert a sample ICS file to JSON and XML?
Start with the sample shown above and run the download. It writes calendar.json and calendar.xml and prints a loss count for each direction. Both counts are zero for this input. Replace events.ics with your own file to use the same program; keep the loss-report loop when doing so.
A FormLoss describes something the destination cannot carry, with a kind, property path and count. This is distinct from a parse error. Text folding, blank or malformed lines, duplicate parameters and invalid XML characters are among the documented loss kinds. A form can represent the calendar’s meaning while changing how the original text was arranged.
The writer does not modify the parsed text document. Keep the original bytes if exact source preservation matters. Do not use a successful JSON or XML write as evidence that the source was a valid calendar or that no information was lost: the result object supplies the information needed to make that decision.
How do you read jCal or xCal back into ICS?
Reading the JSON or XML back produces a new calendar tree, as the variation demonstrates. Save that tree’s ToArray() result to get ICS text again. Check Defects on each read result. A repair is reported rather than hidden behind a thrown content exception.
This round trip is not a general ICS repair service. It cannot recover a malformed source line that the form did not carry. Decide which loss kinds your application accepts before replacing an original file. A harmless change in folding may be acceptable for an export; dropping an unrecognized property may not be.
XML input prohibits document type declarations and has no resolver. Readers also apply input, depth, node and string limits described in the forms reference. Keep those defaults unless you have a specific reason to change them; a bounded read with defects is different from assuming any document that parses is complete.