JSCalendar: Converting from and to iCalendar

The JSCalendar data format is used to represent calendar data, and is meant as an alternative to the widely deployed iCalendar data format. While new calendaring services and applications might use JSCalendar as their main data format to exchange calendaring data, they are likely to interoperate with services and clients that just support iCalendar. Similarly, existing calendaring data is stored in iCalendar format in databases and other calendar stores, and providers and users might want to represent this data also in JSCalendar. Lastly, some implementations might want to preserve custom iCalendar properties, that have no equivalent in JSCalendar when converting between these formats. To facilitate these use cases, this document provides an informational guide how to convert JSCalendar data from and to iCalendar.

JSCalendar and iCalendar have a lot of semantics in common, but they are not interchangeable formats: JSCalendar contains a richer data model to express calendar information such as event locations and participants; while future iCalendar extensions may allow a direct mapping, for now there may be no representation directly in iCalendar of some properties and these have been marked as implementation specific for mapping. iCalendar may contain arbitrary, non-standardised data with custom properties/attributes. Translating these into JSCalendar is implementation specific. iCalendar has some obsolete features that have been removed from JSCalendar due to not being useful and/or supported in the real world (e.g. custom email alerts to send to random people). Translating these may lose some of the original fidelity. Implementations may use a custom property to store data that could not be mapped directly in either direction in the original or a custom format, however this is not interoperable. Accordingly, this document does not standardize a canonical translation between iCalendar and JSCalendar, and implementations MUST NOT make any assumptions how iCalendar data is represented in JSCalendar by other systems.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in .

A JSEvent maps to the the iCalendar VEVENT component type . The following tables maps the JSEvent-specific properties to iCalendar: Property iCalendar counterpart duration DURATION property. If the VEVENT contains a DTEND property, the this maps to the duration property as the time span between DTSTART and DTEND when converting the respective time points to the UTC time zone.

A JSTask object maps to the iCalendar VTODO component type . The following tables maps the JSTask-specific properties to iCalendar: Property iCalendar counterpart due DUE property estimatedDuration ESTIMATED-DURATION property in the RFC draft , or the DURATION property otherwise. statusUpdatedAt COMPLETED property. The JSTask status property MUST have value completed. progress PARTSTAT and COMPLETED properties, including the definitions in the RFC draft . status STATUS property, including the definitions in the RFC draft .

A JSGroup maps to a iCalendar VCALENDAR containing VEVENT or VTODO components. Property iCalendar counterpart entries VEVENT and VTODO components embedded in a VCALENDAR component. source SOURCE property.

This section contains recommendations how to map JSCalendar from and to iCalendar. It lists all common JSCalendar object properties in alphabetical order. Property iCalendar counterpart @type Determined by the iCalendar component type: jsevent for VEVENT, jstask for VTODO, jsgroup for VCALENDAR. alerts Each entry maps to a VALARM component. The ACTION property maps to action, where both DISPLAY and AUDIO values map to the display action. An EMAIL value maps to a JSCalendar email action. relativeTo and offset map to the TRIGGER property. categories CONCEPT property, defined in . color COLOR property, as specified in . created CREATED property. description DESCRIPTION property. descriptionContentType Implementation-specific. excluded EXDATE property. freeBusyStatus TRANSP property. isAllDay See . keywords CATEGORIES property, as specified in . links ATTACH (), URL or IMAGE () properties with URI value types map to the the Link href. The FMTTYPE parameter maps to type, the SIZE parameter to size. Mapping other properties is implementation-specific. locale LANGUAGE parameter of the SUMMARY or DESCRIPTION property. localizations Implementation-specific. locations See . method METHOD property of the embedding VCALENDAR. participants See . priority PRIORITY property. privacy CLASS property. prodId PRODID property. recurrenceOverrides RDATE and EXDATE properties, and any VEVENT or VTODO instances with a recurrence-id and same UID as the mapped main object. recurrenceRule RRULE property. For all-day calendar objects, map the until property value to an iCalendar DATE (effectively removing the time component). To convert a DATE-typed UNTIL from iCalendar, set the time components of the LocalDate value to 23:59:59. If the iCalendar UNTIL value is a UTC date time, convert it to the local time in the JSCalendar calendar object time zone. relatedTo RELATED-TO property. replyTo An iCalendar ORGANIZER with a mailto: URI mapped to the imip method, or any other URI mapped to the other method. Mapping multiple methods is implementation-specific. sequence SEQUENCE property. start See . status STATUS property. timeZone See . timeZones Each entry in the property maps to a VTIMEZONE in the embedding VCALENDAR component. title SUMMARY property. uid UID property. updated DTSTAMP and LAST-MODIFIED properties. useDefaultAlerts Implementation-specific. virtualLocations See .

JSEvent and JSTask objects share the start, timeZone and isAllDay properties to express their occurrence in time. The following table defines how to map these properties: Property iCalendar counterpart start and non-null timeZone The start property value maps to an iCalendar DTSTART of type local DATE-TIME and the timeZone value to its TZID parameter. If the time zone is Etc/UTC, then the start time may alternatively map to an iCalendar UTC DATE-TIME without a TZID parameter. start and isAllDay is true The start property value maps to an iCalendar DTSTART property value of type DATE. When mapping from iCalendar, the time component of the start property value is zero. start and null timeZone and isAllDay is false The start property value maps to an iCalendar DTSTART of type local DATE-TIME and no TZID parameter.

The iCalendar counterpart for JSCalendar Location objects is the iCalendar LOCATION property, or implementation-specific. Property iCalendar counterpart coordinates GEO property. description Implementation-specific. linkIds Implementation-specific. name LOCATION property value. rel Implementation-specific. timeZone Implementation-specific. uri The LOCATION ALTREP parameter. The iCalendar counterpart for JSCalendar VirtualLocation objects is the iCalendar CONFERENCE property. Property iCalendar counterpart description Implementation-specific. name LABEL parameter. uri CONFERENCE property value.

The following table outlines translation of JSCalendar participants. An iCalendar ORGANIZER maps to replyTo and a participant with role owner. If an ATTENDEE with the same CAL-ADDRESS value exists, then it maps to the same participant as the ORGANIZER participant. Other participants map to ATTENDEEs. Property iCalendar counterpart attendance ROLE parameter values REQ-PARTICIPANT, OPT-PARTICIPANT and NON-PARTICIPANT. delegatedFrom DELEGATED-FROM parameter delegatedTo DELEGATED-TO parameter email EMAIL parameter, if defined. Otherwise the CAL-ADDRESS property value, if it is a mailto: URI. expectReply RSVP parameter kind CUTYPE parameter linkIds Implementation-specific. locationId Implementation-specific. memberOf MEMBER parameter name CN parameter participationStatus PARTSTAT parameter roles ROLE parameter. scheduleSequence SEQUENCE property of the participant's latest iMIP message scheduleUpdated DTSTAMP property of the participant's latest iMIP message sendTo A CAL-ADDRESS with a mailto: URI maps to the JSCalendar imip method, any other URI to the other method. Mapping multiple methods is implementation-specific.

Mapping custom or unknown properties between JSCalendar and iCalendar is implementation-specific. Implementations might use vendor-extension properties, which could also serve as basis for discussion for a JSCalendar standard extension. Alternatively, an implementation could preserve iCalendar properties and components in JSCalendar by use of a vendor-extension property formatted as jCal data.

The same security considerations as for apply.

None.

The authors would like to thank the members of CalConnect for their valuable contributions. This specification originated from the work of the API technical committee of CalConnect, the Calendaring and Scheduling Consortium.