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 .

SUBSECOND This parameter is used to define fractional seconds for time values and durations. SUBSECOND MUST NOT be used in date-time calculations or comparisons in iCalendar. It is meant to preserve time precision on time values and duration with sub-second precision, without increasing the time value range within iCalendar. This parameter MAY be specified on properties of type DATE-TIME or DURATION. The integral part of the float value MUST be zero. The value MUST NOT be negative. iCalendar implementations SHOULD ignore this parameter in date time arithmetic. Implementations MUST ignore presence of the SUBSECOND parameter on RECURRENCE-ID properties when determining recurrence overrides. If present on a RECURRENCE-ID property, its value MUST match the SUBSECOND parameter value on the DATE-TIME property that defines the reference point for the recurring instances.

This parameter is defined by the following notation: subsecond-param = float DTSTART;SUBSECOND=0.03:20190605T133015

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. Fractional seconds SHOULD be preserved with the SUBSECOND parameter.

A JSTask object maps to the iCalendar VTODO component type . The following tables maps the JSTask-specific properties to iCalendar: Property iCalendar counterpart due Maps to the DUE property. See . estimatedDuration ESTIMATED-DURATION property in the RFC draft , or the DURATION property otherwise. Fractional seconds SHOULD be preserved with the SUBSECOND parameter. statusUpdatedAt COMPLETED property. The JSTask status property MUST have value completed. Fractional seconds SHOULD be preserved with the SUBSECOND parameter. 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 iCalendar ACTION, where both iCalendar 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. Fractional seconds SHOULD be preserved with the SUBSECOND parameter. description DESCRIPTION property. descriptionContentType Implementation-specific. excluded EXDATE property. Fractional seconds SHOULD be preserved with the SUBSECOND parameter. freeBusyStatus TRANSP property. invitedBy Implementation-specific. 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. If the DTSTART property defines a SUBSECOND parameter, but the RECURRENCE-ID of a recurrence instance does not, then use the SUBSECOND parameter value of DTSTART to determine the recurrence override time stamp. 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 LocalDateTime 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. To convert to iCalendar where the DTSTART or DUE property is of type DATE, omit the time component of the LocalDateTime value. 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. showWithoutTime Implementation-specific. start Maps to the DTSTART property. See . status STATUS property. timeZone Maps to the TZID parameter. 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. Fractional seconds SHOULD be preserved with the SUBSECOND parameter. useDefaultAlerts Implementation-specific. virtualLocations See .

iCalendar defines two different time types, DATE and DATE-TIME, where the latter may occur in three forms (with local time, with UTC time, with local time and time zone reference). In contrast, JSCalendar does not define a distinct type for dates, and date times are defined with the LocalDateTime type only. A JSCalendar time maps to the iCalendar DATE type if all of the following criteria apply: The start (due) property value has zero time, or is not set. The duration (estimatedDuration) property value has zero time, or is a multiple of days or weeks, or is not set. The timeZone property value is null, or is not set. For all other cases, the time maps to an iCalendar DATE-TIME: With local time and time zone reference, if the timeZone property value is set and does not equal Etc/UTC. With UTC time, if the timeZone property value equals Etc/UTC. With local time, if the timeZone property value is null or not set. Fractional seconds SHOULD be preserved with the SUBSECOND 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 both the replyTo property 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.