Calendaring extensions N. Jenkins
Internet-Draft R. Stepanek
Intended status: Informational FastMail
Expires: November 3, 2019 May 2, 2019

JSCalendar: Converting from and to iCalendar


This document provides an informational guideline for converting JSCalendar from and to iCalendar.

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."

This Internet-Draft will expire on November 3, 2019.

Copyright Notice

Copyright (c) 2019 IETF Trust and the persons identified as the document authors. All rights reserved.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents ( in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.

Table of Contents

1. Introduction

1.1. Motivation

The JSCalendar [draft-ietf-calext-jscalendar] data format is used to represent calendar data, and is meant as an alternative to the widely deployed iCalendar [RFC5545] 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.

1.2. Scope and caveats

JSCalendar and iCalendar have a lot of semantics in common, but they are not interchangeable formats:

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.

1.3. Notational Conventions

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 [RFC2119].

2. JSEvent

A JSEvent maps to the the iCalendar VEVENT component type [RFC5545]. The following tables maps the JSEvent-specific properties to iCalendar:

Mapping JSEvent properties
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.

3. JSTask

A JSTask object maps to the iCalendar VTODO component type [RFC5545]. The following tables maps the JSTask-specific properties to iCalendar:

Mapping JSTask properties
Property iCalendar counterpart
due DUE property
estimatedDuration ESTIMATED-DURATION property in the RFC draft [draft-apthorp-ical-tasks], 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 [draft-apthorp-ical-tasks].
status STATUS property, including the definitions in the RFC draft [draft-apthorp-ical-tasks].

4. JSGroup

A JSGroup maps to a iCalendar VCALENDAR containing VEVENT or VTODO components.

Mapping JSGroup properties
Property iCalendar counterpart
entries VEVENT and VTODO components embedded in a VCALENDAR component.
source SOURCE property.

5. Common properties

This section contains recommendations how to map JSCalendar from and to iCalendar. It lists all common JSCalendar object properties in alphabetical order.

Translation between JSCalendar and iCalendar
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 [draft-ietf-calext-ical-relations].
color COLOR property, as specified in [RFC7986].
created CREATED property.
description DESCRIPTION property.
descriptionContentType Implementation-specific.
excluded EXDATE property.
freeBusyStatus TRANSP property.
isAllDay See Section 5.1.
keywords CATEGORIES property, as specified in [RFC7986].
links ATTACH ([RFC5545]), URL or IMAGE ([RFC7986]) 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 Section 5.2.
method METHOD property of the embedding VCALENDAR.
participants See Section 5.3.
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 Section 5.1.
status STATUS property.
timeZone See Section 5.1.
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 Section 5.2.

5.1. Time

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:

Mapping common time 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.

5.2. Locations

The iCalendar counterpart for JSCalendar Location objects is the iCalendar [RFC5545] LOCATION property, or implementation-specific.

Mapping Location properties
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 [RFC7986] CONFERENCE property.

Mapping virtualLocation properties
Property iCalendar counterpart
description Implementation-specific.
name LABEL parameter.
uri CONFERENCE property value.

5.3. Participants

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.

Mapping Participant properties
Property iCalendar counterpart
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.

6. Custom properties

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 [RFC7265] data.

7. Security Considerations

The same security considerations as for [draft-ietf-calext-jscalendar] apply.

8. IANA Considerations


9. Acknowledgments

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.

10. References

10.1. Normative References

[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997.
[RFC5545] Desruisseaux, B., "Internet Calendaring and Scheduling Core Object Specification (iCalendar)", RFC 5545, DOI 10.17487/RFC5545, September 2009.
[RFC7265] Kewisch, P., Daboo, C. and M. Douglass, "jCal: The JSON Format for iCalendar", RFC 7265, DOI 10.17487/RFC7265, May 2014.
[RFC7986] Daboo, C., "New Properties for iCalendar", RFC 7986, DOI 10.17487/RFC7986, October 2016.

10.2. Informative References

[draft-apthorp-ical-tasks] "Task Extensions to iCalendar"
[draft-ietf-calext-ical-relations] "Support for iCalendar Relationships"
[draft-ietf-calext-jscalendar] "Task Extensions to iCalendar"

Authors' Addresses

Neil Jenkins FastMail PO Box 234 Collins St West Melbourne, VIC 8007 Australia EMail: URI:
Robert Stepanek FastMail PO Box 234 Collins St West Melbourne, VIC 8007 Australia EMail: URI: