Calendaring extensions R. Stepanek
Internet-Draft Fastmail
Intended status: Standards Track 21 May 2025
Expires: 22 November 2025
JSCalendar: Converting from and to iCalendar
draft-ietf-calext-jscalendar-icalendar-13
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.
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 22 November 2025.
Copyright Notice
Copyright (c) 2025 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. Code Components
extracted from this document must include 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.
Stepanek Expires 22 November 2025 [Page 1]
Internet-Draft JSCalendar May 2025
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4
1.2. Scope and Goals . . . . . . . . . . . . . . . . . . . . . 4
1.3. How to Read the Examples . . . . . . . . . . . . . . . . 4
1.3.1. iCalendar Examples . . . . . . . . . . . . . . . . . 5
1.3.2. JSCalendar Examples . . . . . . . . . . . . . . . . . 6
1.4. Lossy versus Lossless Conversion . . . . . . . . . . . . 8
2. Converting iCalendar to JSCalendar . . . . . . . . . . . . . 8
2.1. General rules . . . . . . . . . . . . . . . . . . . . . . 8
2.1.1. iCalendar Objects . . . . . . . . . . . . . . . . . . 8
2.1.2. Recurring Components . . . . . . . . . . . . . . . . 11
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 . . . . . . . . . . . . . . . . . . . . . . . 16
2.2.3. VCONFERENCE . . . . . . . . . . . . . . . . . . . . . 18
2.2.4. VEVENT . . . . . . . . . . . . . . . . . . . . . . . 20
2.2.5. VLOCATION . . . . . . . . . . . . . . . . . . . . . . 23
2.2.6. VTODO . . . . . . . . . . . . . . . . . . . . . . . . 25
2.3. Properties . . . . . . . . . . . . . . . . . . . . . . . 28
2.3.1. ACKNOWLEDGED . . . . . . . . . . . . . . . . . . . . 29
2.3.2. ACTION . . . . . . . . . . . . . . . . . . . . . . . 29
2.3.3. ATTACH . . . . . . . . . . . . . . . . . . . . . . . 30
2.3.4. ATTENDEE . . . . . . . . . . . . . . . . . . . . . . 32
2.3.5. CALENDAR-ADDRESS . . . . . . . . . . . . . . . . . . 36
2.3.6. CATEGORIES . . . . . . . . . . . . . . . . . . . . . 37
2.3.7. CLASS . . . . . . . . . . . . . . . . . . . . . . . . 37
2.3.8. COLOR . . . . . . . . . . . . . . . . . . . . . . . . 38
2.3.9. CONCEPT . . . . . . . . . . . . . . . . . . . . . . . 38
2.3.10. CONFERENCE . . . . . . . . . . . . . . . . . . . . . 39
2.3.11. COORDINATES . . . . . . . . . . . . . . . . . . . . . 40
2.3.12. CREATED . . . . . . . . . . . . . . . . . . . . . . . 40
2.3.13. DESCRIPTION . . . . . . . . . . . . . . . . . . . . . 40
2.3.14. DTEND . . . . . . . . . . . . . . . . . . . . . . . . 41
2.3.15. DTSTAMP . . . . . . . . . . . . . . . . . . . . . . . 43
2.3.16. DTSTART . . . . . . . . . . . . . . . . . . . . . . . 43
2.3.17. DUE . . . . . . . . . . . . . . . . . . . . . . . . . 44
2.3.18. DURATION . . . . . . . . . . . . . . . . . . . . . . 46
2.3.19. ESTIMATED-DURATION . . . . . . . . . . . . . . . . . 46
2.3.20. EXDATE . . . . . . . . . . . . . . . . . . . . . . . 46
2.3.21. GEO . . . . . . . . . . . . . . . . . . . . . . . . . 47
2.3.22. IMAGE . . . . . . . . . . . . . . . . . . . . . . . . 49
2.3.23. LAST-MODIFIED . . . . . . . . . . . . . . . . . . . . 50
2.3.24. LINK . . . . . . . . . . . . . . . . . . . . . . . . 51
Stepanek Expires 22 November 2025 [Page 2]
Internet-Draft JSCalendar May 2025
2.3.25. LOCATION . . . . . . . . . . . . . . . . . . . . . . 52
2.3.26. LOCATION-TYPE . . . . . . . . . . . . . . . . . . . . 53
2.3.27. METHOD . . . . . . . . . . . . . . . . . . . . . . . 54
2.3.28. NAME . . . . . . . . . . . . . . . . . . . . . . . . 55
2.3.29. ORGANIZER . . . . . . . . . . . . . . . . . . . . . . 56
2.3.30. PERCENT-COMPLETE . . . . . . . . . . . . . . . . . . 58
2.3.31. PRIORITY . . . . . . . . . . . . . . . . . . . . . . 58
2.3.32. PRODID . . . . . . . . . . . . . . . . . . . . . . . 59
2.3.33. RDATE . . . . . . . . . . . . . . . . . . . . . . . . 59
2.3.34. RECURRENCE-ID . . . . . . . . . . . . . . . . . . . . 60
2.3.35. RELATED-TO . . . . . . . . . . . . . . . . . . . . . 60
2.3.36. RRULE . . . . . . . . . . . . . . . . . . . . . . . . 62
2.3.37. SEQUENCE . . . . . . . . . . . . . . . . . . . . . . 64
2.3.38. SHOW-WITHOUT-TIME . . . . . . . . . . . . . . . . . . 65
2.3.39. STATUS . . . . . . . . . . . . . . . . . . . . . . . 65
2.3.40. SOURCE . . . . . . . . . . . . . . . . . . . . . . . 66
2.3.41. STYLED-DESCRIPTION . . . . . . . . . . . . . . . . . 66
2.3.42. SUMMARY . . . . . . . . . . . . . . . . . . . . . . . 67
2.3.43. TRANSP . . . . . . . . . . . . . . . . . . . . . . . 68
2.3.44. TRIGGER . . . . . . . . . . . . . . . . . . . . . . . 68
2.3.45. UID . . . . . . . . . . . . . . . . . . . . . . . . . 70
3. Converting JSCalendar to iCalendar . . . . . . . . . . . . . 70
3.1. Alert . . . . . . . . . . . . . . . . . . . . . . . . . . 70
3.2. Event and Task . . . . . . . . . . . . . . . . . . . . . 71
3.3. Group . . . . . . . . . . . . . . . . . . . . . . . . . . 76
3.4. Link . . . . . . . . . . . . . . . . . . . . . . . . . . 78
3.5. Location . . . . . . . . . . . . . . . . . . . . . . . . 79
3.6. Participant . . . . . . . . . . . . . . . . . . . . . . . 80
3.7. VirtualLocation . . . . . . . . . . . . . . . . . . . . . 84
4. Updates to iCalendar . . . . . . . . . . . . . . . . . . . . 85
4.1. New Properties . . . . . . . . . . . . . . . . . . . . . 85
4.1.1. JSID . . . . . . . . . . . . . . . . . . . . . . . . 85
4.1.2. JSPROP . . . . . . . . . . . . . . . . . . . . . . . 86
4.2. New Parameters . . . . . . . . . . . . . . . . . . . . . 89
4.2.1. JSID . . . . . . . . . . . . . . . . . . . . . . . . 89
4.2.2. JSPTR . . . . . . . . . . . . . . . . . . . . . . . . 90
5. Updates to JSCalendar . . . . . . . . . . . . . . . . . . . . 91
5.1. New Properties . . . . . . . . . . . . . . . . . . . . . 91
5.1.1. iCalComponent . . . . . . . . . . . . . . . . . . . . 91
5.1.2. iCalProperty . . . . . . . . . . . . . . . . . . . . 93
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 95
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 95
7.1. Normative References . . . . . . . . . . . . . . . . . . 95
7.2. Informative References . . . . . . . . . . . . . . . . . 97
Appendix A. Discrepancies between iCalendar and JSCalendar . . . 97
A.1. Unsupported iCalendar Elements . . . . . . . . . . . . . 98
A.1.1. Components . . . . . . . . . . . . . . . . . . . . . 98
A.1.2. Properties by Component . . . . . . . . . . . . . . . 98
Stepanek Expires 22 November 2025 [Page 3]
Internet-Draft JSCalendar May 2025
A.1.3. Subcomponents by Component . . . . . . . . . . . . . 101
A.1.4. Properties by Value Type . . . . . . . . . . . . . . 101
A.1.5. Parameters by Property . . . . . . . . . . . . . . . 101
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 103
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 of how to convert that element. All
iCalendar and JSCalendar elements currently registered at IANA are in
scope, but not all of these elements are common to both formats.
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.1.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 following sections define the notation for such examples.
Stepanek Expires 22 November 2025 [Page 4]
Internet-Draft JSCalendar May 2025
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. The following rules apply:
* 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.
* An example that only contains a VCALENDAR component but no
contained components implicitly represents a VCALENDAR component
that contains a VEVENT component.
* Implicit components (those without a BEGIN and END, or omitted
completely) are assumed to contain all mandatory properties with
some value, but the actual value is irrelevant for the example.
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
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
Stepanek Expires 22 November 2025 [Page 5]
Internet-Draft JSCalendar May 2025
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
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
Stepanek Expires 22 November 2025 [Page 6]
Internet-Draft JSCalendar May 2025
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"
}
]
}
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 are
irrelevant for this example, including mandatory properties. The
"..." property requires the "@type" property to be set. 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 ...
Stepanek Expires 22 November 2025 [Page 7]
Internet-Draft JSCalendar May 2025
1.4. Lossy versus Lossless Conversion
This document outlines how to convert iCalendar elements to
JSCalendar elements, and the other way round. Many of these can be
represented by standard elements in both formats, meaning that they
are registered in the iCalendar and JSCalendar IANA registries and
differ from the special-purpose elements introduced in Section 4 and
Section 5. Still, a number of elements in either format have no
standard counterpart in the other. When converting between between
iCalendar and JSCalendar, implementations MAY choose to only convert
elements that have standard element in the target format, or aim to
preserve as many elements as possible.
When to choose between lossy and lossless conversion is
implementation-specific. For example:
* For lossy conversion, an implementation that internally stores
calendar data in JSCalendar format might only want to convert to a
subset of iCalendar elements for iMIP scheduling [RFC6047]. In
this case, it might not make use any of the conversion-specific
iCalendar properties introduced in Section 4.
* For lossless conversion, an implementation that internally stores
calendar data in iCalendar format might want to convert without
loss to JSCalendar when updating calendar events with JMAP
[jmap-calendars]. For that, it can use the conversion-specific
properties defined in Section 5.
All the examples in this document illustrate lossless conversion, if
not explicitly stated otherwise in the example.
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 [jscalendarbis] (Section 2.3). Its properties convert as
follows:
Stepanek Expires 22 November 2025 [Page 8]
Internet-Draft JSCalendar May 2025
+===============+============+==================+=========+======+
| Name | Reference | Group property | See | Note |
+===============+============+==================+=========+======+
| ATTACH | [RFC5545], | links | Section | |
| | Section | | 2.3.3 | |
| | 3.8.1.1 | | | |
+---------------+------------+------------------+---------+------+
| 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 | |
| | Section | | 2.3.9 | |
| | 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 | | | |
+---------------+------------+------------------+---------+------+
| IMAGE | [RFC7986], | links | Section | |
| | Section | | 2.3.22 | |
| | 5.10 | | | |
+---------------+------------+------------------+---------+------+
| 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 | |
Stepanek Expires 22 November 2025 [Page 9]
Internet-Draft JSCalendar May 2025
| | Section | entries/*/prodId | 2.3.32 | |
| | 3.7.3 | | | |
+---------------+------------+------------------+---------+------+
| SOURCE | [RFC7986], | source | Section | |
| | Section | | 2.3.40 | |
| | 5.8 | | | |
+---------------+------------+------------------+---------+------+
| UID | [RFC5545], | uid | Section | |
| | Section | | 2.3.45 | |
| | 3.8.4.7 | | | |
+---------------+------------+------------------+---------+------+
Table 1: Properties of the VCALENDAR component
Its components convert as follows:
+========+===============+================+=========+======+
| Name | Reference | Group property | See | Note |
+========+===============+================+=========+======+
| VEVENT | [RFC5545], | entries | Section | |
| | Section 3.6.1 | | 2.2.4 | |
+--------+---------------+----------------+---------+------+
| VTODO | [RFC5545], | entries | Section | |
| | Section 3.6.2 | | 2.2.6 | |
+--------+---------------+----------------+---------+------+
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 order of elements in the "entries" property is implementation-
specific, e.g. entries need not be in the same order as their source
components in the iCalendar object.
The following example illustrates how to convert the VCALENDAR
component:
BEGIN:VCALENDAR
UID:41aa02b6-42d0-4f45-8cb4-8b5075be2e14
BEGIN:VEVENT
...
Stepanek Expires 22 November 2025 [Page 10]
Internet-Draft JSCalendar May 2025
{
"@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. As an
exception to this rule, this does not apply to recurrence overrides,
defined as follows.
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 a
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:
Stepanek Expires 22 November 2025 [Page 11]
Internet-Draft JSCalendar May 2025
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
{
"@type": "Group",
"entries": [
{
"...": "",
"@type": "Event",
"recurrenceOverrides": {
"2024-02-02T14:00:00": {
"start": "2024-02-02T16:00:00"
}
},
"recurrenceRule": {
"@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 following example illustrates how to convert stand-alone
recurrence instances:
Stepanek Expires 22 November 2025 [Page 12]
Internet-Draft JSCalendar May 2025
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:20240103T170000
...
END:VEVENT
END:VCALENDAR
{
"@type": "Group",
"entries": [
{
"...": "",
"@type": "Event",
"recurrenceId": "2024-02-02T14:00:00",
"recurrenceIdTimeZone": "Europe/Berlin",
"start": "2024-02-02T16:00:00",
"timeZone": "Europe/Berlin",
"uid": "F4257E1D-5461-4EF6-840F-9DFC653EB559"
},
{
"...": "",
"@type": "Event",
"recurrenceId": "2024-01-03T14:00:00",
"recurrenceIdTimeZone": "Europe/Berlin",
"start": "2024-01-03T17: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 [jscalendarbis]
(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 22 November 2025 [Page 13]
Internet-Draft JSCalendar May 2025
This document defines the new JSID (Section 4.2.1) parameter and JSID
property (Section 4.1.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 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 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 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.
Otherwise, how to convert the TZID parameter value is implementation-
specific: software libraries such as the International Components for
Unicode (https://icu.unicode.org/) support converting Microsoft time
zone names to IANA time zone identifiers. Alternatively, finding an
IANA time zone for which the time zone offset changes match those of
the custom time zone over the span of the event or task is typically
possible.
Stepanek Expires 22 November 2025 [Page 14]
Internet-Draft JSCalendar May 2025
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 [jscalendarbis] (Section 4.4.6). Its properties
convert as follows:
+====================+============+=================+=========+====+
| Name | Reference | Participant | See |Note|
| | | property | | |
+====================+============+=================+=========+====+
| ATTACH | [RFC5545], | links | Section | |
| | Section | | 2.3.3 | |
| | 3.8.1.1 | | | |
+--------------------+------------+-----------------+---------+----+
| CALENDAR-ADDRESS | [RFC9073], | calendarAddress | Section | |
| | Section | | 2.3.5 | |
| | 6.4 | | | |
+--------------------+------------+-----------------+---------+----+
| DESCRIPTION | [RFC5545], | description | Section | |
| | Section | | 2.3.13 | |
| | 3.8.1.5 | | | |
+--------------------+------------+-----------------+---------+----+
| LINK | [RFC9253], | links | Section | |
| | Section | | 2.3.24 | |
| | 8.2 | | | |
+--------------------+------------+-----------------+---------+----+
| STYLED-DESCRIPTION | [RFC9073], | description | Section | |
| | Section | | 2.3.41 | |
| | 6.5 | | | |
+--------------------+------------+-----------------+---------+----+
| SUMMARY | [RFC5545], | name | Section | |
| | Section | | 2.3.42 | |
| | 3.8.1.12 | | | |
+--------------------+------------+-----------------+---------+----+
Table 3: Properties of the PARTICIPANT component
Stepanek Expires 22 November 2025 [Page 15]
Internet-Draft JSCalendar May 2025
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:
BEGIN:PARTICIPANT
UID:47AD2E1C-49D4-45DF-BD83-8398ACC7D8E2
DESCRIPTION:A participant
...
END:PARTICIPANT
"participants": {
"p32": {
"@type": "Participant",
"description": "A participant",
"iCalComponent": {
"@type": "ICalComponent",
"name": "participant",
"properties": [
[
"uid",
{},
"text",
"47AD2E1C-49D4-45DF-BD83-8398ACC7D8E2"
]
]
}
}
}
Figure 9: Converting the PARTICIPANT component
2.2.2. VALARM
The VALARM component [RFC5545] (Section 3.6.6) converts to an Alert
object [jscalendarbis] (Section 4.5.2). Its properties convert as
follows:
Stepanek Expires 22 November 2025 [Page 16]
Internet-Draft JSCalendar May 2025
+==============+============+==============+=========+===========+
| 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.35 | |
| | 3.8.4.5 | | | |
+--------------+------------+--------------+---------+-----------+
| TRIGGER | [RFC5545], | trigger | Section | |
| | Section | | 2.3.44 | |
| | 3.8.6.3 | | | |
+--------------+------------+--------------+---------+-----------+
Table 4: 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:VALARM
TRIGGER:-PT30M
ACTION:DISPLAY
DESCRIPTION:Breakfast meeting
END:VALARM
Stepanek Expires 22 November 2025 [Page 17]
Internet-Draft JSCalendar May 2025
"alerts": {
"a8": {
"@type": "Alert",
"iCalComponent": {
"@type": "ICalComponent",
"name": "valarm",
"properties": [
[
"description",
{},
"text",
"Breakfast meeting"
]
]
},
"trigger": {
"@type": "OffsetTrigger",
"offset": "-PT30M"
},
"action": "display"
}
}
Figure 10: Converting the VALARM component
2.2.3. VCONFERENCE
The VCONFERENCE component [icaljscalexts] (Section 6.1) converts to a
VirtualLocation object [jscalendarbis] (Section 4.2.7). It MUST
convert to the same VirtualLocation to which its related CONFERENCE
property (Section 2.3.10) converts. If no related CONFERENCE
property is set in the calendar component, then implementations MUST
NOT convert the VCONFERENCE component.
Its properties convert as follows:
Stepanek Expires 22 November 2025 [Page 18]
Internet-Draft JSCalendar May 2025
+====================+============+=============+=========+======+
| Name | Reference | Location | See | Note |
| | | property | | |
+====================+============+=============+=========+======+
| DESCRIPTION | [RFC5545], | description | Section | |
| | Section | | 2.3.13 | |
| | 3.8.1.5 | | | |
+--------------------+------------+-------------+---------+------+
| STYLED-DESCRIPTION | [RFC9073], | description | Section | |
| | Section | | 2.3.41 | |
| | 6.5 | | | |
+--------------------+------------+-------------+---------+------+
Table 5: Properties of the VCONFERENCE component
Other properties or components MAY be converted to the
"iCalComponent" property (Section 5.1.1) of the VirtualLocation
object.
The following example illustrates how to convert the VCONFERENCE
component:
BEGIN:VCONFERENCE
URI;VALUE=URI:https://chat.example.com/x?id=123456
STYLED-DESCRIPTION;VALUE=TEXT;FMTTYPE=text/html:Click here to download the client...
...
END:VCONFERENCE
CONFERENCE;VALUE=URI;FEATURE=AUDIO,VIDEO;
LABEL=Team meeting:https://chat.example.com/x?id=123456
"virtualLocations": {
"1": {
"@type": "VirtualLocation",
"name": "Team meeting",
"description": "Click here to download the client...",
"descriptionContentType": "text/html",
"uri": "https://chat.example.com/x?id=123456",
"features": {
"audio": true,
"video": true
}
}
}
Figure 11: Converting the VCONFERENCE component
Stepanek Expires 22 November 2025 [Page 19]
Internet-Draft JSCalendar May 2025
2.2.4. VEVENT
The VEVENT component [RFC5545] (Section 3.6.1) converts to a Event
object [jscalendarbis] (Section 2.1). Its properties convert as
follows:
+============+================+========================+=======+====+
|Name |Reference |Event property |See |Note|
+============+================+========================+=======+====+
|ATTACH |[RFC5545], |links |Section| |
| |Section 3.8.1.1 | |2.3.3 | |
+------------+----------------+------------------------+-------+----+
|ATTENDEE |[RFC5545], |participants |Section| |
| |Section 3.8.4.1 | |2.3.4 | |
+------------+----------------+------------------------+-------+----+
|CATEGORIES |[RFC5545], |keywords |Section| |
| |Section 3.8.1.2 | |2.3.6 | |
+------------+----------------+------------------------+-------+----+
|CLASS |[RFC5545], |privacy |Section| |
| |Section 3.8.1.3 | |2.3.7 | |
+------------+----------------+------------------------+-------+----+
|COLOR |[RFC7986], |color |Section| |
| |Section 5.9 | |2.3.8 | |
+------------+----------------+------------------------+-------+----+
|CONCEPT |[RFC9253], |categories |Section| |
| |Section 8.1 | |2.3.9 | |
+------------+----------------+------------------------+-------+----+
|CONFERENCE |[RFC7986], |virtualLocations |Section| |
| |Section 5.11 | |2.3.10 | |
+------------+----------------+------------------------+-------+----+
|CREATED |[RFC5545], |created |Section| |
| |Section 3.8.7.1 | |2.3.12 | |
+------------+----------------+------------------------+-------+----+
|DESCRIPTION |[RFC5545], |description |Section| |
| |Section 3.8.1.5 | |2.3.13 | |
+------------+----------------+------------------------+-------+----+
|DTEND |[RFC5545], |duration, endTimeZone |Section| |
| |Section 3.8.2.2 | |2.3.14 | |
+------------+----------------+------------------------+-------+----+
|DTSTAMP |[RFC5545], |updated |Section| |
| |Section 3.8.7.2 | |2.3.15 | |
+------------+----------------+------------------------+-------+----+
|DTSTART |[RFC5545], |start |Section| |
| |Section 3.8.2.4 | |2.3.16 | |
+------------+----------------+------------------------+-------+----+
|DURATION |[RFC5545], |duration |Section| |
| |Section 3.8.2.5 | |2.3.18 | |
+------------+----------------+------------------------+-------+----+
Stepanek Expires 22 November 2025 [Page 20]
Internet-Draft JSCalendar May 2025
|EXDATE |[RFC5545], |recurrenceOverrides |Section| |
| |Section 3.8.5.1 | |2.3.20 | |
+------------+----------------+------------------------+-------+----+
|GEO |[RFC5545], |locations |Section| |
| |Section 3.8.1.6 | |2.3.21 | |
+------------+----------------+------------------------+-------+----+
|IMAGE |[RFC7986], |links |Section| |
| |Section 5.10 | |2.3.22 | |
+------------+----------------+------------------------+-------+----+
|LAST- |[RFC5545], |updated |Section| |
|MODIFIED |Section 3.8.7.3 | |2.3.23 | |
+------------+----------------+------------------------+-------+----+
|LINK |[RFC9253], |links |Section| |
| |Section 8.2 | |2.3.24 | |
+------------+----------------+------------------------+-------+----+
|LOCATION |[RFC5545], |locations |Section| |
| |Section 3.8.1.7 | |2.3.25 | |
+------------+----------------+------------------------+-------+----+
|ORGANIZER |[RFC5545], |organizerCalendarAddress|Section| |
| |Section 3.8.4.3 | |2.3.29 | |
+------------+----------------+------------------------+-------+----+
|PRIORITY |[RFC5545], |priority |Section| |
| |Section 3.8.1.9 | |2.3.31 | |
+------------+----------------+------------------------+-------+----+
|RDATE |[RFC5545], |recurrenceOverrides |Section| |
| |Section 3.8.5.2 | |2.3.33 | |
+------------+----------------+------------------------+-------+----+
|RECURRENCE- |[RFC5545], |recurrenceId |Section| |
|ID |Section 3.8.4.4 | |2.3.34 | |
+------------+----------------+------------------------+-------+----+
|RELATED-TO |[RFC5545], |relatedTo |Section| |
| |Section 3.8.4.5 | |2.3.35 | |
+------------+----------------+------------------------+-------+----+
|RRULE |[RFC5545], |recurrenceRule |Section| |
| |Section 3.8.5.3 | |2.3.36 | |
+------------+----------------+------------------------+-------+----+
|SEQUENCE |[RFC5545], |sequence |Section| |
| |Section 3.8.7.4 | |2.3.37 | |
+------------+----------------+------------------------+-------+----+
|SHOW- |[icaljscalexts],|showWithoutTime |Section| |
|WITHOUT- |Section 4.2 | |2.3.38 | |
|TIME | | | | |
+------------+----------------+------------------------+-------+----+
|STATUS |[RFC5545], |status |Section| |
| |Section 3.8.1.11| |2.3.39 | |
+------------+----------------+------------------------+-------+----+
|STYLED- |[RFC9073], |description |Section| |
|DESCRIPTION |Section 6.5 | |2.3.41 | |
Stepanek Expires 22 November 2025 [Page 21]
Internet-Draft JSCalendar May 2025
+------------+----------------+------------------------+-------+----+
|SUMMARY |[RFC5545], |title |Section| |
| |Section 3.8.1.12| |2.3.42 | |
+------------+----------------+------------------------+-------+----+
|TRANSP |[RFC5545], |freeBusyStatus |Section| |
| |Section 3.8.2.7 | |2.3.43 | |
+------------+----------------+------------------------+-------+----+
|UID |[RFC5545], |uid |Section| |
| |Section 3.8.4.7 | |2.3.45 | |
+------------+----------------+------------------------+-------+----+
Table 6: Properties of the VEVENT component
Its components convert as follows:
+=============+==================+==================+=========+====+
| Name | Reference | Event property | See |Note|
+=============+==================+==================+=========+====+
| VALARM | [RFC5545], | alerts | Section | |
| | Section 3.6.6 | | 2.2.2 | |
+-------------+------------------+------------------+---------+----+
| VCONFERENCE | [icaljscalexts], | virtualLocations | Section | |
| | Section 5.1 | | 2.2.3 | |
+-------------+------------------+------------------+---------+----+
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.
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.
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
Stepanek Expires 22 November 2025 [Page 22]
Internet-Draft JSCalendar May 2025
{
"...": "",
"@type": "Group",
"entries": [
{
"@type": "Event",
"start": "2006-01-02T03:04:05",
"timeZone": "Etc/UTC",
"uid": "DE935D01-3DF7-4201-B61A-D77D05C8B21A",
"...": ""
},
{
"@type": "Event",
"uid": "60BE3D6E-6383-473A-BCF1-3C43EA1FA571",
"...": ""
}
]
}
Figure 12: Converting the VEVENT component
2.2.5. VLOCATION
The VLOCATION component [RFC9073] (Section 7.2) converts to a
Location object [jscalendarbis] (Section 4.2.5). Its properties
convert as follows:
Stepanek Expires 22 November 2025 [Page 23]
Internet-Draft JSCalendar May 2025
+====================+==================+=============+=======+====+
| Name | Reference |Location |See |Note|
| | |property | | |
+====================+==================+=============+=======+====+
| ATTACH | [RFC5545], |links |Section| |
| | Section 3.8.1.1 | |2.3.3 | |
+--------------------+------------------+-------------+-------+----+
| COORDINATES | [icaljscalexts], |coordinates |Section| |
| | Section 4.1 | |2.3.11 | |
+--------------------+------------------+-------------+-------+----+
| DESCRIPTION | [RFC5545], |description |Section| |
| | Section 3.8.1.5 | |2.3.13 | |
+--------------------+------------------+-------------+-------+----+
| GEO | [RFC5545], |coordinates |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 | |
+--------------------+------------------+-------------+-------+----+
| LOCATION-TYPE | [RFC9073], |locationTypes|Section| |
| | Section 6.1 | |2.3.26 | |
+--------------------+------------------+-------------+-------+----+
| NAME | [RFC7986], |name |Section| |
| | Section 5.1 | |2.3.28 | |
+--------------------+------------------+-------------+-------+----+
| STYLED-DESCRIPTION | [RFC9073], |description |Section| |
| | Section 6.5 | |2.3.41 | |
+--------------------+------------------+-------------+-------+----+
Table 8: Properties of the VLOCATION component
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
Stepanek Expires 22 November 2025 [Page 24]
Internet-Draft JSCalendar May 2025
"locations": {
"e4": {
"@type": "Location",
"name": "The venue",
"iCalComponent": {
"@type": "ICalComponent",
"name": "vlocation",
"properties": [
[
"structured-data",
{},
"uri",
"http://dir.example.com/venues/big-hall.vcf"
],
[
"uid",
{},
"text",
"4954DC22-5BD6-4E98-844D-0302982F54AC"
]
]
}
}
}
Figure 13: Converting the VLOCATION component
2.2.6. VTODO
The VTODO component [RFC5545] (Section 3.6.2) converts to a Task
object [jscalendarbis] (Section 2.2). Its properties convert as
follows:
+============+================+========================+=======+====+
|Name |Reference |Task property |See |Note|
+============+================+========================+=======+====+
|ATTACH |[RFC5545], |links |Section| |
| |Section 3.8.1.1 | |2.3.3 | |
+------------+----------------+------------------------+-------+----+
|ATTENDEE |[RFC5545], |participants |Section| |
| |Section 3.8.4.1 | |2.3.4 | |
+------------+----------------+------------------------+-------+----+
|CATEGORIES |[RFC5545], |keywords |Section| |
| |Section 3.8.1.2 | |2.3.6 | |
+------------+----------------+------------------------+-------+----+
|CLASS |[RFC5545], |privacy |Section| |
| |Section 3.8.1.3 | |2.3.7 | |
+------------+----------------+------------------------+-------+----+
Stepanek Expires 22 November 2025 [Page 25]
Internet-Draft JSCalendar May 2025
|COLOR |[RFC7986], |color |Section| |
| |Section 5.9 | |2.3.8 | |
+------------+----------------+------------------------+-------+----+
|CONCEPT |[RFC9253], |categories |Section| |
| |Section 8.1 | |2.3.9 | |
+------------+----------------+------------------------+-------+----+
|CONFERENCE |[RFC7986], |virtualLocations |Section| |
| |Section 5.11 | |2.3.10 | |
+------------+----------------+------------------------+-------+----+
|CREATED |[RFC5545], |created |Section| |
| |Section 3.8.7.1 | |2.3.12 | |
+------------+----------------+------------------------+-------+----+
|DESCRIPTION |[RFC5545], |description |Section| |
| |Section 3.8.1.5 | |2.3.13 | |
+------------+----------------+------------------------+-------+----+
|DTSTAMP |[RFC5545], |updated |Section| |
| |Section 3.8.7.2 | |2.3.15 | |
+------------+----------------+------------------------+-------+----+
|DTSTART |[RFC5545], |start |Section| |
| |Section 3.8.2.4 | |2.3.16 | |
+------------+----------------+------------------------+-------+----+
|DUE |[RFC5545], |due |Section| |
| |Section 3.8.2.3 | |2.3.17 | |
+------------+----------------+------------------------+-------+----+
|DURATION |[RFC5545], |duration |Section| |
| |Section 3.8.2.5 | |2.3.18 | |
+------------+----------------+------------------------+-------+----+
|ESTIMATED- |[ical-tasks], |estimatedDuration |Section| |
|DURATION |Section 12.1 | |2.3.19 | |
+------------+----------------+------------------------+-------+----+
|EXDATE |[RFC5545], |recurrenceOverrides |Section| |
| |Section 3.8.5.1 | |2.3.20 | |
+------------+----------------+------------------------+-------+----+
|GEO |[RFC5545], |locations |Section| |
| |Section 3.8.1.6 | |2.3.21 | |
+------------+----------------+------------------------+-------+----+
|IMAGE |[RFC7986], |links |Section| |
| |Section 5.10 | |2.3.22 | |
+------------+----------------+------------------------+-------+----+
|LAST- |[RFC5545], |updated |Section| |
|MODIFIED |Section 3.8.7.3 | |2.3.23 | |
+------------+----------------+------------------------+-------+----+
|LINK |[RFC9253], |links |Section| |
| |Section 8.2 | |2.3.24 | |
+------------+----------------+------------------------+-------+----+
|LOCATION |[RFC5545], |locations |Section| |
| |Section 3.8.1.7 | |2.3.25 | |
+------------+----------------+------------------------+-------+----+
Stepanek Expires 22 November 2025 [Page 26]
Internet-Draft JSCalendar May 2025
|ORGANIZER |[RFC5545], |organizerCalendarAddress|Section| |
| |Section 3.8.4.3 | |2.3.29 | |
+------------+----------------+------------------------+-------+----+
|PERCENT- |[RFC5545], |percentComplete |Section| |
|COMPLETE |Section 3.8.1.8 | |2.3.30 | |
+------------+----------------+------------------------+-------+----+
|PRIORITY |[RFC5545], |priority |Section| |
| |Section 3.8.1.9 | |2.3.31 | |
+------------+----------------+------------------------+-------+----+
|RDATE |[RFC5545], |recurrenceOverrides |Section| |
| |Section 3.8.5.2 | |2.3.33 | |
+------------+----------------+------------------------+-------+----+
|RECURRENCE- |[RFC5545], |recurrenceId |Section| |
|ID |Section 3.8.4.4 | |2.3.34 | |
+------------+----------------+------------------------+-------+----+
|RELATED-TO |[RFC5545], |relatedTo |Section| |
| |Section 3.8.4.5 | |2.3.35 | |
+------------+----------------+------------------------+-------+----+
|RRULE |[RFC5545], |recurrenceRule |Section| |
| |Section 3.8.5.3 | |2.3.36 | |
+------------+----------------+------------------------+-------+----+
|SEQUENCE |[RFC5545], |sequence |Section| |
| |Section 3.8.7.4 | |2.3.37 | |
+------------+----------------+------------------------+-------+----+
|SHOW- |[icaljscalexts],|showWithoutTime |Section| |
|WITHOUT- |Section 4.2 | |2.3.38 | |
|TIME | | | | |
+------------+----------------+------------------------+-------+----+
|STYLED- |[RFC9073], |description |Section| |
|DESCRIPTION |Section 6.5 | |2.3.41 | |
+------------+----------------+------------------------+-------+----+
|SUMMARY |[RFC5545], |title |Section| |
| |Section 3.8.1.12| |2.3.42 | |
+------------+----------------+------------------------+-------+----+
|TRANSP |[RFC5545], |freeBusyStatus |Section| |
| |Section 3.8.2.7 | |2.3.43 | |
+------------+----------------+------------------------+-------+----+
|UID |[RFC5545], |uid |Section| |
| |Section 3.8.4.7 | |2.3.45 | |
+------------+----------------+------------------------+-------+----+
Table 9: Properties of the VTODO component
Its components convert as follows:
Stepanek Expires 22 November 2025 [Page 27]
Internet-Draft JSCalendar May 2025
+=============+==================+==================+=========+====+
| Name | Reference | Task property | See |Note|
+=============+==================+==================+=========+====+
| VALARM | [RFC5545], | alerts | Section | |
| | Section 3.6.6 | | 2.2.2 | |
+-------------+------------------+------------------+---------+----+
| VCONFERENCE | [icaljscalexts], | virtualLocations | Section | |
| | Section 5.1 | | 2.2.3 | |
+-------------+------------------+------------------+---------+----+
Table 10: Components of the VTODO component
Other properties or components MAY be converted to the
"iCalComponent" property (Section 5.1.1) of the Task object.
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.
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 14: Converting the VTODO component
2.3. Properties
Stepanek Expires 22 November 2025 [Page 28]
Internet-Draft JSCalendar May 2025
2.3.1. ACKNOWLEDGED
The ACKNOWLEDGED property [RFC9074] (Section 6.1) in a VALARM
component converts to the "acknowledged" property [jscalendarbis]
(Section 4.5.2) of the Alert object.
The following example illustrates how to convert the ACKNOWLEDGED
property:
BEGIN:VEVENT
BEGIN:VALARM
ACKNOWLEDGED:20241002T114703Z
...
"alerts": {
"a": {
"@type": "Alert",
"acknowledged": "2024-10-02T11:47:03Z",
"...": ""
}
}
Figure 15: 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 [jscalendarbis] (Section 4.5.2) of
the Alert object.
Its values convert as follows:
+=================+==================+
| iCalendar value | JSCalendar value |
+=================+==================+
| DISPLAY | display |
+-----------------+------------------+
| EMAIL | email |
+-----------------+------------------+
Table 11: Values of the ACTION
property
An ACTION property with value AUDIO or any other not listed in
Table 11 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:
Stepanek Expires 22 November 2025 [Page 29]
Internet-Draft JSCalendar May 2025
BEGIN:VEVENT
BEGIN:VALARM
ACTION:DISPLAY
...
"alerts": {
"a": {
"@type": "Alert",
"action": "display",
"...": ""
}
}
Figure 16: Converting the ACTION property for value DISPLAY
BEGIN:VEVENT
BEGIN:VALARM
ACTION:AUDIO
...
"alerts": {
"a": {
"@type": "Alert",
"iCalComponent": {
"@type": "ICalComponent",
"name": "valarm",
"properties": [
[
"action",
{},
"text",
"AUDIO"
]
]
},
"...": ""
}
}
Figure 17: Converting the ACTION property for value AUDIO
2.3.3. ATTACH
The ATTACH property [RFC5545] (Section 3.8.1.1) in a VEVENT, VTODO,
PARTICIPANT, VLOCATION, or VCALENDAR component converts to a Link
object [jscalendarbis] (Section 1.4.11). The converted object is set
in the "links" property of the Event, Task, Participant, Location, or
Group object.
Stepanek Expires 22 November 2025 [Page 30]
Internet-Draft JSCalendar May 2025
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 MUST 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 | |
+---------+--------------------------+---------------+-------------+
| LABEL | [RFC7986], Section 6.4 | title | |
+---------+--------------------------+---------------+-------------+
| LINKREL | [RFC9253], Section 6.1 | rel | See remarks |
| | | | below |
+---------+--------------------------+---------------+-------------+
| SIZE | [RFC8607], Section 4.1 | size | |
+---------+--------------------------+---------------+-------------+
Table 12: Parameters of the ATTACH property
Remarks:
* The LINKREL parameter value is defined to be either an URI or an
"iana-token" [RFC5545] (Section 3.1). Only parameter values of
form "iana-token" convert to the "rel" property of the Link
object. The values convert to lowercase.
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 18: Converting the ATTACH property with URI value
ATTACH;ENCODING=BASE64;VALUE=BINARY;FMTTYPE=image/png:iVBORw
0KGgoAAAANSUhEUgAAAAEAAAABAQAAAAA3bvkkAAAAAmJLR0QAAd2KE6QAA
AAKSURBVAjXY2gAAACCAIHdQ2r0AAAAAElFTkSuQmCC
Stepanek Expires 22 November 2025 [Page 31]
Internet-Draft JSCalendar May 2025
"links": {
"a": {
"@type": "Link",
"href": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABAQAAAAA3bvkkAAAAAmJLR0QAAd2KE6QAAAAKSURBVAjXY2gAAACCAIHdQ2r0AAAAAElFTkSuQmCC",
"contentType": "image/png",
"...": ""
}
}
Figure 19: 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 [jscalendarbis]
(Section 4.4.6). The converted object is set in the "participants"
property of the Event or Task object. The property value converts to
the calendarAddress property of the Participant object.
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. How to deal
with conflicting values is implementation-specific.
The ATTENDEE property parameters convert as follows:
Stepanek Expires 22 November 2025 [Page 32]
Internet-Draft JSCalendar May 2025
+================+================+======================+======+
| Name | Reference | Participant Property | Note |
+================+================+======================+======+
| 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 | | |
+----------------+----------------+----------------------+------+
| EMAIL | [RFC7986], | email | |
| | Section 6.2 | | |
+----------------+----------------+----------------------+------+
| MEMBER | [RFC5545], | memberOf | |
| | Section 3.2.11 | | |
+----------------+----------------+----------------------+------+
| PARTSTAT | [RFC5545], | participationStatus | |
| | Section 3.2.12 | | |
+----------------+----------------+----------------------+------+
| ROLE | [RFC5545], | roles | |
| | Section 3.2.16 | | |
+----------------+----------------+----------------------+------+
| RSVP | [RFC5545], | expectReply | |
| | Section 3.2.17 | | |
+----------------+----------------+----------------------+------+
| SENT-BY | [RFC5545], | sentBy | |
| | Section 3.2.18 | | |
+----------------+----------------+----------------------+------+
Table 13: Parameters of the ATTENDEE property
If no ROLE parameter is set, then the "attendee" role in the "roles"
property MUST be set.
The PARTSTAT of an ATTENDEE property in a VTODO component converts
not only to the "participationStatus" property of the Participant
object, but also to its progress property if the PARTSTAT parameter
value is specific for VTODO components:
Stepanek Expires 22 November 2025 [Page 33]
Internet-Draft JSCalendar May 2025
+==============+================+=====================+============+
| PARTSTAT | Reference | participationStatus | progress |
+==============+================+=====================+============+
| NEEDS-ACTION | [RFC5545], | needs-action | |
| | Section 3.2.12 | | |
+--------------+----------------+---------------------+------------+
| ACCEPTED | [RFC5545], | accepted | |
| | Section 3.2.12 | | |
+--------------+----------------+---------------------+------------+
| DECLINED | [RFC5545], | declined | |
| | Section 3.2.12 | | |
+--------------+----------------+---------------------+------------+
| TENTATIVE | [RFC5545], | tentative | |
| | Section 3.2.12 | | |
+--------------+----------------+---------------------+------------+
| DELEGATED | [RFC5545], | delegated | |
| | Section 3.2.12 | | |
+--------------+----------------+---------------------+------------+
| COMPLETED | [RFC5545], | accepted | completed |
| | Section 3.2.12 | | |
+--------------+----------------+---------------------+------------+
| IN-PROCESS | [RFC5545], | accepted | in-process |
| | Section 3.2.12 | | |
+--------------+----------------+---------------------+------------+
| FAILED | [ical-tasks], | accepted | failed |
| | Section 11.1 | | |
+--------------+----------------+---------------------+------------+
Table 14: Converting the PARTSTAT parameter in a VTODO component
to Participant properties
The following examples illustrate how to convert the ATTENDEE
property:
ATTENDEE;RSVP=TRUE;PARTSTAT=TENTATIVE;CN=Henry Cabot:mailto:hcabot@example.com
ORGANIZER:mailto:organizer@example.com
Stepanek Expires 22 November 2025 [Page 34]
Internet-Draft JSCalendar May 2025
"participants": {
"p3": {
"@type": "Participant",
"calendarAddress": "mailto:hcabot@example.com",
"name": "Henry Cabot",
"participationStatus": "tentative",
"roles": {
"attendee": true
},
"expectReply": true
},
"o4": {
"@type": "Participant",
"calendarAddress": "mailto:organizer@example.com",
"roles": {
"owner": true
}
}
},
"organizerCalendarAddress": "mailto:organizer@example.com"
Figure 20: Converting the ATTENDEE property
BEGIN:PARTICIPANT
CALENDAR-ADDRESS:mailto:foo@example.com
DESCRIPTION:some description
...
END:PARTICIPANT
ATTENDEE;RSVP=TRUE;PARTSTAT=TENTATIVE:mailto:foo@example.com
ORGANIZER:mailto:organizer@example.com
"participants": {
"23": {
"@type": "Participant",
"calendarAddress": "mailto:foo@example.com",
"participationStatus": "tentative",
"expectReply": true,
"description": "some description",
"...": ""
},
"o4": {
"@type": "Participant",
"calendarAddress": "mailto:organizer@example.com",
"...": ""
}
},
"organizerCalendarAddress": "mailto:organizer@example.com"
Figure 21: Converting the ATTENDEE property and PARTICIPANT component
Stepanek Expires 22 November 2025 [Page 35]
Internet-Draft JSCalendar May 2025
BEGIN:VTODO
ATTENDEE;RSVP=TRUE;PARTSTAT=COMPLETED:mailto:foo@example.com
ORGANIZER:mailto:organizer@example.com
...
"@type": "Task",
"participants": {
"1": {
"@type": "Participant",
"calendarAddress": "mailto:foo@example.com",
"participationStatus": "accepted",
"progress": "completed",
"expectReply": true,
"...": ""
},
"o": {
"@type": "Participant",
"calendarAddress": "mailto:organizer@example.com",
"...": ""
}
},
"organizerCalendarAddress": "mailto:organizer@example.com"
Figure 22: Converting the ATTENDEE property with a VTODO-specific
participation status
2.3.5. CALENDAR-ADDRESS
The CALENDAR-ADDRESS property [RFC9073] (Section 6.4) in a
PARTICIPANT component converts to the "calendarAddress" property
[jmap-calendars] (Section 5.1.1) of the Participant object.
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
Stepanek Expires 22 November 2025 [Page 36]
Internet-Draft JSCalendar May 2025
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
[jscalendarbis] (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 [jscalendarbis]
(Section 4.4.3) of the Event or Task object.
Its values convert as follows:
+=================+==================+
| iCalendar value | JSCalendar value |
+=================+==================+
| PUBLIC | public |
+-----------------+------------------+
| PRIVATE | private |
+-----------------+------------------+
| CONFIDENTIAL | secret |
+-----------------+------------------+
Table 15: 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.
Stepanek Expires 22 November 2025 [Page 37]
Internet-Draft JSCalendar May 2025
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 [jscalendarbis]
(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. CONCEPT
The CONCEPT property [RFC9253] (Section 8.1) in a VEVENT, VTODO, or
VCALENDAR component converts to the "categories" property
[jscalendarbis] (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.
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 28: Converting the CONCEPT property
Stepanek Expires 22 November 2025 [Page 38]
Internet-Draft JSCalendar May 2025
2.3.10. CONFERENCE
The CONFERENCE property [RFC7986] (Section 5.11) in a VEVENT or VTODO
component converts to a VirtualLocation object [jscalendarbis]
(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.
The CONFERENCE property and a VCONFERENCE component convert to the
same VirtualLocation, if the CONFERENCE property value matches the
URI property value of the VCONFERENCE component. Also see
Section 2.2.3.
Its parameters convert as follows:
+=========+========================+==========+======+
| Name | Reference | Property | Note |
+=========+========================+==========+======+
| FEATURE | [RFC7986], Section 6.3 | features | |
+---------+------------------------+----------+------+
| LABEL | [RFC7986], Section 6.4 | name | |
+---------+------------------------+----------+------+
Table 16: Parameters of the CONFERENCE property
The following example illustrates how to convert the CONFERENCE
property:
CONFERENCE;VALUE=URI;FEATURE=AUDIO,VIDEO;
LABEL="Web video chat, access code=76543"
:https://chat.example.com/audio?id=123456
"virtualLocations": {
"b2": {
"@type": "VirtualLocation",
"name": "Web video chat, access code=76543",
"uri": "https://chat.example.com/audio?id=123456",
"features": {
"audio": true,
"video": true
}
}
}
Figure 29: Converting the CONFERENCE property
Stepanek Expires 22 November 2025 [Page 39]
Internet-Draft JSCalendar May 2025
2.3.11. COORDINATES
The COORDINATES property [icaljscalexts] (Section 4.1) in a VLOCATION
component converts to the "coordinates" property [jscalendarbis]
(Section 4.2.5) of the Location object.
The following example illustrates how to convert the COORDINATES
property:
BEGIN:VEVENT
GEO;DERIVED=TRUE:48.198634;16.371648
BEGIN:VLOCATION
COORDINATES;VALUE=URI:geo:48.198634,16.371648;crs=wgs84;u=40
...
"locations": {
"1": {
"@type": "Location",
"coordinates": "geo:48.198634,16.371648;crs=wgs84;u=40",
"...": ""
}
}
Figure 30: Converting the COORDINATES 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
[jscalendarbis] (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 31: Converting the CREATED property
2.3.13. DESCRIPTION
The DESCRIPTION property [RFC5545] (Section 3.8.1.5) in a VEVENT,
VTODO, VCALENDAR, VLOCATION, or PARTICIPANT component converts to the
"description" property [jscalendarbis] (Section 4.2.2) of the Event,
Task, Group, Location, Link, or Participant object, unless its
DERIVED parameter value is TRUE.
Stepanek Expires 22 November 2025 [Page 40]
Internet-Draft JSCalendar May 2025
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).
If the LANGUAGE parameter is set and the DESCRIPTION property is set
in a VEVENT or VTODO component, then the parameter value converts to
the "locale" property of the Event or Task object, unless the SUMMARY
property in the same component has the LANGUAGE parameter set.
If the LANGUAGE parameter is set and the DESCRIPTION property is set
in a VCALENDAR component, then the parameter value converts to the
"locale" property of the Group object, unless the NAME property in
the same component has the LANGUAGE parameter set.
The following example illustrates how to convert the DESCRIPTION
property:
DESCRIPTION:Their pancakes are delicious\; they are fluffy and sweet.
"description": "Their pancakes are delicious; they are fluffy and sweet."
Figure 32: 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 [jscalendarbis] (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 it converts to the
"endTimeZone" property of the Event.
Implementations MAY preserve the fact that the duration got
determined by the DTEND property. How to do this depends on the
timezone identifiers of the DTSTART and DTEND properties: If the time
zone identifiers are not equal, then the presence of the
"endTimeZone" property implies that it converted from the DTEND
property. If the time zone identifiers are equal, then
implementations MAY 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".
Stepanek Expires 22 November 2025 [Page 41]
Internet-Draft JSCalendar May 2025
The following examples illustrate how to convert the DTEND property:
DTSTART;TZID=Europe/Berlin:20241017T130000
DTEND;TZID=Asia/Bangkok:20241018T040000
"start": "2024-10-17T13:00:00",
"timeZone": "Europe/Berlin",
"duration": "PT10H",
"endTimeZone": "Asia/Bangkok"
Figure 33: Converting the DTEND property with different timezone
DTSTART;TZID=Australia/Melbourne:20241002T130000
DTEND;TZID=Australia/Melbourne:20241002T140000
"start": "2024-10-02T13:00:00",
"timeZone": "Australia/Melbourne",
"duration": "PT1H",
"iCalComponent": {
"@type": "ICalComponent",
"name": "vevent",
"convertedProperties": {
"duration": {
"@type": "ICalProperty",
"name": "dtend"
}
}
}
Figure 34: Converting the DTEND property with same timezone
DTSTART;VALUE=DATE:20240102
DTEND;VALUE=DATE:20240107
"start": "2024-01-02T00:00:00",
"timeZone": null,
"duration": "P5D",
"showWithoutTime": true,
"iCalComponent": {
"@type": "ICalComponent",
"name": "vevent",
"convertedProperties": {
"duration": {
"@type": "ICalProperty",
"name": "dtend"
}
}
}
Figure 35: Converting the DTEND property with DATE value type
Stepanek Expires 22 November 2025 [Page 42]
Internet-Draft JSCalendar May 2025
2.3.15. DTSTAMP
The DTSTAMP property [RFC5545] (Section 3.8.7.2) in a VEVENT or VTODO
component converts to the "updated" property [jscalendarbis]
(Section 4.1.6) of the Event or Task 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 36: Converting the DTSTAMP property in a VEVENT component
2.3.16. DTSTART
The DTSTART property [RFC5545] (Section 3.8.2.4) in a VEVENT or VTODO
component converts to the "start" property [jscalendarbis]
(Section 4.7.2) of the Event or Task object.
See Section 2.1.5 how to convert DATE and DATE-TIME values.
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 [jscalendarbis] (Section 4.2.4) is "true".
The following examples illustrate how to convert the DTSTART property
for the VEVENT and VTODO components.
DTSTART;TZID=Europe/Berlin:20240921T105302
Stepanek Expires 22 November 2025 [Page 43]
Internet-Draft JSCalendar May 2025
"start": "2024-09-21T10:53:02",
"timeZone": "Europe/Berlin",
"showWithoutTime": false
Figure 37: Converting the DTSTART property with TZID parameter
DTSTART:20240921T105302Z
"start": "2024-09-21T10:53:02",
"timeZone": "Etc/UTC",
"showWithoutTime": false
Figure 38: Converting the DTSTART property with UTC time
DTSTART:20240921T105302
"start": "2024-09-21T10:53:02",
"timeZone": null,
"showWithoutTime": false
Figure 39: Converting the DTSTART property with floating time
DTSTART;VALUE=DATE:20240921
"start": "2024-09-21T00:00:00",
"timeZone": null,
"showWithoutTime": true
Figure 40: 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 [jscalendarbis] (Section 5.2.1) of the
Task object.
See Section 2.1.5 how to convert DATE and DATE-TIME values.
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 it contains both the
DUE and DTSTART properties and the timezone identifier of the DUE
property differs from that of the DTSTART property, then the "due"
date-time property value MUST be relative to the time zone of
DTSTART.
If the value type of the DUE property is DATE, then the value of the
"showWithoutTime" property [jscalendarbis] (Section 4.2.4) is "true".
The following examples illustrate how to convert the DUE property:
Stepanek Expires 22 November 2025 [Page 44]
Internet-Draft JSCalendar May 2025
BEGIN:VTODO
DUE;TZID=Europe/Berlin:20240921T105302
"@type": "Task",
"due": "2024-09-21T10:53:02",
"timeZone": "Europe/Berlin",
"showWithoutTime": false
Figure 41: Converting the DUE property with TZID parameter
BEGIN:VTODO
DUE:20240921T105302Z
"@type": "Task",
"due": "2024-09-21T10:53:02",
"timeZone": "Etc/UTC",
"showWithoutTime": false
Figure 42: Converting the DUE property with UTC time
BEGIN:VTODO
DUE:20240921T105302
"@type": "Task",
"due": "2024-09-21T10:53:02",
"timeZone": null,
"showWithoutTime": false
Figure 43: Converting the DUE property with floating time
BEGIN:VTODO
DUE;VALUE=DATE:20240921
"@type": "Task",
"due": "2024-09-21T00:00:00",
"timeZone": null,
"showWithoutTime": true
Figure 44: Converting the DUE property with value type DATE
BEGIN:VTODO
DTSTART;VALUE=DATE:20250220
DUE;VALUE=DATE:20250221
"@type": "Task",
"start": "2025-02-20T00:00:00",
"due": "2025-02-21T00:00:00",
"showWithoutTime": true
Figure 45: Converting the DUE property with value type DATE in
combination with DTSTART
Stepanek Expires 22 November 2025 [Page 45]
Internet-Draft JSCalendar May 2025
2.3.18. DURATION
The DURATION property [RFC5545] (Section 3.8.2.5) in a VEVENT or
VTODO component converts to the "duration" property [jscalendarbis]
(Section 5.1.2) of the Event or Task object.
The following example illustrates how to convert the DURATION
property:
DURATION:PT1H
"duration": "PT1H"
Figure 46: Converting the DURATION
2.3.19. ESTIMATED-DURATION
The ESTIMATED-DURATION property [ical-tasks] (Section 12.1) in a
VTODO component converts to the "estimatedDuration" property
[jscalendarbis] (Section 5.2.3) of the Task object.
The following example illustrates how to convert the ESTIMATED-
DURATION property:
BEGIN:VTODO
ESTIMATED-DURATION:P2D
"@type": "Task",
"estimatedDuration": "P2D"
Figure 47: Converting the ESTIMATED-DURATION
2.3.20. EXDATE
The EXDATE property [RFC5545] (Section 3.8.5.1) in a VEVENT or VTODO
component converts to a PatchObject value [jscalendarbis]
(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" member to "true" and MUST NOT set any other
property.
The following example illustrates how to convert the EXDATE property:
Stepanek Expires 22 November 2025 [Page 46]
Internet-Draft JSCalendar May 2025
DTSTART:20230101T130000Z
RRULE:FREQ=MONTHLY
EXDATE:20230801T130000Z
"start": "2023-01-01T13:00:00",
"timeZone": "Etc/UTC",
"recurrenceRule": {
"@type": "RecurrenceRule",
"frequency": "monthly"
},
"recurrenceOverrides": {
"2023-08-01T13:00:00": {
"excluded": true
}
}
Figure 48: Converting the EXDATE property
2.3.21. GEO
A GEO property with the DERIVED parameter value "TRUE" does not
convert to JSCalendar. For non-derived GEO properties, the following
rules apply:
The GEO property [RFC5545] (Section 3.8.1.6) in a VEVENT or VTODO
component converts to a Location object [jscalendarbis]
(Section 4.2.5). If the VEVENT or VTODO component also contains the
LOCATION property (Section 2.3.25), then the GEO and LOCATION
properties convert to the same Location object. The converted object
is set in the "locations" property of the Event or Task object.
The GEO property [RFC5545] (Section 3.8.1.6) in a PARTICIPANT
component converts to a Location object [jscalendarbis]
(Section 4.2.5). The converted object is set in the "locations"
property of the Participant object.
The GEO property [RFC5545] (Section 3.8.1.6) in a VLOCATION component
converts to the "coordinates" property [jscalendarbis]
(Section 4.2.5) of the Location object.
The pair of FLOAT values converts to a 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 optional "coord-c" part of the URI
MUST be omitted.
Stepanek Expires 22 November 2025 [Page 47]
Internet-Draft JSCalendar May 2025
Implementations MAY preserve the fact that the Location "coordinates"
property converted from a GEO property. How to do so depends on how
the GEO property converted to a Location object:
* If the GEO property converted from a VLOCATION component, then
implementations MAY add a path to the "coordinates" property in
the "iCalComponent/convertedProperties" property of the Location
object.
* Otherwise, implementations MAY set the "iCalProperty" property of
the Location object. Alternatively they MAY add a "iCalComponent"
property to the object that contains this Location object in its
"locations" property, and point to the "coordinates" property in
the "convertedProperties" property.
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",
"iCalProperty": {
"@type": "ICalProperty",
"name": "geo"
},
"...": ""
}
}
Figure 49: Converting the GEO property in a VEVENT
LOCATION:Taj Mahal
GEO:27.175;78.041944
"locations": {
"2": {
"@type": "Location",
"name": "Taj Mahal",
"coordinates": "geo:27.175,78.041944",
"...": ""
}
}
Figure 50: Converting the GEO and LOCATION properties in a VEVENT
Stepanek Expires 22 November 2025 [Page 48]
Internet-Draft JSCalendar May 2025
BEGIN:VEVENT
BEGIN:VLOCATION
NAME:Eiffel Tower
GEO:48.858222;2.2945
...
"locations": {
"2": {
"@type": "Location",
"name": "Eiffel Tower",
"coordinates": "geo:48.858222,2.2945",
"iCalComponent": {
"@type": "ICalComponent",
"name": "vlocation",
"convertedProperties": {
"coordinates": {
"@type": "ICalProperty",
"name": "geo"
}
}
}
}
}
Figure 51: Converting the GEO property in a VLOCATION
2.3.22. IMAGE
The IMAGE property [RFC7986] (Section 5.10) in a VEVENT, VTODO,
VLOCATION, PARTICIPANT, or VCALENDAR component converts to a Link
object [jscalendarbis] (Section 1.4.11). The converted object is set
in the "links" property of the Event, Task, Location, Participant, or
Group 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:
Stepanek Expires 22 November 2025 [Page 49]
Internet-Draft JSCalendar May 2025
+=========+==========================+=============+======+
| Name | Reference | Property | Note |
+=========+==========================+=============+======+
| DISPLAY | [RFC7986], Section 6.1 | display | |
+---------+--------------------------+-------------+------+
| FMTTYPE | [RFC5545], Section 3.2.8 | contentType | |
+---------+--------------------------+-------------+------+
| LABEL | [RFC7986], Section 6.4 | title | |
+---------+--------------------------+-------------+------+
| LINKREL | [RFC9253], Section 6.1 | rel | |
+---------+--------------------------+-------------+------+
| SIZE | [RFC8607], Section 4.1 | size | |
+---------+--------------------------+-------------+------+
Table 17: Parameters of the IMAGE property
The following example illustrates how to convert the IMAGE property:
IMAGE;VALUE=URI;DISPLAY=BADGE;LABEL=An image;FMTTYPE=image/png:
https://example.com/images/party.png
"links": {
"4": {
"@type": "Link",
"href": "https://example.com/images/party.png",
"display": {
"badge": true
},
"rel": "icon",
"contentType": "image/png",
"title": "An image"
}
}
Figure 52: Converting the IMAGE property
2.3.23. LAST-MODIFIED
The LAST-MODIFIED property [RFC5545] (Section 3.8.7.3) in a VCALENDAR
component converts to the "updated" property [jscalendarbis]
(Section 4.1.6) of the Group object.
The LAST-MODIFIED property [RFC5545] (Section 3.8.7.3) in a VEVENT or
VTODO component does _not_ convert to the "updated" property
[jscalendarbis] (Section 4.1.6) of the Event or Task object.
Implementations MAY instead preserve the LAST-MODIFIED property in
the "iCalComponent" property.
Stepanek Expires 22 November 2025 [Page 50]
Internet-Draft JSCalendar May 2025
The following example illustrates how to convert the LAST-MODIFIED
property:
BEGIN:VCALENDAR
LAST-MODIFIED:20240914T231257Z
...
"@type": "Group",
"updated": "2024-09-14T23:12:57Z"
Figure 53: Converting the IMAGE property
2.3.24. LINK
A LINK property [RFC9253] (Section 8.2) with value type URI in a
VEVENT, VTODO, PARTICIPANT, VLOCATION, or VCALENDAR component
converts to a Link object [jscalendarbis] (Section 1.4.11). The
converted object is set in the "links" property of the Event, Task,
Participant, Location, or Group object.
The property value converts to the "href" property of the Link
object.
The LINK property parameters convert as follows:
+=========+==========================+===============+=============+
| Name | Reference | Link Property | Note |
+=========+==========================+===============+=============+
| FMTTYPE | [RFC5545], Section 3.2.8 | contentType | |
+---------+--------------------------+---------------+-------------+
| LABEL | [RFC7986], Section 6.4 | title | |
+---------+--------------------------+---------------+-------------+
| LINKREL | [RFC9253], Section 6.1 | rel | See remarks |
| | | | below |
+---------+--------------------------+---------------+-------------+
Table 18: Parameters of the LINK property
Remarks:
* The LINKREL parameter value is defined to be either an URI or an
"iana-token" [RFC5545] (Section 3.1). Only parameter values of
form "iana-token" convert to the "rel" property of the Link
object. The values convert to lowercase.
A LINK property with any other value type does not convert to a
standard JSCalendar element. Implementations MAY convert it to the
"iCalComponent" property (Section 5.1.1).
Stepanek Expires 22 November 2025 [Page 51]
Internet-Draft JSCalendar May 2025
The following example illustrates how to convert the LINK property:
LINK;LINKREL=source;LABEL=Venue;VALUE=URI:
https://example.com/events
"links": {
"a": {
"@type": "Link",
"href": "https://example.com/events",
"title": "Venue",
"rel": "source"
}
}
Figure 54: Converting the LINK property
2.3.25. LOCATION
The LOCATION property [RFC5545] (Section 3.8.1.7) in a VEVENT or
VTODO component converts to a Location object [jscalendarbis]
(Section 4.2.5), unless its DERIVED parameter value is TRUE. The
converted object is set in the "locations" property of the Event or
Task. 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 convert to a Location object.
If the calendar component contains multiple VLOCATION components,
then the LOCATION property also converts to the "mainLocationId"
property of the Event or Task object. If the LOCATION property is
not derived, then the identifier of its Location object is set in the
"mainLocationId". If instead the LOCATION property is derived and
its property value matches the NAME property value of a VLOCATION
component, then the "mainLocationId" property value matches the
identifier of the Location object to which that VLOCATION component
converts to.
The following example illustrates how to convert the LOCATION
property:
LOCATION:Conference Room - F123\, Bldg. 002
"locations": {
"f45": {
"@type": "Location",
"name": "Conference Room - F123, Bldg. 002",
"...": ""
}
}
Stepanek Expires 22 November 2025 [Page 52]
Internet-Draft JSCalendar May 2025
Figure 55: Converting the LOCATION property
The following example illustrates how to convert the LOCATION
property and multiple VLOCATION components:
LOCATION;DERIVED=TRUE:Fred's Bar
BEGIN:VLOCATION
JSID:1
NAME:Fred's Bar
LOCATION-TYPE:bar
...
END:VLOCATION
BEGIN:VLOCATION
JSID:2
NAME:XYZ Parking
LOCATION-TYPE:parking
GEO:40.71427;-74.00597
...
END:VLOCATION
"locations": {
"1": {
"@type": "Location",
"name": "Fred's Bar",
"...": ""
},
"2": {
"@type": "Location",
"name": "XYZ Parking",
"...": ""
}
},
"mainLocationId": "1"
Figure 56: Converting the LOCATION property and multiple
VLOCATION components
2.3.26. LOCATION-TYPE
The LOCATION-TYPE property [RFC9073] (Section 6.1) in a VLOCATION
component converts to the "locationTypes" property [jscalendarbis]
(Section 4.2.5) of the Location object.
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.
Stepanek Expires 22 November 2025 [Page 53]
Internet-Draft JSCalendar May 2025
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 57: 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 [jscalendarbis]
(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
...
{
"@type": "Group",
"entries": [
{
"@type": "Event",
"method": "request",
"...": ""
}
],
"...": ""
}
Stepanek Expires 22 November 2025 [Page 54]
Internet-Draft JSCalendar May 2025
Figure 58: Converting the METHOD property
2.3.28. NAME
The NAME property [RFC7986] (Section 5.1) in a VLOCATION component
converts to the "name" property of the Location [jscalendarbis]
(Section 4.2.5) or Participant [jscalendarbis] (Section 4.4.6)
object.
The NAME property [RFC7986] (Section 5.1) in a VCALENDAR component
converts to the "title" property [jscalendarbis] (Section 4.2.1) of
the Group object. If the LANGUAGE parameter is set, then the
parameter value converts to the "locale" property [jscalendarbis]
(Section 4.2.9) of the same object.
The following examples illustrate how to convert the NAME property:
BEGIN:VCALENDAR
NAME;LANGUAGE=de:Feiertage Deutschland 2025
...
{
"@type": "Group",
"title": "Feiertage Deutschland 2025",
"locale": "de",
"...": ""
}
Figure 59: Converting the NAME property in a VCALENDAR component
BEGIN:VEVENT
BEGIN:VLOCATION
NAME:Room B
...
END:VLOCATION
...
"locations": {
"1": {
"@type": "Location",
"name": "Room B",
"iCalComponent": {
"@type": "ICalComponent",
"name": "vlocation"
}
}
}
Figure 60: Converting the NAME property in the VLOCATION component
Stepanek Expires 22 November 2025 [Page 55]
Internet-Draft JSCalendar May 2025
2.3.29. ORGANIZER
The ORGANIZER property [RFC5545] (Section 3.8.4.3) in a VEVENT or
VTODO component converts to the "organizerCalendarAddress" property
[jscalendarbis] (Section 4.4.4) of the Event or Task object and to a
Participant object in the "participants" property [jscalendarbis]
(Section 4.4.6). The ORGANIZER property value converts to the
"calendarAddress" property of the Participant, the "owner" role is
set in Participant "roles" property.
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. How to deal with conflicting property values is
implementation-specific.
The ORGANIZER property parameters convert as follows:
+======+==========================+==========+======+
| Name | Reference | Property | Note |
+======+==========================+==========+======+
| CN | [RFC5545], Section 3.2.2 | name | |
+------+--------------------------+----------+------+
| DIR | [RFC5545], Section 3.2.6 | links | |
+------+--------------------------+----------+------+
Table 19: 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
Stepanek Expires 22 November 2025 [Page 56]
Internet-Draft JSCalendar May 2025
"organizerCalendarAddress": "mailto:foo@example.com",
"participants": {
"a": {
"@type": "Participant",
"calendarAddress": "mailto:foo@example.com",
"roles": {
"owner": true
}
},
"b": {
"@type": "Participant",
"calendarAddress": "mailto:bar@example.com",
"expectReply": true,
"...": ""
}
}
Figure 61: 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
"organizerCalendarAddress": "mailto:foo@example.com",
"participants": {
"a": {
"@type": "Participant",
"calendarAddress": "mailto:foo@example.com",
"name": "Jane Doe",
"participationStatus": "accepted",
"roles": {
"attendee": true,
"owner": true
},
"expectReply": false
},
"b": {
"@type": "Participant",
"calendarAddress": "mailto:bar@example.com",
"expectReply": true,
"...": ""
}
}
Figure 62: Converting an ORGANIZER and ATTENDEE property
Stepanek Expires 22 November 2025 [Page 57]
Internet-Draft JSCalendar May 2025
2.3.30. PERCENT-COMPLETE
The PERCENT-COMPLETE property [RFC5545] (Section 3.8.1.8) in a VTODO
component converts to the "percentComplete" property [jscalendarbis]
(Section 5.2.4) of the Task object.
The following examples illustrate how to convert the PERCENT-COMPLETE
property:
BEGIN:VCALENDAR
BEGIN:VTODO
PERCENT-COMPLETE:53
...
{
"@type": "Group",
"entries": [
{
"@type": "Task",
"percentComplete": 53,
"...": ""
}
],
"...": ""
}
Figure 63: Converting the PERCENT-COMPLETE property in a VEVENT
component
2.3.31. PRIORITY
The PRIORITY property [RFC5545] (Section 3.8.1.9) in a VEVENT or
VTODO component converts to the "priority" property [jscalendarbis]
(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 64: Converting the PRIORITY property
Stepanek Expires 22 November 2025 [Page 58]
Internet-Draft JSCalendar May 2025
2.3.32. PRODID
The PRODID property [RFC5545] (Section 3.7.3) in a VCALENDAR
component converts to the "prodId" property [jscalendarbis]
(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 65: Converting the PRODID property
2.3.33. RDATE
A RDATE property [RFC5545] (Section 3.8.5.2) with value type DATE or
DATE-TIME in a VEVENT or VTODO component converts to a PatchObject
value [jscalendarbis] (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 object. The PatchObject
value MUST be an empty JSON object.
A RDATE property with 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.
Stepanek Expires 22 November 2025 [Page 59]
Internet-Draft JSCalendar May 2025
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",
"recurrenceRule": {
"@type": "RecurrenceRule",
"frequency": "monthly"
},
"recurrenceOverrides": {
"2023-08-05T17:00:00": {}
}
Figure 66: Converting the RDATE property
2.3.34. RECURRENCE-ID
The RECURRENCE-ID property [RFC5545] (Section 3.8.4.4) in a VEVENT or
VTODO component converts to the "recurrenceId" property
[jscalendarbis] (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.35. RELATED-TO
The RELATED-TO property [RFC5545] (Section 3.8.4.5) in a VEVENT,
VTODO, or VALARM component converts to a Relation object
[jscalendarbis] (Section 1.4.10). The converted object is set in the
"relatedTo" property of the Event or Task object [jscalendarbis]
(Section 4.1.3), or the Alert object [jscalendarbis] (Section 4.5.2).
The property value in a VEVENT or VTODO converts as-is to the id of
the Relation object in the "relatedTo" property. The property value
in a VALARM converts to the same value as the id 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.
Stepanek Expires 22 November 2025 [Page 60]
Internet-Draft JSCalendar May 2025
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 67: Converting the RELATED-TO property in a VEVENT
BEGIN:VEVENT
...
BEGIN:VALARM
UID:8297C37D-BA2D-4476-91AE-C1EAA364F8E1
JSID:alert1
TRIGGER:-PT15M
DESCRIPTION:Event reminder
ACTION:DISPLAY
ACKNOWLEDGED:20210302T151514Z
END:VALARM
...
BEGIN:VALARM
UID:DE7B5C34-83FF-47FE-BE9E-FF41AE6DD097
JSID:alert2
TRIGGER;VALUE=DATE-TIME:20210302T152000Z
RELATED-TO;RELTYPE=SNOOZE:8297C37D-BA2D-4476-91AE-C1EAA364F8E1
DESCRIPTION:Event reminder
ACTION:DISPLAY
END:VALARM
...
Stepanek Expires 22 November 2025 [Page 61]
Internet-Draft JSCalendar May 2025
"alerts": {
"alert1": {
"@type": "Alert",
"trigger": {
"@type": "OffsetTrigger",
"offset": "-PT15M"
},
"...": ""
},
"alert2": {
"@type": "Alert",
"trigger": {
"@type": "AbsoluteTrigger",
"when": "2021-03-02T15:20:00Z"
},
"relatedTo": {
"alert1": {
"@type": "Relation",
"relation": {
"snooze": true
}
}
},
"...": ""
}
}
Figure 68: Converting the RELATED-TO property in a VALARM
2.3.36. RRULE
The RRULE property [RFC5545] (Section 3.8.5.3) in a VEVENT or VTODO
component converts to a RecurrenceRule object [jscalendarbis]
(Section 4.3.3). The converted object is set in the "recurrenceRule"
property of the Event or Task object.
The RECUR value type converts to a RecurrenceRule object as follows:
Stepanek Expires 22 November 2025 [Page 62]
Internet-Draft JSCalendar May 2025
+==================+=========================+
| 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 20: 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 object.
The following example illustrates how to convert the RRULE property:
Stepanek Expires 22 November 2025 [Page 63]
Internet-Draft JSCalendar May 2025
DTSTART;TZID=Europe/Berlin:20240101T010000
RRULE:FREQ=YEARLY
;INTERVAL=2
;BYMONTH=1
;BYDAY=SU
;BYHOUR=8,9
;BYMINUTE=30
;UNTIL=20240930T120000Z
"recurrenceRule": {
"@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 69: Example for converting the RRULE property
2.3.37. SEQUENCE
The SEQUENCE property [RFC5545] (Section 3.8.7.4) in a VEVENT or
VTODO component converts to the "sequence" property [jscalendarbis]
(Section 4.1.7) of the Event or Task object.
The following example illustrates how to convert the SEQUENCE
property:
SEQUENCE:3
"sequence": 3
Figure 70: Example for converting the SEQUENCE property
Stepanek Expires 22 November 2025 [Page 64]
Internet-Draft JSCalendar May 2025
2.3.38. SHOW-WITHOUT-TIME
The SHOW-WITHOUT-TIME property [icaljscalexts] (Section 4.2) in a
VEVENT or VTODO component converts to the "showWithoutTime" property
[jscalendarbis] (Section 4.2.4) of the Event or Task object. As
outlined in the definition of the SHOW-WITHOUT-TIME property, the
property MUST be ignored if the temporal value type of the VEVENT or
VTODO component is DATE, or if the property value is "FALSE".
The following example illustrates how to convert the SHOW-WITHOUT-
TIME property:
DTSTART;TZID=America/Chicago:20250521T080000
DURATION:PT12H
SHOW-WITHOUT-TIME;VALUE=BOOLEAN:TRUE
"start": "2025-05-21T08:00:00",
"timeZone": "America/Chicago",
"duration": "PT12H",
"showWithoutTime": true
Figure 71: Example for converting the SHOW-WITHOUT-TIME property
2.3.39. STATUS
The STATUS property [RFC5545] (Section 3.8.1.11) in a VEVENT
component converts to the "status" property [jscalendarbis]
(Section 5.1.3) of the Event object. The STATUS property in a VTODO
component converts to the "progress" property [jscalendarbis]
(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 72: Example for converting the STATUS property in a VEVENT
component
BEGIN:VTODO
STATUS:IN-PROCESS
...
{
"@type": "Task",
"progress": "in-process",
"...": ""
}
Stepanek Expires 22 November 2025 [Page 65]
Internet-Draft JSCalendar May 2025
Figure 73: Example for converting the STATUS property in a VTODO
component
2.3.40. SOURCE
The SOURCE property [RFC7986] (Section 5.8) in a VCALENDAR component
converts to the "source" property [jscalendarbis] (Section 5.3.2) of
the Group object.
The following example illustrates how to convert the SOURCE property:
BEGIN:VCALENDAR
SOURCE;VALUE=URI:https://example.com/holidays.ics
...
{
"@type": "Group",
"source": "https://example.com/holidays.ics",
"...": ""
}
Figure 74: Example for converting the SOURCE property
2.3.41. STYLED-DESCRIPTION
The STYLED-DESCRIPTION property [RFC9073] (Section 6.5) in a
PARTICIPANT, VLOCATION, VEVENT or VTODO component converts to the
"description" property [jscalendarbis] (Section 4.2.2) of the
Participant, Location, Event or Task object under the following
conditions:
* The property value type MUST be TEXT.
* The FMTTYPE parameter either MUST 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 value is
TRUE, then another property in the same component is expected to
contain the description.
If these conditions are not met, implementations MAY preserve the
property in the "iCalComponent" property (Section 5.1.1).
If the LANGUAGE parameter is set and the STYLED-DESCRIPTION property
is set in a VEVENT or VTODO component, then the parameter value
converts to the "locale" property of the Event or Task object, unless
the SUMMARY or DESCRIPTION properties in the same component have the
LANGUAGE parameter set.
Stepanek Expires 22 November 2025 [Page 66]
Internet-Draft JSCalendar May 2025
Its parameters convert as follows:
+=========+===============+========================+======+
| Name | Reference | Property | Note |
+=========+===============+========================+======+
| FMTTYPE | [RFC5545], | descriptionContentType | |
| | Section 3.2.8 | | |
+---------+---------------+------------------------+------+
Table 21: Parameters of the STYLED-DESCRIPTION property
The following example illustrates how to convert the STYLED-
DESCRIPTION property:
STYLED-DESCRIPTION;VALUE=TEXT;FMTTYPE=text/html:
hello\,world
"description": "hello,world",
"descriptionContentType": "text/html"
Figure 75: Converting the STYLED-DESCRIPTION property
2.3.42. SUMMARY
The SUMMARY property [RFC5545] (Section 3.8.1.12) in a VEVENT or
VTODO component converts to the "title" property [jscalendarbis]
(Section 4.2.1) of the Event or Task object. If the LANGUAGE
parameter is set, then the parameter value converts to the "locale"
property [jscalendarbis] (Section 4.2.9) of the same object.
The SUMMARY property [RFC5545] (Section 3.8.1.12) in a PARTICIPANT
component converts to the "name" property [jscalendarbis]
(Section 4.2.5).
The following examples illustrate how to convert the SUMMARY
property:
SUMMARY:Birthday Party
"title": "Birthday Party"
Figure 76: Converting the SUMMARY property in a VEVENT
SUMMARY;LANGUAGE=fr:Fête d'anniversaire
"title": "Fête d'anniversaire",
"locale": "fr"
Figure 77: Converting the SUMMARY property with LANGUAGE
parameter in a VEVENT
Stepanek Expires 22 November 2025 [Page 67]
Internet-Draft JSCalendar May 2025
BEGIN:VEVENT
BEGIN:PARTICIPANT
SUMMARY:John
...
"participants": {
"1": {
"@type": "Participant",
"name": "John",
"...": ""
}
}
Figure 78: Converting the SUMMARY property in a PARTICIPANT
2.3.43. TRANSP
The TRANSP property [RFC5545] (Section 3.8.2.7) in a VEVENT or VTODO
component converts to the "freeBusyStatus" property [jscalendarbis]
(Section 4.4.2) of the Event or Task object.
Its values convert as follows:
+=================+==================+
| iCalendar value | JSCalendar value |
+=================+==================+
| OPAQUE | busy |
+-----------------+------------------+
| TRANSPARENT | free |
+-----------------+------------------+
Table 22: Values of the TRANSP
property
The following example illustrates how to convert the TRANSP property:
TRANSP:TRANSPARENT
"freeBusyStatus": "free"
Figure 79: Converting the TRANSP property
2.3.44. 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
[jscalendarbis] (Section 4.5.2) of the Alert object.
Stepanek Expires 22 November 2025 [Page 68]
Internet-Draft JSCalendar May 2025
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 23: Parameters of the TRIGGER property
The following examples illustrate how to convert the TRIGGER
property:
BEGIN:VEVENT
...
BEGIN:VALARM
TRIGGER;RELATED=END:PT5M
...
"alerts": {
"2d": {
"@type": "Alert",
"trigger": {
"@type": "OffsetTrigger",
"offset": "PT5M",
"relativeTo": "end"
},
"...": ""
}
}
Figure 80: Converting the TRIGGER property to an OffsetTrigger
BEGIN:VEVENT
...
BEGIN:VALARM
TRIGGER;VALUE=DATE-TIME:20250302T010203Z
...
Stepanek Expires 22 November 2025 [Page 69]
Internet-Draft JSCalendar May 2025
"alerts": {
"14": {
"@type": "Alert",
"trigger": {
"@type": "AbsoluteTrigger",
"when": "2025-03-02T01:02:03Z"
},
"...": ""
}
}
Figure 81: Converting the TRIGGER property to an AbsoluteTrigger
2.3.45. UID
The UID property [RFC5545] (Section 3.8.4.7) in a VEVENT, VTODO, or
VCALENDAR component converts to the "uid" property [jscalendarbis]
(Section 4.1.2) of the Event, Task, or Group object.
The following example illustrates how to convert the UID property:
UID:5ACEA86F-40CF-47EE-9CCA-7C85588A589F
"uid": "5ACEA86F-40CF-47EE-9CCA-7C85588A589F"
Figure 82: Converting the UID property
3. Converting JSCalendar to iCalendar
3.1. Alert
The Alert object [jscalendarbis] (Section 4.5.2) converts to a VALARM
component (Section 2.2.2). Its properties convert as follows:
Stepanek Expires 22 November 2025 [Page 70]
Internet-Draft JSCalendar May 2025
+==============+==================+==============+===============+
| Name | Reference | Property (or | See |
| | | other) | |
+==============+==================+==============+===============+
| acknowledged | [jscalendarbis], | ACKNOWLEDGED | Section 2.3.1 |
| | Section 4.5.2 | | |
+--------------+------------------+--------------+---------------+
| action | [jscalendarbis], | ACTION | Section 2.3.2 |
| | Section 4.5.2 | | |
+--------------+------------------+--------------+---------------+
| relatedTo | [jscalendarbis], | RELATED-TO | Section |
| | Section 4.1.3 | | 2.3.35, and |
| | | | remarks below |
+--------------+------------------+--------------+---------------+
| trigger | [jscalendarbis], | TRIGGER | Section |
| | Section 4.5.2 | | 2.3.44 |
+--------------+------------------+--------------+---------------+
Table 24: 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 MAY be set.
Other properties MAY be converted to JSPROP properties
(Section 4.1.2) in the VALARM component.
3.2. Event and Task
The Event object [jscalendarbis] (Section 2.1) converts to a VEVENT
component (Section 2.2.4), the Task object [jscalendarbis]
(Section 2.2) converts to a VTODO component (Section 2.2.6).
The following table defines how to convert properties that are common
to both the Event and Task object types. Table 26 and Table 27 later
in this section define how to convert properties specific to either
Event or Task objects.
+========================+================+============+===========+
|Name |Reference |Property (or|See |
| | |other) | |
+========================+================+============+===========+
|alerts |[jscalendarbis],|VALARM |Alert |
| |Section 4.5.2 |(component) |object |
| | | |(Section |
Stepanek Expires 22 November 2025 [Page 71]
Internet-Draft JSCalendar May 2025
| | | |3.1) |
+------------------------+----------------+------------+-----------+
|categories |[jscalendarbis],|CONCEPT |Section |
| |Section 4.2.10 | |2.3.9 |
+------------------------+----------------+------------+-----------+
|color |[jscalendarbis],|COLOR |Section |
| |Section 4.2.11 | |2.3.8 |
+------------------------+----------------+------------+-----------+
|created |[jscalendarbis],|CREATED |Section |
| |Section 4.1.5 | |2.3.12 |
+------------------------+----------------+------------+-----------+
|description |[jscalendarbis],|DESCRIPTION,|Section |
| |Section 4.2.2 |or STYLED- |2.3.13, |
| | |DESCRIPTION |Section |
| | | |2.3.41, and|
| | | |remarks |
| | | |below |
+------------------------+----------------+------------+-----------+
|descriptionContentType |[jscalendarbis],|FMTTYPE |Section |
| |Section 4.2.3 |(parameter) |2.3.41, and|
| | |of STYLED- |remarks |
| | |DESCRIPTION |below |
+------------------------+----------------+------------+-----------+
|freeBusyStatus |[jscalendarbis],|TRANSP |Section |
| |Section 4.4.2 | |2.3.43 |
+------------------------+----------------+------------+-----------+
|keywords |[jscalendarbis],|CATEGORIES |Section |
| |Section 4.2.9 | |2.3.6 |
+------------------------+----------------+------------+-----------+
|links |[jscalendarbis],|ATTACH, or |Link object|
| |Section 4.2.7 |other |(Section |
| | | |3.4) |
+------------------------+----------------+------------+-----------+
|locale |[jscalendarbis],|LANGUAGE |Section |
| |Section 4.2.9 |(parameter) |2.3.42, |
| | |of either |Section |
| | |SUMMARY, or |2.3.13, |
| | |DESCRIPTION,|Section |
| | |or STYLED- |2.3.41 |
| | |DESCRIPTION | |
| | |(in order of| |
| | |preference) | |
+------------------------+----------------+------------+-----------+
|locations |[jscalendarbis],|LOCATION, |Location |
| |Section 4.2.5 |GEO, or |object |
| | |VLOCATION |(Section |
| | |(component) |3.5) |
+------------------------+----------------+------------+-----------+
Stepanek Expires 22 November 2025 [Page 72]
Internet-Draft JSCalendar May 2025
|mainLocationId |[jscalendarbis],|LOCATION |Location |
| |Section 4.2.6 | |object |
| | | |(Section |
| | | |3.5) |
+------------------------+----------------+------------+-----------+
|method |[jscalendarbis],|METHOD of |Section |
| |Section 4.1.8 |iCalendar |2.3.27, and|
| | |object |Group |
| | | |object |
| | | |(Section |
| | | |3.3) |
+------------------------+----------------+------------+-----------+
|organizerCalendarAddress|[jscalendarbis],|ORGANIZER |Section |
| |Section 4.4.4 | |2.3.29 |
+------------------------+----------------+------------+-----------+
|participants |[jscalendarbis],|ATTENDEE, or|Participant|
| |Section 4.4.6 |PARTICIPANT |object |
| | |(component) |(Section |
| | | |3.6) |
+------------------------+----------------+------------+-----------+
|priority |[jscalendarbis],|PRIORITY |Section |
| |Section 4.4.1 | |2.3.31 |
+------------------------+----------------+------------+-----------+
|privacy |[jscalendarbis],|CLASS |Section |
| |Section 4.4.3 | |2.3.7 |
+------------------------+----------------+------------+-----------+
|prodId |[jscalendarbis],|PRODID of |Section |
| |Section 4.1.4 |iCalendar |2.3.32, and|
| | |object |Group |
| | | |object |
| | | |(Section |
| | | |3.3) |
+------------------------+----------------+------------+-----------+
|recurrenceId |[jscalendarbis],|RECURRENCE- |Section |
| |Section 4.3.1 |ID |2.3.34 |
+------------------------+----------------+------------+-----------+
|recurrenceIdTimeZone |[jscalendarbis],|TZID |Section |
| |Section 4.3.2 |(parameter) |2.3.34 |
| | |of | |
| | |RECURRENCE- | |
| | |ID | |
+------------------------+----------------+------------+-----------+
|recurrenceOverrides |[jscalendarbis],|RDATE, |Section |
| |Section 4.3.5 |EXDATE or |2.1.2, and |
| | |recurrence |remarks |
| | |override |below |
| | |component | |
+------------------------+----------------+------------+-----------+
Stepanek Expires 22 November 2025 [Page 73]
Internet-Draft JSCalendar May 2025
|recurrenceRule |[jscalendarbis],|RRULE |Section |
| |Section 4.3.3 | |2.3.36 |
+------------------------+----------------+------------+-----------+
|relatedTo |[jscalendarbis],|RELATED-TO |Section |
| |Section 4.1.3 | |2.3.35 |
+------------------------+----------------+------------+-----------+
|sequence |[jscalendarbis],|SEQUENCE |Section |
| |Section 4.1.7 | |2.3.37 |
+------------------------+----------------+------------+-----------+
|showWithoutTime |[jscalendarbis],|SHOW- |Section |
| |Section 4.2.4 |WITHOUT-TIME|2.3.38, and|
| | | |remarks |
| | | |below |
+------------------------+----------------+------------+-----------+
|start |[jscalendarbis],|DTSTART |Section |
| |Section 4.7.2 | |2.3.16 |
+------------------------+----------------+------------+-----------+
|timeZone |[jscalendarbis],|TZID |Section |
| |Section 4.7.1 |(parameter) |2.3.16, |
| | |of DTSTART |Section |
| | |and DUE |2.3.17 |
+------------------------+----------------+------------+-----------+
|title |[jscalendarbis],|SUMMARY |Section |
| |Section 4.2.1 | |2.3.42 |
+------------------------+----------------+------------+-----------+
|uid |[jscalendarbis],|UID |Section |
| |Section 4.1.2 | |2.3.45 |
+------------------------+----------------+------------+-----------+
|updated |[jscalendarbis],|DTSTAMP, and|Section |
| |Section 4.1.6 |LAST- |2.3.15, |
| | |MODIFIED |Section |
| | | |2.3.23 |
+------------------------+----------------+------------+-----------+
|virtualLocations |[jscalendarbis],|CONFERENCE |Section |
| |Section 4.2.6 | |2.3.10 |
+------------------------+----------------+------------+-----------+
Table 25: Properties of the Event and Task object
Remarks:
Stepanek Expires 22 November 2025 [Page 74]
Internet-Draft JSCalendar May 2025
* The "descriptionContentType" property value determines if the
"description" property converts to the DESCRIPTION or STYLED-
DESCRIPTION property. A description of content type "text/plain"
converts to the DESCRIPTION property. Any other description
converts to the STYLED-DESCRIPTION property, in which case a plain
text version of the rich-text description MAY be set additionally
in the DESCRIPTION property, having its DERIVED parameter set to
"TRUE". How to derive plain text from rich-text is
implementation-specific.
* The entries in the "recurrenceOverrides" property convert
depending on the contents of the PatchObject value. A PatchObject
that sets the "excluded" member to "true" converts to an EXDATE
property for the date-time of that recurrence instance. An empty
PatchObject converts to an RDATE property. Any other PatchObject
converts to a recurrence override component in the embedding
VCALENDAR component.
* The "showWithoutTime" only converts to the SHOW-WITHOUT-TIME
property under the following conditions: the property value is
"true" and either the "timeZone" property value is not null or the
time component is non-zero in the "start", "due" or "duration"
property values.
Properties specific to the Event object type convert to iCalendar
properties as follows:
+=============+==================+================+=================+
| Name | Reference | Property | See |
| | | (or other) | |
+=============+==================+================+=================+
| duration | [jscalendarbis], | DURATION, | Section 2.3.18, |
| | Section 5.1.2 | or DTEND | Section 2.3.14 |
+-------------+------------------+----------------+-----------------+
| endTimeZone | [jscalendarbis], | TZID | Section 2.3.14, |
| | Section 5.1.3 | parameter | Section 2.3.17 |
| | | of DTEND | |
+-------------+------------------+----------------+-----------------+
| status | [jscalendarbis], | STATUS | Section 2.3.39 |
| | Section 5.1.3 | | |
+-------------+------------------+----------------+-----------------+
Table 26: Properties of the Event object
Properties specific to the Task object type convert to iCalendar
properties as follows:
Stepanek Expires 22 November 2025 [Page 75]
Internet-Draft JSCalendar May 2025
+===================+================+=====================+=======+
| Name |Reference | Property (or other) |See |
+===================+================+=====================+=======+
| due |[jscalendarbis],| DUE |Section|
| |Section 5.2.1 | |2.3.17 |
+-------------------+----------------+---------------------+-------+
| estimatedDuration |[jscalendarbis],| ESTIMATED-DURATION |Section|
| |Section 5.2.3 | |2.3.19 |
+-------------------+----------------+---------------------+-------+
| percentComplete |[jscalendarbis],| PERCENT-COMPLETE |Section|
| |Section 5.2.4 | |2.3.30 |
+-------------------+----------------+---------------------+-------+
| progress |[jscalendarbis],| STATUS |Section|
| |Section 5.2.5 | |2.3.39 |
+-------------------+----------------+---------------------+-------+
Table 27: Properties of the Task object
Other properties MAY be converted to JSPROP properties
(Section 4.1.2) in the VEVENT or VTODO component.
3.3. Group
The Group object [jscalendarbis] (Section 2.3) converts to a
VCALENDAR component (Section 2.1.1). Its properties convert as
follows:
+============+==================+================+===============+
| Name | Reference | Property (or | See |
| | | other) | |
+============+==================+================+===============+
| categories | [jscalendarbis], | CONCEPT | Section 2.3.9 |
| | Section 4.2.10 | | |
+------------+------------------+----------------+---------------+
| color | [jscalendarbis], | COLOR | Section 2.3.8 |
| | Section 4.2.11 | | |
+------------+------------------+----------------+---------------+
| created | [jscalendarbis], | CREATED | Section |
| | Section 4.1.5 | | 2.3.12 |
+------------+------------------+----------------+---------------+
| entries | [jscalendarbis], | VEVENT or | Event and |
| | Section 5.3.1 | VTODO | Task object |
| | | (component) | (Section |
| | | | 3.2), and |
| | | | remarks below |
+------------+------------------+----------------+---------------+
| keywords | [jscalendarbis], | CATEGORIES | Section 2.3.6 |
| | Section 4.2.9 | | |
Stepanek Expires 22 November 2025 [Page 76]
Internet-Draft JSCalendar May 2025
+------------+------------------+----------------+---------------+
| links | [jscalendarbis], | ATTACH, or | Link object |
| | Section 4.2.7 | other | (Section 3.4) |
+------------+------------------+----------------+---------------+
| locale | [jscalendarbis], | LANGUAGE | Section |
| | Section 4.2.9 | (parameter) of | 2.3.28, |
| | | either NAME, | Section |
| | | or DESCRIPTION | 2.3.13 |
| | | (in order of | |
| | | preference) | |
+------------+------------------+----------------+---------------+
| prodId | [jscalendarbis], | PRODID | Section |
| | Section 4.1.4 | | 2.3.32, and |
| | | | remarks below |
+------------+------------------+----------------+---------------+
| source | [jscalendarbis], | SOURCE | Section |
| | Section 5.3.2 | | 2.3.40 |
+------------+------------------+----------------+---------------+
| title | [jscalendarbis], | NAME | Section |
| | Section 4.2.1 | | 2.3.28 |
+------------+------------------+----------------+---------------+
| uid | [jscalendarbis], | UID | Section |
| | Section 4.1.2 | | 2.3.45 |
+------------+------------------+----------------+---------------+
| updated | [jscalendarbis], | LAST-MODIFIED | Section |
| | Section 4.1.6 | | 2.3.23 |
+------------+------------------+----------------+---------------+
Table 28: 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.
Other properties MAY be converted to JSPROP properties
(Section 4.1.2) in the VCALENDAR component.
Stepanek Expires 22 November 2025 [Page 77]
Internet-Draft JSCalendar May 2025
3.4. Link
The Link object [jscalendarbis] (Section 1.4.11) converts either an
ATTACH property (Section 2.3.3) or an IMAGE property
(Section 2.3.22). Which iCalendar property to choose is
implementation-specific. As a guideline:
* Choose the iCalendar property name indicated in the Link object's
iCalProperty (Section 5.1.2) property, if set.
* Choose IMAGE, if the "rel" property value is "icon".
* Choose LINK, if the "rel" property is set to any value other than
"icon".
* Choose ATTACH otherwise.
The href property converts to the "iCalendar" property value. The
other Link properties convert as follows:
+=============+==================+============+===================+
| Name | Reference | Parameter | See |
| | | (or other) | |
+=============+==================+============+===================+
| contentType | [jscalendarbis], | FMTTYPE | Section 2.3.3 |
| | Section 1.4.11 | | |
+-------------+------------------+------------+-------------------+
| display | [jscalendarbis], | DISPLAY | Section 2.3.22, |
| | Section 1.4.11 | | and remarks below |
+-------------+------------------+------------+-------------------+
| rel | [jscalendarbis], | LINKREL | Section 6.1 of |
| | Section 1.4.11 | | [RFC9253], and |
| | | | remarks below |
+-------------+------------------+------------+-------------------+
| size | [jscalendarbis], | SIZE | Section 2.3.3 |
| | Section 1.4.11 | | |
+-------------+------------------+------------+-------------------+
| title | [RFC7986], | LABEL | Section 2.3.3 |
| | Section 6.4 | | |
+-------------+------------------+------------+-------------------+
Table 29: Properties of the Link object
Remarks:
* The LINKREL parameter MUST be omitted if the Link object converts
to an IMAGE property and the "rel" property value is "icon".
Stepanek Expires 22 November 2025 [Page 78]
Internet-Draft JSCalendar May 2025
Other properties MAY be converted to JSPROP properties
(Section 4.1.2) in the same component to which the Link object
converts to as a property.
3.5. Location
The Location object [jscalendarbis] (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.5). Which iCalendar element to choose is
implementation-specific. As a guideline:
* If the "iCalProperty" or "iCalComponent" property on the Location
object is set, or the parent JSCalendar object contains an entry
for that Location in the "convertedProperties" property of its
"iCalComponent" property, then convert the object back to the
named iCalendar element.
* Choose LOCATION if the key of the Location object in the
"locations" property matches the "mainLocationId" property, or if
the "name" property is set and the iCalendar component does not
already contain a LOCATION property. The "name" property converts
to the LOCATION property value.
* Choose the VLOCATION component otherwise.
Implementations MAY convert one of the Location objects to both a
VLOCATION component and the LOCATION and GEO properties of the
component that contains the VLOCATION component. In this case, the
DERIVED parameter MUST be set on the LOCATION and GEO properties with
value "TRUE".
The properties convert to a VLOCATION component as follows:
Stepanek Expires 22 November 2025 [Page 79]
Internet-Draft JSCalendar May 2025
+======================+================+==================+========+
|Name |Reference |Property (or |See |
| | |other) | |
+======================+================+==================+========+
|coordinates |[jscalendarbis],|COORDINATES |Section |
| |Section 4.2.5 | |2.3.11, |
| | | |Section |
| | | |2.3.21 |
+----------------------+----------------+------------------+--------+
|description |[jscalendarbis],|DESCRIPTION, or |Section |
| |Section 4.2.5 |STYLED-DESCRIPTION|2.3.13, |
| | | |Section |
| | | |2.3.41 |
+----------------------+----------------+------------------+--------+
|descriptionContentType|[jscalendarbis],|FMTTYPE |Section |
| |Section 4.2.5 |(parameter) of |2.3.41 |
| | |STYLED-DESCRIPTION| |
+----------------------+----------------+------------------+--------+
|links |[jscalendarbis],|ATTACH, or other |Link |
| |Section 4.2.7 | |object |
| | | |(Section|
| | | |3.4) |
+----------------------+----------------+------------------+--------+
|locationTypes |[jscalendarbis],|LOCATION-TYPE |Section |
| |Section 4.2.5 | |2.3.26 |
+----------------------+----------------+------------------+--------+
|name |[jscalendarbis],|NAME |Section |
| |Section 4.2.5 | |2.3.28 |
+----------------------+----------------+------------------+--------+
Table 30: Properties of the Location object
Other properties MAY be converted to JSPROP properties
(Section 4.1.2) in the VLOCATION component, or the component which
the Location converts to as a property.
3.6. Participant
The Participant object [jscalendarbis] (Section 4.4.6) converts to
both an ATTENDEE property (Section 2.3.4) and a PARTICIPANT component
(Section 2.2.1):
* It converts to an ATTENDEE property if the calendarAddress
[jscalendarbis] (Section 4.4.6) property is set.
Stepanek Expires 22 November 2025 [Page 80]
Internet-Draft JSCalendar May 2025
* It converts to a PARTICIPANT component if any of the Participant
properties in Table 32 are set. If the Participant object also
converts to an ATTENDEE property, then the CALENDAR-ADDRESS
property value of the PARTICIPANT component MUST match the
ATTENDEE property value.
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.
Stepanek Expires 22 November 2025 [Page 81]
Internet-Draft JSCalendar May 2025
+=====================+==================+================+=======+
| Name | Reference | Parameter (or |See |
| | | other) | |
+=====================+==================+================+=======+
| calendarAddress | [jscalendarbis], | ATTENDEE |Section|
| | Section 4.4.6 | |2.3.4 |
+---------------------+------------------+----------------+-------+
| delegatedFrom | [jscalendarbis], | DELEGATED-FROM |Section|
| | Section 4.4.6 | |2.3.4 |
+---------------------+------------------+----------------+-------+
| delegatedTo | [jscalendarbis], | DELEGATED-TO |Section|
| | Section 4.4.6 | |2.3.4 |
+---------------------+------------------+----------------+-------+
| email | [jscalendarbis], | EMAIL |Section|
| | Section 4.4.6 | |2.3.4 |
+---------------------+------------------+----------------+-------+
| expectReply | [jscalendarbis], | RSVP |Section|
| | Section 4.4.6 | |2.3.4 |
+---------------------+------------------+----------------+-------+
| kind | [jscalendarbis], | CUTYPE |Section|
| | Section 4.4.6 | |2.3.4 |
+---------------------+------------------+----------------+-------+
| memberOf | [jscalendarbis], | MEMBER |Section|
| | Section 4.4.6 | |2.3.4 |
+---------------------+------------------+----------------+-------+
| name | [jscalendarbis], | CN |Section|
| | Section 4.2.5 | |2.3.4 |
+---------------------+------------------+----------------+-------+
| participationStatus | [jscalendarbis], | PARTSTAT |Section|
| | Section 4.4.6 | |2.3.4 |
+---------------------+------------------+----------------+-------+
| progress | [jscalendarbis], | PARTSTAT |Section|
| | Section 5.2.5 | |2.3.4, |
| | | |and |
| | | |remarks|
| | | |below |
+---------------------+------------------+----------------+-------+
| roles | [jscalendarbis], | ROLE |Section|
| | Section 4.4.6 | |2.3.4 |
+---------------------+------------------+----------------+-------+
| sentBy | [jscalendarbis], | SENT-BY |Section|
| | Section 4.4.6 | |2.3.4 |
+---------------------+------------------+----------------+-------+
Table 31: Properties of the Participant object that convert to
the ATTENDEE property
Remarks:
Stepanek Expires 22 November 2025 [Page 82]
Internet-Draft JSCalendar May 2025
* The "attendee" role does not convert to the ROLE parameter: it
either is implied if the Participant object converts to an
ATTENDEE, otherwise implementations MAY preserve it using the
JSPROP (Section 4.1.2) property. The "owner" role does not
convert to any standard iCalendar element: it either is implied if
the property value of the ATTENDEE is equal to the value of the
ORGANIZER property in the same component, otherwise
implementations MAY preserve it using the JSPROP (Section 4.1.2)
property.
* The progress property converts to the PARTSTAT parameter as
outlined in Table 14.
The following Participant properties convert to the PARTICIPANT
component:
+======================+================+==================+========+
|Name |Reference |Property (or |See |
| | |other) | |
+======================+================+==================+========+
|description |[jscalendarbis],|DESCRIPTION, or |Section |
| |Section 4.4.5 |STYLED-DESCRIPTION|2.3.13, |
| | | |Section |
| | | |2.3.41, |
| | | |and |
| | | |remarks |
| | | |below |
+----------------------+----------------+------------------+--------+
|descriptionContentType|[jscalendarbis],|FMTTYPE |Section |
| |Section 4.4.5 |(parameter) of |2.3.41 |
| | |STYLED-DESCRIPTION| |
+----------------------+----------------+------------------+--------+
|links |[jscalendarbis],|ATTACH, or other |Link |
| |Section 4.2.7 | |object |
| | | |(Section|
| | | |3.4) |
+----------------------+----------------+------------------+--------+
|name |[jscalendarbis],|NAME |Section |
| |Section 4.2.5 | |2.3.28 |
+----------------------+----------------+------------------+--------+
|percentComplete |[jscalendarbis],|PERCENT-COMPLETE |Section |
| |Section 5.2.4 | |2.3.30 |
+----------------------+----------------+------------------+--------+
Table 32: Properties of the Participant object that convert to
the PARTICIPANT component
Stepanek Expires 22 November 2025 [Page 83]
Internet-Draft JSCalendar May 2025
Other properties MAY be converted to JSPROP properties
(Section 4.1.2) in the PARTICIPANT component, or the component which
the Participant converts to as a property.
3.7. VirtualLocation
The VirtualLocation object [jscalendarbis] (Section 4.2.6) converts
to a CONFERENCE property (Section 2.3.10). If the "description"
property is set, then it also converts to a VCONFERENCE component
(Section 2.2.3).
The "uri" property converts to the CONFERENCE property value. If the
VirtualLocation object converts to a VCONFERENCE component, then the
"uri" property also converts to the URI property of the VCONFERENCE
component.
The following properties convert to parameters of the CONFERENCE
property:
+==========+==================+======================+=========+
| Name | Reference | Parameter (or other) | See |
+==========+==================+======================+=========+
| features | [jscalendarbis], | FEATURE | Section |
| | Section 4.2.6 | | 2.3.10 |
+----------+------------------+----------------------+---------+
| name | [jscalendarbis], | LABEL | Section |
| | Section 4.2.5 | | 2.3.10 |
+----------+------------------+----------------------+---------+
Table 33: Properties of the VirtualLocation object
The following properties convert to properties of the VCONFERENCE
component:
Stepanek Expires 22 November 2025 [Page 84]
Internet-Draft JSCalendar May 2025
+=====================+================+==================+=======+
|Name |Reference |Property (or |See |
| | |other) | |
+=====================+================+==================+=======+
|description |[jscalendarbis],|DESCRIPTION, or |Section|
| |Section 4.2.7 |STYLED-DESCRIPTION|2.3.13,|
| | | |Section|
| | | |2.3.41 |
+---------------------+----------------+------------------+-------+
|descriptionContenType|[jscalendarbis],|FMTTYPE |Section|
| |Section 4.2.7 |(parameter) of |2.3.41 |
| | |STYLED-DESCRIPTION| |
+---------------------+----------------+------------------+-------+
Table 34: Properties of the VirtualLocation object
Other properties MAY be converted to JSPROP properties
(Section 4.1.2) of the VCONFERENCE component.
4. Updates to iCalendar
4.1. New Properties
4.1.1. JSID
Property Name:
JSID
Purpose:
This property preserves the identifier of a JSCalendar object
value in iCalendar.
Value type:
TEXT; also see "Format Definition" below for value restrictions.
Property Parameters:
IANA and non-standard property parameters can be specified on this
property.
Conformance:
This property can be specified at most once in any calendar
component.
Description:
Stepanek Expires 22 November 2025 [Page 85]
Internet-Draft JSCalendar May 2025
This property specifies the JSON object key of the JSCalendar
object to which an iCalendar component converts to. For example,
this property set in a VALARM component within a VEVENT component
defines the key of the Alert object value in the Event object's
"alerts" property (see Figure 83).
The value of the JSID property MUST be a valid object key
according to the definition of the JSCalendar property to which
the component converts to.
Format Definition:
This property is defined by the following notation:
jsid-prop = "JSID" *(";" other-param) ":" TEXT CRLF
Example(s):
The following example illustrates how to convert the JSID property
set in a VALARM component.
BEGIN:VEVENT
...
BEGIN:VALARM
JSID:myalert1
...
END:VALARM
"@type": "Event",
"alerts": {
"myalert1": {
"@type": "Alert",
"...": ""
}
}
Figure 83: Converting the JSID property of a VALARM component
4.1.2. JSPROP
Property Name:
JSPROP
Purpose:
This property represents a JSCalendar property in iCalendar.
Value type:
TEXT; also see "Format Definition" below for value restrictions.
Stepanek Expires 22 November 2025 [Page 86]
Internet-Draft JSCalendar May 2025
Property Parameters:
The JSPTR parameter (Section 4.2.2) MUST be specified on this
property. Other IANA and non-standard property parameters can be
specified on this property.
Conformance:
This property can be specified multiple times in any calendar
component.
Description:
This property converts an arbitrary JSCalendar property from and
to iCalendar. The iCalendar property value is the JSON-encoded
value of the JSCalendar property, represented as a TEXT value.
The JSON value MUST NOT be the null value, and it SHOULD NOT
contain insignificant whitespace as defined in Section 2 of
[RFC8259]. The value of the JSPTR parameter points to the
JSCalendar property within the JSCalendar object.
The root of the JSON pointer is always the JSCalendar object to
which the calendar component converts to, even if the JSON pointer
starts with the SOLIDUS (U+002F) character. The pointer MUST NOT
reference into an array.
All JSPROP properties in a calendar component together form a
PatchObject [jscalendarbis] (Section 1.4.9): the JSPTR parameter
of a JSPROP property corresponds to a key in the PatchObject, the
property value corresponds to the JSON value for that key. When
converting from iCalendar to JSCalendar, the PatchObject MUST only
be applied after all other iCalendar elements of the component
have been converted. Only new properties are allowed to be set, a
JSON pointer in the PatchObject that points to an existing
property MUST be ignored.
Format Definition:
This property is defined by the following notation:
Stepanek Expires 22 November 2025 [Page 87]
Internet-Draft JSCalendar May 2025
jsprop = "JSPROP" jsprop-param ":" TEXT CRLF
jsprop-param = *(
; The following are MANDATORY and MUST NOT
; occur more than once
( ";" jsptr-param )
;
; The following is OPTIONAL
; and MAY occur more than once.
;
(";" other-param)
;
)
Example(s):
The following example illustrates how to convert a JSPROP property
with a JSON boolean value
JSPROP;JSPTR="example.com:foo":true
"example.com:foo": true
Figure 84: Converting the JSPROP property with a JSON boolean
value
The following example illustrates how to convert a JSPROP property
with a JSON object value
JSPROP;JSPTR="example.com:foo":{"bar":1234\,"baz":"bam"}
"example.com:foo": {
"bar": 1234,
"baz": "bam"
}
Figure 85: Converting the JSPROP property with a JSON object value
The following example illustrates how to convert a JSPROP property
that points to a property within a JSCalendar Alert. The JSON
pointer in the JSPTR parameter is relative to the Alert object.
BEGIN:VEVENT
...
BEGIN:VALARM
JSPROP;JSPTR="example.com:foo":"bar"
...
END:VALARM
Stepanek Expires 22 November 2025 [Page 88]
Internet-Draft JSCalendar May 2025
"@type": "Event",
"alerts": {
"a1": {
"@type": "Alert",
"example.com:foo": "bar",
"...": ""
}
}
Figure 86: Converting the JSPROP property within a VALARM
component
The following example illustrates how to convert a JSPROP property
that points to a property within a JSCalendar Link. The JSON
pointer in the JSPTR parameter is relative to the Event object
because the Link object converts to an iCalendar property. The
JSID parameter (Section 4.2.1) on the ATTACH property ensures that
the JSON path remains valid during conversion.
BEGIN:VEVENT
...
ATTACH;JSID=mylink1:https://www.rfc-editor.org/rfc/rfc8984.html
JSPROP;JSPTR="links/mylink1/example.com:foo":"bar"
...
"@type": "Event",
"links": {
"mylink1": {
"@type": "Link",
"example.com:foo": "bar",
"...": ""
}
}
Figure 87: Converting the JSPROP property within a VALARM
component
4.2. New Parameters
4.2.1. JSID
Parameter Name:
JSID
Format Definition:
jsid-param = "JSID" "=" param-value
Description:
Stepanek Expires 22 November 2025 [Page 89]
Internet-Draft JSCalendar May 2025
This parameter specifies the JSON object key of the JSCalendar
object to which an iCalendar property converts to. For example,
this parameter set on an ATTACH property within a VEVENT component
defines the key of the Link object value in the Event object's
"links" property (see below for an example).
The value of the JSID parameter MUST be a valid key according to
the definition of the JSCalendar property to which the property
that this parameter is set on converts to. Typically, this
requires the value to be a valid Id [jscalendarbis]
(Section 1.4.1).
Example(s):
ATTACH;JSID=mylink1:https://example.com
"links": {
"mylink1": {
"@type": "Link",
"href": "https://example.com"
}
}
Figure 88: Converting the JSID parameter on an ATTACH property
4.2.2. JSPTR
Parameter Name:
JSPTR
Format Definition:
jsptr-param = "JSPTR" "=" quoted-string
Description:
This parameter is specified on a JSPROP (Section 4.1.2) property.
Its value is a JSON pointer [RFC6901] that points to a JSCalendar
property.
Description:
This parameter has a single value that MUST be a valid JSON
pointer as defined in [RFC6901]. The value MUST be quoted to
preserve its case-sensitivity and it MUST NOT contain the DQUOTE
character. See Section 3.2 of [RFC5545] for how to format
parameter values.
Example(s):
JSPROP;JSPTR="example.com:foo":"bar"
For further examples, see Section 4.1.2.
Stepanek Expires 22 November 2025 [Page 90]
Internet-Draft JSCalendar May 2025
5. Updates to JSCalendar
5.1. New Properties
5.1.1. iCalComponent
Name:
iCalComponent
Context:
Any JSCalendar object
Type:
ICalComponent (optional)
Description
This contains information about an iCalendar component that got
converted to JSCalendar. It allows for preserving 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 which did not convert to standard
JSCalendar elements. 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 [jscalendarbis]. 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
Stepanek Expires 22 November 2025 [Page 91]
Internet-Draft JSCalendar May 2025
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.33).
properties: *[][] (optional) This contains properties of the
iCalendar component which did not convert to standard
JSCalendar elements. The value MUST be a list of iCalendar
properties formatted in jCal as defined in Section 3.4 of
[RFC7265].
The example in Figure 89 describes how to convert unknown iCalendar
elements to the "iCalComponent" property. The "X-FOO" parameter set
on the SUMMARY property illustrates how to preserve an unknown
iCalendar parameter on a property that does convert to a standard
JSCalendar element. The "X-BAR" property and "X-BAZ" component
illustrate how to convert entirely unknown iCalendar elements.
BEGIN:VEVENT
SUMMARY;X-FOO=bar:test
...
X-BAR:bam
...
BEGIN:X-BAZ
UID:507A08F9-81D8-4D16-9480-D6D75E977943
END:X-BAZ
...
Stepanek Expires 22 November 2025 [Page 92]
Internet-Draft JSCalendar May 2025
{
"@type": "Event",
"title": "test",
"iCalComponent": {
"@type": "ICalComponent",
"name": "vevent",
"convertedProperties": {
"title": {
"@type": "ICalProperty",
"name": "summary",
"parameters": {
"x-foo": "bar"
}
}
},
"properties": [
[
"x-bar",
{},
"unknown",
"bam"
]
],
"components": [
[
"x-baz",
[
[
"uid",
{},
"text",
"507A08F9-81D8-4D16-9480-D6D75E977943"
]
],
[]
]
]
},
"...": ""
}
Figure 89: Converting unknown iCalendar elements to the
iCalComponent property
5.1.2. iCalProperty
Name:
iCalProperty
Stepanek Expires 22 November 2025 [Page 93]
Internet-Draft JSCalendar May 2025
Context:
Any JSCalendar object
Type:
ICalProperty (optional)
Description:
This contains conversion-related information about an iCalendar
property that got partially or fully converted to a JSCalendar
object. It allows for preserving 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].
The example in Figure 90 describes how to convert an unknown
parameter to the "iCalProperty" property. The ATTACH property
converts to a Link object. To preserve the unknown "X-FOO"
parameter, the "iCalProperty" property is set on the Link object.
ATTACH;X-FOO=bar:https://example.com/example.jpg
"links": {
"l1": {
"@type": "Link",
"href": "https://example.com/example.jpg",
"iCalProperty": {
"@type": "ICalProperty",
"name": "attach",
"parameters": {
"x-foo": "bar"
}
}
}
}
Stepanek Expires 22 November 2025 [Page 94]
Internet-Draft JSCalendar May 2025
Figure 90: Converting the ATTACH property with an unknown parameter
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,
.
[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,
.
[RFC5870] Mayrhofer, A. and C. Spanring, "A Uniform Resource
Identifier for Geographic Locations ('geo' URI)",
RFC 5870, DOI 10.17487/RFC5870, June 2010,
.
[RFC6047] Melnikov, A., Ed., "iCalendar Message-Based
Interoperability Protocol (iMIP)", RFC 6047,
DOI 10.17487/RFC6047, December 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,
.
Stepanek Expires 22 November 2025 [Page 95]
Internet-Draft JSCalendar May 2025
[RFC6901] Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed.,
"JavaScript Object Notation (JSON) Pointer", RFC 6901,
DOI 10.17487/RFC6901, April 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,
.
[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, .
[RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", STD 90, RFC 8259,
DOI 10.17487/RFC8259, December 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,
.
[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,
.
Stepanek Expires 22 November 2025 [Page 96]
Internet-Draft JSCalendar May 2025
[RFC9253] Douglass, M., "Support for iCalendar Relationships",
RFC 9253, DOI 10.17487/RFC9253, August 2022,
.
[TZDB] "IANA Time Zone Database",
.
7.2. Informative References
[ical-tasks]
Douglass, M. and A. Apthorp, "Task Extensions to
iCalendar", Work in Progress, Internet-Draft, draft-ietf-
calext-ical-tasks, 30 July 2024,
.
[icaljscalexts]
Stepanek, R., "iCalendar Format Extensions for
JSCalendar", Work in Progress, Internet-Draft, draft-
stepanek-icalendar-jscalendar-extensions, 13 May 2025,
.
[jmap-calendars]
Jenkins, N.M. and M. Douglass, "JMAP for Calendars", Work
in Progress, Internet-Draft, draft-ietf-jmap-calendars, 22
July 2024, .
[jscalendarbis]
Jenkins, N.M. and R. Stepanek, "JSCalendar: A JSON
Representation of Calendar Data", Work in Progress,
Internet-Draft, draft-ietf-calext-jscalendarbis, 13 May
2025, .
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 and only complete at the time of publication of
this document.
Stepanek Expires 22 November 2025 [Page 97]
Internet-Draft JSCalendar May 2025
Implementations MAY choose to convert the following elements, for
example using the properties defined in Section 4 and Section 5, or
they might convert them to some vendor-specific extension properties.
Later RFC documents might also define new standard elements and
register them at IANA, either extending this list of inconvertible
elements, or rather reduce it by introducing a standard element to
convert to.
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
* VFREEBUSY [RFC5545], Section 3.6.4
* VJOURNAL [RFC5545], Section 3.6.3
* VRESOURCE [RFC9073], Section 7.3
* VTIMEZONE [RFC5545], Section 3.6.5
* VSTATUS [ical-tasks], Section 14.1
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 [RFC9073], Section 7.1
* CATEGORIES [RFC5545], Section 3.8.1.2
* COMMENT [RFC5545], Section 3.8.1.4
* CONTACT [RFC5545], Section 3.8.4.2
* CREATED [RFC5545], Section 3.8.7.1
* LAST-MODIFIED [RFC5545], Section 3.8.7.3
* LINK [RFC9253], Section 8.2
Stepanek Expires 22 November 2025 [Page 98]
Internet-Draft JSCalendar May 2025
* LOCATION [RFC5545], Section 3.8.1.7
* PARTICIPANT-TYPE [RFC9073], Section 6.2
* PRIORITY [RFC5545], Section 3.8.1.9
* REASON [ical-tasks], Section 12.2
* 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
* STRUCTURED-DATA [RFC9074], Section 6.6
* UID [RFC5545], Section 3.8.4.7
* URL [RFC5545], Section 3.8.4.6
A.1.2.2. VALARM [RFC5545], Section 3.6.6
* 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
* 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 [RFC5545], Section 3.4
* CALSCALE [RFC5545], Section 3.7.1
* LINK [RFC9253], Section 8.2
Stepanek Expires 22 November 2025 [Page 99]
Internet-Draft JSCalendar May 2025
* REFRESH-INTERVAL [RFC7986], Section 5.7
* URL [RFC5545], Section 3.8.4.6
* VERSION [RFC5545], Section 3.7.4
A.1.2.4. VEVENT [RFC5545], Section 3.6.1
* COMMENT [RFC5545], Section 3.8.1.4
* CONTACT [RFC5545], Section 3.8.4.2
* LINK [RFC9253], Section 8.2
* REFID [RFC9253], Section 8.3
* REQUEST-STATUS [RFC5545], Section 3.8.8.3
* RESOURCES [RFC5545], Section 3.8.1.10
* STRUCTURED-DATA [RFC9074], Section 6.6
* URL [RFC5545], Section 3.8.4.6
A.1.2.5. VLOCATION [RFC9073], Section 7.2
* LINK [RFC9253], Section 8.2
* UID [RFC5545], Section 3.8.4.7
* STRUCTURED-DATA [RFC9074], Section 6.6
A.1.2.6. VTODO [RFC5545], Section 3.6.2
* COMMENT [RFC5545], Section 3.8.1.4
* COMPLETED [RFC5545], Section 3.8.2.1
* CONTACT [RFC5545], Section 3.8.4.2
* LINK [RFC9253], Section 8.2
* REFID [RFC9253], Section 8.3
* REQUEST-STATUS [RFC5545], Section 3.8.8.3
* RESOURCES [RFC5545], Section 3.8.1.10
Stepanek Expires 22 November 2025 [Page 100]
Internet-Draft JSCalendar May 2025
* STRUCTURED-DATA [RFC9074], Section 6.6
* TASK-MODE [ical-tasks], Section 12.4
* URL [RFC5545], Section 3.8.4.6
A.1.3. Subcomponents by Component
The following components are defined to contain the listed
subcomponents. But these subcomponents do not convert to a standard
JSCalendar element.
A.1.3.1. PARTICIPANT [RFC9073], Section 7.1
* VLOCATION [RFC9073], Section 7.2
A.1.4. 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.
A.1.4.1. RDATE [RFC5545], Section 3.8.5.2
* PERIOD [RFC5545], Section 3.3.9
A.1.5. 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.5.1. ATTACH [RFC5545], Section 3.8.1.1
* FILENAME [RFC8607], Section 4.2
* MANAGED-ID [RFC8607], Section 4.3
A.1.5.2. ATTENDEE [RFC5545], Section 3.8.4.1
* DIR [RFC5545], Section 3.2.6
* 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
Stepanek Expires 22 November 2025 [Page 101]
Internet-Draft JSCalendar May 2025
* LANGUAGE [RFC5545], Section 3.2.10
A.1.5.3. CATEGORIES [RFC5545], Section 3.8.1.2
* LANGUAGE [RFC5545], Section 3.2.10
A.1.5.4. CONFERENCE [RFC7986], Section 5.11
* LANGUAGE [RFC5545], Section 3.2.10
A.1.5.5. DESCRIPTION [RFC5545], Section 3.8.1.5
* ALTREP [RFC5545], Section 3.2.1
A.1.5.6. IMAGE [RFC7986], Section 5.10
* ALTREP [RFC5545], Section 3.2.1
* DISPLAY [RFC7986], Section 6.1 (if the parameter value contains
more than one "displayval").
A.1.5.7. LINK [RFC9253], Section 8.2
* LANGUAGE [RFC5545], Section 3.2.10
* LINKREL [RFC9253], Section 6.1 (if the parameter value does not
conform to the "reg-rel-type" ABNF in [RFC8288], Section 3.3).
A.1.5.8. LOCATION [RFC5545], Section 3.8.1.7
* ALTREP [RFC5545], Section 3.2.1
* LANGUAGE [RFC5545], Section 3.2.10
A.1.5.9. NAME [RFC7986], Section 5.1
* ALTREP [RFC5545], Section 3.2.1
A.1.5.10. ORGANIZER [RFC5545], Section 3.8.4.3
* SENT-BY [RFC5545], Section 3.2.18
* LANGUAGE [RFC5545], Section 3.2.10
* SCHEDULE-AGENT [RFC6638], Section 7.1
* SCHEDULE-FORCE-SEND [RFC6638], Section 7.2
Stepanek Expires 22 November 2025 [Page 102]
Internet-Draft JSCalendar May 2025
* SCHEDULE-STATUS [RFC6638], Section 7.3
A.1.5.11. RECURRENCE-ID [RFC5545], Section 3.8.4.4
* RANGE [RFC5545], Section 3.2.13
A.1.5.12. RELATED-TO [RFC5545], Section 3.8.4.5
* GAP [RFC9253], Section 6.2
A.1.5.13. REQUEST-STATUS [RFC5545], Section 3.8.8.3
* LANGUAGE [RFC5545], Section 3.2.10
A.1.5.14. RESOURCES [RFC5545], Section 3.8.1.10
* ALTREP [RFC5545], Section 3.2.1
* LANGUAGE [RFC5545], Section 3.2.10
A.1.5.15. STYLED-DESCRIPTION [RFC9073], Section 6.5
* ALTREP [RFC5545], Section 3.2.1
* DERIVED [RFC9073], Section 5.3
A.1.5.16. SUMMARY [RFC5545], Section 3.8.1.12
* ALTREP [RFC5545], Section 3.2.1
A.1.5.17. TZNAME [RFC5545], Section 3.8.3.2
* LANGUAGE [RFC5545], Section 3.2.10
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 22 November 2025 [Page 103]