JSCalendar: Converting from and to iCalendar
draft-ietf-calext-jscalendar-icalendar-01

Abstract

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 https://datatracker.ietf.org/drafts/current/.

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 December 31, 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 (https://trustee.ietf.org/license-info) 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
• 1.2. Scope and caveats
• 1.3. Notational Conventions
• 2. New iCalendar parameters
• 2.1. SUBSECOND parameter
• 3. JSEvent
• 4. JSTask
• 5. JSGroup
• 6. Common properties
• 6.1. Time properties and types
• 6.2. Locations
• 6.3. Participants
• 7. Custom properties
• 8. Security Considerations
• 9. IANA Considerations
• 10. Acknowledgments
• 11. References
• 11.1. Normative References
• 11.2. Informative References
• Authors' Addresses

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:

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

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. New iCalendar parameters

2.1. SUBSECOND parameter

This parameter is defined by the following notation:

                                    subsecond-param = float
                                

Parameter name:

SUBSECOND

Purpose:

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.

Description:

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.

Format Definition:

Example:

DTSTART;SUBSECOND=0.03:20190605T133015

3. JSEvent

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

4. JSTask

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

5. JSGroup

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

6. Common properties

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

6.1. Time properties and types

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:

For all other cases, the time maps to an iCalendar DATE-TIME:

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

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

6.2. Locations

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

The iCalendar counterpart for JSCalendar VirtualLocation objects is the iCalendar [RFC7986] CONFERENCE property.

6.3. Participants

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.

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

8. Security Considerations

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

9. IANA Considerations

None.

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

11. References

11.1. Normative References

11.2. Informative References

Authors' Addresses