--- 1/draft-ietf-calext-jscalendar-icalendar-00.txt 2019-06-29 09:13:15.168361260 -0700 +++ 2/draft-ietf-calext-jscalendar-icalendar-01.txt 2019-06-29 09:13:15.208362271 -0700 @@ -1,18 +1,18 @@ Calendaring extensions N. Jenkins Internet-Draft R. Stepanek Intended status: Informational FastMail -Expires: November 3, 2019 May 2, 2019 +Expires: December 31, 2019 June 29, 2019 JSCalendar: Converting from and to iCalendar - draft-ietf-calext-jscalendar-icalendar-00 + 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. @@ -20,21 +20,21 @@ 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. + 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 @@ -43,35 +43,37 @@ 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 . . . . . . . . . . . . . . . . . . . . . . . . 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 + 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 @@ -116,230 +118,284 @@ 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 +2. New iCalendar parameters - A _JSEvent_ maps to the the iCalendar VEVENT component type - [RFC5545]. The following tables maps the JSEvent-specific properties - to iCalendar: +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. + + 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 | + | | 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. | + | | zone. Fractional seconds SHOULD be preserved with the | + | | SUBSECOND parameter. | +----------+--------------------------------------------------------+ Table 1: Mapping JSEvent properties -3. JSTask +4. JSTask - A _JSTask_ object maps to the iCalendar VTODO component type - [RFC5545]. The following tables maps the JSTask-specific properties - to iCalendar: + 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 | + | 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. | + | | 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 -4. JSGroup +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 -5. Common 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. +------------------------+------------------------------------------+ | 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. | + | | 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. | + | created | CREATED property. Fractional seconds | + | | SHOULD be preserved with the SUBSECOND | + | | parameter. | | | | | description | DESCRIPTION property. | | | | | descriptionContentType | Implementation-specific. | | | | - | excluded | EXDATE property. | + | excluded | EXDATE property. Fractional seconds | + | | SHOULD be preserved with the SUBSECOND | + | | parameter. | | | | | freeBusyStatus | TRANSP property. | | | | - | isAllDay | See Section 5.1. | + | 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. | | | | | locale | LANGUAGE parameter of the SUMMARY or | | | DESCRIPTION property. | | | | | localizations | Implementation-specific. | | | | - | locations | See Section 5.2. | + | locations | See Section 6.2. | | | | | method | METHOD property of the embedding | | | VCALENDAR. | | | | - | participants | See Section 5.3. | + | 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. | + | | 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 LocalDate | + | | 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. | + | | 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. | | | | - | start | See Section 5.1. | + | showWithoutTime | Implementation-specific. | + | | | + | start | Maps to the DTSTART property. See | + | | Section 6.1. | | | | | status | STATUS property. | | | | - | timeZone | See Section 5.1. | + | 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 5.2. | + | virtualLocations | See Section 6.2. | +------------------------+------------------------------------------+ Table 4: Translation between JSCalendar and iCalendar -5.1. Time +6.1. Time properties and types - 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: + 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. - +------------+------------------------------------------------------+ - | 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 | | - +------------+------------------------------------------------------+ + A JSCalendar time maps to the iCalendar DATE type if all of the + following criteria apply: - Table 5: Mapping common time properties + o The "start" ("due") property value has zero time, or is not set. -5.2. Locations + o The "duration" ("estimatedDuration") property value has zero time, + or is a multiple of days or weeks, or is not set. + + 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. | @@ -348,44 +404,44 @@ | | | | name | LOCATION property value. | | | | | rel | Implementation-specific. | | | | | timeZone | Implementation-specific. | | | | | uri | The LOCATION ALTREP parameter. | +-------------+----------------------------------+ - Table 6: Mapping Location properties + Table 5: 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 + Table 6: Mapping virtualLocation properties -5.3. Participants +6.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. + 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 | @@ -415,71 +471,71 @@ | | | | 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 + Table 7: Mapping Participant properties -6. Custom properties +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. -7. Security Considerations +8. Security Considerations The same security considerations as for [draft-ietf-calext-jscalendar] apply. -8. IANA Considerations +9. IANA Considerations None. -9. Acknowledgments +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. -10. References +11. References -10.1. Normative 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, . [RFC5545] Desruisseaux, B., Ed., "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 +11.2. Informative References [draft-apthorp-ical-tasks] "Task Extensions to iCalendar", . [draft-ietf-calext-ical-relations] "Support for iCalendar Relationships", .