Calendaring extensions R. Stepanek Internet-Draft Fastmail Intended status: Experimental 4 November 2024 Expires: 8 May 2025 JSCalendar: Converting from and to iCalendar draft-ietf-calext-jscalendar-icalendar-08 Abstract This document defines how to convert calendaring information between the JSCalendar and iCalendar data formats. It considers every JSCalendar and iCalendar element registered at IANA at the time of publication. It defines conversion rules for all elements that are common to both formats, as well as how convert arbitrary or unknown JSCalendar and iCalendar elements. Note This note is to be removed before publishing as an RFC. This document is unfinished. The term TBD stands for any unknown item. 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 8 May 2025. Copyright Notice Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. Stepanek Expires 8 May 2025 [Page 1] Internet-Draft JSCalendar November 2024 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 Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4 1.2. Scope and Goals . . . . . . . . . . . . . . . . . . . . . 4 1.3. How to Read the Examples . . . . . . . . . . . . . . . . 5 1.3.1. iCalendar Examples . . . . . . . . . . . . . . . . . 5 1.3.2. JSCalendar Examples . . . . . . . . . . . . . . . . . 7 2. Converting iCalendar to JSCalendar . . . . . . . . . . . . . 8 2.1. General rules . . . . . . . . . . . . . . . . . . . . . . 8 2.1.1. iCalendar Objects . . . . . . . . . . . . . . . . . . 8 2.1.2. Recurring Components . . . . . . . . . . . . . . . . 10 2.1.3. JSCalendar Ids . . . . . . . . . . . . . . . . . . . 13 2.1.4. Timezone identifiers . . . . . . . . . . . . . . . . 14 2.1.5. DATE and DATE-TIME . . . . . . . . . . . . . . . . . 15 2.2. Components . . . . . . . . . . . . . . . . . . . . . . . 15 2.2.1. PARTICIPANT . . . . . . . . . . . . . . . . . . . . . 15 2.2.2. VALARM . . . . . . . . . . . . . . . . . . . . . . . 17 2.2.3. VEVENT . . . . . . . . . . . . . . . . . . . . . . . 19 2.2.4. VLOCATION . . . . . . . . . . . . . . . . . . . . . . 24 2.2.5. VRESOURCE . . . . . . . . . . . . . . . . . . . . . . 25 2.2.6. VTIMEZONE . . . . . . . . . . . . . . . . . . . . . . 27 2.2.7. VTODO . . . . . . . . . . . . . . . . . . . . . . . . 31 2.3. Properties . . . . . . . . . . . . . . . . . . . . . . . 36 2.3.1. ACKNOWLEDGED . . . . . . . . . . . . . . . . . . . . 36 2.3.2. ACTION . . . . . . . . . . . . . . . . . . . . . . . 36 2.3.3. ATTACH . . . . . . . . . . . . . . . . . . . . . . . 38 2.3.4. ATTENDEE . . . . . . . . . . . . . . . . . . . . . . 39 2.3.5. CALENDAR-ADDRESS . . . . . . . . . . . . . . . . . . 41 2.3.6. CATEGORIES . . . . . . . . . . . . . . . . . . . . . 42 2.3.7. CLASS . . . . . . . . . . . . . . . . . . . . . . . . 42 2.3.8. COLOR . . . . . . . . . . . . . . . . . . . . . . . . 43 2.3.9. COMMENT . . . . . . . . . . . . . . . . . . . . . . . 43 2.3.10. CONCEPT . . . . . . . . . . . . . . . . . . . . . . . 45 2.3.11. CONFERENCE . . . . . . . . . . . . . . . . . . . . . 46 2.3.12. CREATED . . . . . . . . . . . . . . . . . . . . . . . 47 2.3.13. DESCRIPTION . . . . . . . . . . . . . . . . . . . . . 47 2.3.14. DTEND . . . . . . . . . . . . . . . . . . . . . . . . 48 2.3.15. DTSTAMP . . . . . . . . . . . . . . . . . . . . . . . 49 Stepanek Expires 8 May 2025 [Page 2] Internet-Draft JSCalendar November 2024 2.3.16. DTSTART . . . . . . . . . . . . . . . . . . . . . . . 50 2.3.17. DUE . . . . . . . . . . . . . . . . . . . . . . . . . 51 2.3.18. DURATION . . . . . . . . . . . . . . . . . . . . . . 52 2.3.19. EXDATE . . . . . . . . . . . . . . . . . . . . . . . 53 2.3.20. EXRULE . . . . . . . . . . . . . . . . . . . . . . . 54 2.3.21. GEO . . . . . . . . . . . . . . . . . . . . . . . . . 54 2.3.22. IMAGE . . . . . . . . . . . . . . . . . . . . . . . . 55 2.3.23. LAST-MODIFIED . . . . . . . . . . . . . . . . . . . . 56 2.3.24. LINK . . . . . . . . . . . . . . . . . . . . . . . . 56 2.3.25. LOCATION . . . . . . . . . . . . . . . . . . . . . . 58 2.3.26. LOCATION-TYPE . . . . . . . . . . . . . . . . . . . . 59 2.3.27. METHOD . . . . . . . . . . . . . . . . . . . . . . . 59 2.3.28. NAME . . . . . . . . . . . . . . . . . . . . . . . . 60 2.3.29. ORGANIZER . . . . . . . . . . . . . . . . . . . . . . 61 2.3.30. PARTICIPANT-TYPE . . . . . . . . . . . . . . . . . . 63 2.3.31. PERCENT-COMPLETE . . . . . . . . . . . . . . . . . . 64 2.3.32. PRIORITY . . . . . . . . . . . . . . . . . . . . . . 65 2.3.33. PRODID . . . . . . . . . . . . . . . . . . . . . . . 66 2.3.34. RDATE . . . . . . . . . . . . . . . . . . . . . . . . 66 2.3.35. RECURRENCE-ID . . . . . . . . . . . . . . . . . . . . 67 2.3.36. RELATED-TO . . . . . . . . . . . . . . . . . . . . . 67 2.3.37. REQUEST-STATUS . . . . . . . . . . . . . . . . . . . 70 2.3.38. RRULE . . . . . . . . . . . . . . . . . . . . . . . . 70 2.3.39. SEQUENCE . . . . . . . . . . . . . . . . . . . . . . 72 2.3.40. STATUS . . . . . . . . . . . . . . . . . . . . . . . 73 2.3.41. SOURCE . . . . . . . . . . . . . . . . . . . . . . . 73 2.3.42. STRUCTURED-DATA . . . . . . . . . . . . . . . . . . . 74 2.3.43. STYLED-DESCRIPTION . . . . . . . . . . . . . . . . . 75 2.3.44. SUMMARY . . . . . . . . . . . . . . . . . . . . . . . 76 2.3.45. TRANSP . . . . . . . . . . . . . . . . . . . . . . . 76 2.3.46. TRIGGER . . . . . . . . . . . . . . . . . . . . . . . 77 2.3.47. TZID . . . . . . . . . . . . . . . . . . . . . . . . 78 2.3.48. TZID-ALIAS-OF . . . . . . . . . . . . . . . . . . . . 79 2.3.49. TZNAME . . . . . . . . . . . . . . . . . . . . . . . 79 2.3.50. TZOFFSETFROM . . . . . . . . . . . . . . . . . . . . 79 2.3.51. TZOFFSETTO . . . . . . . . . . . . . . . . . . . . . 79 2.3.52. TZUNTIL . . . . . . . . . . . . . . . . . . . . . . . 79 2.3.53. TZURL . . . . . . . . . . . . . . . . . . . . . . . . 79 2.3.54. UID . . . . . . . . . . . . . . . . . . . . . . . . . 80 2.3.55. URL . . . . . . . . . . . . . . . . . . . . . . . . . 80 3. Converting JSCalendar to iCalendar . . . . . . . . . . . . . 80 3.1. Alert . . . . . . . . . . . . . . . . . . . . . . . . . . 80 3.2. Event and Task . . . . . . . . . . . . . . . . . . . . . 81 3.3. Group . . . . . . . . . . . . . . . . . . . . . . . . . . 86 3.4. Link . . . . . . . . . . . . . . . . . . . . . . . . . . 88 3.5. Location . . . . . . . . . . . . . . . . . . . . . . . . 89 3.6. Participant . . . . . . . . . . . . . . . . . . . . . . . 91 3.7. TimeZone . . . . . . . . . . . . . . . . . . . . . . . . 94 Stepanek Expires 8 May 2025 [Page 3] Internet-Draft JSCalendar November 2024 3.8. VirtualLocation . . . . . . . . . . . . . . . . . . . . . 96 4. Updates to iCalendar . . . . . . . . . . . . . . . . . . . . 97 4.1. New iCalendar parameters . . . . . . . . . . . . . . . . 97 4.1.1. JSCALID . . . . . . . . . . . . . . . . . . . . . . . 97 4.2. New iCalendar properties . . . . . . . . . . . . . . . . 97 4.2.1. JSCALID . . . . . . . . . . . . . . . . . . . . . . . 97 4.2.2. JSPROP . . . . . . . . . . . . . . . . . . . . . . . 97 5. Updates to JSCalendar . . . . . . . . . . . . . . . . . . . . 97 5.1. New JSCalendar properties . . . . . . . . . . . . . . . . 97 5.1.1. iCalComponent . . . . . . . . . . . . . . . . . . . . 97 5.1.2. iCalProperty . . . . . . . . . . . . . . . . . . . . 99 5.1.3. locations (Participant) . . . . . . . . . . . . . . . 99 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 100 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 100 7.1. Normative References . . . . . . . . . . . . . . . . . . 100 7.2. Informative References . . . . . . . . . . . . . . . . . 102 Appendix A. Discrepancies between iCalendar and JSCalendar . . . 102 A.1. Unsupported iCalendar Elements . . . . . . . . . . . . . 102 A.1.1. Components . . . . . . . . . . . . . . . . . . . . . 102 A.1.2. Properties by Component . . . . . . . . . . . . . . . 103 A.1.3. Properties by Value Type . . . . . . . . . . . . . . 104 A.1.4. Parameters by Property . . . . . . . . . . . . . . . 105 A.2. Unsupported JSCalendar Elements . . . . . . . . . . . . . 107 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 107 1. Introduction 1.1. Notational Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. The ABNF definitions in this document use the notations of [RFC5234]. ABNF rules not defined in this document either are defined in [RFC5234] or [RFC5545]. 1.2. Scope and Goals This document outlines how to convert calendaring information between the iCalendar and JSCalendar data formats. It describes which elements are common to both, but also highlights where the two formats differ. For each common element, it defines a conversion rule and includes an example how to convert this element. All iCalendar and JSCalendar elements currently registered at IANA are in scope, but not all of these elements are common to both formats. Stepanek Expires 8 May 2025 [Page 4] Internet-Draft JSCalendar November 2024 For elements that have no counterpart in the other format, it is the goal of this document to define how to preserve them during conversion, but in general it is not the goal to achieve this by defining new standard elements. Instead, this document defines special-purpose properties to preserve arbitrary elements. These conversion-specific properties are defined in Section 4.2.2 for iCalendar, and Sections 5.1.1 and 5.1.2 for JSCalendar. Appendix A further outlines the discrepancies between the two formats. 1.3. How to Read the Examples Later sections contain examples that illustrate how to convert between the iCalendar and JSCalendar data formats. The notation of these examples is such that their main points should be clear to the reader, but their contents can also be parsed for automated testing. The authors of this document implemented a tool that extracts these examples for interoperation testing. The following sections define the notation for such examples. 1.3.1. iCalendar Examples An iCalendar example contains either an extract or a complete representation of iCalendar data. It always represents an iCalendar object, even if the example only depicts non-VCALENDAR components or properties. An example that only contains iCalendar properties implicitly represents a VEVENT component that is part of a VCALENDAR component. An example that only contains one or more non-VCALENDAR components implicitly represents a VCALENDAR component that contains them. Implicit components are assumed to contain mandatory properties with some value, but the actual value is irrelevant for the main point of the example. Notably, if an implicit component includes an ATTENDEE but not an ORGANIZER property, then an ORGANIZER property implicitly is present, too. The same applies for an example with an ORGANIZER but no ATTENDEE property. Figure 1 contains three examples, all of which represent the same iCalendar data. In the first example, both the VEVENT component and VCALENDAR component are implicit. In the second example, only the VCALENDAR component and its mandatory properties are implicit. The third example depicts a complete VCALENDAR component, nothing is implicit. SUMMARY:hello Stepanek Expires 8 May 2025 [Page 5] Internet-Draft JSCalendar November 2024 BEGIN:VEVENT DTSTAMP:20060102T030405Z DTSTART:20060102T030405Z SUMMARY:hello UID:CC0A494A-6E07-4827-8294-0752DD1ECFA4 END:VEVENT BEGIN:VCALENDAR PRODID:-//FOO//bar//EN VERSION:2.0 BEGIN:VEVENT DTSTAMP:20060102T030405Z DTSTART:20060102T030405Z SUMMARY:hello UID:CC0A494A-6E07-4827-8294-0752DD1ECFA4 END:VEVENT END:VCALENDAR Figure 1: Examples for implicit and explicit iCalendar component notation A line containing just the value ... stands for any other properties that might be present in a component but are irrelevant for this example. This includes mandatory properties as described for implicit components. The line ... at the end of the example additionally stands for any END content lines to complete components that started with BEGIN content lines, and any of their missing mandatory properties. Figure 2 illustrates this as an alternative representation for the examples of Figure 1. BEGIN:VCALENDAR BEGIN:VEVENT SUMMARY:hello ... Figure 2: Example for additional properties and component ENDs represented by ... A line starting with a single space represents the continuation of a folded content line (Section 3.1 of [RFC5545]). Figure 3 illustrates this. SUMMARY:he llo Figure 3: Example for a folded content line Stepanek Expires 8 May 2025 [Page 6] Internet-Draft JSCalendar November 2024 1.3.2. JSCalendar Examples A JSCalendar example always represents a Group object, even if the example only depicts one of the Group entries or properties. JSCalendar objects are depicted either explicitly or implicitly. An explicit JSCalendar object starts and ends with braces. An implicit JSCalendar object omits braces, it only consists of JSON name/value pairs, separated by comma. An implicit JSCalendar object is assumed to be of type Event, unless it contains the @type property with a different value. It is assumed to contain all mandatory properties with some value; if they are not depicted, their actual value is irrelevant for the main point of the example. Figure 4 illustrates this with multiple examples, all of which represent the same JSCalendar data. The first example contains an implicit JSCalendar object of type Event. The second example contains an implicit JSCalendar object with a @type property. The third example contains an explicit Event object but the Group object containing it is omitted. The fourth example contains the full Group object, nothing is omitted. "title": "hello" "@type": "Event", "title": "hello" { "@type": "Event", "title": "hello", "start": "2006-01-02T03:04:05", "timeZone": "Etc/UTC", "uid": "CC0A494A-6E07-4827-8294-0752DD1ECFA4", "updated": "2006-01-02T03:04:05Z" } { "@type": "Group", "entries": [ { "@type": "Event", "title": "hello", "start": "2006-01-02T03:04:05", "timeZone": "Etc/UTC", "uid": "CC0A494A-6E07-4827-8294-0752DD1ECFA4", "updated": "2006-01-02T03:04:05Z" } ] } Stepanek Expires 8 May 2025 [Page 7] Internet-Draft JSCalendar November 2024 Figure 4: Examples for implicit and explicit JSCalendar object notation A property with name "..." and value "" stands for additional properties that might be present in a JSCalendar object, but which are irrelevant for this example. This includes mandatory properties. Figure 5 illustrates this as an alternative representation for the examples of Figure 4. { "@type": "Event", "title": "hello", "...": "" } Figure 5: Example for additional properties represented by ... 2. Converting iCalendar to JSCalendar 2.1. General rules 2.1.1. iCalendar Objects Section 3.4 of [RFC5545] allows for an iCalendar stream to contain one or more iCalendar objects. In contrast, this specification only defines conversion for streams consisting of a single iCalendar object. Converting streams of multiple iCalendar objects is implementation-specific. All following sections of this document use the terms "iCalendar object" and "VCALENDAR component" interchangeably. The VCALENDAR component [RFC5545] (Section 3.4) converts to a Group object [RFC8984] (Section 2.3). Its properties convert as follows: +===============+============+==================+=========+======+ | Name | Reference | Group property | See | Note | +===============+============+==================+=========+======+ | CATEGORIES | [RFC5545], | keywords | Section | | | | Section | | 2.3.6 | | | | 3.8.1.2 | | | | +---------------+------------+------------------+---------+------+ | COLOR | [RFC7986], | color | Section | | | | Section | | 2.3.8 | | | | 5.9 | | | | +---------------+------------+------------------+---------+------+ | CONCEPT | [RFC9253], | categories | Section | | Stepanek Expires 8 May 2025 [Page 8] Internet-Draft JSCalendar November 2024 | | Section | | 2.3.10 | | | | 8.1 | | | | +---------------+------------+------------------+---------+------+ | CREATED | [RFC5545], | created | Section | | | | Section | | 2.3.12 | | | | 3.8.7.1 | | | | +---------------+------------+------------------+---------+------+ | DESCRIPTION | [RFC5545], | description | Section | | | | Section | | 2.3.13 | | | | 3.8.1.5 | | | | +---------------+------------+------------------+---------+------+ | LAST-MODIFIED | [RFC5545], | updated | Section | | | | Section | | 2.3.23 | | | | 3.8.7.3 | | | | +---------------+------------+------------------+---------+------+ | LINK | [RFC9253], | links | Section | | | | Section | | 2.3.24 | | | | 8.2 | | | | +---------------+------------+------------------+---------+------+ | METHOD | [RFC5545], | entries/*/method | Section | | | | Section | | 2.3.27 | | | | 3.7.2 | | | | +---------------+------------+------------------+---------+------+ | NAME | [RFC7986], | title | Section | | | | Section | | 2.3.28 | | | | 5.1 | | | | +---------------+------------+------------------+---------+------+ | PRODID | [RFC5545], | prodId, | Section | | | | Section | entries/*/prodId | 2.3.33 | | | | 3.7.3 | | | | +---------------+------------+------------------+---------+------+ | SOURCE | [RFC7986], | source | Section | | | | Section | | 2.3.41 | | | | 5.8 | | | | +---------------+------------+------------------+---------+------+ | UID | [RFC5545], | uid | Section | | | | Section | | 2.3.54 | | | | 3.8.4.7 | | | | +---------------+------------+------------------+---------+------+ | URL | [RFC5545], | links | Section | | | | Section | | 2.3.55 | | | | 3.8.4.6 | | | | +---------------+------------+------------------+---------+------+ Table 1: Properties of the VCALENDAR component Its components convert as follows: Stepanek Expires 8 May 2025 [Page 9] Internet-Draft JSCalendar November 2024 +===========+===============+================+=========+======+ | Name | Reference | Group property | See | Note | +===========+===============+================+=========+======+ | VEVENT | [RFC5545], | entries | Section | | | | Section 3.6.1 | | 2.2.3 | | +-----------+---------------+----------------+---------+------+ | VTIMEZONE | [RFC5545], | timeZones | Section | | | | Section 3.6.5 | | 2.2.6 | | +-----------+---------------+----------------+---------+------+ | VTODO | [RFC5545], | entries | Section | | | | Section 3.6.2 | | 2.2.7 | | +-----------+---------------+----------------+---------+------+ Table 2: Components of the VCALENDAR component Other properties or components MAY be converted to the iCalComponent property (Section 5.1.1) of the Group object. The following example illustrates how to convert the VCALENDAR component: BEGIN:VCALENDAR UID:41aa02b6-42d0-4f45-8cb4-8b5075be2e14 BEGIN:VEVENT ... { "...": "", "@type": "Group", "entries": [ { "...": "", "@type": "Event" } ], "uid": "41aa02b6-42d0-4f45-8cb4-8b5075be2e14" } Figure 6: Converting the VCALENDAR component 2.1.2. Recurring Components Components in an iCalendar object generally convert to distinct JSCalendar objects. For example, two VEVENT components with different UID property values in the same iCalendar object convert to two separate Event objects in the Group object's entries. This rule does not apply to recurrence overrides, defined as follows. Stepanek Expires 8 May 2025 [Page 10] Internet-Draft JSCalendar November 2024 A VEVENT (or VTODO) component is a recurrence override if it has the RECURRENCE-ID property set, and the iCalendar object contains a VEVENT (or VTODO) component that does not have the RECURRENCE-ID but the RRULE property set, and the UID property values of the two components are equal. The component without the RECURRENCE-ID property is in that case referred to as the "main component". The main component converts to an entry in the Group object's entries property. The recurrence override converts to the recurrenceOverrides property of the converted main component. Its RECURRENCE-ID property value converts to the key in the recurrenceOverrides property. The value of the recurrenceOverrides property at that key is the PatchObject that transform the converted main component into the converted recurrence override. The recurrenceId and recurrenceIdTimeZone properties MUST NOT be set in the PatchObject. The following example illustrates how to convert a main component and its recurrence override: BEGIN:VCALENDAR BEGIN:VEVENT UID:F4257E1D-5461-4EF6-840F-9DFC653EB559 RRULE:FREQ=DAILY DTSTART;TZID=Europe/Berlin:20240101T140000 ... END:VEVENT BEGIN:VEVENT UID:F4257E1D-5461-4EF6-840F-9DFC653EB559 RECURRENCE-ID;TZID=Europe/Berlin:20240202T140000 DTSTART;TZID=Europe/Berlin:20240202T160000 ... END:VEVENT END:VCALENDAR Stepanek Expires 8 May 2025 [Page 11] Internet-Draft JSCalendar November 2024 { "...": "", "@type": "Group", "entries": [ { "...": "", "@type": "Event", "recurrenceOverrides": { "2024-02-02T14:00:00": { "start": "2024-02-02T16:00:00" } }, "recurrenceRules": [ { "@type": "RecurrenceRule", "frequency": "daily" } ], "start": "2024-01-01T14:00:00", "timeZone": "Europe/Berlin", "uid": "F4257E1D-5461-4EF6-840F-9DFC653EB559" } ] } Figure 7: Converting VEVENT recurrence overrides A VEVENT (or VTODO) component is a stand-alone recurrence instance if it has the RECURRENCE-ID property set and the iCalendar object does not contain its related main component. Each stand-alone recurrence instance converts to a distinct Event (or Task) object in the Group object's entries property. The recurrenceId property MUST be set, the recurrenceIdTimeZone property MUST be set if not "null". The converted objects sort in order of appearance of the iCalendar components. The following example illustrates how to convert stand-alone recurrence instances: Stepanek Expires 8 May 2025 [Page 12] Internet-Draft JSCalendar November 2024 BEGIN:VCALENDAR BEGIN:VEVENT UID:F4257E1D-5461-4EF6-840F-9DFC653EB559 RECURRENCE-ID;TZID=Europe/Berlin:20240202T140000 DTSTART;TZID=Europe/Berlin:20240202T160000 ... END:VEVENT BEGIN:VEVENT UID:F4257E1D-5461-4EF6-840F-9DFC653EB559 RECURRENCE-ID;TZID=Europe/Berlin:20240103T140000 DTSTART;TZID=Europe/Berlin:20240103T160000 ... END:VEVENT END:VCALENDAR { "...": "", "@type": "Group", "entries": [ { "...": "", "@type": "Event", "recurrenceId": "2024-02-02T14:00:00", "recurrenceIdTimeZone": "2024-02-02T14:00:00", "start": "2024-02-02T16:00:00", "timeZone": "Europe/Berlin", "uid": "F4257E1D-5461-4EF6-840F-9DFC653EB559" }, { "...": "", "@type": "Event", "recurrenceId": "2024-01-03T14:00:00", "recurrenceIdTimeZone": "2024-02-02T14:00:00", "start": "2024-01-03T14:00:00", "timeZone": "Europe/Berlin", "uid": "F4257E1D-5461-4EF6-840F-9DFC653EB559" } ] } Figure 8: Converting VEVENT recurrence instances 2.1.3. JSCalendar Ids JSCalendar generally uses JSON objects to represent a collection of same-typed values. The keys are of type Id [RFC8984] (Section 1.4.1), the values are JSCalendar object types. If an iCalendar element converts to a value in such a collection, then an implementation needs to choose an identifier as key. Stepanek Expires 8 May 2025 [Page 13] Internet-Draft JSCalendar November 2024 This document defines the new JSCALID (Section 4.1.1) parameter and JSCALID property (Section 4.2.1), which allow to set a JSCalendar Id value when converting from JSCalendar to iCalendar. If they are set on a property or the component, then its value MUST be used as key when converting that element from iCalendar to JSCalendar. If no such parameter or property is set, then an implementation is free to choose any identifier, as long the following requirements are met: * The identifier MUST be a valid Id value. * The identifiers for the exact same iCalendar element MUST stay the same, irrespective of the order in which components, properties and parameters are processed. 2.1.4. Timezone identifiers Converting temporal properties such as DTSTART, DTEND, and RECURRENCE-ID requires to not only determine the date and time of the property value, but also the timezone it references. If the property value data type is DATE [RFC5545] (Section 3.3.4) or DATE-TIME in FORM #1: DATE WITH LOCAL TIME [RFC5545] (Section 3.3.5) then the timezone identifier is the JSON null value in JSCalendar. If the property value data type is DATE-TIME in FORM #2: DATE WITH UTC TIME [RFC5545] (Section 3.3.5) then the timezone identifier is the string "Etc/UTC" in JSCalendar. If the property value data type is DATE-TIME in FORM #3: DATE WITH LOCAL TIME AND TIME ZONE REFERENCE [RFC5545] (Section 3.3.5) then the timezone identifier is determined by the TZID parameter value: If the TZID parameter value is equal to a name in the IANA Time Zone Database [TZDB] then the timezone identifier is that verbatim name. If the TZID parameter value is unequal to an IANA timezone name then implementations MAY determine the name of an IANA timezone which has the same timezone rules over the timespan of the calendar object. Otherwise, the non-IANA timezone identifier is represented in JSCalendar as a string starting with the / (SLASH) character, followed by the TZID parameter value. The corresponding VTIMEZONE MUST be converted to the timeZones property with the prefixed identifier as key. See Figure 14 for an example. Stepanek Expires 8 May 2025 [Page 14] Internet-Draft JSCalendar November 2024 2.1.5. DATE and DATE-TIME iCalendar provides the DATE and DATE-TIME value types to distinguish date-only from date-time values. JSCalendar only supports date-time values. A property value of type DATE-TIME converts to either a LocalDateTime or UTCDateTime, depending on the JSCalendar property definition. A DATE value type converts to a LocalDateTime with zero time. 2.2. Components 2.2.1. PARTICIPANT The PARTICIPANT component [RFC9073] (Section 7.1) converts to a Participant object [RFC8984] (Section 4.4.6). Its properties convert as follows: +================+==========+====================+=======+=========+ |Name |Reference |Participant property|See |Note | +================+==========+====================+=======+=========+ |ATTACH |[RFC5545],|links |Section| | | |Section | |2.3.3 | | | |3.8.1.1 | | | | +----------------+----------+--------------------+-------+---------+ |CALENDAR-ADDRESS|[RFC9073],|calendarAddress |Section| | | |Section | |2.3.5 | | | |6.4 | | | | +----------------+----------+--------------------+-------+---------+ |COMMENT |[RFC5545],|participationComment|Section|Only one | | |Section | |2.3.9 |comment | | |3.8.1.4 | | |supported| +----------------+----------+--------------------+-------+---------+ |DESCRIPTION |[RFC5545],|description |Section| | | |Section | |2.3.13 | | | |3.8.1.5 | | | | +----------------+----------+--------------------+-------+---------+ |DTSTAMP |[RFC5545],|scheduleUpdated |Section| | | |Section | |2.3.15 | | | |3.8.7.2 | | | | +----------------+----------+--------------------+-------+---------+ |GEO |[RFC5545],|locations |Section| | | |Section | |2.3.21 | | | |3.8.1.6 | | | | +----------------+----------+--------------------+-------+---------+ |LINK |[RFC9253],|links |Section| | | |Section | |2.3.24 | | | |8.2 | | | | Stepanek Expires 8 May 2025 [Page 15] Internet-Draft JSCalendar November 2024 +----------------+----------+--------------------+-------+---------+ |LOCATION |[RFC5545],|locations |Section| | | |Section | |2.3.25 | | | |3.8.1.7 | | | | +----------------+----------+--------------------+-------+---------+ |PARTICIPANT-TYPE|[RFC9073],|roles |Section| | | |Section | |2.3.30 | | | |6.2 | | | | +----------------+----------+--------------------+-------+---------+ |SEQUENCE |[RFC5545],|scheduleSequence |Section| | | |Section | |2.3.39 | | | |3.8.7.4 | | | | +----------------+----------+--------------------+-------+---------+ |STRUCTURED-DATA |[RFC9073],|links |Section| | | |Section | |2.3.42 | | | |6.6 | | | | +----------------+----------+--------------------+-------+---------+ |SUMMARY |[RFC5545],|name |Section| | | |Section | |2.3.44 | | | |3.8.1.12 | | | | +----------------+----------+--------------------+-------+---------+ |URL |[RFC5545],|links |Section| | | |Section | |2.3.55 | | | |3.8.4.6 | | | | +----------------+----------+--------------------+-------+---------+ Table 3: Properties of the PARTICIPANT component Its components convert as follows: +===========+=============+======================+=========+======+ | Name | Reference | Participant property | See | Note | +===========+=============+======================+=========+======+ | VLOCATION | [RFC9073], | locations | Section | | | | Section 7.2 | | 2.2.4 | | +-----------+-------------+----------------------+---------+------+ Table 4: Components of the PARTICIPANT component Other properties or components MAY be converted to the iCalComponent property (Section 5.1.1) of the Participant object. This includes mandatory properties such as UID [RFC5545] (Section 3.8.4.7). The following example illustrates how to convert the PARTICIPANT component: Stepanek Expires 8 May 2025 [Page 16] Internet-Draft JSCalendar November 2024 BEGIN:VEVENT BEGIN:PARTICIPANT UID:47AD2E1C-49D4-45DF-BD83-8398ACC7D8E2 STRUCTURED-DATA;VALUE=URI: http://dir.example.com/vcard/contacts/contact1.vcf PARTICIPANT-TYPE:CONTACT DESCRIPTION:A contact END:PARTICIPANT ... { "...": "", "@type": "Event", "participants": { "p32": { "@type": "Participant", "description": "A contact", "iCalComponent": { "name": "participant", "properties": [ [ "uid", {}, "text", "47AD2E1C-49D4-45DF-BD83-8398ACC7D8E2" ] ] }, "links": { "l4": { "@type": "Link", "href": "http://dir.example.com/vcard/contacts/contact1.vcf" } }, "roles": { "contact": true } } } } Figure 9: Converting the PARTICIPANT component 2.2.2. VALARM The VALARM component [RFC5545] (Section 3.6.6) converts to a Alert object [RFC8984] (Section 4.5.2). Its properties convert as follows: Stepanek Expires 8 May 2025 [Page 17] Internet-Draft JSCalendar November 2024 +==============+============+==============+=========+===========+ | Name | Reference | Alert | See | Note | | | | property | | | +==============+============+==============+=========+===========+ | ACKNOWLEDGED | [RFC9074], | acknowledged | Section | | | | Section | | 2.3.1 | | | | 6.1 | | | | +--------------+------------+--------------+---------+-----------+ | ACTION | [RFC5545], | action | Section | Only if | | | Section | | 2.3.2 | ACTION is | | | 3.8.6.1 | | | EMAIL or | | | | | | DISPLAY. | +--------------+------------+--------------+---------+-----------+ | RELATED-TO | [RFC5545], | relatedTo | Section | | | | Section | | 2.3.36 | | | | 3.8.4.5 | | | | +--------------+------------+--------------+---------+-----------+ | TRIGGER | [RFC5545], | trigger | Section | | | | Section | | 2.3.46 | | | | 3.8.6.3 | | | | +--------------+------------+--------------+---------+-----------+ Table 5: Properties of the VALARM component Other properties or components MAY be converted to the iCalComponent property (Section 5.1.1) of the Alert object. This includes mandatory properties such as ATTENDEE [RFC5545] (Section 3.8.4.1), DESCRIPTION [RFC5545] (Section 3.8.1.5), or SUMMARY [RFC5545] (Section 3.8.1.12). The following example illustrates how to convert the VALARM component: BEGIN:VEVENT BEGIN:VALARM TRIGGER:-PT30M ACTION:DISPLAY DESCRIPTION:Breakfast meeting END:VALARM ... Stepanek Expires 8 May 2025 [Page 18] Internet-Draft JSCalendar November 2024 { "...": "", "@type": "Event", "alerts": { "a8": { "@type": "Alert", "iCalComponent": { "name": "valarm", "properties": [ [ "description", {}, "text", "Breakfast meeting" ] ] }, "trigger": { "@type": "OffsetTrigger", "offset": "-PT30M" }, "action": "display" } } } Figure 10: Converting the VALARM component 2.2.3. VEVENT The VEVENT component [RFC5545] (Section 3.6.1) converts to a Event object [RFC8984] (Section 2.1). VEVENT components with different UID property values in the same iCalendar object convert to different entries in the Group. They sort in the same order as in the VCALENDAR component. Its properties convert as follows: +===========+==========+===================================+=======+====+ |Name |Reference |Event property |See |Note| +===========+==========+===================================+=======+====+ |ATTACH |[RFC5545],|links |Section| | | |Section | |2.3.3 | | | |3.8.1.1 | | | | +-----------+----------+-----------------------------------+-------+----+ |ATTENDEE |[RFC5545],|participants |Section| | | |Section | |2.3.4 | | Stepanek Expires 8 May 2025 [Page 19] Internet-Draft JSCalendar November 2024 | |3.8.4.1 | | | | +-----------+----------+-----------------------------------+-------+----+ |CATEGORIES |[RFC5545],|keywords |Section| | | |Section | |2.3.6 | | | |3.8.1.2 | | | | +-----------+----------+-----------------------------------+-------+----+ |CLASS |[RFC5545],|privacy |Section| | | |Section | |2.3.7 | | | |3.8.1.3 | | | | +-----------+----------+-----------------------------------+-------+----+ |COLOR |[RFC7986],|color |Section| | | |Section | |2.3.8 | | | |5.9 | | | | +-----------+----------+-----------------------------------+-------+----+ |COMMENT |[RFC5545],|participants/*/participationComment|Section| | | |Section | |2.3.9 | | | |3.8.1.4 | | | | +-----------+----------+-----------------------------------+-------+----+ |CONCEPT |[RFC9253],|categories |Section| | | |Section | |2.3.10 | | | |8.1 | | | | +-----------+----------+-----------------------------------+-------+----+ |CONFERENCE |[RFC7986],|virtualLocations |Section| | | |Section | |2.3.11 | | | |5.11 | | | | +-----------+----------+-----------------------------------+-------+----+ |CREATED |[RFC5545],|created |Section| | | |Section | |2.3.12 | | | |3.8.7.1 | | | | +-----------+----------+-----------------------------------+-------+----+ |DESCRIPTION|[RFC5545],|description |Section| | | |Section | |2.3.13 | | | |3.8.1.5 | | | | +-----------+----------+-----------------------------------+-------+----+ |DTEND |[RFC5545],|duration |Section| | | |Section | |2.3.14 | | | |3.8.2.2 | | | | +-----------+----------+-----------------------------------+-------+----+ |DTSTAMP |[RFC5545],|updated, scheduleUpdated |Section| | | |Section | |2.3.15 | | | |3.8.7.2 | | | | +-----------+----------+-----------------------------------+-------+----+ |DTSTART |[RFC5545],|start |Section| | | |Section | |2.3.16 | | | |3.8.2.4 | | | | +-----------+----------+-----------------------------------+-------+----+ |DURATION |[RFC5545],|duration |Section| | | |Section | |2.3.18 | | Stepanek Expires 8 May 2025 [Page 20] Internet-Draft JSCalendar November 2024 | |3.8.2.5 | | | | +-----------+----------+-----------------------------------+-------+----+ |EXDATE |[RFC5545],|recurrenceOverrides |Section| | | |Section | |2.3.19 | | | |3.8.5.1 | | | | +-----------+----------+-----------------------------------+-------+----+ |EXRULE |[RFC2445],|excludedRecurrenceRules |Section| | | |Section | |2.3.20 | | | |4.8.5.2 | | | | +-----------+----------+-----------------------------------+-------+----+ |GEO |[RFC5545],|locations |Section| | | |Section | |2.3.21 | | | |3.8.1.6 | | | | +-----------+----------+-----------------------------------+-------+----+ |IMAGE |[RFC7986],|links |Section| | | |Section | |2.3.22 | | | |5.10 | | | | +-----------+----------+-----------------------------------+-------+----+ |LAST- |[RFC5545],|updated |Section| | |MODIFIED |Section | |2.3.23 | | | |3.8.7.3 | | | | +-----------+----------+-----------------------------------+-------+----+ |LINK |[RFC9253],|links |Section| | | |Section | |2.3.24 | | | |8.2 | | | | +-----------+----------+-----------------------------------+-------+----+ |LOCATION |[RFC5545],|locations |Section| | | |Section | |2.3.25 | | | |3.8.1.7 | | | | +-----------+----------+-----------------------------------+-------+----+ |ORGANIZER |[RFC5545],|replyTo |Section| | | |Section | |2.3.29 | | | |3.8.4.3 | | | | +-----------+----------+-----------------------------------+-------+----+ |PRIORITY |[RFC5545],|priority |Section| | | |Section | |2.3.32 | | | |3.8.1.9 | | | | +-----------+----------+-----------------------------------+-------+----+ |RDATE |[RFC5545],|recurrenceOverrides |Section| | | |Section | |2.3.34 | | | |3.8.5.2 | | | | +-----------+----------+-----------------------------------+-------+----+ |RECURRENCE-|[RFC5545],|recurrenceId |Section| | |ID |Section | |2.3.35 | | | |3.8.4.4 | | | | +-----------+----------+-----------------------------------+-------+----+ |RELATED-TO |[RFC5545],|relatedTo |Section| | | |Section | |2.3.36 | | Stepanek Expires 8 May 2025 [Page 21] Internet-Draft JSCalendar November 2024 | |3.8.4.5 | | | | +-----------+----------+-----------------------------------+-------+----+ |REQUEST- |[RFC5545],|requestStatus |Section| | |STATUS |Section | |2.3.37 | | | |3.8.8.3 | | | | +-----------+----------+-----------------------------------+-------+----+ |RRULE |[RFC5545],|recurrenceRules |Section| | | |Section | |2.3.38 | | | |3.8.5.3 | | | | +-----------+----------+-----------------------------------+-------+----+ |SEQUENCE |[RFC5545],|sequence |Section| | | |Section | |2.3.39 | | | |3.8.7.4 | | | | +-----------+----------+-----------------------------------+-------+----+ |STATUS |[RFC5545],|status |Section| | | |Section | |2.3.40 | | | |3.8.1.11 | | | | +-----------+----------+-----------------------------------+-------+----+ |STRUCTURED-|[RFC9073],|links |Section| | |DATA |Section | |2.3.42 | | | |6.6 | | | | +-----------+----------+-----------------------------------+-------+----+ |STYLED- |[RFC9073],|description |Section| | |DESCRIPTION|Section | |2.3.43 | | | |6.5 | | | | +-----------+----------+-----------------------------------+-------+----+ |SUMMARY |[RFC5545],|title |Section| | | |Section | |2.3.44 | | | |3.8.1.12 | | | | +-----------+----------+-----------------------------------+-------+----+ |TRANSP |[RFC5545],|freeBusyStatus |Section| | | |Section | |2.3.45 | | | |3.8.2.7 | | | | +-----------+----------+-----------------------------------+-------+----+ |UID |[RFC5545],|uid |Section| | | |Section | |2.3.54 | | | |3.8.4.7 | | | | +-----------+----------+-----------------------------------+-------+----+ |URL |[RFC5545],|links |Section| | | |Section | |2.3.55 | | | |3.8.4.6 | | | | +-----------+----------+-----------------------------------+-------+----+ Table 6: Properties of the VEVENT component Its components convert as follows: Stepanek Expires 8 May 2025 [Page 22] Internet-Draft JSCalendar November 2024 +========+===============+================+=========+======+ | Name | Reference | Event property | See | Note | +========+===============+================+=========+======+ | VALARM | [RFC5545], | alerts | Section | | | | Section 3.6.6 | | 2.2.2 | | +--------+---------------+----------------+---------+------+ Table 7: Components of the VEVENT component Other properties or components MAY be converted to the iCalComponent property (Section 5.1.1) of the Event object. The following example illustrates how to convert the VEVENT component: BEGIN:VCALENDAR BEGIN:VEVENT UID:DE935D01-3DF7-4201-B61A-D77D05C8B21A DTSTART:20060102T030405Z ... END:VEVENT BEGIN:VEVENT UID:60BE3D6E-6383-473A-BCF1-3C43EA1FA571 ... END:VEVENT END:VCALENDAR { "...": "", "@type": "Group", "entries": [ { "@type": "Event", "showWithoutTime": false, "start": "2006-01-02T03:04:05", "timeZone": "Etc/UTC", "uid": "DE935D01-3DF7-4201-B61A-D77D05C8B21A", "...": "" }, { "@type": "Event", "uid": "60BE3D6E-6383-473A-BCF1-3C43EA1FA571", "...": "" } ] } Figure 11: Converting the VEVENT component Stepanek Expires 8 May 2025 [Page 23] Internet-Draft JSCalendar November 2024 2.2.4. VLOCATION The VLOCATION component [RFC9073] (Section 7.2) converts to a Location object [RFC8984] (Section 4.2.5). Its properties convert as follows: +=================+============+===============+=========+======+ | Name | Reference | Location | See | Note | | | | property | | | +=================+============+===============+=========+======+ | ATTACH | [RFC5545], | links | Section | | | | Section | | 2.3.3 | | | | 3.8.1.1 | | | | +-----------------+------------+---------------+---------+------+ | DESCRIPTION | [RFC5545], | description | Section | | | | Section | | 2.3.13 | | | | 3.8.1.5 | | | | +-----------------+------------+---------------+---------+------+ | GEO | [RFC5545], | coordinates | Section | | | | Section | | 2.3.21 | | | | 3.8.1.6 | | | | +-----------------+------------+---------------+---------+------+ | IMAGE | [RFC7986], | links | Section | | | | Section | | 2.3.22 | | | | 5.10 | | | | +-----------------+------------+---------------+---------+------+ | LINK | [RFC9253], | links | Section | | | | Section | | 2.3.24 | | | | 8.2 | | | | +-----------------+------------+---------------+---------+------+ | LOCATION-TYPE | [RFC9073], | locationTypes | Section | | | | Section | | 2.3.26 | | | | 6.1 | | | | +-----------------+------------+---------------+---------+------+ | NAME | [RFC7986], | name | Section | | | | Section | | 2.3.28 | | | | 5.1 | | | | +-----------------+------------+---------------+---------+------+ | STRUCTURED-DATA | [RFC9073], | links | Section | | | | Section | | 2.3.42 | | | | 6.6 | | | | +-----------------+------------+---------------+---------+------+ Table 8: Properties of the VLOCATION component Stepanek Expires 8 May 2025 [Page 24] Internet-Draft JSCalendar November 2024 Other properties or components MAY be converted to the iCalComponent property (Section 5.1.1) of the Location object. This includes mandatory properties such as UID [RFC5545] (Section 3.8.4.7). The following example illustrates how to convert the VLOCATION component: BEGIN:VLOCATION UID:4954DC22-5BD6-4E98-844D-0302982F54AC NAME:The venue STRUCTURED-DATA;VALUE=URI: http://dir.example.com/venues/big-hall.vcf END:VLOCATION "locations": { "e4": { "@type": "Location", "name": "The venue", "links": { "21": { "@type": "Link", "href": "http://dir.example.com/venues/big-hall.vcf", "iCalProperty": { "@type": "ICalProperty", "name": "structured-data" } } }, "iCalComponent": { "@type": "ICalComponent", "properties": [ [ "uid", {}, "text", "4954DC22-5BD6-4E98-844D-0302982F54AC" ] ] } } } Figure 12: Converting the VLOCATION component 2.2.5. VRESOURCE The VRESOURCE component [RFC9073] (Section 7.3) converts to a Participant object [RFC8984] (Section 4.4.6). Stepanek Expires 8 May 2025 [Page 25] Internet-Draft JSCalendar November 2024 Its properties convert as follows: +=================+=================+=============+=========+======+ | Name | Reference | Participant | See | Note | | | | property | | | +=================+=================+=============+=========+======+ | ATTACH | [RFC5545], | links | Section | | | | Section 3.8.1.1 | | 2.3.3 | | +-----------------+-----------------+-------------+---------+------+ | DESCRIPTION | [RFC5545], | description | Section | | | | Section 3.8.1.5 | | 2.3.13 | | +-----------------+-----------------+-------------+---------+------+ | GEO | [RFC5545], | locations | Section | | | | Section 3.8.1.6 | | 2.3.21 | | +-----------------+-----------------+-------------+---------+------+ | IMAGE | [RFC7986], | links | Section | | | | Section 5.10 | | 2.3.22 | | +-----------------+-----------------+-------------+---------+------+ | LINK | [RFC9253], | links | Section | | | | Section 8.2 | | 2.3.24 | | +-----------------+-----------------+-------------+---------+------+ | NAME | [RFC7986], | name | Section | | | | Section 5.1 | | 2.3.28 | | +-----------------+-----------------+-------------+---------+------+ | STRUCTURED-DATA | [RFC9073], | links | Section | | | | Section 6.6 | | 2.3.42 | | +-----------------+-----------------+-------------+---------+------+ Table 9: Properties of the VRESOURCE component Other properties or components MAY be converted to the iCalComponent property (Section 5.1.1) of the Participant object. This includes mandatory properties such as UID [RFC5545] (Section 3.8.4.7). The following example illustrates how to convert the VRESOURCE component: BEGIN:VEVENT BEGIN:VRESOURCE UID:456789-abcdef-98765432 NAME:The projector RESOURCE-TYPE:projector STRUCTURED-DATA;VALUE=URI:http://dir.example.com/projectors/3d.vcf END:VRESOURCE ... Stepanek Expires 8 May 2025 [Page 26] Internet-Draft JSCalendar November 2024 { "...": "", "@type": "Event", "participants": { "p2": { "@type": "Participant", "description": "A contact", "iCalComponent": { "name": "participant", "properties": [ [ "uid", {}, "text", "456789-abcdef-98765432" ], [ "resource-type", {}, "text", "projector" ] ] }, "kind": "resource", "links": { "l4": { "@type": "Link", "href": "http://dir.example.com/projectors/3d.vcf" } }, "name": "The projector" } } } Figure 13: Converting the VRESOURCE component 2.2.6. VTIMEZONE The VTIMEZONE component [RFC5545] (Section 3.6.5) converts to a TimeZone object [RFC8984] (Section 4.7.2). Its properties convert as follows: Stepanek Expires 8 May 2025 [Page 27] Internet-Draft JSCalendar November 2024 +===============+=================+============+=========+======+ | Name | Reference | TimeZone | See | Note | | | | property | | | +===============+=================+============+=========+======+ | LAST-MODIFIED | [RFC5545], | updated | Section | | | | Section 3.8.7.3 | | 2.3.23 | | +---------------+-----------------+------------+---------+------+ | TZID | [RFC5545], | tzId | Section | | | | Section 3.8.3.1 | | 2.3.47 | | +---------------+-----------------+------------+---------+------+ | TZID-ALIAS-OF | [RFC7808], | aliases | Section | | | | Section 7.2 | | 2.3.48 | | +---------------+-----------------+------------+---------+------+ | TZUNTIL | [RFC7808], | validUntil | Section | | | | Section 7.1 | | 2.3.52 | | +---------------+-----------------+------------+---------+------+ | TZURL | [RFC5545], | url | Section | | | | Section 3.8.3.5 | | 2.3.53 | | +---------------+-----------------+------------+---------+------+ Table 10: Properties of the VTIMEZONE component Its components convert as follows: +==========+===============+===================+=========+======+ | Name | Reference | TimeZone property | See | Note | +==========+===============+===================+=========+======+ | DAYLIGHT | [RFC5545], | daylight | In this | | | | Section 3.6.5 | | section | | +----------+---------------+-------------------+---------+------+ | STANDARD | [RFC5545], | standard | In this | | | | Section 3.6.5 | | section | | +----------+---------------+-------------------+---------+------+ Table 11: Components of the VTIMEZONE component Other properties or components MAY be converted to the iCalComponent property (Section 5.1.1) of the TimeZone object. The DAYLIGHT component [RFC5545] (Section 3.6.5) and STANDARD component [RFC5545] (Section 3.6.5) convert to a TimeZoneRule object [RFC8984] (Section 4.7.2). Their properties convert as follows: Stepanek Expires 8 May 2025 [Page 28] Internet-Draft JSCalendar November 2024 +==============+============+=====================+=========+======+ | Name | Reference | TimeZoneRule | See | Note | | | | property | | | +==============+============+=====================+=========+======+ | COMMENT | [RFC5545], | comments | Section | | | | Section | | 2.3.9 | | | | 3.8.1.4 | | | | +--------------+------------+---------------------+---------+------+ | DTSTART | [RFC5545], | start | Section | | | | Section | | 2.3.16 | | | | 3.8.2.4 | | | | +--------------+------------+---------------------+---------+------+ | RDATE | [RFC5545], | recurrenceOverrides | Section | | | | Section | | 2.3.34 | | | | 3.8.5.2 | | | | +--------------+------------+---------------------+---------+------+ | RRULE | [RFC5545], | recurrenceRules | Section | | | | Section | | 2.3.38 | | | | 3.8.5.3 | | | | +--------------+------------+---------------------+---------+------+ | TZNAME | [RFC5545], | names | Section | | | | Section | | 2.3.49 | | | | 3.8.3.2 | | | | +--------------+------------+---------------------+---------+------+ | TZOFFSETFROM | [RFC5545], | offsetFrom | Section | | | | Section | | 2.3.50 | | | | 3.8.3.3 | | | | +--------------+------------+---------------------+---------+------+ | TZOFFSETTO | [RFC5545], | offsetTo | Section | | | | Section | | 2.3.51 | | | | 3.8.3.4 | | | | +--------------+------------+---------------------+---------+------+ Table 12: Properties of the DAYLIGHT or STANDARD component Other properties or components MAY be converted to the iCalComponent property (Section 5.1.1) of the TimeZoneRule object. The following example illustrates how to convert the VTIMEZONE component: Stepanek Expires 8 May 2025 [Page 29] Internet-Draft JSCalendar November 2024 BEGIN:VCALENDAR BEGIN:VTIMEZONE TZID:CustomTz TZID-ALIAS-OF:Puerto_Rico TZID-ALIAS-OF:America/Anguilla LAST-MODIFIED:20240909T122233Z TZUNTIL:20080709T000000Z TZURL:https://example.com/tz/CustomTz.ics BEGIN:DAYLIGHT TZNAME:AWT TZOFFSETFROM:-0400 TZOFFSETTO:-0300 DTSTART:19420503T000000 END:DAYLIGHT BEGIN:DAYLIGHT TZNAME:APT TZOFFSETFROM:-0300 TZOFFSETTO:-0300 DTSTART:19450814T200000 END:DAYLIGHT BEGIN:STANDARD TZNAME:AST TZOFFSETFROM:-0300 TZOFFSETTO:-0400 DTSTART:19450930T020000 END:STANDARD END:VTIMEZONE BEGIN:VEVENT DTSTART;TZID=CustomTz:20080708T130000 ... { "...": "", "@type": "Group", "entries": [ { "...": "", "@type": "Event", "start": "2008-07-08T13:00:00", "timeZone": "/CustomTz" } ], "timeZones": { "/CustomTz": { "@type": "TimeZone", "aliases": { "Puerto_Rico": true, "America/Anguilla": true }, Stepanek Expires 8 May 2025 [Page 30] Internet-Draft JSCalendar November 2024 "validUntil": "2008-07-09T00:00:00Z", "daylight": [ { "@type": "TimeZoneRule", "offsetFrom": "-0400", "offsetTo": "-0300", "start": "1942-05-03T00:00:00", "names": { "AWT": true } }, { "@type": "TimeZoneRule", "offsetFrom": "-0300", "offsetTo": "-0300", "start": "1945-08-14T20:00:00", "names": { "APT": true } } ], "standard": [ { "@type": "TimeZoneRule", "offsetFrom": "-0300", "offsetTo": "-0400", "start": "1945-09-30T02:00:00", "names": { "AST": true } } ], "tzId": "CustomTz", "updated": "2024-09-09T12:22:33Z", "url": "https://example.com/tz/CustomTz.ics" } } } Figure 14: Converting the VTIMEZONE component 2.2.7. VTODO The VTODO component [RFC5545] (Section 3.6.2) converts to a Task object [RFC8984] (Section 2.2). Stepanek Expires 8 May 2025 [Page 31] Internet-Draft JSCalendar November 2024 VTODO components with different UID property values in the same iCalendar object convert to different entries in the Group. They sort in the same order as in the VCALENDAR component. Its properties convert as follows: +===========+==========+===================================+=======+====+ |Name |Reference |Task property |See |Note| +===========+==========+===================================+=======+====+ |ATTACH |[RFC5545],|links |Section| | | |Section | |2.3.3 | | | |3.8.1.1 | | | | +-----------+----------+-----------------------------------+-------+----+ |ATTENDEE |[RFC5545],|participants |Section| | | |Section | |2.3.4 | | | |3.8.4.1 | | | | +-----------+----------+-----------------------------------+-------+----+ |CATEGORIES |[RFC5545],|keywords |Section| | | |Section | |2.3.6 | | | |3.8.1.2 | | | | +-----------+----------+-----------------------------------+-------+----+ |CLASS |[RFC5545],|privacy |Section| | | |Section | |2.3.7 | | | |3.8.1.3 | | | | +-----------+----------+-----------------------------------+-------+----+ |COLOR |[RFC7986],|color |Section| | | |Section | |2.3.8 | | | |5.9 | | | | +-----------+----------+-----------------------------------+-------+----+ |COMMENT |[RFC5545],|participants/*/participationComment|Section| | | |Section | |2.3.9 | | | |3.8.1.4 | | | | +-----------+----------+-----------------------------------+-------+----+ |CONCEPT |[RFC9253],|categories |Section| | | |Section | |2.3.10 | | | |8.1 | | | | +-----------+----------+-----------------------------------+-------+----+ |CONFERENCE |[RFC7986],|virtualLocations |Section| | | |Section | |2.3.11 | | | |5.11 | | | | +-----------+----------+-----------------------------------+-------+----+ |CREATED |[RFC5545],|created |Section| | | |Section | |2.3.12 | | | |3.8.7.1 | | | | +-----------+----------+-----------------------------------+-------+----+ |DESCRIPTION|[RFC5545],|description |Section| | | |Section | |2.3.13 | | | |3.8.1.5 | | | | Stepanek Expires 8 May 2025 [Page 32] Internet-Draft JSCalendar November 2024 +-----------+----------+-----------------------------------+-------+----+ |DTSTAMP |[RFC5545],|updated, scheduleUpdated |Section| | | |Section | |2.3.15 | | | |3.8.7.2 | | | | +-----------+----------+-----------------------------------+-------+----+ |DTSTART |[RFC5545],|start |Section| | | |Section | |2.3.16 | | | |3.8.2.4 | | | | +-----------+----------+-----------------------------------+-------+----+ |DUE |[RFC5545],|due |Section| | | |Section | |2.3.17 | | | |3.8.2.3 | | | | +-----------+----------+-----------------------------------+-------+----+ |DURATION |[RFC5545],|duration |Section| | | |Section | |2.3.18 | | | |3.8.2.5 | | | | +-----------+----------+-----------------------------------+-------+----+ |EXDATE |[RFC5545],|recurrenceOverrides |Section| | | |Section | |2.3.19 | | | |3.8.5.1 | | | | +-----------+----------+-----------------------------------+-------+----+ |EXRULE |[RFC2445],|excludedRecurrenceRules |Section| | | |Section | |2.3.20 | | | |4.8.5.2 | | | | +-----------+----------+-----------------------------------+-------+----+ |GEO |[RFC5545],|locations |Section| | | |Section | |2.3.21 | | | |3.8.1.6 | | | | +-----------+----------+-----------------------------------+-------+----+ |IMAGE |[RFC7986],|links |Section| | | |Section | |2.3.22 | | | |5.10 | | | | +-----------+----------+-----------------------------------+-------+----+ |LAST- |[RFC5545],|updated |Section| | |MODIFIED |Section | |2.3.23 | | | |3.8.7.3 | | | | +-----------+----------+-----------------------------------+-------+----+ |LINK |[RFC9253],|links |Section| | | |Section | |2.3.24 | | | |8.2 | | | | +-----------+----------+-----------------------------------+-------+----+ |LOCATION |[RFC5545],|locations |Section| | | |Section | |2.3.25 | | | |3.8.1.7 | | | | +-----------+----------+-----------------------------------+-------+----+ |ORGANIZER |[RFC5545],|replyTo |Section| | | |Section | |2.3.29 | | | |3.8.4.3 | | | | Stepanek Expires 8 May 2025 [Page 33] Internet-Draft JSCalendar November 2024 +-----------+----------+-----------------------------------+-------+----+ |PERCENT- |[RFC5545],|percentComplete |Section| | |COMPLETE |Section | |2.3.31 | | | |3.8.1.8 | | | | +-----------+----------+-----------------------------------+-------+----+ |PRIORITY |[RFC5545],|priority |Section| | | |Section | |2.3.32 | | | |3.8.1.9 | | | | +-----------+----------+-----------------------------------+-------+----+ |RDATE |[RFC5545],|recurrenceOverrides |Section| | | |Section | |2.3.34 | | | |3.8.5.2 | | | | +-----------+----------+-----------------------------------+-------+----+ |RECURRENCE-|[RFC5545],|recurrenceId |Section| | |ID |Section | |2.3.35 | | | |3.8.4.4 | | | | +-----------+----------+-----------------------------------+-------+----+ |RELATED-TO |[RFC5545],|relatedTo |Section| | | |Section | |2.3.36 | | | |3.8.4.5 | | | | +-----------+----------+-----------------------------------+-------+----+ |REQUEST- |[RFC5545],|requestStatus |Section| | |STATUS |Section | |2.3.37 | | | |3.8.8.3 | | | | +-----------+----------+-----------------------------------+-------+----+ |RRULE |[RFC5545],|recurrenceRules |Section| | | |Section | |2.3.38 | | | |3.8.5.3 | | | | +-----------+----------+-----------------------------------+-------+----+ |SEQUENCE |[RFC5545],|sequence |Section| | | |Section | |2.3.39 | | | |3.8.7.4 | | | | +-----------+----------+-----------------------------------+-------+----+ |STRUCTURED-|[RFC9073],|links |Section| | |DATA |Section | |2.3.42 | | | |6.6 | | | | +-----------+----------+-----------------------------------+-------+----+ |STYLED- |[RFC9073],|description |Section| | |DESCRIPTION|Section | |2.3.43 | | | |6.5 | | | | +-----------+----------+-----------------------------------+-------+----+ |SUMMARY |[RFC5545],|title |Section| | | |Section | |2.3.44 | | | |3.8.1.12 | | | | +-----------+----------+-----------------------------------+-------+----+ |TRANSP |[RFC5545],|freeBusyStatus |Section| | | |Section | |2.3.45 | | | |3.8.2.7 | | | | Stepanek Expires 8 May 2025 [Page 34] Internet-Draft JSCalendar November 2024 +-----------+----------+-----------------------------------+-------+----+ |UID |[RFC5545],|uid |Section| | | |Section | |2.3.54 | | | |3.8.4.7 | | | | +-----------+----------+-----------------------------------+-------+----+ |URL |[RFC5545],|links |Section| | | |Section | |2.3.55 | | | |3.8.4.6 | | | | +-----------+----------+-----------------------------------+-------+----+ Table 13: Properties of the VTODO component Its components convert as follows: +========+===============+===============+=========+======+ | Name | Reference | Task property | See | Note | +========+===============+===============+=========+======+ | VALARM | [RFC5545], | alerts | Section | | | | Section 3.6.6 | | 2.2.2 | | +--------+---------------+---------------+---------+------+ Table 14: Components of the VTODO component Other properties or components MAY be converted to the iCalComponent property (Section 5.1.1) of the Task object. The following example illustrates how to convert the VTODO component: BEGIN:VCALENDAR BEGIN:VTODO UID:83C80482-806D-41C4-8029-E438F793005D DUE:20060102T030405Z ... { "...": "", "@type": "Group", "entries": [ { "...": "", "@type": "Task", "due": "2006-01-02T03:04:05", "timeZone": "Etc/UTC", "uid": "83C80482-806D-41C4-8029-E438F793005D" } ] } Figure 15: Converting the VTODO component Stepanek Expires 8 May 2025 [Page 35] Internet-Draft JSCalendar November 2024 2.3. Properties 2.3.1. ACKNOWLEDGED The ACKNOWLEDGED property [RFC9074] (Section 6.1) in a VALARM component converts to the acknowledged property [RFC8984] (Section 4.5.2) of the Alert object. The following example illustrates how to convert the ACKNOWLEDGED property: BEGIN:VEVENT BEGIN:VALARM TRIGGER:-PT5M ACTION:DISPLAY ACKNOWLEDGED:20241002T114703Z ... "alerts": { "a": { "@type": "Alert", "acknowledged": "2024-10-02T11:47:03Z", "...": "" } } Figure 16: Converting the ACKNOWLEDGED property 2.3.2. ACTION The ACTION property [RFC5545] (Section 3.8.6.1) in a VALARM component converts to the action property [RFC8984] (Section 4.5.2) of the Alert object. Its values convert as follows: +=================+==================+ | iCalendar value | JSCalendar value | +=================+==================+ | DISPLAY | display | +-----------------+------------------+ | EMAIL | email | +-----------------+------------------+ Table 15: Values of the ACTION property Stepanek Expires 8 May 2025 [Page 36] Internet-Draft JSCalendar November 2024 An ACTION property with value AUDIO or any other not listed in Table 15 does not convert to the action property. Instead, the property converts to the iCalComponent/properties property (Section 5.1.1) of the Alert. The following examples illustrate how to convert the ACTION property: BEGIN:VEVENT BEGIN:VALARM TRIGGER:-PT5M ACTION:DISPLAY ... "alerts": { "a": { "@type": "Alert", "action": "display", "...": "" } } Figure 17: Converting the ACTION property for value DISPLAY BEGIN:VEVENT BEGIN:VALARM TRIGGER:-PT5M ACTION:AUDIO ... "alerts": { "a": { "@type": "Alert", "iCalComponent": { "name": "valarm", "properties": [ [ "action", {}, "text", "AUDIO" ] ] }, "...": "" } } Figure 18: Converting the ACTION property for value AUDIO Stepanek Expires 8 May 2025 [Page 37] Internet-Draft JSCalendar November 2024 2.3.3. ATTACH The ATTACH property [RFC5545] (Section 3.8.1.1) in a VEVENT, VTODO, VRESOURCE, PARTICIPANT, or VLOCATION component converts to a Link object [RFC8984] (Section 1.4.11). The converted object is set in the links property of the Event, Task, Participant, or Location object. The property value converts to the href property of the Link object. A value of type URI converts as-is. A value of type BINARY converts to a URI in the "data" URL scheme ([RFC2397]. If the FMTTYPE parameter is set on the ATTACH property, then the parameter value SHOULD be set in the mediatype part of the data URL. The ATTACH property parameters convert as follows: +=========+==========================+===============+======+ | Name | Reference | Link Property | Note | +=========+==========================+===============+======+ | FMTTYPE | [RFC5545], Section 3.2.8 | contentType | | +---------+--------------------------+---------------+------+ | SIZE | [RFC8607], Section 4.1 | size | | +---------+--------------------------+---------------+------+ Table 16: Parameters of the ATTACH property The following examples illustrate how to convert the ATTACH property: ATTACH:https://example.com/foo.pdf "links": { "a": { "@type": "Link", "href": "https://example.com/foo.pdf" } } Figure 19: Converting the ATTACH property with URI value ATTACH;ENCODING=BASE64;VALUE=BINARY;FMTTYPE=image/png:iVBORw 0KGgoAAAANSUhEUgAAAAEAAAABAQAAAAA3bvkkAAAAAmJLR0QAAd2KE6QAA AAKSURBVAjXY2gAAACCAIHdQ2r0AAAAAElFTkSuQmCC "links": { "a": { "@type": "Link", "href": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABAQAAAAA3bvkkAAAAAmJLR0QAAd2KE6QAAAAKSURBVAjXY2gAAACCAIHdQ2r0AAAAAElFTkSuQmCC", "contentType": "image/png" } } Stepanek Expires 8 May 2025 [Page 38] Internet-Draft JSCalendar November 2024 Figure 20: Converting the ATTACH property with BINARY value 2.3.4. ATTENDEE The ATTENDEE property [RFC5545] (Section 3.8.4.1) in a VEVENT or VTODO component converts to a Participant object [RFC8984] (Section 4.4.6). The converted object is set in the participants property of the Event or Task object. The property value converts to both the calendarAddress and sendTo properties of the Participant object. If the CAL-ADDRESS value is in the "mailto" scheme, then it converts to the "imip" method in the sendTo property, otherwise it converts to the "other" method. The ATTENDEE property parameters convert as follows: +=====================+================+=====================+======+ | Name | Reference | Participant | Note | | | | Property | | +=====================+================+=====================+======+ | CN | [RFC5545], | name | | | | Section 3.2.2 | | | +---------------------+----------------+---------------------+------+ | CUTYPE | [RFC5545], | kind | | | | Section 3.2.3 | | | +---------------------+----------------+---------------------+------+ | DELEGATED-FROM | [RFC5545], | delegatedFrom | | | | Section 3.2.4 | | | +---------------------+----------------+---------------------+------+ | DELEGATED-TO | [RFC5545], | delegatedTo | | | | Section 3.2.5 | | | +---------------------+----------------+---------------------+------+ | DIR | [RFC5545], | links | | | | Section 3.2.6 | | | +---------------------+----------------+---------------------+------+ | EMAIL | [RFC7986], | email | | | | Section 6.2 | | | +---------------------+----------------+---------------------+------+ | MEMBER | [RFC5545], | memberOf | | | | Section | | | | | 3.2.11 | | | +---------------------+----------------+---------------------+------+ | PARTSTAT | [RFC5545], | participationStatus | | | | Section | | | | | 3.2.12 | | | +---------------------+----------------+---------------------+------+ | ROLE | [RFC5545], | roles | | | | Section | | | Stepanek Expires 8 May 2025 [Page 39] Internet-Draft JSCalendar November 2024 | | 3.2.16 | | | +---------------------+----------------+---------------------+------+ | RSVP | [RFC5545], | expectReply | | | | Section | | | | | 3.2.17 | | | +---------------------+----------------+---------------------+------+ | SCHEDULE-AGENT | [RFC6638], | scheduleAgent | | | | Section 7.1 | | | +---------------------+----------------+---------------------+------+ | SCHEDULE-FORCE-SEND | [RFC6638], | scheduleForceSend | | | | Section 7.2 | | | +---------------------+----------------+---------------------+------+ | SCHEDULE-STATUS | [RFC6638], | scheduleStatus | | | | Section 7.3 | | | +---------------------+----------------+---------------------+------+ Table 17: Parameters of the ATTENDEE property If no ROLE parameter is set, then the "attendee" role in the roles property MUST be set. Every calendar address value of the DELEGATED-FROM, DELEGATED-TO, or MEMBER parameters converts to the identifier of an Participant object. This identifier is determined by finding that Participant object in the participants property, which has a calendarAddress property value matching the parameter value. If no such Participant object exists after all properties and components have been converted, then a new Participant object having that calendarAddress property value is created. If multiple Participant objects match, then choosing the Participant identifier is implementation-specific. An ATTENDEE property and a PARTICIPANT component in the same iCalendar component convert to the same Participant object, if their converted calendarAddress property values are equal after URI normalization [RFC3986] (Section 6). How to deal with conflicting values when converting other Participant properties is implementation-specific. The following examples illustrate how to convert the ATTENDEE property: ATTENDEE;PARTSTAT=TENTATIVE;CN=Henry Cabot:mailto:hcabot@example.com Stepanek Expires 8 May 2025 [Page 40] Internet-Draft JSCalendar November 2024 "participants": { "p3": { "@type": "Participant", "calendarAddress": "mailto:hcabot@example.com", "name": "Henry Cabot", "participationStatus": "tentative", "roles": { "attendee": true }, "sendTo": { "imip": "mailto:hcabot@example.com" } }, "o4": { "...": "" } } Figure 21: Converting the ATTENDEE property BEGIN:PARTICIPANT CALENDAR-ADDRESS:mailto:foo@example.com DTSTAMP:20230723T125201Z ... END:PARTICIPANT ATTENDEE;PARTSTAT=TENTATIVE:mailto:foo@example.com "participants": { "23": { "@type": "Participant", "calendarAddress": "mailto:foo@example.com", "participationStatus": "tentative", "scheduleUpdated": "2023-07-23T12:52:01Z", "...": "" }, "o4": { "...": "" } } Figure 22: Converting the ATTENDEE property and PARTICIPANT component 2.3.5. CALENDAR-ADDRESS The CALENDAR-ADDRESS property [RFC9073] (Section 6.4) in a PARTICIPANT component converts to the calendarAddress property [I-D.ietf-jmap-calendars] (Section 5.1.1) of the Participant object. Stepanek Expires 8 May 2025 [Page 41] Internet-Draft JSCalendar November 2024 The following example illustrates how to convert the CALENDAR-ADDRESS property: BEGIN:PARTICIPANT CALENDAR-ADDRESS:mailto:foo@example.com ... "participants": { "a2": { "@type": "Participant", "calendarAddress": "mailto:foo@example.com", "...": "" } } Figure 23: Converting the CALENDAR-ADDRESS property 2.3.6. CATEGORIES The CATEGORIES property [RFC5545] (Section 3.8.1.2) in a VEVENT, VTODO, or VCALENDAR component converts to the keywords property [RFC8984] (Section 4.2.9) of the Event, Task, or Group object. The list of category values converts to a set of keywords. The values convert case-sensitively. All CATEGORIES properties in the same iCalendar component convert to the keywords property in the JSCalendar object. The following example illustrates how to convert the CATEGORIES property: CATEGORIES:APPOINTMENT,EDUCATION CATEGORIES:meeting "keywords": { "APPOINTMENT": true, "EDUCATION": true, "meeting": true } Figure 24: Converting the CATEGORIES property 2.3.7. CLASS The CLASS property [RFC5545] (Section 3.8.1.3) in a VEVENT or VTODO component converts to the privacy property [RFC8984] (Section 4.4.3) of the Event or Task object. Its values convert as follows: Stepanek Expires 8 May 2025 [Page 42] Internet-Draft JSCalendar November 2024 +=================+==================+ | iCalendar value | JSCalendar value | +=================+==================+ | PUBLIC | public | +-----------------+------------------+ | PRIVATE | private | +-----------------+------------------+ | CONFIDENTIAL | secret | +-----------------+------------------+ Table 18: Values of the CLASS property Any other value does not convert to the class property. Instead, the property converts to the iCalComponent/properties property (Section 5.1.1) of the JSCalendar object. The following example illustrates how to convert the CLASS property: CLASS:PRIVATE "privacy": "private" Figure 25: Converting the CLASS property 2.3.8. COLOR The COLOR property [RFC7986] (Section 5.9) in a VEVENT, VTODO, or VCALENDAR component converts to the color property [RFC8984] (Section 4.2.11) of the Event, Task, or Group object. Its value converts verbatim. The following examples illustrate how to convert the COLOR property: COLOR:maroon "color": "maroon" Figure 26: Converting the COLOR property with color name COLOR:#ffa07a "color": "#ffa07a" Figure 27: Converting the COLOR property with numeric value 2.3.9. COMMENT The COMMENT property [RFC5545] (Section 3.8.1.4) in a DAYLIGHT or STANDARD component converts to the comments property [RFC8984] (Section 4.7.2) of the TimeZoneRule object. Stepanek Expires 8 May 2025 [Page 43] Internet-Draft JSCalendar November 2024 The COMMENT property [RFC5545] (Section 3.8.1.4) in a PARTICIPANT component converts to the participationComment property [RFC8984] (Section 4.4.6). The COMMENT property [RFC5545] (Section 3.8.1.4) in an iTIP-scheduled [RFC5546] VEVENT or VTODO component converts to the participationComment property [RFC8984] (Section 4.4.6) of that Participant object, which represents the source of this scheduling message, if any. It otherwise converts to the iCalComponent/ properties property (Section 5.1.1) of the Event or Task object. Multiple COMMENT properties in a DAYLIGHT or STANDARD component convert in order of appearance in the comments property. Converting multiple COMMENT properties to the single-valued participationComment property is implementation-specific. The following examples illustrate how to convert the COMMENT property: BEGIN:VCALENDAR BEGIN:VTIMEZONE TZID:NonIana BEGIN:DAYLIGHT TZOFFSETFROM:-0400 TZOFFSETTO:-0300 DTSTART:20010503T000000 COMMENT:take note of this COMMENT:and this END:DAYLIGHT END:VTIMEZONE ... Stepanek Expires 8 May 2025 [Page 44] Internet-Draft JSCalendar November 2024 { "@type": "Group", "timeZones": { "/NonIana": { "@type": "TimeZone", "daylight": [ { "@type": "TimeZoneRule", "comments": [ "take note of this", "and this" ], "...": "" } ], "...": "" } }, "...": "" } Figure 28: Converting the COMMENT property in a DAYLIGHT component BEGIN:PARTICIPANT UID:127ABD62-D07A-4F39-AA62-530E37A8DF78 COMMENT:I'll think about it ... "participants": { "g2": { "@type": "Participant", "participationComment": "I'll think about it", "...": "" } } Figure 29: Converting the COMMENT property in a PARTICIPANT component 2.3.10. CONCEPT The CONCEPT property [RFC9253] (Section 8.1) in a VEVENT, VTODO, or VCALENDAR component converts to the categories property [RFC8984] (Section 4.2.10) of the Event, Task, or Group object. The list of URI values converts to a set of URIs. Multiple occurrences of the CONCEPT property in the same iCalendar component convert to the same categories property in the JSCalendar object. Stepanek Expires 8 May 2025 [Page 45] Internet-Draft JSCalendar November 2024 The following example illustrates how to convert the CONCEPT property: CONCEPT:https://example.com/event-types/arts/music CONCEPT:https://example.com/event-types/arts/literature "categories": { "https://example.com/event-types/arts/music": true, "https://example.com/event-types/arts/literature": true } Figure 30: Converting the CONCEPT property 2.3.11. CONFERENCE The CONFERENCE property [RFC7986] (Section 5.11) in a VEVENT or VTODO component converts to a VirtualLocation object [RFC8984] (Section 4.2.6). The converted object is set in the virtualLocations property of the Event or Task object. The property value converts to the uri property of the VirtualLocation object. Its parameters convert as follows: +=========+========================+==========+======+ | Name | Reference | Property | Note | +=========+========================+==========+======+ | FEATURE | [RFC7986], Section 6.3 | features | | +---------+------------------------+----------+------+ | LABEL | [RFC7986], Section 6.4 | name | | +---------+------------------------+----------+------+ Table 19: Parameters of the CONFERENCE property The following example illustrates how to convert the CONFERENCE property: CONFERENCE;VALUE=URI;FEATURE=AUDIO,VIDEO; LABEL=Attendee dial-in:https://chat.example.com/audio?id=123456 Stepanek Expires 8 May 2025 [Page 46] Internet-Draft JSCalendar November 2024 "virtualLocations": { "b2": { "@type": "VirtualLocation", "name": "Attendee dial-in", "uri": "https://chat.example.com/audio?id=123456", "features": { "audio": true, "video": true } } } Figure 31: Converting the CONFERENCE property 2.3.12. CREATED The CREATED property [RFC5545] (Section 3.8.7.1) in a VEVENT, VTODO, or VCALENDAR component converts to the created property [RFC8984] (Section 4.1.5) of the Event, Task, or Group object. The following example illustrates how to convert the CREATED property: CREATED:20240329T133000Z "created": "2024-03-29T13:30:00Z" Figure 32: Converting the CREATED property 2.3.13. DESCRIPTION The DESCRIPTION property [RFC5545] (Section 3.8.1.5) in a VEVENT, VTODO, VCALENDAR, VLOCATION, VRESOURCE, or PARTICIPANT component converts to the description property [RFC8984] (Section 4.2.2) of the Event, Task, Group, Location, Link, or Participant object, unless its DERIVED parameter value is TRUE. If the DERIVED parameter value is TRUE, then the property does not convert to the description property. Instead, a non-derived STYLED- DESCRIPTION property is expected to contain the description. Implementations MAY preserve the property in the iCalComponent property (Section 5.1.1). The following example illustrates how to convert the DESCRIPTION property: DESCRIPTION:The pancakes there are delicious\; they are fluffy and sweet. "description": "The pancakes there are delicious; they are fluffy and sweet." Stepanek Expires 8 May 2025 [Page 47] Internet-Draft JSCalendar November 2024 Figure 33: Converting the DESCRIPTION property 2.3.14. DTEND The DTEND property [RFC5545] (Section 3.8.2.2) in a VEVENT component converts to the duration property [RFC8984] (Section 5.1.2) of the Event object. The duration is the timespan between the points in time of the DTSTART and DTEND property values when converted to UTC time. If the timezone identifier (Section 2.1.4) of the DTEND property differs from that of the DTSTART property, then the DTEND property also converts to a Location object. The timezone identifier converts to the timeZone property of the Location object. The relativeTo property of the Location is set to "end". The Location object is set in the locations property of the Event object. Implementations MAY preserve the fact that the duration got determined by the DTEND property. How to this depends on if the timezone identifiers of DTSTART and DTEND are equal. If the identifiers are equal, then implementations MUST set the iCalComponent property (Section 5.1.1) in the Event object and there add an entry for the path "duration" in the convertedProperties property. The value MUST be an ICalProperty object with the name property set to "dtend". If instead the timezone identifiers are not equal, then implementations MUST set the iCalProperty property (Section 5.1.2) of the Location object. The following examples illustrate how to convert the DTEND property: DTSTART;TZID=Australia/Melbourne:20241002T130000 DTEND;TZID=Australia/Melbourne:20241002T140000 "start": "2024-10-02T13:00:00", "timeZone": "Australia/Melbourne", "duration": "PT1H", "iCalComponent": { "convertedProperties": { "duration": { "@type": "ICalProperty", "name": "dtend" } } } Figure 34: Converting the DTEND property with same timezone Stepanek Expires 8 May 2025 [Page 48] Internet-Draft JSCalendar November 2024 DTSTART;TZID=Europe/Berlin:20241017T130005 DTEND;TZID=Asia/Bangkok:20241018T020325 "start": "2024-10-17T13:00:05", "timeZone": "Europe/Berlin", "duration": "PT9H20M", "locations": { "l5": { "timeZone": "Asia/Bangkok", "relativeTo": "end", "iCalProperty": { "@type": "ICalProperty", "name": "dtend" } } } Figure 35: Converting the DTEND property with different timezone DTSTART;VALUE=DATE:20240102 DTEND;VALUE=DATE:20240112 "start": "2024-01-02T00:00:00", "timeZone": null, "duration": "P1W2D", "showWithoutTime": true Figure 36: Converting the DTEND property with DATE value type 2.3.15. DTSTAMP The DTSTAMP property [RFC5545] (Section 3.8.7.2) in a VEVENT or VTODO component converts to the updated property [RFC8984] (Section 4.1.6) of the Event or Task object. Both the LAST-MODIFIED and DTSTAMP properties convert to the updated property. If both are present in the same component, then the DTSTAMP property value has higher precedence. Implementations MAY in that case preserve the value of the LAST-MODIFIED property in the iCalComponent property. An Event or Task object which has the method property set might represent an iTIP reply of one of the participants in the object. In this case the value of the updated property in the Event or Task also converts to the scheduleUpdated property [RFC8984] (Section 4.4.6) of that Participant object, which represents the participant from which the iTIP reply originated. Stepanek Expires 8 May 2025 [Page 49] Internet-Draft JSCalendar November 2024 The DTSTAMP property in a PARTICIPANT component converts to the scheduleUpdated property [RFC8984] (Section 4.4.6) of the Participant object. The following examples illustrate how to convert the DTSTAMP property: BEGIN:VCALENDAR METHOD:REPLY BEGIN:VEVENT DTSTAMP:20240304T132000Z ... { "@type": "Group", "entries": [ { "@type": "Event", "method": "reply", "updated": "2024-03-04T13:20:00Z", "...": "" } ], "...": "" } Figure 37: Converting the DTSTAMP property in a VEVENT component BEGIN:VEVENT BEGIN:PARTICIPANT DTSTAMP:20240304T132000Z ... "participants": { "f4": { "@type": "Participant", "scheduleUpdated": "2024-03-04T13:20:00Z", "...": "" } } Figure 38: Converting the DTSTAMP property in a PARTICIPANT component 2.3.16. DTSTART The DTSTART property [RFC5545] (Section 3.8.2.4) in a VEVENT, VTODO, DAYLIGHT or STANDARD component converts to the start property [RFC8984] (Section 4.7.2) of the Event, Task, or TimeZoneRule object. See Section 2.1.5 how to convert DATE and DATE-TIME values. Stepanek Expires 8 May 2025 [Page 50] Internet-Draft JSCalendar November 2024 For VEVENT and VTODO components, the timezone identifier (Section 2.1.4) of the DTSTART property converts to the timeZone property of the Event or Task object. In addition, if the value type of the DTSTART property is DATE, then the value of the showWithoutTime property [RFC8984] (Section 4.2.4) is "true". The following examples illustrate how to convert the DTSTART property for the VEVENT and VTODO components. See Section 2.2.6 for examples how to convert the DTSTART property for the DAYLIGHT and STANDARD components. DTSTART;TZID=Europe/Berlin:20240921T105302 "start": "2024-09-21T10:53:02", "timeZone": "Europe/Berlin", "showWithoutTime": "false" Figure 39: Converting the DTSTART property with TZID parameter DTSTART:20240921T105302Z "start": "2024-09-21T10:53:02", "timeZone": "Etc/UTC", "showWithoutTime": "false" Figure 40: Converting the DTSTART property with UTC time DTSTART:20240921T105302 "start": "2024-09-21T10:53:02", "timeZone": null, "showWithoutTime": "false" Figure 41: Converting the DTSTART property with floating time DTSTART;VALUE=DATE:20240921 "start": "2024-09-21T00:00:00", "timeZone": null, "showWithoutTime": "true" Figure 42: Converting the DTSTART property with value type DATE 2.3.17. DUE The DUE property [RFC5545] (Section 3.8.2.3) in a VTODO component converts to the due property [RFC8984] (Section 5.2.1) of the Task object. See Section 2.1.5 how to convert DATE and DATE-TIME values. Stepanek Expires 8 May 2025 [Page 51] Internet-Draft JSCalendar November 2024 If the VTODO component does not contain a DTSTART property, then the timezone identifier (Section 2.1.4) of the DUE property converts to the timeZone property of the Task object. If instead the VTODO component contains both the DUE and DTSTART properties, then the timezone identifier of the DUE property does not convert to a standard JSCalendar element. The value of the due property MUST denote the date and time relative to the timezone of the DTSTART property. If the value type of the DUE property is DATE, then the value of the showWithoutTime property [RFC8984] (Section 4.2.4) is "true". The following examples illustrate how to convert the DUE property: DUE;TZID=Europe/Berlin:20240921T105302 "due": "2024-09-21T10:53:02", "timeZone": "Europe/Berlin", "showWithoutTime": "false" Figure 43: Converting the DUE property with TZID parameter DUE:20240921T105302Z "start": "2024-09-21T10:53:02", "timeZone": "Etc/UTC", "showWithoutTime": "false" Figure 44: Converting the DUE property with UTC time DUE:20240921T105302 "start": "2024-09-21T10:53:02", "timeZone": null, "showWithoutTime": "false" Figure 45: Converting the DUE property with floating time DUE;VALUE=DATE:20240921 "start": "2024-09-21T00:00:00", "timeZone": null, "showWithoutTime": "true" Figure 46: Converting the DUE property with value type DATE 2.3.18. DURATION The DURATION property [RFC5545] (Section 3.8.2.5) in a VEVENT or VTODO component converts to the duration property [RFC8984] (Section 5.1.2) of the Event or Task object. Stepanek Expires 8 May 2025 [Page 52] Internet-Draft JSCalendar November 2024 The following example illustrates how to convert the DURATION property: DURATION:PT1H "duration": "PT1H" Figure 47: Converting the DURATION 2.3.19. EXDATE The EXDATE property [RFC5545] (Section 3.8.5.1) of value type DATE or DATE-TIME in a VEVENT or VTODO component converts to a PatchObject object [RFC8984] (Section 1.4.9). The converted object is set in the recurrenceOverrides property of the Event or Task object. The property value converts to the key in the recurrenceOverrides property value. See Section 2.1.5 how to convert DATE and DATE-TIME values. The date-time MUST be relative to the timezone identified by the timeZone property of the Event or Task. The PatchObject value MUST set the excluded property to "true" and MUST NOT set any other property. An EXDATE property of value type PERIOD does not convert to a standard JSCalendar element. Implementations MAY convert it to the iCalComponent property (Section 5.1.1) of the Event or Task object. The following example illustrates how to convert the EXDATE property: DTSTART:20230101T130000Z RRULE:FREQ=MONTHLY EXDATE:20230801T130000Z "start": "2023-01-01T13:00:00", "timeZone": "Etc/UTC", "recurrenceRules": [ { "@type": "RecurrenceRule", "frequency": "monthly" } ], "recurrenceOverrides": { "2023-08-01T13:00:00": { "excluded": true } } Figure 48: Converting the EXDATE property Stepanek Expires 8 May 2025 [Page 53] Internet-Draft JSCalendar November 2024 2.3.20. EXRULE The EXRULE property [RFC2445] (Section 4.8.5.2) in a VEVENT or VTODO component converts to a RecurrenceRule object [RFC8984] (Section 4.3.3). The converted object is set in the excludedRecurrenceRules property of the Event or Task. See Section 2.3.38 for an example how to convert a recurrence rule. 2.3.21. GEO The GEO property [RFC5545] (Section 3.8.1.6) in a VLOCATION component converts to the coordinates property [RFC8984] (Section 4.2.5). The GEO property [RFC5545] (Section 3.8.1.6) in a VEVENT, VTODO, PARTICIPANT or VRESOURCE component converts to a Location object [RFC8984] (Section 4.2.5). The converted object is set in the locations property of the Event, Task, or Participant object. The pair of FLOAT values converts to an URI with the "geo" scheme [RFC5870]. The first FLOAT value converts to the "coord-a" part of the URI, the second FLOAT value to the "coord-b" part. A preceding plus sign (+) of the FLOAT value MUST be omitted, a preceding minus sign (-) MUST be preserved. The third, altitude coordinate MUST NOT be set, unless its value is known. The following examples illustrate how to convert the GEO property: GEO:+45.5;-93.3 "locations": { "d4": { "@type": "Location", "coordinates": "geo:45.5,-93.3" } } Figure 49: Converting the GEO property in a VEVENT BEGIN:VEVENT BEGIN:VLOCATION NAME:Eiffel Tower GEO:48.858222;2.2945 ... Stepanek Expires 8 May 2025 [Page 54] Internet-Draft JSCalendar November 2024 "locations": { "2": { "@type": "Location", "name": "Eiffel Tower", "coordinates": "geo:48.858222,2.2945" } } Figure 50: Converting the GEO property in a VLOCATION 2.3.22. IMAGE The IMAGE property [RFC7986] (Section 5.10) in a VEVENT, VTODO, VLOCATION, or VRESOURCE component converts to a Link object [RFC8984] (Section 1.4.11). The converted object is set in the links property of the Event, Task, Location, or Participant object. The property value converts to the href property of the Link object. A value of type URI converts as-is. See Section 2.3.3 how to convert a BINARY value. If the DISPLAY parameter is set, then the "rel" property of the Link object MUST be set to "icon". Its parameters convert as follows: +=========+==========================+=============+======+ | Name | Reference | Property | Note | +=========+==========================+=============+======+ | DISPLAY | [RFC7986], Section 6.1 | display | | +---------+--------------------------+-------------+------+ | FMTTYPE | [RFC5545], Section 3.2.8 | contentType | | +---------+--------------------------+-------------+------+ | SIZE | [RFC8607], Section 4.1 | size | | +---------+--------------------------+-------------+------+ Table 20: Parameters of the IMAGE property Implementations MAY preserve the fact that the Link object got converted from an IMAGE property. To so, they MUST set the iCalProperty (Section 5.1.2) on the Link object. The following example illustrates how to convert the IMAGE property: IMAGE;VALUE=URI;DISPLAY=BADGE;FMTTYPE=image/png: https://example.com/images/party.png Stepanek Expires 8 May 2025 [Page 55] Internet-Draft JSCalendar November 2024 "links": { "4": { "@type": "Link", "href": "https://example.com/images/party.png", "display": "badge", "rel": "icon", "contentType": "image/png", "iCalProperty": { "@type": "ICalProperty", "name": "image" } } } Figure 51: Converting the IMAGE property 2.3.23. LAST-MODIFIED The LAST-MODIFIED property [RFC5545] (Section 3.8.7.3) in a VEVENT, VTODO, VCALENDAR, or VTIMEZONE component converts to the updated property [RFC8984] (Section 4.1.6) of the Event, Task, Group, or TimeZone object. Both the LAST-MODIFIED and DTSTAMP properties convert to the updated property. If both are present in the same component, then the DTSTAMP property value has higher precedence. Implementations MAY in that case preserve the value of the LAST-MODIFIED property in the iCalComponent property. The following example illustrates how to convert the LAST-MODIFIED property: LAST-MODIFIED:20240914T231257Z "updated": "2024-09-14T23:12:57Z" Figure 52: Converting the IMAGE property 2.3.24. LINK The LINK property [RFC9253] (Section 8.2) in a VEVENT, VTODO, VCALENDAR, VRESOURCE, PARTICIPANT, or VLOCATION component converts to a Link object [RFC8984] (Section 1.4.11) under the following conditions: * The property value type is URI. Stepanek Expires 8 May 2025 [Page 56] Internet-Draft JSCalendar November 2024 * The LINKREL parameter either is not set, or the parameter value is a registered relation type as defined in [RFC8288] (Section 2.1.1). The converted object is set in the links property of the Event, Task, Group, Participant, or Location object. The LINK property value converts to the href property of the Link object. Its parameters convert as follows: +=========+==========================+=============+======+ | Name | Reference | Property | Note | +=========+==========================+=============+======+ | FMTTYPE | [RFC5545], Section 3.2.8 | contentType | | +---------+--------------------------+-------------+------+ | LABEL | [RFC7986], Section 6.4 | title | | +---------+--------------------------+-------------+------+ | LINKREL | [RFC9253], Section 6.1 | rel | | +---------+--------------------------+-------------+------+ Table 21: Parameters of the LINK property A LINK property with a value type other than URI or an unregistered LINK parameter value does not convert to a standard JSCalendar element. Implementations MAY convert it to the iCalComponent property (Section 5.1.1). The following examples illustrate how to convert the LINK property: LINK;LABEL=Venue;VALUE=URI:https://example.com/events "links": { "l1": { "@type": "Link", "href": "https://example.com/events", "title": "Venue" } } Figure 53: Converting the LINK property to a Link object BEGIN:VEVENT LINK;LINKREL="https://example.com/linkrel/costStructure"; VALUE=XML-REFERENCE: https://example.com/xmlDocs/bidFramework.xml#xpointer(id("cost")) ... Stepanek Expires 8 May 2025 [Page 57] Internet-Draft JSCalendar November 2024 "iCalComponent": { "@type": "ICalComponent", "name": "vevent", "properties": [ [ "link", { "linkrel": "https://example.com/linkrel/costStructure" }, "xml-reference", "https://example.com/xmlDocs/bidFramework.xml#xpointer(id(\"cost\"))" ] ] } Figure 54: Converting the LINK property to iCalComponent 2.3.25. LOCATION The LOCATION property [RFC5545] (Section 3.8.1.7) in a VEVENT, VTODO, or PARTICIPANT component converts to a Location object [RFC8984] (Section 4.2.5), unless its DERIVED parameter value is TRUE. The converted object is set in the locations property of the Event, Task, or Participant object. The property value converts to the title property of the Location object. If the DERIVED parameter value is TRUE, then the property does not convert to a Location object. Instead, a VLOCATION component is expected to represent the location. Implementations MAY preserve the property in the iCalComponent property (Section 5.1.1). The following example illustrates how to convert the LOCATION property: LOCATION:Conference Room - F123\, Bldg. 002 "locations": { "f45": { "@type": "Location", "title": "Conference Room - F123, Bldg. 002" } } Figure 55: Converting the LOCATION property Stepanek Expires 8 May 2025 [Page 58] Internet-Draft JSCalendar November 2024 2.3.26. LOCATION-TYPE The LOCATION-TYPE property [RFC9073] (Section 6.1) in a VLOCATION component converts to the locationTypes property [RFC8984] (Section 4.2.5). The list of location type values converts to a set of location types. The values convert case-sensitively. All LOCATION-TYPE properties in the same VLOCATION convert to the locationTypes property in the Location object. The following example illustrates how to convert the LOCATION-TYPE property: BEGIN:VEVENT BEGIN:VLOCATION LOCATION-TYPE:hotel,restaurant LOCATION-TYPE:bar ... "locations": { "1": { "@type": "Location", "locationTypes": { "bar": true, "hotel": true, "restaurant": true }, "...": "" } } Figure 56: Converting the LOCATION property 2.3.27. METHOD The METHOD property [RFC5545] (Section 3.7.2) in a VCALENDAR component converts to the method property [RFC8984] (Section 4.1.8) of all Event or Task objects that are listed in the Group object's entries property. The property value converts in lowercase. The following example illustrates how to convert the METHOD property: BEGIN:VCALENDAR METHOD:REQUEST BEGIN:VEVENT ... Stepanek Expires 8 May 2025 [Page 59] Internet-Draft JSCalendar November 2024 { "@type": "Group", "entries": [ { "@type": "Event", "method": "request", "...": "" } ], "...": "" } Figure 57: Converting the METHOD property 2.3.28. NAME The NAME property [RFC7986] (Section 5.1) in a VLOCATION or VRESOURCE component converts to the name property of the Location [RFC8984] (Section 4.2.5) or Participant [RFC8984] (Section 4.4.6) object. The NAME property [RFC7986] (Section 5.1) in a VCALENDAR component converts to the title property [RFC8984] (Section 4.2.1) of the Group object. The following examples illustrate how to convert the NAME property: BEGIN:VCALENDAR NAME:Company Vacation Days ... { "@type": "Group", "title": "Company Vacation Days", "...": "" } Figure 58: Converting the NAME property in a VCALENDAR component BEGIN:VEVENT BEGIN:PARTICIPANT NAME:John Doe ... END:PARTICIPANT BEGIN:VLOCATION NAME:Fred's Bar ... END:VLOCATION ... Stepanek Expires 8 May 2025 [Page 60] Internet-Draft JSCalendar November 2024 "locations": { "1": { "@type": "Location", "name": "Fred's Bar", "...": "" } }, "participants": { "1": { "@type": "Participant", "name": "John Doe", "...": "" } } Figure 59: Converting the NAME property in the VLOCATION and PARTICIPANT components 2.3.29. ORGANIZER The ORGANIZER property [RFC5545] (Section 3.8.4.3) in a VEVENT or VTODO component converts to the replyTo property [RFC8984] (Section 4.4.4). In addition, it converts to a Participant object in the participants property [RFC8984] (Section 4.4.6). If the CAL-ADDRESS property value is in the "mailto" scheme, then it converts to the "imip" method in the replyTo property, otherwise it converts to the "other" method. The property value also converts to the calendarAddress property of the Participant object. The "owner" role is set in the roles property of the Participant. In contrast to the ATTENDEE property, the property value does not convert to the sendTo property of the Participant object. An ORGANIZER property, an ATTENDEE property, and a PARTICIPANT component in the same iCalendar component all convert to the same Participant object, if their converted calendarAddress property values are equal after URI normalization [RFC3986] (Section 6). How to deal with conflicting values when converting other Participant properties is implementation-specific. Implementations MAY preserve arbitrary parameters of the ORGANIZER property, in which case they MUST convert these to a "replyTo" entry in the convertedProperties property of the Event or Task object's iCalComponent property (Section 5.1.1). The ORGANIZER property parameters convert as follows: Stepanek Expires 8 May 2025 [Page 61] Internet-Draft JSCalendar November 2024 +======+==========================+==========+======+ | Name | Reference | Property | Note | +======+==========================+==========+======+ | CN | [RFC5545], Section 3.2.2 | name | | +------+--------------------------+----------+------+ | DIR | [RFC5545], Section 3.2.6 | links | | +------+--------------------------+----------+------+ Table 22: Parameters of the ORGANIZER property The following examples illustrate how to convert the ORGANIZER property: ORGANIZER:mailto:foo@example.com ... ATTENDEE;RSVP=TRUE;PARTSTAT=NEEDS-ACTION:mailto:bar@example.com "replyTo": { "imip": "mailto:foo@example.com" }, "participants": { "a": { "@type": "Participant", "calendarAddress": "mailto:foo@example.com", "roles": { "owner": true } }, "b": { "@type": "Participant", "...": "" } } Figure 60: Converting an ORGANIZER property ORGANIZER:mailto:foo@example.com ATTENDEE;RSVP=FALSE;PARTSTAT=ACCEPTED;CN="Jane Doe":mailto:foo@example.com ... ATTENDEE;RSVP=TRUE;PARTSTAT=NEEDS-ACTION:mailto:bar@example.com Stepanek Expires 8 May 2025 [Page 62] Internet-Draft JSCalendar November 2024 "replyTo": { "imip": "mailto:foo@example.com" }, "participants": { "a": { "@type": "Participant", "calendarAddress": "mailto:foo@example.com", "name": "Jane Doe", "participationStatus": "accepted", "roles": { "attendee": true, "owner": true }, "sendTo": { "imip": "mailto:foo@example.com" } }, "b": { "@type": "Participant", "...": "" } } Figure 61: Converting an ORGANIZER and ATTENDEE property 2.3.30. PARTICIPANT-TYPE The PARTICIPANT-TYPE property [RFC9073] (Section 6.2) in a PARTICIPANT component converts to the roles property [RFC8984] (Section 4.4.6) of the Participant object. The property value converts in lowercase. The following example illustrates how to convert the PARTICIPANT-TYPE property: BEGIN:PARTICIPANT PARTICIPANT-TYPE:CONTACT CALENDAR-ADDRESS:mailto:foo@example.com ... END:PARTICIPANT ATTENDEE;RSVP=YES;PARTSTAT=NEEDS-ACTION:mailto:foo@example.com Stepanek Expires 8 May 2025 [Page 63] Internet-Draft JSCalendar November 2024 "participants": { "a": { "@type": "Participant", "roles": { "attendee": true, "contact": true }, "...": "" }, "b": { "...": "" } } Figure 62: Converting the PARTICIPANT-TYPE property 2.3.31. PERCENT-COMPLETE The PERCENT-COMPLETE property [RFC5545] (Section 3.8.1.8) in a VTODO component converts to the percentComplete property [RFC8984] (Section 5.2.4) of the Task object. A Task object which has the method property set might represent an iTIP reply of one of the participants in the object. In this case the value of the percentComplete property in the Task also converts to the percentComplete [RFC8984] (Section 4.4.6) of that Participant object, which represents the participant from which the iTIP reply originated. The PERCENT-COMPLETE property in a PARTICIPANT component converts to the percentComplete property [RFC8984] (Section 4.4.6) of the Participant object. The following examples illustrate how to convert the PERCENT-COMPLETE property: BEGIN:VCALENDAR METHOD:REPLY BEGIN:VTODO PERCENT-COMPLETE:53 ... Stepanek Expires 8 May 2025 [Page 64] Internet-Draft JSCalendar November 2024 { "@type": "Group", "entries": [ { "@type": "Task", "method": "reply", "percentComplete": 53, "...": "" } ], "...": "" } Figure 63: Converting the PERCENT-COMPLETE property in a VEVENT component BEGIN:VTODO BEGIN:PARTICIPANT PERCENT-COMPLETE:78 ... "@type": "Task", "participants": { "f4": { "@type": "Participant", "percentComplete": 78, "...": "" } } Figure 64: Converting the PERCENT-COMPLETE property in a PARTICIPANT component 2.3.32. PRIORITY The PRIORITY property [RFC5545] (Section 3.8.1.9) in a VEVENT or VTODO component converts to the priority property [RFC8984] (Section 4.4.1) of the Event or Task object. The following example illustrates how to convert the PRIORITY property: PRIORITY:3 "priority": 3 Figure 65: Converting the PRIORITY property Stepanek Expires 8 May 2025 [Page 65] Internet-Draft JSCalendar November 2024 2.3.33. PRODID The PRODID property [RFC5545] (Section 3.7.3) in a VCALENDAR component converts to the prodId property [RFC8984] (Section 4.1.4) of the Group object, and to the prodId property of all Event or Task objects that are listed in the Group object's entries property. The property value converts verbatim. The following example illustrates how to convert the PRODID property: BEGIN:VCALENDAR PRODID:-//BAZ//bam//EN BEGIN:VEVENT ... { "@type": "Group", "prodId": "-//BAZ//bam//EN", "entries": [ { "@type": "Event", "prodId": "-//BAZ//bam//EN", "...": "" } ], "...": "" } Figure 66: Converting the PRODID property 2.3.34. RDATE The RDATE property [RFC5545] (Section 3.8.5.2) of type DATE or DATE- TIME in a VEVENT, VTODO, DAYLIGHT or STANDARD component converts to a PatchObject object [RFC8984] (Section 1.4.9). The converted object is set in the recurrenceOverrides property of the Event, Task, or TimeZoneRule object. The property value converts to the key in the recurrenceOverrides property value. See Section 2.1.5 how to convert DATE and DATE-TIME values. For Event Task objects, the date-time MUST be relative to the timezone identified by the timeZone property, for TimeZoneRule objects the date-time is relative to the UTC offset specified in the offsetFrom property. The PatchObject value MUST be an empty JSON object. Stepanek Expires 8 May 2025 [Page 66] Internet-Draft JSCalendar November 2024 An RDATE property of value type PERIOD does not convert to a standard JSCalendar element. Implementations MAY convert it to the iCalComponent property (Section 5.1.1) of the Event, Task, or TimeZoneRule object. The following example illustrates how to convert the RDATE property: DTSTART:20230101T130000Z RRULE:FREQ=MONTHLY RDATE:20230805T170000Z "start": "2023-01-01T13:00:00", "timeZone": "Etc/UTC", "recurrenceRules": [ { "@type": "RecurrenceRule", "frequency": "monthly" } ], "recurrenceOverrides": { "2023-08-05T17:00:00": {} } Figure 67: Converting the RDATE property 2.3.35. RECURRENCE-ID The RECURRENCE-ID property [RFC5545] (Section 3.8.4.4) in a VEVENT or VTODO component converts to the recurrenceId property [RFC8984] (Section 4.3.1) of the Event or Task object. The timezone identifier (Section 2.1.4) of the RECURRENCE-ID property converts to the recurrenceIdTimeZone property. See Section 2.1.5 how to convert DATE and DATE-TIME values. The RANGE parameter [RFC5545] (Section 3.2.13) does not convert to a standard JSCalendar element. Implementations MAY preserve it in the iCalComponent (Section 5.1.1) property. See Section 2.1.2 for further requirements and examples. 2.3.36. RELATED-TO The RELATED-TO property [RFC5545] (Section 3.8.4.5) in a VEVENT, VTODO, or VALARM component converts to a Relation object [RFC8984] (Section 1.4.10). The converted object is set in the relatedTo property of the Event or Task object [RFC8984] (Section 4.1.3), or the Alert object [RFC8984] (Section 4.5.2). Stepanek Expires 8 May 2025 [Page 67] Internet-Draft JSCalendar November 2024 The property value in a VEVENT or VTODO converts as-is to the key of the Relation object in the relatedTo property. The property value in a VALARM converts to the same value as the key of that Alert object, which represents the VALARM component having that property value set in the UID property. Any RELTYPE parameters convert to the relations property in that Relation object. The parameter values convert in lowercase. The GAP parameter [RFC9253] (Section 6.2) does not convert a standard JSCalendar element. Implementations MAY convert it to the iCalProperty property (Section 5.1.2) of the Relation object. The following examples illustrate how to convert the RELATED-TO property: BEGIN:VEVENT RELATED-TO;RELTYPE=PARENT:4E05861C-A0C9-46AC-9A66-760FC1E0E167 RELATED-TO:4120A9B1-1133-4AC0-9185-C4C8396048ED ... "relatedTo": { "4E05861C-A0C9-46AC-9A66-760FC1E0E167": { "@type": "Relation", "relation": { "parent": true } }, "4120A9B1-1133-4AC0-9185-C4C8396048ED": { "@type": "Relation" } } Figure 68: Converting the RELATED-TO property in a VEVENT Stepanek Expires 8 May 2025 [Page 68] Internet-Draft JSCalendar November 2024 BEGIN:VEVENT ... BEGIN:VALARM UID:8297C37D-BA2D-4476-91AE-C1EAA364F8E1 TRIGGER:-PT15M DESCRIPTION:Event reminder ACTION:DISPLAY ACKNOWLEDGED:20210302T151514Z END:VALARM ... BEGIN:VALARM UID:DE7B5C34-83FF-47FE-BE9E-FF41AE6DD097 TRIGGER;VALUE=DATE-TIME:20210302T152000Z RELATED-TO;RELTYPE=SNOOZE:8297C37D-BA2D-4476-91AE-C1EAA364F8E1 DESCRIPTION:Event reminder ACTION:DISPLAY END:VALARM ... "alerts": { "1": { "@type": "Alert", "trigger": { "@type": "OffsetTrigger", "offset": "-PT15M" }, "...": "" }, "2": { "@type": "Alert", "trigger": { "@type": "AbsoluteTrigger", "when": "2021-03-02T15:20:00Z" }, "relatedTo": { "1": { "relation": { "snooze": true } } }, "...": "" } } Figure 69: Converting the RELATED-TO property in a VALARM Stepanek Expires 8 May 2025 [Page 69] Internet-Draft JSCalendar November 2024 2.3.37. REQUEST-STATUS The REQUEST-STATUS property [RFC5545] (Section 3.8.8.3) in a VEVENT or VTODO component converts to the requestStatus property [RFC8984] (Section 4.4.7) of the Event or Task object. The following example illustrates how to convert the REQUEST-STATUS property: 2.3.37.1. Example: Converting the REQUEST-STATUS property REQUEST-STATUS:2.0;Success "requestStatus": "2.0;Success" Figure 70: Converting the REQUEST-STATUS property 2.3.38. RRULE The RRULE property [RFC5545] (Section 3.8.5.3) in a VEVENT, VTODO, DAYLIGHT or STANDARD component converts to a RecurrenceRule object [RFC8984] (Section 4.3.3). The converted object is set in the recurrenceRules property of the Event, Task, or TimeZoneRule object. The RECUR value data type converts to a RecurrenceRule object as follows: Stepanek Expires 8 May 2025 [Page 70] Internet-Draft JSCalendar November 2024 +==================+=========================+ | RRULE field | RecurrenceRule property | +==================+=========================+ | FREQ | frequency | +------------------+-------------------------+ | UNTIL | until | +------------------+-------------------------+ | COUNT | count | +------------------+-------------------------+ | INTERVAL | interval | +------------------+-------------------------+ | BYSECOND | bySecond | +------------------+-------------------------+ | BYMINUTE | byMinute | +------------------+-------------------------+ | BYHOUR | byHour | +------------------+-------------------------+ | BYDAY | byDay | +------------------+-------------------------+ | BYMONTHDAY | byMonthDay | +------------------+-------------------------+ | BYYEARDAY | byYearDay | +------------------+-------------------------+ | BYWEEKNO | byWeekNo | +------------------+-------------------------+ | BYMONTH | byMonth | +------------------+-------------------------+ | BYSETPOS | bySetPosition | +------------------+-------------------------+ | WKST | firstDayOfWeek | +------------------+-------------------------+ | RSCALE [RFC7529] | rscale | +------------------+-------------------------+ | SKIP [RFC7529] | skip | +------------------+-------------------------+ Table 23: Converting the RECUR value type to a RecurrenceRule object The string values of the FREQ, WKST, RSCALE convert to lowercase. The UNTIL part in a VEVENT or VTODO converts to a LocalDateTime value relative to the timezone of the Event or Task, or to floating time for the TimeZoneRule object. The following example illustrates how to convert the RRULE property: Stepanek Expires 8 May 2025 [Page 71] Internet-Draft JSCalendar November 2024 DTSTART;TZID=Europe/Berlin:20240101T010000 RRULE:FREQ=YEARLY ;INTERVAL=2 ;BYMONTH=1 ;BYDAY=SU ;BYHOUR=8,9 ;BYMINUTE=30 ;UNTIL=20240930T120000Z "recurrenceRules": [ { "@type": "RecurrenceRule", "frequency": "yearly", "interval": 2, "byMonth": [ "1" ], "byDay": [ { "@type": "NDay", "day": "su" } ], "byHour": [ 8, 9 ], "byMinute": [ 30 ], "until": "2024-09-30T14:00:00" } ], "start": "2024-01-01T01:00:00", "timeZone": "Europe/Berlin" Figure 71: Example for converting the RRULE property 2.3.39. SEQUENCE The SEQUENCE property [RFC5545] (Section 3.8.7.4) in a VEVENT or VTODO component converts to the sequence property [RFC8984] (Section 4.1.7) of the Event or Task object. The SEQUENCE property in a PARTICIPANT component converts to the scheduleSequence property [RFC8984] (Section 4.4.6) of the Participant object. The following example illustrates how to convert the SEQUENCE property: Stepanek Expires 8 May 2025 [Page 72] Internet-Draft JSCalendar November 2024 SEQUENCE:3 "sequence": 3 Figure 72: Example for converting the SEQUENCE property 2.3.40. STATUS The STATUS property [RFC5545] (Section 3.8.1.11) in a VEVENT component converts to the status property [RFC8984] (Section 5.1.3) of the Event object. The STATUS property in a VTODO component converts to the progress property [RFC8984] (Section 5.2.5) of the Task object. The property value converts in lowercase. The following examples illustrate how to convert the STATUS property: STATUS:TENTATIVE "status": "tentative" Figure 73: Example for converting the STATUS property in a VEVENT component BEGIN:VTODO STATUS:IN-PROCESS ... { "@type": "Task", "progress": "in-process", "...": "" } Figure 74: Example for converting the STATUS property in a VTODO component 2.3.41. SOURCE The SOURCE property [RFC7986] (Section 5.8) in a VCALENDAR component converts to the source property [RFC8984] (Section 5.3.2). The following example illustrates how to convert the SOURCE property: BEGIN:VCALENDAR SOURCE;VALUE=URI:https://example.com/holidays.ics ... Stepanek Expires 8 May 2025 [Page 73] Internet-Draft JSCalendar November 2024 { "@type": "Group", "source": "https://example.com/holidays.ics", "...": "" } Figure 75: Example for converting the SOURCE property 2.3.42. STRUCTURED-DATA The STRUCTURED-DATA property [RFC9073] (Section 6.6) of type URI or BINARY in a VEVENT, VTODO, VCALENDAR, VRESOURCE, PARTICIPANT, or VLOCATION component converts to a Link object [RFC8984] (Section 1.4.11). The converted object is set in the links property of the Event, Task, Group, Participant, or Location object. The property value converts to the href property of the Link object. A value of type URI converts as-is. See Section 2.3.3 how to convert a BINARY value. Its parameters convert as follows: +=========+==========================+=============+======+ | Name | Reference | Property | Note | +=========+==========================+=============+======+ | FMTTYPE | [RFC5545], Section 3.2.8 | contentType | | +---------+--------------------------+-------------+------+ Table 24: Parameters of the STRUCTURED-DATA property Implementations MAY preserve the fact that the Link object got converted from a STRUCTURED-DATA property. To so, they MUST set the iCalProperty (Section 5.1.2) on the Link object. The following example illustrates how to convert the STRUCTURED-DATA property: STRUCTURED-DATA;FMTTYPE=application/ld+json; SCHEMA="https://schema.org/FlightReservation"; ENCODING=BASE64;VALUE=BINARY:InRydW5jYXRlZC4uLiIK Stepanek Expires 8 May 2025 [Page 74] Internet-Draft JSCalendar November 2024 "links": { "@type": "Link", "contentType": "application/ld+json", "href": "data:application/ld+json;base64,InRydW5jYXRlZC4uLiIK", "iCalProperty": { "@type": "ICalProperty", "name": "structured-data", "parameters": { "schema": "https://schema.org/FlightReservation" }, "valueType": "binary" } } Figure 76: Converting the STRUCTURED-DATA property 2.3.43. STYLED-DESCRIPTION The STYLED-DESCRIPTION property [RFC9073] (Section 6.5) in a VEVENT or VTODO component converts to the description property [RFC8984] (Section 4.2.2) under the following conditions: * The property value type MUST be TEXT. * The FMTTYPE parameter either MUST NOT not be set, or its value MUST be a media type [RFC6838] with top-level type "text". * Its DERIVED parameter value MUST NOT be TRUE. If the DERIVED parameter value is TRUE, then the property does not convert to the description property. Instead, an non-derived STYLED- DESCRIPTION property or the DESCRIPTION property is expected to contain the description. Implementations MAY preserve the property in the iCalComponent property (Section 5.1.1). Its parameters convert as follows: +=========+===============+========================+======+ | Name | Reference | Property | Note | +=========+===============+========================+======+ | FMTTYPE | [RFC5545], | descriptionContentType | | | | Section 3.2.8 | | | +---------+---------------+------------------------+------+ Table 25: Parameters of the STYLED-DESCRIPTION property The following example illustrates how to convert the STYLED- DESCRIPTION property: Stepanek Expires 8 May 2025 [Page 75] Internet-Draft JSCalendar November 2024 STYLED-DESCRIPTION;VALUE=TEXT;FMTTYPE=text/html: hello,world "description": "hello,world", "descriptionContentType": "text/html" Figure 77: Converting the STYLED-DESCRIPTION property 2.3.44. SUMMARY The SUMMARY property [RFC5545] (Section 3.8.1.12) in a VEVENT or VTODO component converts to the title property [RFC8984] (Section 4.2.1). The SUMMARY property [RFC5545] (Section 3.8.1.12) in a PARTICIPANT component converts to the name property [RFC8984] (Section 4.2.5). The following examples illustrate how to convert the SUMMARY property: SUMMARY:Birthday Party "title": "Birthday Party" Figure 78: Converting the SUMMARY property in a VEVENT BEGIN:VEVENT BEGIN:PARTICIPANT SUMMARY:John ... "participants": { "1": { "@type": "Participant", "name": "John", "...": "" } } Figure 79: Converting the SUMMARY property in a PARTICIPANT 2.3.45. TRANSP The TRANSP property [RFC5545] (Section 3.8.2.7) in a VEVENT or VTODO component converts to the freeBusyStatus property [RFC8984] (Section 4.4.2). Its values convert as follows: Stepanek Expires 8 May 2025 [Page 76] Internet-Draft JSCalendar November 2024 +=================+==================+ | iCalendar value | JSCalendar value | +=================+==================+ | OPAQUE | busy | +-----------------+------------------+ | TRANSPARENT | free | +-----------------+------------------+ Table 26: Values of the TRANSP property The following example illustrates how to convert the TRANSP property: TRANSP:TRANSPARENT "freeBusyStatus": "free" Figure 80: Converting the TRANSP property 2.3.46. TRIGGER The TRIGGER property [RFC5545] (Section 3.8.6.3) in a VALARM component converts to either an AbsoluteTrigger or OffsetTrigger object. The converted object is set in the trigger property [RFC8984] (Section 4.5.2) of the Alert object. A property of value type DURATION converts an OffsetTrigger object. The property value converts to its offset property. A value of type DATE-TIME converts to an AbsoluteTrigger object. The property value converts to its when property. Its parameters convert as follows: +=========+===========================+============+================+ | Name | Reference | Property | Note | +=========+===========================+============+================+ | RELATED | [RFC5545], | relativeTo | If | | | Section 3.2.14 | | VALUE=DURATION | +---------+---------------------------+------------+----------------+ Table 27: Parameters of the TRIGGER property The following examples illustrate how to convert the TRIGGER property: Stepanek Expires 8 May 2025 [Page 77] Internet-Draft JSCalendar November 2024 BEGIN:VEVENT ... BEGIN:VALARM TRIGGER;RELATED=END:PT5M ... "alerts": { "2d": { "@type": "Alert", "trigger": { "@type": "OffsetTrigger", "offset": "PT5M", "relativeTo": "end" }, "...": "" } } Figure 81: Converting the TRIGGER property to an OffsetTrigger BEGIN:VEVENT ... BEGIN:VALARM TRIGGER;VALUE=DATE-TIME:20250302T010203Z ... "alerts": { "14": { "@type": "Alert", "trigger": { "@type": "AbsoluteTrigger", "when": "2025-03-02T01:02:03Z" }, "...": "" } } Figure 82: Converting the TRIGGER property to an AbsoluteTrigger 2.3.47. TZID The TZID property [RFC5545] (Section 3.8.3.1) in a VTIMEZONE component converts to the tzId property [RFC8984] (Section 4.7.2). See Figure 14 for an example. Stepanek Expires 8 May 2025 [Page 78] Internet-Draft JSCalendar November 2024 2.3.48. TZID-ALIAS-OF The TZID-ALIAS-OF property [RFC7808] (Section 7.2) in a VTIMEZONE component converts to an entry in the aliases property [RFC8984] (Section 4.7.2) of the TimeZone object. See Figure 14 for an example. 2.3.49. TZNAME The TZNAME property [RFC5545] (Section 3.8.3.2) in a DAYLIGHT or STANDARD component converts to an entry in the names property [RFC8984] (Section 4.7.2) of the TimeZoneRule object. See Figure 14 for an example. 2.3.50. TZOFFSETFROM The TZOFFSETFROM property [RFC5545] (Section 3.8.3.3) in a DAYLIGHT or STANDARD component converts to the offsetFrom property [RFC8984] (Section 4.7.2) of the TimeZoneRule object. See Figure 14 for an example. 2.3.51. TZOFFSETTO The TZOFFSETTO property [RFC5545] (Section 3.8.3.4) in a DAYLIGHT or STANDARD component converts to the offsetTo property [RFC8984] (Section 4.7.2) of the TimeZoneRule object. See Figure 14 for an example. 2.3.52. TZUNTIL The TZUNTIL property [RFC7808] (Section 7.1) in a VTIMEZONE component converts to the validUntil property [RFC8984] (Section 4.7.2). See Section 2.1.5 how to convert DATE and DATE-TIME values. See Figure 14 for an example. 2.3.53. TZURL The TZURL property [RFC5545] (Section 3.8.3.5) in a VTIMEZONE component converts to the url property [RFC8984] (Section 4.7.2) of the TimeZone object. See Figure 14 for an example. Stepanek Expires 8 May 2025 [Page 79] Internet-Draft JSCalendar November 2024 2.3.54. UID The UID property [RFC5545] (Section 3.8.4.7) in a VEVENT, VTODO, or VCALENDAR component converts to the uid property [RFC8984] (Section 4.1.2). The following example illustrates how to convert the UID property: UID:5ACEA86F-40CF-47EE-9CCA-7C85588A589F "uid": "5ACEA86F-40CF-47EE-9CCA-7C85588A589F" Figure 83: Converting the UID property 2.3.55. URL The URL property [RFC5545] (Section 3.8.4.6) in a VEVENT, VTODO, VCALENDAR, or PARTICIPANT component converts to a Link object [RFC8984] (Section 1.4.11). The converted object is set in the links property of the Event, Task, Group, or Participant object. The property value converts to the href property of the Link object. Implementations MAY preserve the fact that the Link object got converted from an URL property. To so, they MUST set the iCalProperty (Section 5.1.2) on the Link object. The following example illustrates how to convert the URL property: URL:https://example.com/calendar/birtdays.ics "links": { "3": { "@type": "Link", "href": "https://example.com/calendar/birtdays.ics", "iCalProperty": { "@type": "ICalProperty", "name": "url" } } } Figure 84: Converting the IMAGE property 3. Converting JSCalendar to iCalendar 3.1. Alert The Alert object [RFC8984] (Section 4.5.2) converts to a VALARM component (Section 2.2.2). Stepanek Expires 8 May 2025 [Page 80] Internet-Draft JSCalendar November 2024 Its properties convert as follows: +==============+===============+==============+===================+ | Name | Reference | Property (or | See | | | | other) | | +==============+===============+==============+===================+ | acknowledged | [RFC8984], | ACKNOWLEDGED | Section 2.3.1 | | | Section 4.5.2 | | | +--------------+---------------+--------------+-------------------+ | action | [RFC8984], | ACTION | Section 2.3.2 | | | Section 4.5.2 | | | +--------------+---------------+--------------+-------------------+ | relatedTo | [RFC8984], | RELATED-TO | Section 2.3.36, | | | Section 4.1.3 | | and remarks below | +--------------+---------------+--------------+-------------------+ | trigger | [RFC8984], | TRIGGER | Section 2.3.46 | | | Section 4.5.2 | | | +--------------+---------------+--------------+-------------------+ Table 28: Properties of the Alert object Remarks: * The value of the RELATED-TO property is the UID property value of that VALARM component, to which the related Alert object converts to. Consequently, the UID property for such a VALARM MUST be set, otherwise the UID property SHOULD be set. 3.2. Event and Task The Event object [RFC8984] (Section 2.1) converts to a VEVENT component (Section 2.2.3), the Task object [RFC8984] (Section 2.2) converts to a VTODO component (Section 2.2.7). The following table defines how to convert properties that are common to both the Event and Task object types. Table 30 and Table 31 later in this section define how to convert properties specific to either Event or Task objects. +=======================+==========+============+===================+ |Name |Reference |Property (or|See | | | |other) | | +=======================+==========+============+===================+ |alerts |[RFC8984],|VALARM |Alert object | | |Section |(component) |(Section 3.1) | | |4.5.2 | | | +-----------------------+----------+------------+-------------------+ |categories |[RFC8984],|CONCEPT |Section 2.3.10 | Stepanek Expires 8 May 2025 [Page 81] Internet-Draft JSCalendar November 2024 | |Section | | | | |4.2.10 | | | +-----------------------+----------+------------+-------------------+ |color |[RFC8984],|COLOR |Section 2.3.8 | | |Section | | | | |4.2.11 | | | +-----------------------+----------+------------+-------------------+ |created |[RFC8984],|CREATED |Section 2.3.12 | | |Section | | | | |4.1.5 | | | +-----------------------+----------+------------+-------------------+ |description |[RFC8984],|DESCRIPTION,|Section 2.3.13, | | |Section |or STYLED- |Section 2.3.43, and| | |4.2.2 |DESCRIPTION |remarks below | +-----------------------+----------+------------+-------------------+ |descriptionContentType |[RFC8984],|FMTTYPE |Section 2.3.43, and| | |Section |(parameter) |remarks below | | |4.2.3 |of STYLED- | | | | |DESCRIPTION | | +-----------------------+----------+------------+-------------------+ |excluded |[RFC8984],| |Section 2.3.19, and| | |Section | |remarks about | | |4.3.6 | |recurrenceOverrides| | | | |below | +-----------------------+----------+------------+-------------------+ |excludedRecurrenceRules|[RFC8984],|EXRULE |Section 2.3.20 | | |Section | | | | |4.3.4 | | | +-----------------------+----------+------------+-------------------+ |freeBusyStatus |[RFC8984],|TRANSP |Section 2.3.45 | | |Section | | | | |4.4.2 | | | +-----------------------+----------+------------+-------------------+ |keywords |[RFC8984],|CATEGORIES |Section 2.3.6 | | |Section | | | | |4.2.9 | | | +-----------------------+----------+------------+-------------------+ |links |[RFC8984],|ATTACH, or |Link object | | |Section |other |(Section 3.4) | | |4.2.7 | | | +-----------------------+----------+------------+-------------------+ |locale |[RFC8984],|TBD | | | |Section | | | | |4.2.8 | | | +-----------------------+----------+------------+-------------------+ |localizations |[RFC8984],|TBD | | | |Section | | | | |4.6.1 | | | Stepanek Expires 8 May 2025 [Page 82] Internet-Draft JSCalendar November 2024 +-----------------------+----------+------------+-------------------+ |locations |[RFC8984],|LOCATION, |Location object | | |Section |GEO, or |(Section 3.5) | | |4.2.5 |VLOCATION | | | | |(component) | | +-----------------------+----------+------------+-------------------+ |method |[RFC8984],|METHOD of |Section 2.3.27, and| | |Section |iCalendar |Group object | | |4.1.8 |object |(Section 3.3) | +-----------------------+----------+------------+-------------------+ |participants |[RFC8984],|ATTENDEE, or|Participant object | | |Section |PARTICIPANT |(Section 3.6) | | |4.4.6 |(component) | | +-----------------------+----------+------------+-------------------+ |priority |[RFC8984],|PRIORITY |Section 2.3.32 | | |Section | | | | |4.4.1 | | | +-----------------------+----------+------------+-------------------+ |privacy |[RFC8984],|CLASS |Section 2.3.7 | | |Section | | | | |4.4.3 | | | +-----------------------+----------+------------+-------------------+ |prodId |[RFC8984],|PRODID of |Section 2.3.33, and| | |Section |iCalendar |Group object | | |4.1.4 |object |(Section 3.3) | +-----------------------+----------+------------+-------------------+ |recurrenceId |[RFC8984],|RECURRENCE- |Section 2.3.35 | | |Section |ID | | | |4.3.1 | | | +-----------------------+----------+------------+-------------------+ |recurrenceIdTimeZone |[RFC8984],|TZID |Section 2.3.35 | | |Section |(parameter) | | | |4.3.2 |of | | | | |RECURRENCE- | | | | |ID | | +-----------------------+----------+------------+-------------------+ |recurrenceOverrides |[RFC8984],|RDATE, |Section 2.1.2, and | | |Section |EXDATE or |remarks below | | |4.3.5 |recurrence | | | | |override | | | | |component | | +-----------------------+----------+------------+-------------------+ |recurrenceRules |[RFC8984],|RRULE |Section 2.3.38 | | |Section | | | | |4.3.3 | | | +-----------------------+----------+------------+-------------------+ |relatedTo |[RFC8984],|RELATED-TO |Section 2.3.36 | | |Section | | | Stepanek Expires 8 May 2025 [Page 83] Internet-Draft JSCalendar November 2024 | |4.1.3 | | | +-----------------------+----------+------------+-------------------+ |replyTo |[RFC8984],|ORGANIZER |Section 2.3.29, and| | |Section | |remarks below | | |4.4.4 | | | +-----------------------+----------+------------+-------------------+ |requestStatus |[RFC8984],|REQUEST- |Section 2.3.37 | | |Section |STATUS | | | |4.4.7 | | | +-----------------------+----------+------------+-------------------+ |sentBy |[RFC8984],|TBD | | | |Section | | | | |4.4.5 | | | +-----------------------+----------+------------+-------------------+ |sequence |[RFC8984],|SEQUENCE |Section 2.3.39 | | |Section | | | | |4.1.7 | | | +-----------------------+----------+------------+-------------------+ |showWithoutTime |[RFC8984],|TBD | | | |Section | | | | |4.2.4 | | | +-----------------------+----------+------------+-------------------+ |start |[RFC8984],|DTSTART |Section 2.3.16 | | |Section | | | | |4.7.2 | | | +-----------------------+----------+------------+-------------------+ |timeZone |[RFC8984],|TZID |Section 2.3.16, | | |Section |(parameter) |Section 2.3.17 | | |4.7.1 |of DTSTART | | | | |and DUE | | +-----------------------+----------+------------+-------------------+ |timeZones |[RFC8984],|VTIMEZONE |TimeZone object | | |Section |(component) |(Section 3.7) | | |4.7.2 |of iCalendar| | | | |object | | +-----------------------+----------+------------+-------------------+ |title |[RFC8984],|SUMMARY |Section 2.3.44 | | |Section | | | | |4.2.1 | | | +-----------------------+----------+------------+-------------------+ |uid |[RFC8984],|UID |Section 2.3.54 | | |Section | | | | |4.1.2 | | | +-----------------------+----------+------------+-------------------+ |updated |[RFC8984],|DTSTAMP, and|Section 2.3.15, | | |Section |LAST- |Section 2.3.23 | | |4.1.6 |MODIFIED | | +-----------------------+----------+------------+-------------------+ Stepanek Expires 8 May 2025 [Page 84] Internet-Draft JSCalendar November 2024 |useDefaultAlerts |[RFC8984],|TBD | | | |Section | | | | |4.5.1 | | | +-----------------------+----------+------------+-------------------+ |virtualLocations |[RFC8984],|CONFERENCE |Section 2.3.11 | | |Section | | | | |4.2.6 | | | +-----------------------+----------+------------+-------------------+ Table 29: Properties of the Event and Task object Remarks: * The descriptionContentType property value determines if to convert the description property to the DESCRIPTION or STYLED-DESCRIPTION property. A description of content type "text/plain" converts to the DESCRIPTION property. Any other description converts to a STYLED-DESCRIPTION; in this case, a plain text version of the rich-text description SHOULD be set in the DESCRIPTION property and its DERIVED parameter MUST be set to "TRUE". * The entries in the recurrenceOverrides property convert depending on the contents of the patch object value. A patch object that sets the excluded property to "true" converts to an EXDATE property for the date-time of that recurrence instance. An empty patch object converts to an RDATE property. Any other patch object converts to a recurrence override component in the embedding VCALENDAR component. * The replyTo property converts to the ORGANIZER property. If the replyTo property value only defines a single scheduling method then the URI value of that method converts to the ORGANIZER property value. If the replyTo property defines multiple scheduling methods, and a Participant object with a calendarAddress property value matching one of the replyTo URIs exists in the same Event or Task, then the URI matching the calendarAddress property converts to the ORGANIZER property value. Otherwise choosing the ORGANIZER property value is implementation- specific. TBD how to convert other replyTo methods. Properties specific to the Event object type convert to iCalendar properties as follows: Stepanek Expires 8 May 2025 [Page 85] Internet-Draft JSCalendar November 2024 +==========+===============+=====================+=================+ | Name | Reference | Property (or other) | See | +==========+===============+=====================+=================+ | duration | [RFC8984], | DURATION, or DTEND | Section 2.3.18, | | | Section 5.1.2 | | Section 2.3.14 | +----------+---------------+---------------------+-----------------+ | status | [RFC8984], | STATUS | Section 2.3.40 | | | Section 5.1.3 | | | +----------+---------------+---------------------+-----------------+ Table 30: Properties of the Event object Properties specific to the Task object type convert to iCalendar properties as follows: +===================+===============+=====================+=========+ | Name | Reference | Property (or | See | | | | other) | | +===================+===============+=====================+=========+ | due | [RFC8984], | DUE | Section | | | Section 5.2.1 | | 2.3.17 | +-------------------+---------------+---------------------+---------+ | estimatedDuration | [RFC8984], | TBD | | | | Section 5.2.3 | | | +-------------------+---------------+---------------------+---------+ | percentComplete | [RFC8984], | PERCENT-COMPLETE | Section | | | Section 5.2.4 | | 2.3.31 | +-------------------+---------------+---------------------+---------+ | progress | [RFC8984], | STATUS | Section | | | Section 5.2.5 | | 2.3.40 | +-------------------+---------------+---------------------+---------+ | progressUpdated | [RFC8984], | TBD | | | | Section 5.2.6 | | | +-------------------+---------------+---------------------+---------+ Table 31: Properties of the Task object 3.3. Group The Group object [RFC8984] (Section 2.3) converts to a VCALENDAR component (Section 2.1.1). Its properties convert as follows: Stepanek Expires 8 May 2025 [Page 86] Internet-Draft JSCalendar November 2024 +============+============+===============+=======================+ | Name | Reference | Property (or | See | | | | other) | | +============+============+===============+=======================+ | categories | [RFC8984], | CONCEPT | Section 2.3.10 | | | Section | | | | | 4.2.10 | | | +------------+------------+---------------+-----------------------+ | color | [RFC8984], | COLOR | Section 2.3.8 | | | Section | | | | | 4.2.11 | | | +------------+------------+---------------+-----------------------+ | created | [RFC8984], | CREATED | Section 2.3.12 | | | Section | | | | | 4.1.5 | | | +------------+------------+---------------+-----------------------+ | entries | [RFC8984], | VEVENT or | Event and Task object | | | Section | VTODO | (Section 3.2), and | | | 5.3.1 | (component) | remarks below | +------------+------------+---------------+-----------------------+ | keywords | [RFC8984], | CATEGORIES | Section 2.3.6 | | | Section | | | | | 4.2.9 | | | +------------+------------+---------------+-----------------------+ | links | [RFC8984], | ATTACH, or | Link object | | | Section | other | (Section 3.4) | | | 4.2.7 | | | +------------+------------+---------------+-----------------------+ | locale | [RFC8984], | TBD | | | | Section | | | | | 4.2.8 | | | +------------+------------+---------------+-----------------------+ | prodId | [RFC8984], | PRODID | Section 2.3.33, and | | | Section | | remarks below | | | 4.1.4 | | | +------------+------------+---------------+-----------------------+ | source | [RFC8984], | SOURCE | Section 2.3.41 | | | Section | | | | | 5.3.2 | | | +------------+------------+---------------+-----------------------+ | title | [RFC8984], | NAME | Section 2.3.28 | | | Section | | | | | 4.2.1 | | | +------------+------------+---------------+-----------------------+ | uid | [RFC8984], | UID | Section 2.3.54 | | | Section | | | | | 4.1.2 | | | +------------+------------+---------------+-----------------------+ Stepanek Expires 8 May 2025 [Page 87] Internet-Draft JSCalendar November 2024 | updated | [RFC8984], | LAST-MODIFIED | Section 2.3.23 | | | Section | | | | | 4.1.6 | | | +------------+------------+---------------+-----------------------+ Table 32: Properties of the Group object Remarks: * The prodId property value of the Group object is expected to be equal to the prodId property value of all the Group entries. They all convert to the same, single PRODID property in the VCALENDAR component. How to convert unequal prodId property values is implementation-specific. * The method property value in all the Group entries is expected to be equal. How to convert entries with unequal method property values is implementation-specific. 3.4. Link The Link object [RFC8984] (Section 1.4.11) converts either an ATTACH property (Section 2.3.3), an IMAGE property (Section 2.3.22), a LINK property (Section 2.3.24), a STRUCTURED-DATA property (Section 2.3.42), or an URL property (Section 2.3.55). Which iCalendar property to choose is implementation-specific. As a guideline: * Choose IMAGE, if the display property is set or the rel property value is "icon". * Choose LINK, if the rel property is set to any other value. * Choose URL, if only the href property is set and its value links to a dynamic rendition of the calendar object. * TBD - Choose STRUCTURED-DATA, if the schema property is set. * Choose ATTACH otherwise. The href property converts to the iCalendar property value. The other Link properties convert as follows: Stepanek Expires 8 May 2025 [Page 88] Internet-Draft JSCalendar November 2024 +=============+================+============+===================+ | Name | Reference | Parameter | See | | | | (or other) | | +=============+================+============+===================+ | cid | [RFC8984], | TBD | | | | Section 1.4.11 | | | +-------------+----------------+------------+-------------------+ | contentType | [RFC8984], | FMTTYPE | Section 2.3.3 | | | Section 1.4.11 | | | +-------------+----------------+------------+-------------------+ | display | [RFC8984], | DISPLAY | Section 2.3.22 | | | Section 1.4.11 | | | +-------------+----------------+------------+-------------------+ | rel | [RFC8984], | LINKREL | Section 2.3.24, | | | Section 1.4.11 | | and remarks below | +-------------+----------------+------------+-------------------+ | size | [RFC8984], | SIZE | Section 2.3.3 | | | Section 1.4.11 | | | +-------------+----------------+------------+-------------------+ | title | [RFC8984], | TBD | | | | Section 4.2.1 | | | +-------------+----------------+------------+-------------------+ Table 33: Properties of the Link object Remarks: * The LINKREL parameter SHOULD be omitted if the Link object converts to an IMAGE property and the rel property value is "icon". 3.5. Location The Location object [RFC8984] (Section 4.2.5) converts to either a LOCATION (Section 2.3.25), GEO (Section 2.3.21), or DTEND (Section 2.3.21) property, or it converts to a VLOCATION component (Section 2.2.4). Which iCalendar element to choose is implementation-specific. As a guideline: * Choose LOCATION, if only the title property is set and the iCalendar component not already contains a LOCATION property. The title property converts to the LOCATION property value. * Choose GEO, if only the coordinates property is set the iCalendar component not already contains a GEO property. The coordinates property converts to the GEO property value. TBD - How to convert arbitrary geo: URIs? Stepanek Expires 8 May 2025 [Page 89] Internet-Draft JSCalendar November 2024 * Choose DTEND, if the embedding object is an Event, only the timeZone and the relativeTo properties are set, the relativeTo property value is "end" and the iCalendar component not already contains a DTEND property. The timeZone property converts to the TZID parameter of the DTEND property. The duration of the embedding Event object determines the DTEND property value. * Choose the VLOCATION component otherwise. Implementations MAY convert one of the Location objects that convert to a VLOCATION also to the LOCATION property; converting the title or description property to the LOCATION property value is a reasonable choice. The DERIVED parameter MUST be set on the LOCATION property. The properties convert to a VLOCATION component as follows: +===============+===============+===============+===============+ | Name | Reference | Property (or | See | | | | other) | | +===============+===============+===============+===============+ | coordinates | [RFC8984], | GEO | Section | | | Section 4.2.5 | | 2.3.21 | +---------------+---------------+---------------+---------------+ | description | [RFC8984], | DESCRIPTION | Section | | | Section 4.2.2 | | 2.3.13 | +---------------+---------------+---------------+---------------+ | links | [RFC8984], | ATTACH, or | Link object | | | Section 4.2.7 | other | (Section 3.4) | +---------------+---------------+---------------+---------------+ | locationTypes | [RFC8984], | LOCATION-TYPE | Section | | | Section 4.2.5 | | 2.3.26 | +---------------+---------------+---------------+---------------+ | name | [RFC8984], | NAME | Section | | | Section 4.2.5 | | 2.3.28 | +---------------+---------------+---------------+---------------+ | relativeTo | [RFC8984], | TBD | | | | Section 4.5.2 | | | +---------------+---------------+---------------+---------------+ | timeZone | [RFC8984], | TBD | | | | Section 4.7.1 | | | +---------------+---------------+---------------+---------------+ Table 34: Properties of the Location object Stepanek Expires 8 May 2025 [Page 90] Internet-Draft JSCalendar November 2024 3.6. Participant The Participant object [RFC8984] (Section 4.4.6) either converts to one of an ATTENDEE property (Section 2.3.4), a PARTICIPANT component (Section 2.2.1), or a VRESOURCE component (Section 2.2.5); or it converts to both an ATTENDEE property and a PARTICIPANT component: * It converts to an ATTENDEE property if at least one of the calendarAddress [I-D.ietf-jmap-calendars] (Section 5.1.1) or sendTo [RFC8984] (Section 4.4.6) properties is set. The calendarAddress property converts to the ATTENDEE property value, if set; otherwise one of the scheduling methods in the sendTo property converts to the ATTENDEE property value. * It converts to a PARTICIPANT component if it converts to an ATTENDEE property but not all of its properties convert to ATTENDEE property parameters as depicted in Table 35. In this case the CALENDAR-ADDRESS property value of the PARTICIPANT MUST be set to the ATTENDEE property value. Alternatively, the Participant object also converts to a PARTICIPANT component if it does not convert to an ATTENDEE property but its kind property value is unequal to "resource". * It converts to a VRESOURCE component if it does not convert to an ATTENDEE property and its kind property value is "resource". The following Participant properties convert to the ATTENDEE property. How to convert these properties if the Participant does not convert to an ATTENDEE is implementation-specific. +=====================+============+=====================+=========+ | Name | Reference | Parameter (or | See | | | | other) | | +=====================+============+=====================+=========+ | delegatedFrom | [RFC8984], | DELEGATED-FROM | Section | | | Section | | 2.3.4 | | | 4.4.6 | | | +---------------------+------------+---------------------+---------+ | delegatedTo | [RFC8984], | DELEGATED-TO | Section | | | Section | | 2.3.4 | | | 4.4.6 | | | +---------------------+------------+---------------------+---------+ | email | [RFC8984], | EMAIL | Section | | | Section | | 2.3.4 | | | 4.4.6 | | | +---------------------+------------+---------------------+---------+ | expectReply | [RFC8984], | RSVP | Section | | | Section | | 2.3.4 | Stepanek Expires 8 May 2025 [Page 91] Internet-Draft JSCalendar November 2024 | | 4.4.6 | | | +---------------------+------------+---------------------+---------+ | kind | [RFC8984], | CUTYPE | Section | | | Section | | 2.3.4 | | | 4.4.6 | | | +---------------------+------------+---------------------+---------+ | invitedBy | [RFC8984], | TBD | | | | Section | | | | | 4.4.6 | | | +---------------------+------------+---------------------+---------+ | memberOf | [RFC8984], | MEMBER | Section | | | Section | | 2.3.4 | | | 4.4.6 | | | +---------------------+------------+---------------------+---------+ | name | [RFC8984], | CN | Section | | | Section | | 2.3.4 | | | 4.2.5 | | | +---------------------+------------+---------------------+---------+ | participationStatus | [RFC8984], | PARTSTAT | Section | | | Section | | 2.3.4 | | | 4.4.6 | | | +---------------------+------------+---------------------+---------+ | roles | [RFC8984], | ROLE, or | Section | | | Section | PARTICIPANT-TYPE | 2.3.4, | | | 4.4.6 | property of the | Section | | | | PARTICIPANT | 2.3.30, | | | | component | and | | | | | remarks | | | | | below | +---------------------+------------+---------------------+---------+ | scheduleAgent | [RFC8984], | SCHEDULE-AGENT | Section | | | Section | | 2.3.4 | | | 4.4.6 | | | +---------------------+------------+---------------------+---------+ | scheduleForceSend | [RFC8984], | SCHEDULE-FORCE-SEND | Section | | | Section | | 2.3.4 | | | 4.4.6 | | | +---------------------+------------+---------------------+---------+ | scheduleSequence | [RFC8984], | TBD | | | | Section | | | | | 4.4.6 | | | +---------------------+------------+---------------------+---------+ | scheduleStatus | [RFC8984], | SCHEDULE-STATUS | Section | | | Section | | 2.3.4 | | | 4.4.6 | | | +---------------------+------------+---------------------+---------+ | scheduleUpdated | [RFC8984], | TBD | | | | Section | | | Stepanek Expires 8 May 2025 [Page 92] Internet-Draft JSCalendar November 2024 | | 4.4.6 | | | +---------------------+------------+---------------------+---------+ | sendTo | [RFC8984], | TBD | | | | Section | | | | | 4.4.6 | | | +---------------------+------------+---------------------+---------+ | sentBy | [RFC8984], | TBD | | | | Section | | | | | 4.4.5 | | | +---------------------+------------+---------------------+---------+ Table 35: Properties of the Participant object that convert to the ATTENDEE property Remarks: * The "optional" role converts to the "OPT-PARTICIPANT" ROLE parameter value, the "chair" role to "CHAIR", "informational" to "NON-PARTICIPANT". The "attendee" role does convert to the ROLE parameter, it is implied by the ATTENDEE property. The "owner" role does not convert to the ROLE parameter, if the property value of the ATTENDEE is equal to the value of the ORGANIZER property in the same component. All other roles require a PARTICIPANT component and convert to the PARTICIPANT-TYPE property in that component. The following Participant properties convert to the PARTICIPANT or VRESOURCE component: +======================+============+==================+==========+ | Name | Reference | Property (or | See | | | | other) | | +======================+============+==================+==========+ | description | [RFC8984], | DESCRIPTION | Section | | | Section | | 2.3.13 | | | 4.2.2 | | | +----------------------+------------+------------------+----------+ | language | [RFC8984], | TBD | | | | Section | | | | | 4.4.6 | | | +----------------------+------------+------------------+----------+ | links | [RFC8984], | ATTACH, or other | Link | | | Section | | object | | | 4.2.7 | | (Section | | | | | 3.4) | +----------------------+------------+------------------+----------+ | locationId | [RFC8984], | TBD | | | | Section | | | Stepanek Expires 8 May 2025 [Page 93] Internet-Draft JSCalendar November 2024 | | 4.4.6 | | | +----------------------+------------+------------------+----------+ | name | [RFC8984], | NAME | Section | | | Section | | 2.3.28 | | | 4.2.5 | | | +----------------------+------------+------------------+----------+ | participationComment | [RFC8984], | COMMENT | Section | | | Section | | 2.3.9 | | | 4.4.6 | | | +----------------------+------------+------------------+----------+ | percentComplete | [RFC8984], | PERCENT-COMPLETE | Section | | | Section | | 2.3.31 | | | 5.2.4 | | | +----------------------+------------+------------------+----------+ | progress | [RFC8984], | TBD | | | | Section | | | | | 5.2.5 | | | +----------------------+------------+------------------+----------+ | progressUpdated | [RFC8984], | TBD | | | | Section | | | | | 5.2.6 | | | +----------------------+------------+------------------+----------+ | roles | [RFC8984], | PARTICIPANT-TYPE | Section | | | Section | | 2.3.30 | | | 4.4.6 | | | +----------------------+------------+------------------+----------+ Table 36: Properties of the Participant object that convert to the PARTICIPANT or VRESOURCE component 3.7. TimeZone The TimeZone object [RFC8984] (Section 4.7.2) converts to a VTIMEZONE component (Section 2.2.6). Its properties convert as follows: Stepanek Expires 8 May 2025 [Page 94] Internet-Draft JSCalendar November 2024 +============+===============+=====================+==============+ | Name | Reference | Property (or other) | See | +============+===============+=====================+==============+ | aliases | [RFC8984], | TZID-ALIAS-OF | Section | | | Section 4.7.2 | | 2.3.48 | +------------+---------------+---------------------+--------------+ | daylight | [RFC8984], | DAYLIGHT | TimeZoneRule | | | Section 4.7.2 | (component) | below | +------------+---------------+---------------------+--------------+ | standard | [RFC8984], | STANDARD | TimeZoneRule | | | Section 4.7.2 | (component) | below | +------------+---------------+---------------------+--------------+ | tzId | [RFC8984], | TZID | Section | | | Section 4.7.2 | | 2.3.47 | +------------+---------------+---------------------+--------------+ | url | [RFC8984], | TZURL | Section | | | Section 4.7.2 | | 2.3.53 | +------------+---------------+---------------------+--------------+ | validUntil | [RFC8984], | TZUNTIL | Section | | | Section 4.7.2 | | 2.3.52 | +------------+---------------+---------------------+--------------+ Table 37: Properties of the TimeZone object The TimeZoneRule object [RFC8984] (Section 4.7.2) converts to a DAYLIGHT or STANDARD component (Section 2.2.6). Its properties convert as follows: Stepanek Expires 8 May 2025 [Page 95] Internet-Draft JSCalendar November 2024 +=====================+===============+==============+=========+ | Name | Reference | Property (or | See | | | | other) | | +=====================+===============+==============+=========+ | comments | [RFC8984], | COMMENT | Section | | | Section 4.7.2 | | 2.3.9 | +---------------------+---------------+--------------+---------+ | names | [RFC8984], | TZNAME | Section | | | Section 4.7.2 | | 2.3.49 | +---------------------+---------------+--------------+---------+ | offsetFrom | [RFC8984], | TZOFFSETFROM | Section | | | Section 4.7.2 | | 2.3.50 | +---------------------+---------------+--------------+---------+ | offsetTo | [RFC8984], | TZOFFSETTO | Section | | | Section 4.7.2 | | 2.3.51 | +---------------------+---------------+--------------+---------+ | recurrenceOverrides | [RFC8984], | RDATE | Section | | | Section 4.3.5 | | 2.3.34 | +---------------------+---------------+--------------+---------+ | recurrenceRules | [RFC8984], | RRULE | Section | | | Section 4.3.3 | | 2.3.38 | +---------------------+---------------+--------------+---------+ | start | [RFC8984], | DTSTART | Section | | | Section 4.7.2 | | 2.3.16 | +---------------------+---------------+--------------+---------+ Table 38: Properties of the TimeZoneRule object 3.8. VirtualLocation The VirtualLocation object [RFC8984] (Section 4.2.6) converts to a CONFERENCE property (Section 2.3.11). The uri property converts to the CONFERENCE property value. Its other properties convert as follows: Stepanek Expires 8 May 2025 [Page 96] Internet-Draft JSCalendar November 2024 +=============+===============+======================+=========+ | Name | Reference | Parameter (or other) | See | +=============+===============+======================+=========+ | description | [RFC8984], | TBD | | | | Section 4.2.2 | | | +-------------+---------------+----------------------+---------+ | features | [RFC8984], | FEATURE | Section | | | Section 4.2.6 | | 2.3.11 | +-------------+---------------+----------------------+---------+ | name | [RFC8984], | LABEL | Section | | | Section 4.2.5 | | 2.3.11 | +-------------+---------------+----------------------+---------+ Table 39: Properties of the VirtualLocation object 4. Updates to iCalendar 4.1. New iCalendar parameters 4.1.1. JSCALID TBD 4.2. New iCalendar properties 4.2.1. JSCALID TBD 4.2.2. JSPROP TBD 5. Updates to JSCalendar 5.1. New JSCalendar properties 5.1.1. iCalComponent Name: iCalComponent Context: Any JSCalendar object Type: ICalComponent (optional) Stepanek Expires 8 May 2025 [Page 97] Internet-Draft JSCalendar November 2024 Description This contains information about an iCalendar component that got partially or fully converted to JSCalendar. It allows to preserve the name of the iCalendar component and some or all of its properties and subcomponents. An ICalComponent object has the following properties: @type: String (mandatory) This specifies the type of this object. This MUST be ICalComponent. name: String (mandatory) This is the name of the iCalendar component in lowercase. components: *[][] (optional) This contains subcomponents of the iCalendar component. The value MUST be a list of iCalendar components formatted in jCal as defined in Section 3.3 of [RFC7265]. convertedProperties: String[ICalProperty] (optional) This contains conversion-related information about the component's properties that got partially or fully converted to JSCalendar. Each key defines the path to a property of the JSCalendar object on which the iCalComponent property is set on. The value for each key contains information about the iCalendar property which converted to the object property located at that key (see Section 5.1.2). The key MUST be a valid key of a PatchObject as defined in Section 1.4.9 of [RFC8984]. The key MUST NOT point into a nested property, unless there is no way to otherwise preserve the iCalendar property elements. For example, if a VEVENT contains an ATTENDEE property, then any iCalendar information about the ATTENDEE property MUST be set in the iCalProperty property of the converted Participant object (see Section 2.3.4). In contrast, information about a RDATE property contained in a VEVENT would be located by a key pointing into the recurrenceOverrides property of the Event object (see Section 2.3.34). properties: *[][] (optional) This contains properties of the iCalendar component. The value MUST be a list of iCalendar properties formatted in jCal as defined in Section 3.4 of [RFC7265]. Stepanek Expires 8 May 2025 [Page 98] Internet-Draft JSCalendar November 2024 5.1.2. iCalProperty Name: iCalProperty Context: Any JSCalendar object Type: ICalProperty (optional) Description: This contains conversion-related information about an iCalendar property that got partially or fully converted to JSCalendar. It allows to preserve the name of the iCalendar property and some or all of its parameters. An ICalProperty object has the following properties: @type: String (mandatory) This specifies the type of this object. This MUST be ICalProperty. name: String (mandatory) This is the name of the iCalendar property in lowercase. valueType: String (optional) This is the name of the iCalendar property value type in lowercase. parameters: String[String] (optional) This contains parameters of the iCalendar property. The value MUST comply with iCalendar parameters formatted in jCal as defined in Section 3.5 of [RFC7265]. 5.1.3. locations (Participant) Name: locations Context Participant Type: Id[Location] (optional) Stepanek Expires 8 May 2025 [Page 99] Internet-Draft JSCalendar November 2024 Description: This represents locations associated with the participant. In contrast to the locationId property, this allows to associate multiple locations with the Participant object. It also allow to more clearly express that a location just is relevant for a single participant. 6. IANA Considerations 7. References 7.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, . [RFC2397] Masinter, L., "The "data" URL scheme", RFC 2397, DOI 10.17487/RFC2397, August 1998, . [RFC2445] Dawson, F. and D. Stenerson, "Internet Calendaring and Scheduling Core Object Specification (iCalendar)", RFC 2445, DOI 10.17487/RFC2445, November 1998, . [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, . [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/RFC5234, January 2008, . [RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and Scheduling Core Object Specification (iCalendar)", RFC 5545, DOI 10.17487/RFC5545, September 2009, . [RFC5546] Daboo, C., Ed., "iCalendar Transport-Independent Interoperability Protocol (iTIP)", RFC 5546, DOI 10.17487/RFC5546, December 2009, . Stepanek Expires 8 May 2025 [Page 100] Internet-Draft JSCalendar November 2024 [RFC5870] Mayrhofer, A. and C. Spanring, "A Uniform Resource Identifier for Geographic Locations ('geo' URI)", RFC 5870, DOI 10.17487/RFC5870, June 2010, . [RFC6638] Daboo, C. and B. Desruisseaux, "Scheduling Extensions to CalDAV", RFC 6638, DOI 10.17487/RFC6638, June 2012, . [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type Specifications and Registration Procedures", BCP 13, RFC 6838, DOI 10.17487/RFC6838, January 2013, . [RFC7265] Kewisch, P., Daboo, C., and M. Douglass, "jCal: The JSON Format for iCalendar", RFC 7265, DOI 10.17487/RFC7265, May 2014, . [RFC7529] Daboo, C. and G. Yakushev, "Non-Gregorian Recurrence Rules in the Internet Calendaring and Scheduling Core Object Specification (iCalendar)", RFC 7529, DOI 10.17487/RFC7529, May 2015, . [RFC7808] Douglass, M. and C. Daboo, "Time Zone Data Distribution Service", RFC 7808, DOI 10.17487/RFC7808, March 2016, . [RFC7953] Daboo, C. and M. Douglass, "Calendar Availability", RFC 7953, DOI 10.17487/RFC7953, August 2016, . [RFC7986] Daboo, C., "New Properties for iCalendar", RFC 7986, DOI 10.17487/RFC7986, October 2016, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [RFC8288] Nottingham, M., "Web Linking", RFC 8288, DOI 10.17487/RFC8288, October 2017, . [RFC8607] Daboo, C., Quillaud, A., and K. Murchison, Ed., "Calendaring Extensions to WebDAV (CalDAV): Managed Attachments", RFC 8607, DOI 10.17487/RFC8607, June 2019, . Stepanek Expires 8 May 2025 [Page 101] Internet-Draft JSCalendar November 2024 [RFC8984] Jenkins, N. and R. Stepanek, "JSCalendar: A JSON Representation of Calendar Data", RFC 8984, DOI 10.17487/RFC8984, July 2021, . [RFC9073] Douglass, M., "Event Publishing Extensions to iCalendar", RFC 9073, DOI 10.17487/RFC9073, August 2021, . [RFC9074] Daboo, C. and K. Murchison, Ed., ""VALARM" Extensions for iCalendar", RFC 9074, DOI 10.17487/RFC9074, August 2021, . [RFC9253] Douglass, M., "Support for iCalendar Relationships", RFC 9253, DOI 10.17487/RFC9253, August 2022, . [TZDB] "IANA Time Zone Database", . 7.2. Informative References [I-D.ietf-jmap-calendars] Jenkins, N.M. and M. Douglass, "JMAP for Calendars", Work in Progress, Internet-Draft, draft-ietf-jmap-calendars, 22 July 2024, . Appendix A. Discrepancies between iCalendar and JSCalendar This section highlights iCalendar and JSCalendar elements for which no conversion rule to a standard element is defined in this document. This is informational; implementations MAY convert these elements, for example by use of the special-purpose properties defined in this document, or some vendor-specific extension properties. Alternatively newer standards might define new standard elements and register them at IANA. A.1. Unsupported iCalendar Elements A.1.1. Components The following components do not convert to a standard element in JSCalendar: * AVAILABLE [RFC7953], Section 3.1 * VAVAILABILITY [RFC7953], Section 3.1 Stepanek Expires 8 May 2025 [Page 102] Internet-Draft JSCalendar November 2024 * VFREEBUSY [RFC5545], Section 3.6.4 * VJOURNAL [RFC5545], Section 3.6.3 A.1.2. Properties by Component The following components are defined to contain the listed properties. But these properties do not convert to a standard JSCalendar element. A.1.2.1. PARTICIPANT * CATEGORIES [RFC5545], Section 3.8.1.2 * CONTACT [RFC5545], Section 3.8.4.2 * CREATED [RFC5545], Section 3.8.7.1 * LAST-MODIFIED [RFC5545], Section 3.8.7.3 * PRIORITY [RFC5545], Section 3.8.1.9 * RELATED-TO [RFC5545], Section 3.8.4.5 * REQUEST-STATUS [RFC5545], Section 3.8.8.3 * RESOURCES [RFC5545], Section 3.8.1.10 * STATUS [RFC5545], Section 3.8.1.11 * STYLED-DESCRIPTION [RFC9073], Section 6.5 * UID [RFC5545], Section 3.8.4.7 A.1.2.2. VALARM * ATTACH [RFC5545], Section 3.8.1.1 * ATTENDEE [RFC5545], Section 3.8.4.1 * DESCRIPTION [RFC5545], Section 3.8.1.5 * DURATION [RFC5545], Section 3.8.2.5 * PROXIMITY [RFC9074], Section 8.1 * REPEAT [RFC5545], Section 3.8.6.2 Stepanek Expires 8 May 2025 [Page 103] Internet-Draft JSCalendar November 2024 * STYLED-DESCRIPTION [RFC9073], Section 6.5 * SUMMARY [RFC5545], Section 3.8.1.12 * UID [RFC5545], Section 3.8.4.7 A.1.2.3. VCALENDAR * CALSCALE [RFC5545], Section 3.7.1 * REFRESH-INTERVAL [RFC7986], Section 5.7 * VERSION [RFC5545], Section 3.7.4 A.1.2.4. VEVENT * CONTACT [RFC5545], Section 3.8.4.2 * REFID [RFC9253], Section 8.3 * RESOURCES [RFC5545], Section 3.8.1.10 A.1.2.5. VLOCATION * UID [RFC5545], Section 3.8.4.7 A.1.2.6. VRESOURCE * RESOURCE-TYPE [RFC9073], Section 6.3 * UID [RFC5545], Section 3.8.4.7 A.1.2.7. VTODO * COMPLETED [RFC5545], Section 3.8.2.1 * CONTACT [RFC5545], Section 3.8.4.2 * REFID [RFC9253], Section 8.3 * RESOURCES [RFC5545], Section 3.8.1.10 A.1.3. Properties by Value Type The following properties convert to a standard JSCalendar element for some other value type, but they do not for the listed value types. Stepanek Expires 8 May 2025 [Page 104] Internet-Draft JSCalendar November 2024 A.1.3.1. LINK * XML-REFERENCE [RFC9253], Section 7 A.1.3.2. RDATE * PERIOD [RFC5545], Section 3.3.9 A.1.3.3. STRUCTURED-DATA * TEXT [RFC9073], Section 6.6 A.1.4. Parameters by Property The following properties are defined to contain the listed parameters. But these parameters do not convert to a standard JSCalendar element. A.1.4.1. ATTACH * FILENAME [RFC8607], Section 4.2 * MANAGED-ID [RFC8607], Section 4.3 A.1.4.2. ATTENDEE * SENT-BY [RFC5545], Section 3.2.18 * LANGUAGE [RFC5545], Section 3.2.10 A.1.4.3. CATEGORIES * LANGUAGE [RFC5545], Section 3.2.10 A.1.4.4. COMMENT * ALTREP [RFC5545], Section 3.2.1 * LANGUAGE [RFC5545], Section 3.2.10 A.1.4.5. CONFERENCE * LANGUAGE [RFC5545], Section 3.2.10 A.1.4.6. DESCRIPTION * ALTREP [RFC5545], Section 3.2.1 Stepanek Expires 8 May 2025 [Page 105] Internet-Draft JSCalendar November 2024 * LANGUAGE [RFC5545], Section 3.2.10 A.1.4.7. IMAGE * ALTREP [RFC5545], Section 3.2.1 A.1.4.8. LINK * LANGUAGE [RFC5545], Section 3.2.10 A.1.4.9. LOCATION * ALTREP [RFC5545], Section 3.2.1 * LANGUAGE [RFC5545], Section 3.2.10 A.1.4.10. NAME * ALTREP [RFC5545], Section 3.2.1 * LANGUAGE [RFC5545], Section 3.2.10 A.1.4.11. ORGANIZER * SCHEDULE-AGENT [RFC6638], Section 7.1 * SCHEDULE-FORCE-SEND [RFC6638], Section 7.2 * SCHEDULE-STATUS [RFC6638], Section 7.3 * SENT-BY [RFC5545], Section 3.2.18 * LANGUAGE [RFC5545], Section 3.2.10 A.1.4.12. PARTICIPANT-TYPE * ORDER [RFC9073], Section 5.1 A.1.4.13. RECURRENCE-ID * RANGE [RFC5545], Section 3.2.13 A.1.4.14. RELATED-TO * GAP [RFC9253], Section 6.2 A.1.4.15. REQUEST-STATUS Stepanek Expires 8 May 2025 [Page 106] Internet-Draft JSCalendar November 2024 * LANGUAGE [RFC5545], Section 3.2.10 A.1.4.16. RESOURCES * ALTREP [RFC5545], Section 3.2.1 * LANGUAGE [RFC5545], Section 3.2.10 A.1.4.17. STRUCTURED-DATA * SCHEMA [RFC9073], Section 5.2 A.1.4.18. STYLED-DESCRIPTION * ALTREP [RFC5545], Section 3.2.1 * LANGUAGE [RFC5545], Section 3.2.10 * DERIVED [RFC9073], Section 5.3 A.1.4.19. SUMMARY * ALTREP [RFC5545], Section 3.2.1 * LANGUAGE [RFC5545], Section 3.2.10 A.1.4.20. TZNAME * LANGUAGE [RFC5545], Section 3.2.10 A.2. Unsupported JSCalendar Elements Unfinished JSCalendar elements and conversion rules are marked with the term "TBD" in Section 3. Author's Address Robert Stepanek Fastmail PO Box 234 Collins St West Melbourne VIC 8007 Australia Email: rsto@fastmailteam.com URI: https://www.fastmail.com Stepanek Expires 8 May 2025 [Page 107]