Internet DRAFT - draft-ietf-calext-jscalendar-icalendar
draft-ietf-calext-jscalendar-icalendar
Calendaring extensions R. Stepanek
Internet-Draft FastMail
Intended status: Standards Track M. Douglass
Expires: 12 January 2023 BCS
11 July 2022
JSCalendar: Converting from and to iCalendar
draft-ietf-calext-jscalendar-icalendar-07
Abstract
This document provides the required methods for converting JSCalendar
from and to iCalendar.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on 12 January 2023.
Copyright Notice
Copyright (c) 2022 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 & Douglass Expires 12 January 2023 [Page 1]
Internet-Draft JSCalendar July 2022
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1. Note (to be deleted later) . . . . . . . . . . . . . . . 4
1.2. Motivation . . . . . . . . . . . . . . . . . . . . . . . 4
1.3. Scope and caveats . . . . . . . . . . . . . . . . . . . . 4
1.4. Notational Conventions . . . . . . . . . . . . . . . . . 6
2. iCalendar pre-processing . . . . . . . . . . . . . . . . . . 6
3. Translating iCalendar components to JSCalendar . . . . . . . 7
3.1. VALARM . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.2. VCALENDAR . . . . . . . . . . . . . . . . . . . . . . . . 10
3.3. VEVENT . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.4. VLOCATION . . . . . . . . . . . . . . . . . . . . . . . . 11
3.5. VTIMEZONE, STANDARD, DAYLIGHT . . . . . . . . . . . . . . 12
3.6. VTODO . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4. Translating iCalendar properties to JSCalendar . . . . . . . 14
4.1. ATTACH . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.2. ATTENDEE . . . . . . . . . . . . . . . . . . . . . . . . 14
4.3. CALSCALE . . . . . . . . . . . . . . . . . . . . . . . . 17
4.4. CATEGORIES . . . . . . . . . . . . . . . . . . . . . . . 17
4.5. CLASS . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.6. COLOR . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.7. COMMENT . . . . . . . . . . . . . . . . . . . . . . . . . 18
4.8. COMPLETED . . . . . . . . . . . . . . . . . . . . . . . . 18
4.9. CONCEPT . . . . . . . . . . . . . . . . . . . . . . . . . 18
4.10. CONFERENCE . . . . . . . . . . . . . . . . . . . . . . . 19
4.11. CONTACT . . . . . . . . . . . . . . . . . . . . . . . . . 19
4.12. CREATED . . . . . . . . . . . . . . . . . . . . . . . . . 19
4.13. DESCRIPTION . . . . . . . . . . . . . . . . . . . . . . . 20
4.14. DTEND, DTSTART, DUE, DURATION . . . . . . . . . . . . . . 21
4.15. ESTIMATED-DURATION . . . . . . . . . . . . . . . . . . . 24
4.16. EXDATE . . . . . . . . . . . . . . . . . . . . . . . . . 24
4.17. EXRULE . . . . . . . . . . . . . . . . . . . . . . . . . 24
4.18. DTSTAMP and LAST-MODIFIED . . . . . . . . . . . . . . . . 24
4.19. GEO . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
4.20. IMAGE . . . . . . . . . . . . . . . . . . . . . . . . . . 25
4.21. LOCATION . . . . . . . . . . . . . . . . . . . . . . . . 25
4.22. METHOD . . . . . . . . . . . . . . . . . . . . . . . . . 25
4.23. ORGANIZER . . . . . . . . . . . . . . . . . . . . . . . . 26
4.24. PERCENT-COMPLETE . . . . . . . . . . . . . . . . . . . . 26
4.25. PRIORITY . . . . . . . . . . . . . . . . . . . . . . . . 28
4.26. PRODID . . . . . . . . . . . . . . . . . . . . . . . . . 29
4.27. RECURRENCE-ID . . . . . . . . . . . . . . . . . . . . . . 29
4.28. RELATED-TO . . . . . . . . . . . . . . . . . . . . . . . 29
4.29. REQUEST-STATUS . . . . . . . . . . . . . . . . . . . . . 30
4.30. RESOURCES . . . . . . . . . . . . . . . . . . . . . . . . 30
4.31. RDATE . . . . . . . . . . . . . . . . . . . . . . . . . . 31
4.32. RRULE . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Stepanek & Douglass Expires 12 January 2023 [Page 2]
Internet-Draft JSCalendar July 2022
4.33. SEQUENCE . . . . . . . . . . . . . . . . . . . . . . . . 35
4.34. STATUS . . . . . . . . . . . . . . . . . . . . . . . . . 35
4.35. STRUCTURED-DATA . . . . . . . . . . . . . . . . . . . . . 35
4.36. SUMMARY . . . . . . . . . . . . . . . . . . . . . . . . . 36
4.37. TRANSP . . . . . . . . . . . . . . . . . . . . . . . . . 36
4.38. UID . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
4.39. URL . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
5. Translating non-standard iCalendar to JSCalendar . . . . . . 37
5.1. urn:ietf:rfcXXXX#components . . . . . . . . . . . . . . . 37
5.2. urn:ietf:rfcXXXX#properties . . . . . . . . . . . . . . . 38
5.3. urn:ietf:rfcXXXX#parameters . . . . . . . . . . . . . . . 39
5.4. urn:ietf:rfcXXXX#prop . . . . . . . . . . . . . . . . . . 40
6. Translating iCalendar Recurrences . . . . . . . . . . . . . . 40
6.1. Translating iCalendar Recurrences: Simple objects with
overrides . . . . . . . . . . . . . . . . . . . . . . . . 40
6.2. Translating iCalendar Recurrences: Overrides with no
master . . . . . . . . . . . . . . . . . . . . . . . . . 41
7. Translating iCalendar: Further examples . . . . . . . . . . . 41
7.1. Recurring event with ATTACH . . . . . . . . . . . . . . . 41
7.2. Simple event with CONTACT . . . . . . . . . . . . . . . . 43
7.3. Simple event with RESOURCES . . . . . . . . . . . . . . . 45
7.4. Recurring event. Attendees only in overrides . . . . . . 45
8. Translating JSCalendar objects to iCalendar . . . . . . . . . 48
8.1. Event . . . . . . . . . . . . . . . . . . . . . . . . . . 48
8.2. Group . . . . . . . . . . . . . . . . . . . . . . . . . . 49
8.3. Task . . . . . . . . . . . . . . . . . . . . . . . . . . 49
9. Translating JSCalendar properties to iCalendar . . . . . . . 50
9.1. alerts . . . . . . . . . . . . . . . . . . . . . . . . . 50
9.1.1. action . . . . . . . . . . . . . . . . . . . . . . . 50
9.1.2. title and description . . . . . . . . . . . . . . . . 51
9.1.3. trigger . . . . . . . . . . . . . . . . . . . . . . . 51
9.1.4. todo . . . . . . . . . . . . . . . . . . . . . . . . 52
9.1.5. Example event with alerts . . . . . . . . . . . . . . 52
9.2. categories . . . . . . . . . . . . . . . . . . . . . . . 54
9.3. color . . . . . . . . . . . . . . . . . . . . . . . . . . 54
9.4. created . . . . . . . . . . . . . . . . . . . . . . . . . 55
9.5. duration . . . . . . . . . . . . . . . . . . . . . . . . 55
9.6. estimatedDuration . . . . . . . . . . . . . . . . . . . . 55
9.7. keywords . . . . . . . . . . . . . . . . . . . . . . . . 56
9.8. locations . . . . . . . . . . . . . . . . . . . . . . . . 56
9.8.1. coordinates . . . . . . . . . . . . . . . . . . . . . 57
9.8.2. description . . . . . . . . . . . . . . . . . . . . . 57
9.8.3. links . . . . . . . . . . . . . . . . . . . . . . . . 57
9.8.4. locationTypes . . . . . . . . . . . . . . . . . . . . 57
9.8.5. name . . . . . . . . . . . . . . . . . . . . . . . . 57
9.8.6. relativeTo . . . . . . . . . . . . . . . . . . . . . 57
9.8.7. timeZone . . . . . . . . . . . . . . . . . . . . . . 57
9.8.8. uid . . . . . . . . . . . . . . . . . . . . . . . . . 58
Stepanek & Douglass Expires 12 January 2023 [Page 3]
Internet-Draft JSCalendar July 2022
9.9. participants . . . . . . . . . . . . . . . . . . . . . . 58
9.10. timezones . . . . . . . . . . . . . . . . . . . . . . . . 58
10. Translating non-standard JSCalendar to iCalendar . . . . . . 59
10.1. New iCalendar properties . . . . . . . . . . . . . . . . 60
10.1.1. X-RFCXXXX-JSPROP Property . . . . . . . . . . . . . 60
10.1.2. X-RFCXXXX-PROP Property . . . . . . . . . . . . . . 61
10.2. New iCalendar Parameters . . . . . . . . . . . . . . . . 64
10.2.1. X-RFCXXXX-JSNAME Parameter . . . . . . . . . . . . . 64
11. JsCalendar base spec updates . . . . . . . . . . . . . . . . 64
12. Security Considerations . . . . . . . . . . . . . . . . . . . 65
13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 65
14. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 65
15. References . . . . . . . . . . . . . . . . . . . . . . . . . 65
15.1. Normative References . . . . . . . . . . . . . . . . . . 65
15.2. Informative References . . . . . . . . . . . . . . . . . 66
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 67
1. Introduction
1.1. Note (to be deleted later)
This is still very much a work in progress. There are
implementations of the mapping but there may be changes over the
coming weeks.
1.2. Motivation
The JSCalendar [RFC8984] data format is used to represent calendar
data, and is meant as an alternative to the widely deployed iCalendar
[RFC5545] data format.
While new calendaring services and applications might use JSCalendar
as their main data format to exchange calendaring data, they are
likely to interoperate with services and clients that just support
iCalendar. Similarly, existing calendaring data is stored in
iCalendar format in databases and other calendar stores, and
providers and users might want to represent this data also in
JSCalendar. Lastly, there is a requirement to preserve custom
iCalendar properties that have no equivalent in JSCalendar when
converting between these formats.
To support these use cases, this document provides the required
approach when converting JSCalendar data from and to iCalendar.
1.3. Scope and caveats
JSCalendar and iCalendar have a lot of semantics in common, but they
are not interchangeable formats:
Stepanek & Douglass Expires 12 January 2023 [Page 4]
Internet-Draft JSCalendar July 2022
* JSCalendar contains a richer data model to express calendar
information such as event locations and participants. while
future iCalendar extensions may allow a direct mapping, for now
there may be no representation directly in iCalendar of some
properties. These values may have to be extracted from a full
copy of the iCalendar format provided as a property in the
JSCalendar data.
* iCalendar may contain arbitrary, non-standardised data with custom
properties/attributes. These will be translated using the same
approach as jCal.
* iCalendar has some obsolete features that have been removed from
JSCalendar due to not being useful and/or supported in the real
world (e.g. custom email alerts to send to random people).
Translating these may lose some of the original fidelity.
* Implementations may use a custom property to store data that could
not be mapped directly in either direction in the original or a
custom format, however this is not interoperable.
* JSCalendar supports fractional seconds in time values whereas
iCalendar does not. A subsequent specification will define how
fractional seconds can be represented in iCalendar.
Accordingly, this document defines a canonical translation between
iCalendar and JSCalendar, and implementations MUST follow the
approaches specified here when iCalendar data is represented in
JSCalendar and vice-versa.
This document defines mappings for the following specifications.
* Internet Calendaring and Scheduling Core Object Specification
(iCalendar) [RFC5545]
* iCalendar Transport-Independent Interoperability Protocol (iTIP)
[RFC5546]
* New Properties for iCalendar [RFC7986]
* Event Publishing Extensions to iCalendar [RFC9073]
* Support for iCalendar Relationships
[draft-ietf-calext-ical-relations]
* "VALARM" Extensions for iCalendar [RFC9074]
Stepanek & Douglass Expires 12 January 2023 [Page 5]
Internet-Draft JSCalendar July 2022
Therefore all of these specifications MUST be implemented to follow
this specification.
1.4. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].
2. iCalendar pre-processing
iCalendar uses a line-folding mechanism to limit lines of data to a
maximum line length (typically 75 octets) to ensure the maximum
likelihood of preserving data integrity as it is transported via
various means (e.g., email) -- see Section 3.1 of [RFC5545].
iCalendar data uses an "escape" character sequence for text values
and property parameter values. See Sections 3.1 and 3.3 of [RFC5545]
as well as [RFC6868].
There is a subtle difference in the number representations between
JSON and iCalendar. While in iCalendar, a number may have leading
zeros, as well as a leading plus sign; this is not the case in JSON.
Numbers should be represented in whatever way needed for the
underlying format.
When converting from iCalendar to JSCalendar: First, iCalendar lines
MUST be unfolded. Afterwards, any iCalendar escaping MUST be
unescaped. Finally, JSON escaping, as described in Section 7 of
[RFC8259], MUST be applied. The reverse order applies when
converting from JSCalendar to iCalendar, which is further described
in Section ?.
iCalendar uses a base64 encoding for binary data. However, it does
not restrict the encoding from being applied to non-binary value
types. So, the following rules are applied when processing a
property with the "ENCODING" property parameter set to "BASE64":
* If the property value type is "BINARY", the base64 encoding MUST
be preserved.
* If the value type is not "BINARY", the "ENCODING" property
parameter MUST be removed, and the value MUST be base64 decoded.
When base64 encoding is used, it MUST conform to Section 4 of
[RFC4648], which is the base64 method used in [RFC5545].
Stepanek & Douglass Expires 12 January 2023 [Page 6]
Internet-Draft JSCalendar July 2022
One key difference in the formatting of values used in iCalendar and
JSCalendar is that, in JSCalendar, the specification uses date/time
values aligned with the extended format of [ISO.8601.2004], which is
more commonly used in Internet applications that make use of the JSON
format. The sections of this document describing the various date
and time formats contain more information on the use of the complete
representation, reduced accuracy, or truncated representation.
3. Translating iCalendar components to JSCalendar
This section is an alphabetic list of [RFC5545] components and how
they are mapped to JSCalendar.
At present VFREEBUSY and VJOURNAL are not mapped in jscalendar.
3.1. VALARM
An [RFC5545] VALARM component is mapped to a member of a JSCalendar
"alerts" object with a type of "Alert" and a small id.
BEGIN: VEVENT
...
BEGIN: VALARM
...
END: VALARM
BEGIN: VALARM
...
END: VALARM
END: VEVENT
maps to
{
"@type": "Event",
...
"alerts": {
"1": {
"@type": "Alert",
...
},
"2": {
"@type": "Alert",
...
}
}
}
Stepanek & Douglass Expires 12 January 2023 [Page 7]
Internet-Draft JSCalendar July 2022
The [RFC5545] VALARM has a number of problems which are not carried
over into JSCalendar. Clients tend to choose how, and in some cases
when to notify the user.
For example, if the user has a smart-watch they may get tapped on the
wrist. The method of notification may depend on which device is
being used and the context, for example a meeting or driving.
Also, many clients are taking into consideration the travel time and
notifying the user earlier if it seems necessary.
Specifying that a client should send emails to all attendees is both
annoying and dangerous. Attendees have their own preferences for how
and when they should be notified.
Accordingly, the specification only allows for "display" and "email"
actions and - other than specifying when - does not allow much else.
Clients and/or servers will generally use the associated event or
task title as identification. User preferences generally indicate
what actions they prefer.
Any ATTENDEE properties in the VALARM MUST be ignored.
An [RFC5545] ACTION property can take the defined values "AUDIO" /
"DISPLAY" / "EMAIL" whereas the JSCalendar "action" property only
supports "display" and "email".
An "AUDIO" alarm SHOULD be mapped to a "display" alert. Any
attachment MUST be ignored.
The iCalendar DESCRIPTION property is required for both ACTION:EMAIL
and ACTION:DISPLAY. Additionally, the iCalendar SUMMARY property is
required for ACTION:EMAIL.
Store the SUMMARY in the optional alert title property and the
DESCRIPTION is the alert description property.
The [RFC5545] example VALARMs will be mapped as follows, assuming
they are all in the same event:
BEGIN:VEVENT
DTSTAMP:20200522T142047Z
DTSTART;TZID=America/New_York:20220622T120000
DURATION:PT1H
SUMMARY:event with alarms
UID:6252D6C40A8308BFE25BBEFsimple-alarms-1
BEGIN:VALARM
TRIGGER;VALUE=DATE-TIME:20220508T120000Z
Stepanek & Douglass Expires 12 January 2023 [Page 8]
Internet-Draft JSCalendar July 2022
REPEAT:4
DURATION:PT15M
ACTION:AUDIO
ATTACH;FMTTYPE=audio/basic:ftp://example.com/pub/
sounds/bell-01.aud
END:VALARM
BEGIN:VALARM
TRIGGER:-PT30M
REPEAT:2
DURATION:PT15M
ACTION:DISPLAY
DESCRIPTION:Breakfast meeting with executive\n
team at 8:30 AM EST.
END:VALARM
BEGIN:VALARM
TRIGGER;RELATED=END:-P2D
ACTION:EMAIL
ATTENDEE:mailto:john_doe@example.com
SUMMARY:*** REMINDER: SEND AGENDA FOR WEEKLY STAFF MEETING ***
DESCRIPTION:A draft agenda needs to be sent out to the attendees
to the weekly managers meeting (MGR-LIST). Attached is a
pointer the document template for the agenda file.
ATTACH;FMTTYPE=application/msword:http://example.com/
templates/agenda.doc
END:VALARM
END:VEVENT
maps to
{
"@type": "Group",
"prodId": "//example.org//Example V3.14//EN",
"entries": [
{
"@type": "Event",
"alerts": {
"1": {
"@type": "Alert",
"action": "display",
"trigger": {
"@type": "AbsoluteTrigger",
"when": "2022-05-08T12:00:00Z"
}
},
"2": {
"@type": "Alert",
"action": "display",
"description": "Breakfast meeting with executive\n
Stepanek & Douglass Expires 12 January 2023 [Page 9]
Internet-Draft JSCalendar July 2022
team at 8:30 AM EST.",
"trigger": {
"@type": "OffsetTrigger",
"offset": "-PT30M"
}
},
"3": {
"@type": "Alert",
"action": "email",
"title": "*** REMINDER: SEND AGENDA FOR WEEKLY
STAFF MEETING ***",
"description": "A draft agenda needs to be sent out to
the attendees to the weekly managers meeting
(MGR-LIST). Attached is a pointer the document
template for the agenda file.",
"trigger": {
"@type": "OffsetTrigger",
"offset": "-P-2D",
"relativeTo": "end"
}
}
},
"created": "2022-05-02T20:04:12Z",
"start": "2022-06-22T12:00:00",
"timeZone": "America/New_York",
"duration": "PT1H",
"title": "event with alarms",
"uid": "6252D6C40A8308BFE25BBEFsimple-alarms-1"
}
]
}
Note that the ATTENDEE, DURATION and REPEAT properties have been
dropped.
3.2. VCALENDAR
A [RFC5545] VCALENDAR component may be mapped to a JSCalendar object
with a type of "Group".
Stepanek & Douglass Expires 12 January 2023 [Page 10]
Internet-Draft JSCalendar July 2022
BEGIN: VCALENDAR
PRODID:-//ABC Corporation//NONSGML My Product//EN
...
END: VCALENDAR
maps to
{
"@type": "Group",
"prodid": "-//ABC Corporation//NONSGML My Product//EN",
...
}
Note that a single Event or Task MAY be converted without a
surrounding Group if the VCALENDAR component only contains PRODID and
CALSCALE properties. In this case the prodid can go in the Event or
Task. The CALSCALE property is dropped - there is no equivalence in
JSCalendar.
3.3. VEVENT
A [RFC5545] VEVENT component is mapped to a JSCalendar object with a
type of "Event".
BEGIN: VEVENT
...
END: VEVENT
maps to
{
"@type": "Event",
...
}
3.4. VLOCATION
A [RFC9073] VLOCATION component is mapped to a JSCalendar object with
a type of "Location". Any properties within the VLOCATION must be
mapped as described below.
Stepanek & Douglass Expires 12 January 2023 [Page 11]
Internet-Draft JSCalendar July 2022
BEGIN: VEVENT
...
BEGIN: VLOCATION
...
END: VLOCATION
END: VEVENT
maps to
{
"@type": "Event",
...
"locations": {
"1": {
"@type": "Location",
...
}
}
}
3.5. VTIMEZONE, STANDARD, DAYLIGHT
A [RFC5545] VTIMEZONE component is mapped to a member of a JSCalendar
"timezones" object with a type of "TimeZone" and an id which follows
the restrictions specified.
The STANDARD and DAYLIGHT components map to JSCalendar TimeZoneRule
objects as members of the
Note that
* There is no current approach for defining standalone sets of
timezones.
* Timezones defined in the IANA timezone database SHOULD NOT be
redefined in the object. Only custom timezones will be defined.
Stepanek & Douglass Expires 12 January 2023 [Page 12]
Internet-Draft JSCalendar July 2022
BEGIN: VTIMEZONE
TZID: Example/Somewhere
...
END: VTIMEZONE
BEGIN: VTIMEZONE
TZID: Example/Somewhere-else
...
END: VTIMEZONE
BEGIN: VEVENT
...
END: VEVENT
maps to
{
"@type": "Event",
...
"timezones": {
"/Example/Somewhere: {
"@type": "TimeZone",
"tzId": "Example/Somewhere",
...
},
"/Example/Somewhere-else": {
"@type": "TimeZone",
"tzId": "Example/Somewhere-else",
...
}
}
}
3.6. VTODO
A [RFC5545] VTODO component is mapped to a JSCalendar object with a
type of "Task".
BEGIN: VTODO
...
END: VTODO
maps to
{
"@type": "Task",
...
}
Stepanek & Douglass Expires 12 January 2023 [Page 13]
Internet-Draft JSCalendar July 2022
4. Translating iCalendar properties to JSCalendar
This section is an alphabetic list of [RFC5545] and [RFC7986]
properties and how they are mapped to JSCalendar.
4.1. ATTACH
A [RFC5545] ATTACH allows for two types of attachment:
* A uri value
* A binary value
Both map to a JSCalendar "link" object with a "rel" of "enclosure"
and the "href" set to the value of the property.
If the FMTTYPE parameter is set then add a JSCalendar "contentType"
property to the link object.
For a binary value use a base64 data uri.
For an example of a recurring event with ATTACH see Section 7.1
4.2. ATTENDEE
An [RFC5545] ATTENDEE maps to the JSCalendar "participant" property
with a JSCalendar "role" of "attendee". The value for role should
always be set.
In the simplest case a JSCalendar "participant" property will be
created and added to the JSCalendar "participants" property.
The value of the ATTENDEE property is used to add an "imip" method to
the JSCalendar "sendTo" property. The value of the entry will be the
ATTENDEE property value.
For example:
Stepanek & Douglass Expires 12 January 2023 [Page 14]
Internet-Draft JSCalendar July 2022
...
ATTENDEE:mailto:user01@example.org
...
maps to
{
...
"participants": {
"be450b70-9bf7-4f6e-8f65-971ede566ce3": {
"@type": "Participant",
"sendTo": {
"imip": "mailto:user01@example.org"
},
...
}
The attendee parameters are mapped to JSCalendar "participant"
properties as follows:
CN: The value of the CN parameter is used to set the JSCalendar
"name" property.
CUTYPE: This maps on to the JSCalendar "kind" property as follows:
INDIVIDUAL "individual"
GROUP "group"
RESOURCE "resource"
ROOM "location"
UNKNOWN No value
Any other value should be converted to lower case and assigned to
the JSCalendar "kind" property.
DELEGATED-FROM: Split the value at any commas and add each resulting
element to the JSCalendar "delegatedFrom" property
DELEGATED-TO: Split the value at any commas and add each resulting
element to the JSCalendar "delegatedFrom" property
DIR: If non-null look in the participant "links" property for a
JSCalendar "link" property with an href with the same value as the
DIR parameter. You may need to search the current override and
the master.
Stepanek & Douglass Expires 12 January 2023 [Page 15]
Internet-Draft JSCalendar July 2022
If none is found create a new one with the JSCalendar "href"
property set to the value of the DIR parameter and the JSCalendar
"rel" property set to "alternate"
LANG: set the JSCalendar "language" property to the value of the
LANG parameter.
MEMBER: If this is set there should be a corresponding ATTENDEE
object with a value equal to the value of the member parameter.
If not it is appropriate to skip this parameter.
If there is a corresponding ATTENDEE then there should be a
corresponding JSCalendar "participant" property. This suggests
that CUTYPE=GROUP ATTENDEE properties should be processed ahead of
the others.
Locate the JSCalendar "participant" property for the group. This
may be in the current override or in the master. Add the id to
the current participants JSCalendar "memberOf" property.
PARTSTAT: If the PARTSTAT parameter is set and is not "NEEDS-ACTION"
then set the JSCalendar "participationStatus" property to the
lower-cased value of the PARTSTAT.
ROLE: This is mapped to the JSCalendar "roles" property as follows:
CHAIR "attendee" and "chair"
REQ-PARTICIPANT "attendee"
OPT-PARTICIPANT "attendee" and "optional"
NON-PARTICIPANT "informational"
Any other value should be converted to lower case and added to the
JSCalendar "roles" property.
RSVP: If the value of the RSVP parameter is TRUE set the JSCalendar
"expectReply" property to "true" otherwise omit it.
SCHEDULE-AGENT: If the value is "CLIENT" (ignoring case) set the
JSCalendar "scheduleAgent" property to "client" otherwise omit it.
SCHEDULE-FORCE-SEND: Set the JSCalendar "scheduleForceSend" property
to the lower-cased value of the [RFC6638] SCHEDULE-FORCE-SEND
parameter.
SCHEDULE-STATUS: Split the value at any commas and add each
Stepanek & Douglass Expires 12 January 2023 [Page 16]
Internet-Draft JSCalendar July 2022
resulting element to the JSCalendar "scheduleStatus" property.
SENT-BY: The value of the SENT-BY parameter is used to set the
JSCalendar "invitedBy" property.
4.3. CALSCALE
A [RFC5545] CALSCALE has no equivalence in JSCalendar. It is
ignored.
4.4. CATEGORIES
These map on to the JSCalendar "keywords" property with each category
being the key to an entry.
...
CATEGORIES:APPOINTMENT,EDUCATION
CATEGORIES:MEETING
...
maps to
...
"keywords": {
"APPOINTMENT": true,
"EDUCATION": true,
"MEETING": true
},
...
4.5. CLASS
Maps to the "privacy" property. The iCalendar property value maps to
the JSCalendar value as follows:
CONFIDENTIAL "secret"
PRIVATE "private"
PUBLIC "public"
iana-token and x-name verbatim copy
4.6. COLOR
The COLOR property is defined in [RFC7986] and maps to the JSCalendar
"color" property. Copy the value verbatim.
Stepanek & Douglass Expires 12 January 2023 [Page 17]
Internet-Draft JSCalendar July 2022
4.7. COMMENT
There is no direct mapping for this property which may appear
multiple times in [RFC5545].
For a scheduling reply it is presumably a message by the participant
so the value or values should be used to set the JSCalendar
"participantComment" property.
4.8. COMPLETED
Set the JSCalendar "progress" property to "completed" and the
"progressUpdated" property to the reformatted date/time.
...
COMPLETED: "20101010T101010Z"
...
maps to
...
"progressUpdated": "2010-10-10T10:10:10Z",
"progress": "completed",
...
4.9. CONCEPT
This [draft-ietf-calext-ical-relations] property may appear multiple
times in components.
Each instance of the property is mapped on to a member of the
JSCalendar "categories" property.
...
CONCEPT:http://example.com/event-types/arts/music
CONCEPT:http://example.com/performance-types/arts/live
...
maps to
...
"categories": {
"http://example.com/event-types/arts/music": true,
"http://example.com/performance-types/arts/live": true
}
...
Stepanek & Douglass Expires 12 January 2023 [Page 18]
Internet-Draft JSCalendar July 2022
4.10. CONFERENCE
Maps to a "VirtualLocation" object. The property value maps to the
"uri" property of the virtual location.
Mapping parameters:
FEATURE: Maps to the "features" property of the virtual location.
LABEL: Maps to the "name" property of the virtual location.
LANGUAGE: No mapping.
4.11. CONTACT
A CONTACT property is mapped on to a participant object with a
"roles" property of "contact". The value of the property is used to
set the jscalendar participant "name" property.
QUESTIONS - what to use for the id? I have a uid but that's my
implementation. There may be multiple CONTACT properties. If we
create PARTICIPANT objects going the other way - how to link them -
"name" == CONTACT value?
Mapping parameters:
ALTREP Use the same process as for the ATTENDEE DIR parameter:
create a link property with the "rel" property set to "alternate"
and the "href" property set to the value of the ALTREP parameter.
Then add the link to the participants "links" property.
LANG Set the participants "language" property.
For an example see Section 7.2
4.12. CREATED
The CREATED property is mapped on to a "created" property with a json
formatted form of the date. Example:
Stepanek & Douglass Expires 12 January 2023 [Page 19]
Internet-Draft JSCalendar July 2022
BEGIN:VEVENT
...
CREATED:19960329T133000Z
...
END:VEVENT
maps to
{
"@type": "Event",
...
"created": "1996-03-29T13:30"00Z",
...
}
4.13. DESCRIPTION
Copy the value, preprocessed according to Section 2 into the
"description" property.
Mapping parameters:
ALTREP No mapping.
LANG Use the "locale" property.
Example:
Stepanek & Douglass Expires 12 January 2023 [Page 20]
Internet-Draft JSCalendar July 2022
BEGIN:VEVENT
...
DESCRIPTION:We are having a meeting all this week at 12 pm fo
r one hour\, with an additional meeting on the first day 2 h
ours long.\nPlease bring your own lunch for the 12 pm meetin
gs.
...
END:VEVENT
maps to
{
"@type": "Event",
...
"description": // Note: comments and string concatenation are not
// allowed per the JSON specification and is used here
// to avoid long lines.
"We are having a meeting all this week at 12 pm for one " +
"hour, with an additional meeting on the first day 2 " +
"hours long.\nPlease bring your own lunch for the 12 pm " +
"meetings.",
...
}
4.14. DTEND, DTSTART, DUE, DURATION
If the DTSTART is a DATE only property then add the JSCalendar
showWithoutTime property with the value set to "true". The
JSCalendar "start" property is set with zero time values.
If the DTSTART has a TZID parameter then set the JSCalendar
"timeZone" property to the value of TZID.
If the DTSTART has a UTC value then set the JSCalendar "timeZone"
property to the value "Etc/UTC". The JSCalendar "start" property is
set without any UTC indicator.
JSCalendar has no equivalent to DTEND. If the component has a DTEND
then calculate a value for "DURATION" from that property and DTSTART
and proceed as below.
If the DTEND has a TZID parameter with a value that differs from the
DTSTART TZID parameter then a "location" object should be created
with a "relativeTo" property set to "end" and a "timezone" property
set to the value of the "TZID" parameter.
Note that a task is not required to have a DTSTART so the JSCalendar
"timezone" property needs to be set from the DUE property.
Stepanek & Douglass Expires 12 January 2023 [Page 21]
Internet-Draft JSCalendar July 2022
Convert a DURATION property to the JSCalendar duration.
Example - DTSTART and DTEND in same timezone:
BEGIN:VEVENT
...
DTSTART;TZID=America/New_York:20170315T150000
DTEND;TZID=America/New_York:20170315T160000
...
END:VEVENT
maps to
{
"@type": "Event",
...
"start": "2017-03-15T15:00:00",
"timeZone": "America/New_York",
"duration": "PT1H"
...
}
Example - DTSTART and DTEND in different timezone:
Stepanek & Douglass Expires 12 January 2023 [Page 22]
Internet-Draft JSCalendar July 2022
BEGIN:VEVENT
...
DTSTART;TZID=America/New_York:20170315T150000
DTEND;TZID=America/LosAngeles:20170315T190000
...
END:VEVENT
maps to
{
"@type": "Event",
...
"start": "2017-03-15T15:00:00",
"timeZone": "America/New_York",
"duration": "PT7H"
...
"locations": {
"1": {
"@type": "location",
"relatedTo": "end",
"timeZone": "America/Los_Angeles"
}
}
}
Example - 3 day event:
BEGIN:VEVENT
...
DTSTART;VALUE=DATE:20210315
DTEND;VALUE=DATE:20210318
...
END:VEVENT
maps to
{
"@type": "Event",
...
"start": "2017-03-15T00:00:00",
"duration": "P3D",
"showWithoutTime": true,
...
}
Stepanek & Douglass Expires 12 January 2023 [Page 23]
Internet-Draft JSCalendar July 2022
4.15. ESTIMATED-DURATION
Copy the ESTIMATED-DURATION value into the JSCalendar
"estimatedDuration" property.
For example:
...
ESTIMATED-DURATION:PT18H
...
maps to
...
"estimatedDuration": "PT18H"
...
4.16. EXDATE
Create a patch object with the recurrence id set from the EXDATE
value. Add a single JSCalendar "excluded" property with the value
set to true. There MUST NOT be any other properties set - other than
"@type".
4.17. EXRULE
Maps to the "excludedRecurrenceRules" property. Also see
Section 4.32.
4.18. DTSTAMP and LAST-MODIFIED
The mapping depends on whether or not the component is a scheduling
entity.
Not a scheduling entity: The [RFC5545] DTSTAMP and LAST-MODIFIED
properties have essentially the same meaning. If both are present
use the value of the latest for the "updated" property. Otherwise
set from whichever is present.
Is a scheduling entity: DTSTAMP should be used to set the
"ScheduleUpdated" property in the "participant" object for the
attendee.
If present LAST-MODIFIED should be used to set the "updated"
property - otherwise set it from the DTSTAMP.
Stepanek & Douglass Expires 12 January 2023 [Page 24]
Internet-Draft JSCalendar July 2022
4.19. GEO
Maps to a Location object, with only the "coordinates" property set.
Note that the JSCalendar coordinates property value MUST be a valid
"geo" URI, so replace the ";" character in the iCalendar value with
"," and prepend the resulting string with "geo:".
4.20. IMAGE
Maps to a Link object with the iCalendar property value mapped to the
location "href" property, and the "rel" property set to "icon".
For a binary value use a base64 data uri in the "href" property.
Mapping parameters:
ALTREP No mapping.
FMTTYPE Maps to the "contentType" property of the Link object.
DISPLAY Maps to the "display" property of the Link object. The
property values "BADGE", "GRAPHIC", "FULLSIZE" and "THUMBNAIL" map
to their lower-case equivalent in JSCalendar.
4.21. LOCATION
If any [RFC9073] "VLOCATION" components are present, then the
[RFC5545]"LOCATION" property should be ignored.
To map the property create a "locations" property with a single
"location" and set the "description" property to the value of the
[RFC5545]"LOCATION" property.
Mapping parameters:
ALTREP Maps to a Link object in the Location "links" property, with
the "href" property set to the parameter value.
4.22. METHOD
Maps to the "method" property of the JSCalendar object. The
JSCalendar property value is the lowercase equivalent of the
iCalendar property value.
Stepanek & Douglass Expires 12 January 2023 [Page 25]
Internet-Draft JSCalendar July 2022
4.23. ORGANIZER
Maps to the "replyTo" property of the JSCalendar object. An
iCalendar property value in the "mailto:" URI scheme, maps to the
"imip" method, any other value maps to the "other" method.
If the iCalendar component also contains an ATTENDEE with the same
calendar user address then map that ATTENDEE as defined in
Section 4.2 and add the "owner" role to the Participant "roles"
property. Otherwise, use the ORGANIZER property to map to a
Participant object. The "roles" property of the Participant MUST
only contain the "owner" role and the "expectReply" property value
MUST be "false". Any iCalendar parameters map as defined for
ATTENDEE.
TBD: SENT-BY parameter. Example.
4.24. PERCENT-COMPLETE
For all methods other than REPLY (or no method), the PERCENT-COMPLETE
applies to the VTODO as a whole. In this case it the value is used
to set the JSCalendar "percentComplete" property in the task object.
BEGIN: VCALENDAR
PRODID:-//ABC Corporation//NONSGML My Product//EN
METHOD:PUBLISH
BEGIN:VTODO
...
PERCENT-COMPLETE:39
END:VTODO
END: VCALENDAR
maps to
{
"@type": "Task",
"prodid": "-//ABC Corporation//NONSGML My Product//EN",
...
"percentComplete": 39
}
PERCENT-COMPLETE in a REPLY is used to indicate the level of
completeness of the ATTENDEE. There should only be a single ATTENDEE
in the VTODO object.
Stepanek & Douglass Expires 12 January 2023 [Page 26]
Internet-Draft JSCalendar July 2022
As ever recurrences complicate matters. For a non-recurring event or
an override that contains the single participant, set the JSCalendar
"percentComplete" property in the JSCalendar "participant" object
representing the attendee.
BEGIN: VCALENDAR
PRODID:-//ABC Corporation//NONSGML My Product//EN
METHOD:REPLY
BEGIN:VTODO
...
ATTENDEE:mailto:douglm@example.org
PERCENT-COMPLETE:39
END:VTODO
END: VCALENDAR
maps to
{
"@type": "Task",
"prodid": "-//ABC Corporation//NONSGML My Product//EN",
...
"participants": {
"be450b70-9bf7-4f6e-8f65-971ede566ce3": {
"@type": "Participant",
"sendTo": {
"imip": "mailto:douglm@example.org"
},
"percentComplete": 39,
"roles": {
"attendee": true
}
},
...
}
In the case of an override with the participant appearing in the
master then add a patch to the override.
Stepanek & Douglass Expires 12 January 2023 [Page 27]
Internet-Draft JSCalendar July 2022
BEGIN: VCALENDAR
PRODID:-//ABC Corporation//NONSGML My Product//EN
METHOD:REPLY
BEGIN:VTODO
...
ATTENDEE:mailto:douglm@example.org
END:VTODO
BEGIN:VTODO
...
RECURRENCE-ID:20200523T120000
...
ATTENDEE:mailto:douglm@example.org
PERCENT-COMPLETE:39
END:VTODO
END: VCALENDAR
maps to
{
"@type": "Task",
"prodid": "-//ABC Corporation//NONSGML My Product//EN",
...
"participants": {
"be450b70-9bf7-4f6e-8f65-971ede566ce3": {
"@type": "Participant",
"sendTo": {
"imip": "mailto:douglm@example.org"
},
"roles": {
"attendee": true
}
},
"recurrenceOverrides": {
"2020-05-23T12:00:00": {
"participants/be4...6ce3/percentComplete": 39
},
...
}
}
4.25. PRIORITY
Simply copy value into the JSCalendar "priority" property.
Stepanek & Douglass Expires 12 January 2023 [Page 28]
Internet-Draft JSCalendar July 2022
4.26. PRODID
For a vcalendar Group object with multiple Event and/or Task object
the [RFC5545] VCALENDAR PRODID is mapped to a JSCalendar "prodid"
property in the group.
When mapping to a single Event and/or Task object the [RFC5545]
VCALENDAR PRODID is mapped to a JSCalendar "prodid" property in the
group
BEGIN: VCALENDAR
PRODID:-//ABC Corporation//NONSGML My Product//EN
BEGIN:VEVENT
...
END:VEVENT
END: VCALENDAR
maps to
{
"@type": "Event",
"prodid": "-//ABC Corporation//NONSGML My Product//EN",
...
}
4.27. RECURRENCE-ID
Refer to Section 6 for information on mapping recurrence ids.
4.28. RELATED-TO
This is mapped to the JSCalendar "relatedTo" property which is a map
of relations with the target UID as the keys. The iCalendar relation
is by default a PARENT relationship. There is no default for
JSCalendar so the relationship must be explicitly specified.
The RELTYPE parameter values map to their lowercase equivalents in
the "relation" property.
Also note that the iCalendar relationship types are not identical.
CHILD and PARENT map to JSCalendar "child" and "parent" but the best
match for iCalendar SIBLING is "next"
Stepanek & Douglass Expires 12 January 2023 [Page 29]
Internet-Draft JSCalendar July 2022
...
RELATED-TO:jsmith.part7.19960817T083000.xyzMail@example.com
RELATED-TO;RELTYPE=SIBLING:
19960401-080045-4000F192713-0052@example.com
...
maps to
"relatedTo" : {
"jsmith.part7.19960817T083000.xyzMail@example.com" : {
"@type" : "Relation",
"relation" : {
"parent" : true
}
},
"19960401-080045-4000F192713-0052@example.com" : {
"@type" : "Relation",
"relation" : {
"next" : true
}
},
},
{
"@type": "Event",
"prodid": "-//ABC Corporation//NONSGML My Product//EN",
...
}
4.29. REQUEST-STATUS
Copy the value into the JSCalendar "requestStatus" property.
4.30. RESOURCES
The RESOURCES property value is a comma-separated list of resources.
First split this into the separate resource names and then each
resource is mapped on a participant object with a "kind" property of
"resource" and the "name" property set to the resource name.
Mapping parameters:
ALTREP Use the same process as for the ATTENDEE DIR parameter:
create a link property with the "rel" property set to "alternate"
and the "href" property set to the value of the ALTREP parameter.
Then add the link to the participants "links" property.
LANG Set the participants "language" property.
Stepanek & Douglass Expires 12 January 2023 [Page 30]
Internet-Draft JSCalendar July 2022
For an example see Section 7.3
4.31. RDATE
If the RDATE has a RANGE=THISANDFUTURE parameter then the recurrence
MUST be split at this RDATE.
Truncate the original object before this RDATE, create a new master
representing the object and link them by setting the jscalendar
"relatedTo" property in both.
Otherwise create a patch object with the recurrence id set from the
RDATE value. If the instance has overrides the differences will also
be set in the object.
4.32. RRULE
Each RRULE is converted to an object in the JSCalendar
"recurrenceRules" property. Each entry has the type
"RecurrenceRule".
...
RRULE:...
...
maps to
...
"recurrenceRules" : [{
"@type" : "RecurrenceRule",
...
}],
...
The recurrence rule object has one property for each element of the
recurrence rule. The iCalendar rule has to be parsed out and the
individual jscalendar property values set. Most take the same type
but there are exceptions.
FREQ (mandatory) Copy into the jscalendar "frequency" property
converted to lowercase.
INTERVAL If present and not 1 copy into the jscalendar "interval"
property.
RSCALE If present copy into the jscalendar "rscale" property
converted to lowercase.
Stepanek & Douglass Expires 12 January 2023 [Page 31]
Internet-Draft JSCalendar July 2022
SKIP If present copy into the jscalendar "skip" property converted
to lowercase.
WKST If present copy into the jscalendar "firstDayOfWeek" property
converted to lowercase.
BYDAY If present each element becomes an entry in the jsCalendar
"byDay" propety. This is an array of NDay objects which may have
2 properties:
day The two character weekday abbreviation.
nthOfPeriod If the weekday abbreviation is preceded by a signed
integer value set the jscalendar "nthOfPeriod" property.
...
RRULE:...,BYDAY=-1MO
...
maps to
...
"recurrenceRules" : [{
"@type" : "RecurrenceRule",
...
"byday": [{
"day": "mo",
"nthOfPeriod": -1
}]
...
}],
...
BYMONTHDAY If present each element will be an element in the
jscalendar "byMonthDay" property.
BYMONTH If present each element will be an element in the jscalendar
"byMonth" property.
Note that the iCalendar values are numeric but the JSCalendar
values are strings. This is because of the possible "L" suffix
for leap months.
BYYEARDAY If present each element will be an element in the
jscalendar "byYearDay" property.
BYWEEKNO If present each element will be an element in the
jscalendar "byWeekNo" property.
Stepanek & Douglass Expires 12 January 2023 [Page 32]
Internet-Draft JSCalendar July 2022
BYHOUR If present each element will be an element in the jscalendar
"byHour" property.
BYMINUTE If present each element will be an element in the
jscalendar "byMinute" property.
BYSECOND If present each element will be an element in the
jscalendar "bySecond" property.
BYSETPOS If present each element will be an element in the
jscalendar "bySetPosition" property.
COUNT If present set in the jscalendar "count" property.
UNTIL If present set the jscalendar "until" property with the
appropriately reformatted value. If the is no time part append a
0 time and reformat as a jscalendar local date/time.
Some examples:
...
RRULE:FREQ=DAILY;COUNT=10
...
maps to
...
"recurrenceRules" : [{
"@type" : "RecurrenceRule",
"frequency": "daily",
"count": 10
}],
...
Stepanek & Douglass Expires 12 January 2023 [Page 33]
Internet-Draft JSCalendar July 2022
...
RRULE:FREQ=YEARLY;UNTIL=20220512T140000Z;
BYMONTH=1;BYDAY=SU,MO,TU,WE,TH,FR,SA
...
maps to
...
"recurrenceRules" : [{
"@type" : "RecurrenceRule",
"frequency": "yearly",
"byMonth": ["1"],
"byDay": [{
"day": "su"
},
}
"day": "mo"
},
}
"day": "tu"
},
}
"day": "we"
},
}
"day": "th"
},
}
"day": "fr"
},
}
"day": "sa"
}],
"until": "2022-05-12T10:00:00"
}],
...
Stepanek & Douglass Expires 12 January 2023 [Page 34]
Internet-Draft JSCalendar July 2022
...
RRULE:FREQ=MONTHLY;COUNT=6;BYDAY=-2MO
...
maps to
...
"recurrenceRules" : [{
"@type" : "RecurrenceRule",
"frequency": "monthly",
"byDay": [{
"day": "mo",
"nthOfPeriod": -2
}],
"count": 6
}],
...
4.33. SEQUENCE
Copy the value into the JSCalendar "sequence" property.
4.34. STATUS
For a VEVENT copy the lower-cased value into the JSCalendar "status"
property.
For a VTODO copy the lower-cased value into the JSCalendar "progress"
property.
4.35. STRUCTURED-DATA
This property is mapped on to a JSCalendar "link" object with the
value mapped on to the JSCalendar "href" property in a manner
depending on the "STRUCTURED-DATA" "VALUE" parameter:
VALUE=TEXT Copy the value as a [RFC2397] data uri either as plain
text or by encoding as a base64 value. If plain text the value
may need escaping as per [RFC2397].
VALUE=BINARY Copy the value as a [RFC2397] data uri speifying base64
encoding.
VALUE=URI Copy the value as-is into the href.
The "STRUCTURED-DATA" "SCHEMA" parameter is mapped on to a JSCalendar
"schema" property within the link object.
Stepanek & Douglass Expires 12 January 2023 [Page 35]
Internet-Draft JSCalendar July 2022
The "STRUCTURED-DATA" "FMTTYPE" parameter is mapped on to a
JSCalendar "contentType" property within the link object.
For example:
...
STRUCTURED-DATA;FMTTYPE=application/ld+json;
SCHEMA="https://schema.org/SportsEvent";
VALUE=TEXT:{\n
"@context": "http://schema.org"\,\n
"@type": "SportsEvent"\,\n
"homeTeam": "Pittsburgh Pirates"\,\n
"awayTeam": "San Francisco Giants"\n
}\n
...
maps to (with data truncated)
...
"links": {
"1": {
"@type" : "Link",
"contentType": "application/ld+json",
"schema": "https://schema.org/SportsEvent",
"href": "data:base64;ewogICAgICAgICJAY29udGV4dCI6IC..."
}
}
...
4.36. SUMMARY
Copy the value into the JSCalendar "title" property.
Mapping parameters:
ALTREP No mapping.
LANG Use the "locale" property.
4.37. TRANSP
If the value of the TRANSP property (ignoring case) is "opaque" set
the JSCalendar "freeBusyStatus" property to the value "busy".
Otherwise set the JSCalendar "freeBusyStatus" property to the value
"free".
Stepanek & Douglass Expires 12 January 2023 [Page 36]
Internet-Draft JSCalendar July 2022
4.38. UID
Copy the value into the JSCalendar "uid" property.
4.39. URL
Maps to a Link object in the JSCalendar object's "links" property,
with the URL property value mapped to the Link "href" property.
5. Translating non-standard iCalendar to JSCalendar
iCalendar data may contain entries for which no standard property or
object type exists in JSCalendar. This mainly occurs for
experimental properties, parameter and components in iCalendar (_X_-
extensions, see Section 3.8.8.2 of [RFC5545]), but may be the case
for other iCalendar data, too. Typically, the semantics or value
types of such entries are known.
This section defines new properties, by which implementations SHOULD
map such data. Applications that have more insight into the
semantics of such iCalendar entries MAY choose to map differently.
NOTE: The verbatim XXXX values in this section will be replaced with
the RFC number of this document before publication. Also, the
following properties require a redefinition of vendor-extension
properties for JSCalendar. Currently, only domain names are allowed
as prefix for vendor extensions. This document assumes that also
URIs with the urn scheme are allowed.
5.1. urn:ietf:rfcXXXX#components
Type: JCalComp[] where JCalComp denotes a jCal-encoded component as
defined in Section 3.3 of [RFC7265]
This property is set on a JSCalendar object for which a standard
mapping from an iCalendar component is defined. If set, it contains
one or more iCalendar components that are direct children of the
iCalendar component represented by the JSCalendar object.
Stepanek & Douglass Expires 12 January 2023 [Page 37]
Internet-Draft JSCalendar July 2022
BEGIN:VEVENT
UID:c2236fe3-4dc9-4b3b-8a18-cd8f29eca594
DTSTART:20220711T104800
BEGIN:X-COMP
UID:6dcff59c-d251-44c9-9010-a62cab390df0
END:X-COMP
END:VEVENT
maps to
{
"@type": "Event",
"uid": "c2236fe3-4dc9-4b3b-8a18-cd8f29eca594",
"start": "2022-07-11T10:48:00",
"urn:ietf:rfcXXXX#components": [
["x-comp", [
["uid", {}, "text", "6dcff59c-d251-44c9-9010-a62cab390df0"]
]
]
}
5.2. urn:ietf:rfcXXXX#properties
Type: JCalProp[] where JCalProp denotes a jCal-encoded property as
defined in Section 3.4 of [RFC7265]
This property is set on a JSCalendar object for which a standard
mapping from an iCalendar component is defined. If set, it contains
one or more iCalendar properties that are set in the iCalendar
component represented by the JSCalendar object.
Stepanek & Douglass Expires 12 January 2023 [Page 38]
Internet-Draft JSCalendar July 2022
BEGIN:VEVENT
UID:c2236fe3-4dc9-4b3b-8a18-cd8f29eca594
DTSTART:20220711T104800
X-PROP;X-PARAM=Bar:Foo
END:VEVENT
maps to
{
"@type": "Event",
"uid": "c2236fe3-4dc9-4b3b-8a18-cd8f29eca594",
"start": "2022-07-11T10:48:00",
"urn:ietf:rfcXXXX#properties": [
["x-prop", {
"x-param": "Bar"
}, "unknown", "Foo"]
]
}
5.3. urn:ietf:rfcXXXX#parameters
Type: String[String] denotes a JSON object encoding iCalendar
parameters as defined in Section 3.5 of [RFC7265]
This property is set on a JSCalendar object for which a standard
mapping from an iCalendar property is defined. If set, it contains
one or more iCalendar parameters that are set on the iCalendar
property represented by the JSCalendar object.
...
ATTACH;X-PARAM=Bar;VALUE=URI:https://example.com/foo.zip
...
maps to
...
{
"@type": "Link",
"href": "https://example.com/foo.zip",
"urn:ietf:rfcXXXX#parameters": {
"x-param": "Bar"
}
}
...
Stepanek & Douglass Expires 12 January 2023 [Page 39]
Internet-Draft JSCalendar July 2022
5.4. urn:ietf:rfcXXXX#prop
A short-form variant of the properties property defined in
Section 5.2 MAY be used to map a single property from iCalendar.
This aims to provide a compact representation for mapping an
iCalendar property without parameters and for which no value type is
known. It is defined as follows:
Name: urn:ietf:rfcXXXX#prop/_propname_ where _propname_ denotes the
ASCII lower-case name (Section 3.1 of [RFC5545]) of the mapped
property.
Type: String where the string must adhere to the definitions of
Section 5 of [RFC7265].
The following example contains both the long-form and short-form
mapping for illustration:
...
X-Foo:Bar
...
maps to short-form
...
"urn:ietf:rfcXXXX#prop/x-foo": "Bar"
...
or long-form
...
"urn:ietf:rfcXXXX#properties": [
["x-foo", { }, "unknown", "Bar"]
]
...
6. Translating iCalendar Recurrences
6.1. Translating iCalendar Recurrences: Simple objects with overrides
A simple object with overrides will be converted to a jsCalendar
master event with the rules, recurrence dates and exclusion dates
translated appropriately.
Overrides MUST be mapped on to a jsCalendar patch object and added to
the "recurrenceOverrides" property of the master event with the key
being the value of the iCalendar RECURRENCE-ID translated to a json
format.
Stepanek & Douglass Expires 12 January 2023 [Page 40]
Internet-Draft JSCalendar July 2022
Any override property with the same value as the master SHOULD be
ommitted. Remaining properties MAY be added in full. Where
appropriate, differences SHOULD be expressed as a patch.
This can result in a significant reduction in size for objects with
small changes to overrides, for example changing the participation
status of an attendee.
6.2. Translating iCalendar Recurrences: Overrides with no master
When inviting an attendee to a single instance of a recurring event,
only that override should be sent to the attendee. In this case the
override should be a complete jsCalendar object with the type set to
the type of the master.
Additionally, there MUST be a recurrenceId property set to the value
of the recurrence id for that override. If the timezone of the start
of the instance is different from the master value, then there must
also be a "recurrenceIdTimeZone" property set to the start timezone
of the master.
7. Translating iCalendar: Further examples
This section provides more complete examples of translating from
[RFC5545] to JSCalendar.
As usual note that json string values may be split because of line
width limits. This is not legal json.
7.1. Recurring event with ATTACH
This is an example of a recurring event with overrides. The first
override removes an ATTACH property and adds an ATTACH property. The
second override removes all ATTACH properties.
BEGIN:VCALENDAR
CALSCALE:GREGORIAN
PRODID:-//example.org//EN
VERSION:2.0
BEGIN:VEVENT
DTSTAMP:20200522T142047Z
DTSTART;TZID=America/New_York:20200522T120000
DURATION:PT1H
RRULE:FREQ=DAILY;COUNT=8
SUMMARY:recurring daily 8 times
UID:6252D6C40A8308BFE25BBDErecur-1
ATTACH;FMTTYPE=text/plain:http://example.org/doc1.txt
ATTACH;FMTTYPE=text/plain:http://example.org/doc2.txt
Stepanek & Douglass Expires 12 January 2023 [Page 41]
Internet-Draft JSCalendar July 2022
ATTACH;FMTTYPE=text/plain:http://example.org/doc3.txt
END:VEVENT
BEGIN:VEVENT
DTSTAMP:20200522T142047Z
DTSTART;TZID=America/New_York:20200523T120000
DURATION:PT1H
RECURRENCE-ID;TZID=America/New_York:20200523T120000
SUMMARY:recurring daily 8 times
UID:6252D6C40A8308BFE25BBDErecur-1
ATTACH;FMTTYPE=text/plain:http://example.org/doc2.txt
ATTACH;FMTTYPE=text/plain:http://example.org/doc3.txt
ATTACH;FMTTYPE=text/plain:http://example.org/doc4.txt
END:VEVENT
BEGIN:VEVENT
DTSTAMP:20200522T142047Z
DTSTART;TZID=America/New_York:20200524T120000
DURATION:PT1H
RECURRENCE-ID;TZID=America/New_York:20200524T120000
SUMMARY:recurring daily 8 times
UID:6252D6C40A8308BFE25BBDErecur-1
END:VEVENT
END:VCALENDAR
maps to
{
"prodId": "//example.org//EN",
"entries": [
{
"links": {
"1": {
"@type": "Link",
"rel": "enclosure",
"contentType": "text/plain",
"href": "http://example.org/doc1.txt"
},
"2": {
"@type": "Link",
"rel": "enclosure",
"contentType": "text/plain",
"href": "http://example.org/doc2.txt"
},
"3": {
"@type": "Link",
"rel": "enclosure",
"contentType": "text/plain",
"href": "http://example.org/doc3.txt"
}
Stepanek & Douglass Expires 12 January 2023 [Page 42]
Internet-Draft JSCalendar July 2022
},
"created ": "2020-05-23T17:04:50Z",
"start": "2020-05-22T12:00:00",
"timeZone": "America/New_York",
"duration": "PT1H",
"title": "recurring daily 8 times",
"uid": "6252D6C40A8308BFE25BBDErecur-1",
"recurrenceRules": [
{
"@type": "RecurrenceRule",
"frequency": "daily",
"count": 8
}
],
"recurrenceOverrides": {
"2020-05-23T12:00:00": {
"recurrenceId": "2020-05-23T12:00:00",
"links/d4a618d4-929c-4c81-ae5b-322afe407a00": null,
"links/fb75b76a-a159-4a86-bd3d-7ace6b39c6c3": {
"@type": "Link",
"rel": "enclosure",
"contentType": "text/plain",
"href": "http://example.org/doc4.txt"
}
},
"2020-05-24T12:00:00": {
"recurrenceId": "2020-05-24T12:00:00",
"links/d4a618d4-929c-4c81-ae5b-322afe407a00": null,
"links/6c54e72e-3413-487c-ae14-fb318a90db43": null,
"links/44087e9a-132c-4a5d-b25d-4ce580edb004": null
}
}
}
]
}
7.2. Simple event with CONTACT
This example shows the conversion of a simple event with a single
CONTACT property in JSCalendar.
BEGIN:VCALENDAR
CALSCALE:GREGORIAN
PRODID:-//Example//EN
VERSION:2.0
BEGIN:VEVENT
DTSTAMP:20200522T142047Z
DTSTART;TZID=America/New_York:20200622T120000
Stepanek & Douglass Expires 12 January 2023 [Page 43]
Internet-Draft JSCalendar July 2022
DURATION:PT1H
SUMMARY:event with contact
UID:6252D6C40A8308BFE25BBEFcontact-1
CONTACT;ALTREP="ldap://example.com:6666/o=ABC%20Industries\,
c=US???(cn=Jim%20Dolittle)":Jim Dolittle\, ABC Industries\,
+1-919-555-XXXX
END:VEVENT
END:VCALENDAR
translates to
{
"@type": "Group",
"prodId": "//Example.org//Example V3.13.2//EN",
"entries": [
{
"@type": "Event",
"participants": {
"40288108-733187c1-0173-3188007b-00000001": {
"@type": "Participant",
"roles": {
"contact": true
},
"description": "Jim Dolittle, ABC Industries,\
+1-919-555-XXXX",
"links": {
"1": {
"@type": "Link",
"href": "ldap://example.com:6666/o=ABC%20Industries,\
c=US???(cn=Jim%20Dolittle)",
"rel": "alternate"
}
}
}
},
"created ": "2020-07-09T03:04:23Z",
"start": "2020-06-22T12:00:00",
"timeZone": "America/New_York",
"duration": "PT1H",
"title": "event with contact",
"uid": "6252D6C40A8308BFE25BBEFcontact-1"
}
]
}
Stepanek & Douglass Expires 12 January 2023 [Page 44]
Internet-Draft JSCalendar July 2022
7.3. Simple event with RESOURCES
TBD
7.4. Recurring event. Attendees only in overrides
In this more complex example there is no ORGANIZER or ATTENDEEs in
the master event. There are overrides which invite one or more
attendees.
For one overrride the ORGANIZER is also an ATTENDEE. In the other
that is not the case. This is reflected in the "roles" property for
the organizer.
Note that each override has its own "participants" property and the
first has a links property to handle the DIR parameter on one
attendee.
BEGIN:VCALENDAR
PRODID://Example.org//Example V3.13.2//EN
VERSION:2.0
BEGIN:VEVENT
CREATED:20200704T035515Z
DURATION:PT1H
DTSTAMP:20200704T035706Z
DTSTART;TZID=America/New_York:20200522T120000
LAST-MODIFIED:20200704T035706Z
SUMMARY:recurring daily 8 times
UID:6252D6C40A8308BFE25BBEFrecur1-1
RRULE:FREQ=DAILY;COUNT=8
END:VEVENT
BEGIN:VEVENT
RECURRENCE-ID;TZID=America/New_York:20200523T120000
ATTENDEE:mailto:douglm@example.org
ATTENDEE;RSVP=TRUE;SCHEDULE-STATUS=1.2;DIR="http://example.org/
vcards/vbede.vcf":mailto:vbede@example.org
CREATED:20200704T035515Z
DURATION:PT1H
DTSTAMP:20200704T035706Z
DTSTART;TZID=America/New_York:20200523T120000
LAST-MODIFIED:20200704T035706Z
ORGANIZER:mailto:douglm@example.org
SUMMARY:recurring daily 8 times
UID:6252D6C40A8308BFE25BBEFrecur1-1
END:VEVENT
BEGIN:VEVENT
RECURRENCE-ID;TZID=America/New_York:20200524T120000
ATTENDEE;RSVP=TRUE;SCHEDULE-STATUS=1.2:mailto:user01@example.org
Stepanek & Douglass Expires 12 January 2023 [Page 45]
Internet-Draft JSCalendar July 2022
ATTENDEE;RSVP=TRUE;SCHEDULE-STATUS=1.2:mailto:vbede@example.org
CREATED:20200704T035515Z
DURATION:PT1H
DTSTAMP:20200704T035706Z
DTSTART;TZID=America/New_York:20200524T120000
LAST-MODIFIED:20200704T035706Z
ORGANIZER:mailto:douglm@example.org
SUMMARY:recurring daily 8 times
UID:6252D6C40A8308BFE25BBEFrecur1-1
END:VEVENT
END:VCALENDAR
translates to
{
"@type": "Group",
"prodId": "//Example.org//Example V3.13.2//EN",
"entries": [
{
"@type": "Event",
"created ": "2020-07-04T03:57:06Z",
"start": "2020-05-22T12:00:00",
"timeZone": "America/New_York",
"duration": "PT1H",
"title": "recurring daily 8 times",
"uid": "6252D6C40A8308BFE25BBEFrecur1-1",
"recurrenceRules": [
{
"@type": "RecurrenceRule",
"frequency": "daily",
"count": 8
}
],
"recurrenceOverrides": {
"2020-05-23T12:00:00": {
"participants": {
"be450b70-9bf7-4f6e-8f65-971ede566ce3": {
"@type": "Participant",
"sendTo": {
"imip": "mailto:douglm@example.org"
},
"roles": {
"attendee": true,
"owner": true
}
},
"a539dfe3-4463-4f28-b9de-17d3a0e99faf": {
"@type": "Participant",
Stepanek & Douglass Expires 12 January 2023 [Page 46]
Internet-Draft JSCalendar July 2022
"sendTo": {
"imip": "mailto:vbede@example.org"
},
"expectReply": true,
"links": {
"1": {
"@type": "Link",
"href": "http://example.org/vcards/vbede.vcf",
"rel": "alternate"
}
},
"roles": {
"attendee": true
},
"scheduleStatus": "1.2"
}
},
"replyTo": {
"imip": "mailto:douglm@example.org"
}
},
"2020-05-24T12:00:00": {
"participants": {
"daeae4cf-6f6a-4ce3-9f4d-6bd884650d3d": {
"@type": "Participant",
"sendTo": {
"imip": "mailto:user01@example.org"
},
"expectReply": true,
"roles": {
"attendee": true
},
"scheduleStatus": "1.2"
},
"a6de6de3-271f-4679-9241-1b3bca6b602d": {
"@type": "Participant",
"sendTo": {
"imip": "mailto:vbede@example.org"
},
"expectReply": true,
"roles": {
"attendee": true
},
"scheduleStatus": "1.2"
},
"aaa8483b-b18b-4dbd-b218-77d8db027d35": {
"@type": "Participant",
"sendTo": {
Stepanek & Douglass Expires 12 January 2023 [Page 47]
Internet-Draft JSCalendar July 2022
"imip": "mailto:douglm@example.org"
},
"roles": {
"owner": true
}
}
},
"replyTo": {
"imip": "mailto:douglm@example.org"
}
}
}
}
]
}
8. Translating JSCalendar objects to iCalendar
This section lists the JSCalendar objects that map to [RFC5545]
components.
8.1. Event
A JSCalendar object with a type of "Event" is mapped on to a
[RFC5545] VEVENT component.
If it is a single VEVENT then a [RFC5545] VCALENDAR component must
surround it and the JSCalendar "prodid" property will be converted to
a [RFC5545] PRODID.
{
"@type": "Event",
"prodid": "-//ABC Corporation//NONSGML My Product//EN",
...
}
maps to
BEGIN: VCALENDAR
PRODID:-//ABC Corporation//NONSGML My Product//EN
BEGIN:VEVENT
...
END:VEVENT
END: VCALENDAR
When converting multiple Event or Task objects the surrounding
[RFC5545] VCALENDAR object must have a [RFC5545] PRODID set from
either the Group "prodid" or generated.
Stepanek & Douglass Expires 12 January 2023 [Page 48]
Internet-Draft JSCalendar July 2022
8.2. Group
A JSCalendar object with a type of "Group" is mapped on to a
[RFC5545] VCALENDAR component.
{
"@type": "Group",
"prodid": "-//ABC Corporation//NONSGML My Product//EN",
...
{
"@type": "Event",
...
}
{
"@type": "Event",
...
}
}
maps to
BEGIN: VCALENDAR
PRODID:-//ABC Corporation//NONSGML My Product//EN
BEGIN:VEVENT
...
END:VEVENT
BEGIN:VEVENT
...
END:VEVENT
END: VCALENDAR
8.3. Task
A JSCalendar object with a type of "Task" is mapped on to a [RFC5545]
VTODO component.
If it is a single VTODO then a [RFC5545] VCALENDAR component must
surround it and the JSCalendar "prodid" property will be converted to
a [RFC5545] PRODID.
Stepanek & Douglass Expires 12 January 2023 [Page 49]
Internet-Draft JSCalendar July 2022
{
"@type": "Task",
"prodid": "-//ABC Corporation//NONSGML My Product//EN",
...
}
maps to
BEGIN: VCALENDAR
PRODID:-//ABC Corporation//NONSGML My Product//EN
BEGIN:VTODO
...
END:VTODO
END: VCALENDAR
When converting multiple Event or Task objects the surrounding
[RFC5545] VCALENDAR object must have a [RFC5545] PRODID set from
either the Group "prodid" or generated.
9. Translating JSCalendar properties to iCalendar
This section is an alphabetic list of all JSCalendar top-level
properties that map to [RFC5545] iCalendar.
9.1. alerts
Each member of a JSCalendar alerts property maps to a [RFC5545]
VALARM component. Only display and email alarms are allowed in
JSCalendar.
9.1.1. action
The JSCalendar "action" property maps to the [RFC5545] ACTION
property. The value SHOULD be the uppercased version of the
JSCalendar "alert" property.
For example:
Stepanek & Douglass Expires 12 January 2023 [Page 50]
Internet-Draft JSCalendar July 2022
...
"action": "display",
...
maps to
ACTION:DISPLAY
and
...
"action": "email",
...
maps to
ACTION:EMAIL
9.1.2. title and description
The iCalendar DESCRIPTION property is required for both ACTION:EMAIL
and ACTION:DISPLAY. Additionally, the iCalendar SUMMARY property is
required for ACTION:EMAIL.
Both of these are optional in a JSCalendar alert. When converting is
there is a title property in the alert use that for the SUMMARY.
Similarly if a JSCalendar description property is present use that
for the description. Otherwise use the alert title property and if
that is absent use the event title.
9.1.3. trigger
A JSCalendar trigger with a type of "AbsoluteTrigger" maps on to a
[RFC5545] TRIGGER property with a "VALUE" parameter of "DATE-TIME"
and a value taken from the JSCalendar "when" property.
For example:
"trigger": {
"@type": "AbsoluteTrigger",
"when": "20210315T133000Z"
}
maps to
TRIGGER;VALUE=DATE-TIME:20210315T133000Z
Stepanek & Douglass Expires 12 January 2023 [Page 51]
Internet-Draft JSCalendar July 2022
A JSCalendar trigger with a type of "OffsetTrigger" maps on to a
[RFC5545] TRIGGER property with a duration value taken from the
JSCalendar "offset" property.
If the JSCalendar trigger has a "relativeTo" property with the value
"end" then the [RFC5545] TRIGGER property will have a RELATED=END
parameter.
For example:
"trigger": {
"@type": "OffsetTrigger",
"offset": "-P2D",
"relativeTo": "end"
}
maps to
TRIGGER;RELATED=END:-P2D
and
"trigger": {
"@type": "OffsetTrigger",
"offset": "-PT30M"
}
maps to
TRIGGER:-PT30M
9.1.4. todo
Need to deal with "acknowledged" and "relatedTo". Also in the
icalendar to jscalendar.
9.1.5. Example event with alerts
{
"@type": "Group",
"prodId": "//Example.org//Example V3.14//EN",
"entries": [
{
"@type": "Event",
"alerts": {
"1": {
"@type": "Alert",
"action": "display",
Stepanek & Douglass Expires 12 January 2023 [Page 52]
Internet-Draft JSCalendar July 2022
"trigger": {
"@type": "AbsoluteTrigger",
"when": "2022-05-08T12:00:00Z"
}
},
"2": {
"@type": "Alert",
"action": "display",
"description": "Breakfast meeting with executive\nteam
at 8:30 AM EST.",
"trigger": {
"@type": "OffsetTrigger",
"offset": "-PT30M"
}
},
"3": {
"@type": "Alert",
"action": "email",
"title": "*** REMINDER: SEND AGENDA FOR WEEKLY
STAFF MEETING ***",
"description": "A draft agenda needs to be sent out to
the attendees to the weekly managers meeting
(MGR-LIST). Attached is a pointer the document
template for the agenda file.",
"trigger": {
"@type": "OffsetTrigger",
"offset": "-P-2D",
"relativeTo": "end"
}
}
},
"created": "2022-05-02T20:04:12Z",
"start": "2022-06-22T12:00:00",
"timeZone": "America/New_York",
"duration": "PT1H",
"title": "event with alarms",
"uid": "6252D6C40A8308BFE25BBEFsimple-alarms-1"
}
]
}
maps to
BEGIN:VEVENT
CREATED:20220502T200412Z
DURATION:PT1H
DTSTAMP:20220502T201921Z
DTSTART;TZID=America/New_York:20220622T120000
LAST-MODIFIED:20220502T201921Z
Stepanek & Douglass Expires 12 January 2023 [Page 53]
Internet-Draft JSCalendar July 2022
SUMMARY:event with alarms
UID:6252D6C40A8308BFE25BBEFsimple-alarms-1
BEGIN:VALARM
ACTION:DISPLAY
TRIGGER;RELATED=START:-PT30M
DESCRIPTION:event with alarms
END:VALARM
BEGIN:VALARM
ACTION:DISPLAY
TRIGGER;VALUE=DATE-TIME:20220508T120000Z
DESCRIPTION:event with alarms
END:VALARM
BEGIN:VALARM
ACTION:EMAIL
TRIGGER;RELATED=END:-P2D
DESCRIPTION:A draft agenda needs to be sent out to the attendees
to the weekly managers meeting (MGR-LIST). Attached is a pointe
r the document template for the agenda file.
SUMMARY:*** REMINDER: SEND AGENDA FOR WEEKLY STAFF MEETING ***
END:VALARM
END:VEVENT
9.2. categories
Each member of the JSCalendar "categories" property maps on to a
[RFC9073] CONCEPT property with the value being the key of each
member.
For example:
...
"categories": {
"http://example.com/event-types/arts/music": true,
"http://example.com/performance-types/arts/live": true
}
...
maps to
...
CONCEPT:http://example.com/event-types/arts/music
CONCEPT:http://example.com/performance-types/arts/live
...
9.3. color
The value is copied verbatim to the [RFC7986] "COLOR" property.
Stepanek & Douglass Expires 12 January 2023 [Page 54]
Internet-Draft JSCalendar July 2022
9.4. created
The JSCalendar "created" property maps on to a [RFC5545] CREATED
property with the value being the [RFC5545] UTC date-time derived
from the value of the property.
For example:
...
"created": "2021-03-15T13:30"00Z"
...
maps to
...
CREATED:20210315T133000Z
...
9.5. duration
The JSCalendar "duration" property is only valid for event objects.
Copy the JSCalendar "duration" property in to the [RFC5545] DURATION
property.
For example:
...
"duration": "PT1H"
...
maps to
...
DURATION:PT1H
...
9.6. estimatedDuration
The JSCalendar "estimatedDuration" property is only valid for task
objects. Copy the JSCalendar "estimatedDuration" property in to the
[RFC5545] ESTIMATED-DURATION property.
For example:
Stepanek & Douglass Expires 12 January 2023 [Page 55]
Internet-Draft JSCalendar July 2022
...
"estimatedDuration": "PT18H"
...
maps to
...
ESTIMATED-DURATION:PT18H
...
9.7. keywords
Each member of the JSCalendar "keywords" property maps on to a
[RFC5545] CATEGORIES property with the value being the key of each
member.
For example:
...
"keywords": {
"APPOINTMENT": true,
"EDUCATION": true,
"MEETING": true
},
...
maps to
...
CATEGORIES:APPOINTMENT
CATEGORIES:EDUCATION
CATEGORIES:MEETING
...
or alternatively
...
CATEGORIES:APPOINTMENT,EDUCATION,MEETING
...
9.8. locations
JSCalendar locations map to [RFC9073] VLOCATION components.
Additionally, for backwards compatibility, one location should be
mapped on to a [RFC5545] LOCATION property.
Stepanek & Douglass Expires 12 January 2023 [Page 56]
Internet-Draft JSCalendar July 2022
9.8.1. coordinates
TODO. Need to decide if to use GEO or define new GEO-URI.
9.8.2. description
The "description" property maps to the DESCRIPTON property value of
the VLOCATION.
9.8.3. links
TODO. First need to define top-level links property mapping.
9.8.4. locationTypes
The keys of the "locationTypes" property map to the LOCATION-TYPE
property value of the VLOCATION. The keys MUST be separated by the
COMMA character (U+002c) and SHOULD sort in ascending alphabetical
order.
9.8.5. name
The "name" property maps to the NAME property value of the VLOCATION.
9.8.6. relativeTo
The "relativeTo" property maps to the RELATED-TO property value of
the VLOCATION. TODO need updated definition of the RELATED-TO draft.
9.8.7. timeZone
The "timeZone" property maps to the TZID property value of the
VLOCATION.
If the TimeZoneId value matches a name from the IANA Time Zone
Database [TZDB] then this value MUST be set in the TZID property.
If the TimeZoneId identifies a custom TimeZone in the JSCalendar
object, then the TZID property value MUST be set to the "tzId"
property value of the custom TimeZone object, and its related
VTIMEZONE added to the VCALENDAR component that encloses the
VLOCATION.
Stepanek & Douglass Expires 12 January 2023 [Page 57]
Internet-Draft JSCalendar July 2022
9.8.8. uid
The "uid" property maps to the UID property value of the VLOCATION.
The identifier of the Location object in the enclosing "locations"
property maps to the JMAP-ID property parameter. The parameter MAY
be omitted if the identifier of the Location matches the "uid" value.
9.9. participants
JSCalendar participants will be mapped on to different iCalendar
properties and components depending on their jsCalendar role values.
A participant with a role containing "contact" MUST be mapped on to
an iCalendar CONTACT property and SHOULD also be mapped on to a
[RFC9073]PARTICIPANT component which provides a better mapping.
A participant with a role containing "owner" MUST be mapped on to an
iCalendar ORGANIZER property and SHOULD also be mapped on to a
[RFC9073]PARTICIPANT component which provides a better mapping.
A participant with a role containing any of "attendee", "optional" or
"informational" MUST be mapped on to an iCalendar ATTENDEE property
and SHOULD also be mapped on to a [RFC9073]PARTICIPANT component
which provides a better mapping.
A more complete mapping may be achieved by creating a
[RFC9073]PARTICIPANT component.
For all properties the participants jsCalendar "language" property,
if present, is mapped on to the iCalendar "LANG" property parameter.
For all properties if the participant contains a jsCalendar "link"
with a "rel" of "alternate" then the value of the link is used for
the iCalendar "ALTREP" property parameter.
Where do we get the cua?
9.10. timezones
The JSCalendar TimeZone objects within a "timezones" property are
mapped on to [RFC5545] VTIMEZONE components within the surrounding
VCALENDAR component. Each mapped TimeZone MUST only appear once.
Stepanek & Douglass Expires 12 January 2023 [Page 58]
Internet-Draft JSCalendar July 2022
{
"@type": "Event",
...
"timezones": {
"/Example/Somewhere: {
"@type": "TimeZone",
"tzId": "Example/Somewhere",
...
},
"/Example/Somewhere-else": {
"@type": "TimeZone",
"tzId": "Example/Somewhere-else",
...
}
}
}
maps to
BEGIN: VTIMEZONE
TZID: Example/Somewhere
...
END: VTIMEZONE
BEGIN: VTIMEZONE
TZID: Example/Somewhere-else
...
END: VTIMEZONE
BEGIN: VEVENT
...
END: VEVENT
When converting multiple Event or Task objects the surrounding
[RFC5545] VCALENDAR object must have a [RFC5545] PRODID set from
either the Group "prodid" or generated.
10. Translating non-standard JSCalendar to iCalendar
JSCalendar objects may contain properties for which no standard
mapping to iCalendar is defined. This may occur for vendor-extension
properties (Section 3.3 of [draft-ietf-calext-jscalendarbis]) or any
other property for which there no standard mapping is defined.
This section defines properties and parameters with which
implementations SHOULD map such data. Applications that have more
insight into the semantics of such iCalendar entries MAY choose to
map differently.
Stepanek & Douglass Expires 12 January 2023 [Page 59]
Internet-Draft JSCalendar July 2022
NOTE: The verbatim XXXX values in this section will be replaced with
the RFC number of this document before publication. Also, the
following properties require a redefinition of vendor-extension
properties for JSCalendar. Currently, only domain names are allowed
as prefix for vendor extensions. This document assumes that also
URIs with the urn scheme are allowed.
10.1. New iCalendar properties
10.1.1. X-RFCXXXX-JSPROP Property
Property name: X-RFCXXXX-JSPROP
Purpose: This property embeds JSCalendar properties in iCalendar.
Value type: URI, also see Format Definition for value restrictions.
Conformance: The property can be specified multiple times in a
calendar component.
Property parameters: The X-RFCXXXX-JSNAME parameter MUST be set
exactly once for this property. The VALUE parameter MAY be set
once, in which case its value MUST be URI. Other IANA and non-
standard property parameters can be specified on this property.
Description: This property maps a JSCalendar property to iCalendar.
The property name is defined using the X-RFCXXXX-JSNAME parameter
(Section 10.2.1). The property value is encoded as a URL using
the data scheme [RFC2397]. The media type MUST be specified as
application/json and MUST NOT define parameters. The property
value MAY be any Javascript Object Notation (JSON) [RFC8259] value
restricted by the I-JSON [RFC7493] profile, be that a JSON object,
array, string, number, true or false.
Format definition: This property is defined by the following
notation:
Stepanek & Douglass Expires 12 January 2023 [Page 60]
Internet-Draft JSCalendar July 2022
jsprop = "X-RFCXXXX-JSPROP" jsprop-param ":" jsprop-value CRLF
jsprop-value = "data:application/json" [";base64"] "," data
; data is defined in RFC 2397, section 3
jsprop-param = *(
; The following is MANDATORY and MUST NOT
; occur more than once
jsname-param /
;
; The following is OPTIONAL,
; but MUST NOT occur more than once.
;
(";" "VALUE" "=" "URI" ) /
;
; The following is OPTIONAL,
; and MAY occur more than once.
;
(";" other-param)
;
)
Example(s):
;
; encodes the property
; ...
; "foo": {
; "bar": 1234
; }
;
X-RFCXXXX-JSPROP;X-RFCXXXX-JSNAME="foo"
:data:application/json;base64,eyJiYXIiOiAxMjM0fQ==
10.1.2. X-RFCXXXX-PROP Property
Property name: X-RFCXXXX-PROP
Purpose: This property embeds simple-typed JSCalendar properties in
iCalendar.
Value type: Default is none. It MAY be set to BOOLEAN, FLOAT or
INTEGER.
Conformance: The property can be specified multiple times in a
calendar component.
Property parameters: The X-RFCXXXX-JSNAME parameter MUST be set
Stepanek & Douglass Expires 12 January 2023 [Page 61]
Internet-Draft JSCalendar July 2022
exactly once for this property. The VALUE parameter MAY be set
once, in which case its value MUST be BOOLEAN, FLOAT or INTEGER.
Other IANA and non-standard property parameters can be specified
on this property.
Description: This property maps a simple-valued JSCalendar property
to iCalendar. The property name is defined using the X-RFCXXXX-
JSNAME parameter. (Section 10.2.1). The property value is set by
the following rules:
* If the JSON property value is a string and its contents solely
consists of characters defined in the value ABNF of Section 3.1
of [RFC5545], then the iCalendar property value is a verbatim
copy of the JSON property value. The VALUE parameter MUST NOT
be set.
* If the JSON property value is a number without fractional and
exponent, then the iCalendar property value is a verbatim copy
of the JSON property value. The VALUE parameter SHOULD be
INTEGER if the JSON property is known to only allow integer
values. Otherwise the parameter value MUST be FLOAT.
* If the JSON property value is a number with fractional or
exponent, then the iCalendar property value is a verbatim copy
of the JSON property value. The VALUE parameter MUST be FLOAT.
* If the JSON property value is verbatim true then the iCalendar
property value is TRUE, or false and FALSE, respectively. The
VALUE parameter MUST be BOOLEAN.
* If none of the above rules match, then the JSCalendar property
MUST NOT map to the X-RFCXXXX-PROP property. Instead, it MAY
map to the X-RFCXXXX-JSPROP (Section 10.1.1) property.
Format definition: This property is defined by the following
notation:
jsprop-short = "X-RFCXXXX-PROP"
(
jsprop-string /
jsprop-int /
jsprop-float /
jsprop-bool
)
jsprop-string = *(
; The following is MANDATORY and MUST NOT
; occur more than once
Stepanek & Douglass Expires 12 January 2023 [Page 62]
Internet-Draft JSCalendar July 2022
jsname-param /
;
; The following MUST NOT occur
;
(";" "VALUE" "=" valuetype ) /
;
; The following is OPTIONAL,
; and MAY occur more than once.
;
(";" other-param)
;
)
":" value ; defined in RFC5545, section 3.1
jsprop-int = *(
; The following are MANDATORY and each MUST NOT
; occur more than once
jsname-param /
( "VALUE" "=" "INTEGER" )
;
; The following is OPTIONAL,
; and MAY occur more than once.
;
(";" other-param)
;
)
":" integer ; defined in RFC5545, section 3.3.8
jsprop-float = *(
; The following are MANDATORY and each MUST NOT
; occur more than once
jsname-param /
( "VALUE" "=" "FLOAT" )
;
; The following is OPTIONAL,
; and MAY occur more than once.
;
(";" other-param)
;
)
":" float ; defined in RFC5545, section 3.3.7
jsprop-bool = *(
; The following are MANDATORY and each MUST NOT
; occur more than once
jsname-param /
( "VALUE" "=" "BOOLEAN" )
;
Stepanek & Douglass Expires 12 January 2023 [Page 63]
Internet-Draft JSCalendar July 2022
; The following is OPTIONAL,
; and MAY occur more than once.
;
(";" other-param)
;
)
":" boolean ; defined in RFC5545, section 3.3.2
Example(s):
;
; encodes the property
; ...
; "foo": 12.3
;
X-RFCXXXX-PROP
;X-RFCXXXX-JSNAME="foo"
;VALUE=FLOAT
:12.3
10.2. New iCalendar Parameters
10.2.1. X-RFCXXXX-JSNAME Parameter
Parameter name: X-RFCXXXX-JSNAME
Purpose: This parameter assigns a JSCalendar property name to
JSCalendar data embedded in an iCalendar property.
Format definition:
jsname-param = "X-RFCXXXX-JSNAME" "=" DQUOTE *QSAFE-CHAR DQUOTE
Description: This parameter is set on a X-RFCXXXX-JSPROP or X-
RFCXXXX-PROP property. It assigns the JSCalendar property name to
the value embedded in the iCalendar property value. The parameter
value contains the verbatim name of the JSCalendar property. It
MUST be quoted to preserve case.
Example(s):
X-RFCXXXX-PROP;X-RFCXXXX-JSNAME="fooBar":baz
11. JsCalendar base spec updates
* Make title and description optional in an alert. Used to hold
SUMMARY and DESCRIPTION if present.
Stepanek & Douglass Expires 12 January 2023 [Page 64]
Internet-Draft JSCalendar July 2022
12. Security Considerations
The same security considerations as for [RFC8984] apply.
13. IANA Considerations
None.
14. Acknowledgments
The authors would like to thank the members of CalConnect for their
valuable contributions. This specification originated from the work
of the API technical committee of CalConnect, the Calendaring and
Scheduling Consortium.
15. References
15.1. Normative References
[draft-ietf-calext-ical-relations]
"Support for iCalendar Relationships",
<https://tools.ietf.org/html/draft-ietf-calext-ical-
relations>.
[draft-ietf-calext-jscalendarbis]
"JSCalendar: A JSON Representation of Calendar Data",
<https://tools.ietf.org/html/draft-ietf-calext-
jscalendarbis>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC2397] Masinter, L., "The "data" URL scheme", RFC 2397,
DOI 10.17487/RFC2397, August 1998,
<https://www.rfc-editor.org/info/rfc2397>.
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006,
<https://www.rfc-editor.org/info/rfc4648>.
[RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and
Scheduling Core Object Specification (iCalendar)",
RFC 5545, DOI 10.17487/RFC5545, September 2009,
<https://www.rfc-editor.org/info/rfc5545>.
Stepanek & Douglass Expires 12 January 2023 [Page 65]
Internet-Draft JSCalendar July 2022
[RFC5546] Daboo, C., Ed., "iCalendar Transport-Independent
Interoperability Protocol (iTIP)", RFC 5546,
DOI 10.17487/RFC5546, December 2009,
<https://www.rfc-editor.org/info/rfc5546>.
[RFC6638] Daboo, C. and B. Desruisseaux, "Scheduling Extensions to
CalDAV", RFC 6638, DOI 10.17487/RFC6638, June 2012,
<https://www.rfc-editor.org/info/rfc6638>.
[RFC6868] Daboo, C., "Parameter Value Encoding in iCalendar and
vCard", RFC 6868, DOI 10.17487/RFC6868, February 2013,
<https://www.rfc-editor.org/info/rfc6868>.
[RFC7265] Kewisch, P., Daboo, C., and M. Douglass, "jCal: The JSON
Format for iCalendar", RFC 7265, DOI 10.17487/RFC7265, May
2014, <https://www.rfc-editor.org/info/rfc7265>.
[RFC7493] Bray, T., Ed., "The I-JSON Message Format", RFC 7493,
DOI 10.17487/RFC7493, March 2015,
<https://www.rfc-editor.org/info/rfc7493>.
[RFC7986] Daboo, C., "New Properties for iCalendar", RFC 7986,
DOI 10.17487/RFC7986, October 2016,
<https://www.rfc-editor.org/info/rfc7986>.
[RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", STD 90, RFC 8259,
DOI 10.17487/RFC8259, December 2017,
<https://www.rfc-editor.org/info/rfc8259>.
[RFC8984] Jenkins, N. and R. Stepanek, "JSCalendar: A JSON
Representation of Calendar Data", RFC 8984,
DOI 10.17487/RFC8984, July 2021,
<https://www.rfc-editor.org/info/rfc8984>.
[RFC9073] Douglass, M., "Event Publishing Extensions to iCalendar",
RFC 9073, DOI 10.17487/RFC9073, August 2021,
<https://www.rfc-editor.org/info/rfc9073>.
[RFC9074] Daboo, C. and K. Murchison, Ed., ""VALARM" Extensions for
iCalendar", RFC 9074, DOI 10.17487/RFC9074, August 2021,
<https://www.rfc-editor.org/info/rfc9074>.
15.2. Informative References
[TZDB] IANA, "Time Zone Database",
<https://www.iana.org/time-zones>.
Stepanek & Douglass Expires 12 January 2023 [Page 66]
Internet-Draft JSCalendar July 2022
Authors' Addresses
Robert Stepanek
FastMail
PO Box 234
Collins St West
Melbourne VIC 8007
Australia
Email: rsto@fastmailteam.com
URI: https://www.fastmail.com
Michael Douglass
Bedework Commercial Services
226 3rd Street
Troy, NY 12180
United States of America
Email: mdouglass@bedework.com
URI: http://bedework.com
Stepanek & Douglass Expires 12 January 2023 [Page 67]
