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
draft-ietf-calext-jscalendar-icalendar-00
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 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
(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.
Jenkins & Stepanek Expires November 3, 2019 [Page 1]
Internet-Draft JSCalendar May 2019
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Motivation . . . . . . . . . . . . . . . . . . . . . . . 2
1.2. Scope and caveats . . . . . . . . . . . . . . . . . . . . 3
1.3. Notational Conventions . . . . . . . . . . . . . . . . . 3
2. JSEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. JSTask . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
4. JSGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
5. Common properties . . . . . . . . . . . . . . . . . . . . . . 5
5.1. Time . . . . . . . . . . . . . . . . . . . . . . . . . . 7
5.2. Locations . . . . . . . . . . . . . . . . . . . . . . . . 8
5.3. Participants . . . . . . . . . . . . . . . . . . . . . . 9
6. Custom properties . . . . . . . . . . . . . . . . . . . . . . 11
7. Security Considerations . . . . . . . . . . . . . . . . . . . 11
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11
9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 11
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 11
10.1. Normative References . . . . . . . . . . . . . . . . . . 11
10.2. Informative References . . . . . . . . . . . . . . . . . 12
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 12
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.
Jenkins & Stepanek Expires November 3, 2019 [Page 2]
Internet-Draft JSCalendar May 2019
1.2. Scope and caveats
JSCalendar and iCalendar have a lot of semantics in common, but they
are not interchangeable formats:
o 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.
o iCalendar may contain arbitrary, non-standardised data with custom
properties/attributes. Translating these into JSCalendar is
implementation specific.
o 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.
o 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. JSEvent
A _JSEvent_ maps to the the iCalendar VEVENT component type
[RFC5545]. The following tables maps the JSEvent-specific properties
to iCalendar:
Jenkins & Stepanek Expires November 3, 2019 [Page 3]
Internet-Draft JSCalendar May 2019
+----------+--------------------------------------------------------+
| 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. |
+----------+--------------------------------------------------------+
Table 1: Mapping JSEvent properties
3. JSTask
A _JSTask_ object maps to the iCalendar VTODO component type
[RFC5545]. The following tables maps the JSTask-specific properties
to iCalendar:
+-------------------+-----------------------------------------------+
| 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]. |
+-------------------+-----------------------------------------------+
Table 2: Mapping JSTask properties
4. JSGroup
A JSGroup maps to a iCalendar VCALENDAR containing VEVENT or VTODO
components.
Jenkins & Stepanek Expires November 3, 2019 [Page 4]
Internet-Draft JSCalendar May 2019
+----------+--------------------------------------------------------+
| Property | iCalendar counterpart |
+----------+--------------------------------------------------------+
| entries | VEVENT and VTODO components embedded in a VCALENDAR |
| | component. |
| | |
| source | SOURCE property. |
+----------+--------------------------------------------------------+
Table 3: Mapping JSGroup properties
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.
+------------------------+------------------------------------------+
| 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. |
| | |
Jenkins & Stepanek Expires November 3, 2019 [Page 5]
Internet-Draft JSCalendar May 2019
| 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. |
| | |
Jenkins & Stepanek Expires November 3, 2019 [Page 6]
Internet-Draft JSCalendar May 2019
| 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. |
+------------------------+------------------------------------------+
Table 4: Translation between JSCalendar and iCalendar
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:
Jenkins & Stepanek Expires November 3, 2019 [Page 7]
Internet-Draft JSCalendar May 2019
+------------+------------------------------------------------------+
| Property | iCalendar counterpart |
+------------+------------------------------------------------------+
| start and | The _start_ property value maps to an iCalendar |
| non-null | DTSTART of type local DATE-TIME and the _timeZone_ |
| 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 | The _start_ property value maps to an iCalendar |
| isAllDay | DTSTART property value of type DATE. When mapping |
| is true | from iCalendar, the time component of the _start_ |
| | property value is zero. |
| | |
| start and | The _start_ property value maps to an iCalendar |
| null | DTSTART of type local DATE-TIME and no TZID |
| timeZone | parameter. |
| and | |
| isAllDay | |
| is false | |
+------------+------------------------------------------------------+
Table 5: Mapping common time properties
5.2. Locations
The iCalendar counterpart for JSCalendar Location objects is the
iCalendar [RFC5545] LOCATION property, or implementation-specific.
Jenkins & Stepanek Expires November 3, 2019 [Page 8]
Internet-Draft JSCalendar May 2019
+-------------+----------------------------------+
| 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. |
+-------------+----------------------------------+
Table 6: Mapping Location properties
The iCalendar counterpart for JSCalendar VirtualLocation objects is
the iCalendar [RFC7986] CONFERENCE property.
+-------------+------------------------------+
| Property | iCalendar counterpart |
+-------------+------------------------------+
| description | Implementation-specific. |
| | |
| name | LABEL parameter. |
| | |
| uri | CONFERENCE property value. |
+-------------+------------------------------+
Table 7: Mapping virtualLocation properties
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.
Jenkins & Stepanek Expires November 3, 2019 [Page 9]
Internet-Draft JSCalendar May 2019
+---------------------+---------------------------------------------+
| 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. |
+---------------------+---------------------------------------------+
Table 8: Mapping Participant properties
Jenkins & Stepanek Expires November 3, 2019 [Page 10]
Internet-Draft JSCalendar May 2019
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
None.
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,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and
Scheduling Core Object Specification (iCalendar)",
RFC 5545, DOI 10.17487/RFC5545, September 2009,
<https://www.rfc-editor.org/info/rfc5545>.
[RFC7265] Kewisch, P., Daboo, C., and M. Douglass, "jCal: The JSON
Format for iCalendar", RFC 7265, DOI 10.17487/RFC7265, May
2014, <https://www.rfc-editor.org/info/rfc7265>.
[RFC7986] Daboo, C., "New Properties for iCalendar", RFC 7986,
DOI 10.17487/RFC7986, October 2016,
<https://www.rfc-editor.org/info/rfc7986>.
Jenkins & Stepanek Expires November 3, 2019 [Page 11]
Internet-Draft JSCalendar May 2019
10.2. Informative References
[draft-apthorp-ical-tasks]
"Task Extensions to iCalendar",
<https://tools.ietf.org/html/draft-apthorp-ical-tasks>.
[draft-ietf-calext-ical-relations]
"Support for iCalendar Relationships",
<https://tools.ietf.org/html/
draft-ietf-calext-ical-relations>.
[draft-ietf-calext-jscalendar]
"Task Extensions to iCalendar",
<https://tools.ietf.org/html/
draft-ietf-calext-jscalendar>.
Authors' Addresses
Neil Jenkins
FastMail
PO Box 234
Collins St West
Melbourne VIC 8007
Australia
Email: neilj@fastmailteam.com
URI: https://www.fastmail.com
Robert Stepanek
FastMail
PO Box 234
Collins St West
Melbourne VIC 8007
Australia
Email: rsto@fastmailteam.com
URI: https://www.fastmail.com
Jenkins & Stepanek Expires November 3, 2019 [Page 12]
