[Docs] [txt|pdf|xml|html] [Tracker] [WG] [Email] [Diff1] [Diff2] [Nits]

Versions: 00 01

Calendaring extensions                                        N. Jenkins
Internet-Draft                                               R. Stepanek
Intended status: Informational                                  FastMail
Expires: December 31, 2019                                 June 29, 2019


              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.






Jenkins & Stepanek      Expires December 31, 2019               [Page 1]


Internet-Draft                 JSCalendar                      June 2019


Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
     1.1.  Motivation  . . . . . . . . . . . . . . . . . . . . . . .   2
     1.2.  Scope and caveats . . . . . . . . . . . . . . . . . . . .   3
     1.3.  Notational Conventions  . . . . . . . . . . . . . . . . .   3
   2.  New iCalendar parameters  . . . . . . . . . . . . . . . . . .   3
     2.1.  SUBSECOND parameter . . . . . . . . . . . . . . . . . . .   3
   3.  JSEvent . . . . . . . . . . . . . . . . . . . . . . . . . . .   4
   4.  JSTask  . . . . . . . . . . . . . . . . . . . . . . . . . . .   4
   5.  JSGroup . . . . . . . . . . . . . . . . . . . . . . . . . . .   5
   6.  Common properties . . . . . . . . . . . . . . . . . . . . . .   5
     6.1.  Time properties and types . . . . . . . . . . . . . . . .   8
     6.2.  Locations . . . . . . . . . . . . . . . . . . . . . . . .   9
     6.3.  Participants  . . . . . . . . . . . . . . . . . . . . . .  10
   7.  Custom properties . . . . . . . . . . . . . . . . . . . . . .  12
   8.  Security Considerations . . . . . . . . . . . . . . . . . . .  12
   9.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  12
   10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . .  12
   11. References  . . . . . . . . . . . . . . . . . . . . . . . . .  12
     11.1.  Normative References . . . . . . . . . . . . . . . . . .  12
     11.2.  Informative References . . . . . . . . . . . . . . . . .  13
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  13

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 December 31, 2019               [Page 2]


Internet-Draft                 JSCalendar                      June 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.  New iCalendar parameters

2.1.  SUBSECOND parameter

   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.




Jenkins & Stepanek      Expires December 31, 2019               [Page 3]


Internet-Draft                 JSCalendar                      June 2019


   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:

   This parameter is defined by the following notation:

                                       subsecond-param = float

   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:

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

                    Table 1: Mapping JSEvent properties

4.  JSTask

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









Jenkins & Stepanek      Expires December 31, 2019               [Page 4]


Internet-Draft                 JSCalendar                      June 2019


   +-------------------+-----------------------------------------------+
   | Property          | iCalendar counterpart                         |
   +-------------------+-----------------------------------------------+
   | due               | Maps to the DUE property. See Section 6.1.    |
   |                   |                                               |
   | estimatedDuration | ESTIMATED-DURATION property in the RFC draft  |
   |                   | [draft-apthorp-ical-tasks], 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              |
   |                   | [draft-apthorp-ical-tasks].                   |
   |                   |                                               |
   | status            | STATUS property, including the definitions in |
   |                   | the RFC draft [draft-apthorp-ical-tasks].     |
   +-------------------+-----------------------------------------------+

                    Table 2: Mapping JSTask properties

5.  JSGroup

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

                    Table 3: Mapping JSGroup properties

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.




Jenkins & Stepanek      Expires December 31, 2019               [Page 5]


Internet-Draft                 JSCalendar                      June 2019


   +------------------------+------------------------------------------+
   | 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             |
   |                        | [draft-ietf-calext-ical-relations].      |
   |                        |                                          |
   | color                  | COLOR property, as specified in          |
   |                        | [RFC7986].                               |
   |                        |                                          |
   | 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     |
   |                        | [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.   |
   |                        |                                          |



Jenkins & Stepanek      Expires December 31, 2019               [Page 6]


Internet-Draft                 JSCalendar                      June 2019


   | locale                 | LANGUAGE parameter of the SUMMARY or     |
   |                        | DESCRIPTION property.                    |
   |                        |                                          |
   | localizations          | Implementation-specific.                 |
   |                        |                                          |
   | locations              | See Section 6.2.                         |
   |                        |                                          |
   | method                 | METHOD property of the embedding         |
   |                        | VCALENDAR.                               |
   |                        |                                          |
   | participants           | See Section 6.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. 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              |



Jenkins & Stepanek      Expires December 31, 2019               [Page 7]


Internet-Draft                 JSCalendar                      June 2019


   |                        | implementation-specific.                 |
   |                        |                                          |
   | sequence               | SEQUENCE property.                       |
   |                        |                                          |
   | showWithoutTime        | Implementation-specific.                 |
   |                        |                                          |
   | start                  | Maps to the DTSTART property. See        |
   |                        | Section 6.1.                             |
   |                        |                                          |
   | status                 | STATUS property.                         |
   |                        |                                          |
   | timeZone               | Maps to the TZID parameter.  See Section |
   |                        | 6.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.    |
   |                        | Fractional seconds SHOULD be preserved   |
   |                        | with the SUBSECOND parameter.            |
   |                        |                                          |
   | useDefaultAlerts       | Implementation-specific.                 |
   |                        |                                          |
   | virtualLocations       | See Section 6.2.                         |
   +------------------------+------------------------------------------+

           Table 4: Translation between JSCalendar and iCalendar

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:

   o  The "start" ("due") property value has zero time, or is not set.

   o  The "duration" ("estimatedDuration") property value has zero time,
      or is a multiple of days or weeks, or is not set.



Jenkins & Stepanek      Expires December 31, 2019               [Page 8]


Internet-Draft                 JSCalendar                      June 2019


   o  The "timeZone" property value is null, or is not set.

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

   o  With local time and time zone reference, if the "timeZone"
      property value is set and does not equal "Etc/UTC".

   o  With UTC time, if the "timeZone" property value equals "Etc/UTC".

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

            +-------------+----------------------------------+
            | 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 5: Mapping Location properties

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










Jenkins & Stepanek      Expires December 31, 2019               [Page 9]


Internet-Draft                 JSCalendar                      June 2019


              +-------------+------------------------------+
              | Property    | iCalendar counterpart        |
              +-------------+------------------------------+
              | description | Implementation-specific.     |
              |             |                              |
              | name        | LABEL parameter.             |
              |             |                              |
              | uri         | CONFERENCE property value.   |
              +-------------+------------------------------+

                Table 6: Mapping virtualLocation properties

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.
































Jenkins & Stepanek      Expires December 31, 2019              [Page 10]


Internet-Draft                 JSCalendar                      June 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 7: Mapping Participant properties








Jenkins & Stepanek      Expires December 31, 2019              [Page 11]


Internet-Draft                 JSCalendar                      June 2019


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

   [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 December 31, 2019              [Page 12]


Internet-Draft                 JSCalendar                      June 2019


11.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 December 31, 2019              [Page 13]


Html markup produced by rfcmarkup 1.129c, available from https://tools.ietf.org/tools/rfcmarkup/