JSCalendar: Converting from and to iCalendar
FastMail
PO Box 234
Collins St West
Melbourne
VIC 8007
Australia
neilj@fastmailteam.com
https://www.fastmail.com
FastMail
PO Box 234
Collins St West
Melbourne
VIC 8007
Australia
rsto@fastmailteam.com
https://www.fastmail.com
Applications
Calendaring extensions
JSON
iCalendar
calendar
events
date
time
This document provides an informational guideline for converting
JSCalendar from and to iCalendar.
The JSCalendar data format
is used to represent calendar data, and is meant as an alternative to
the widely deployed iCalendar data format.
While new calendaring services and applications might use JSCalendar
as their main data format to exchange calendaring data, they are
likely to interoperate with services and clients that just support iCalendar.
Similarly, existing calendaring data is stored in iCalendar format
in databases and other calendar stores, and providers and users might
want to represent this data also in JSCalendar. Lastly, some implementations
might want to preserve custom iCalendar properties, that have no
equivalent in JSCalendar when converting between these formats.
To facilitate these use cases, this document provides an
informational guide how to convert JSCalendar data from and to
iCalendar.
JSCalendar and iCalendar have a lot of semantics in common, but
they are not interchangeable formats:
JSCalendar contains a richer data model to express calendar
information such as event locations and participants;
while future iCalendar extensions
may allow a direct mapping, for now there may be no representation
directly in iCalendar of some properties and these have been marked
as implementation specific for mapping.
iCalendar may contain arbitrary, non-standardised data with custom
properties/attributes. Translating these into JSCalendar is implementation
specific.
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.
Accordingly, this document does not standardize a canonical translation
between iCalendar and JSCalendar, and implementations MUST NOT make
any assumptions how iCalendar data is represented in JSCalendar
by other systems.
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
.
A JSEvent maps to the the iCalendar VEVENT component type
.
The following tables maps the JSEvent-specific properties to iCalendar:
Property
iCalendar counterpart
duration
DURATION property.
If the VEVENT contains a DTEND
property, the this maps to the duration property
as the time span between DTSTART and DTEND when converting the
respective time points to the UTC time zone.
A JSTask object maps to the iCalendar VTODO component type
.
The following tables maps the JSTask-specific properties to iCalendar:
Property
iCalendar counterpart
due
DUE property
estimatedDuration
ESTIMATED-DURATION property in the RFC draft ,
or the DURATION property otherwise.
statusUpdatedAt
COMPLETED property. The JSTask status property
MUST have value completed.
progress
PARTSTAT and COMPLETED properties, including the
definitions in the RFC draft .
status
STATUS property, including the
definitions in the RFC draft .
A JSGroup maps to a iCalendar VCALENDAR containing VEVENT or VTODO components.
Property
iCalendar counterpart
entries
VEVENT and VTODO components embedded in a VCALENDAR component.
source
SOURCE property.
This section contains recommendations how to map JSCalendar from and to iCalendar.
It lists all common JSCalendar object properties in alphabetical order.
Property
iCalendar counterpart
@type
Determined by the iCalendar component type: jsevent
for VEVENT, jstask for VTODO,
jsgroup for VCALENDAR.
alerts
Each entry maps to a VALARM component.
The ACTION property maps to action, where
both DISPLAY and AUDIO
values map to the display action. An EMAIL value maps
to a JSCalendar email action.
relativeTo and offset
map to the TRIGGER property.
categories
CONCEPT property, defined in .
color
COLOR property, as specified in .
created
CREATED property.
description
DESCRIPTION property.
descriptionContentType
Implementation-specific.
excluded
EXDATE property.
freeBusyStatus
TRANSP property.
isAllDay
See .
keywords
CATEGORIES property, as specified in .
links
ATTACH (), URL or IMAGE ()
properties with URI value types map to the the Link href.
The FMTTYPE parameter maps to type,
the SIZE parameter to size.
Mapping other properties is implementation-specific.
locale
LANGUAGE parameter of the SUMMARY or DESCRIPTION property.
localizations
Implementation-specific.
locations
See .
method
METHOD property of the embedding VCALENDAR.
participants
See .
priority
PRIORITY property.
privacy
CLASS property.
prodId
PRODID property.
recurrenceOverrides
RDATE and EXDATE properties, and any VEVENT or
VTODO instances with a recurrence-id and same UID
as the mapped main object.
recurrenceRule
RRULE property. For all-day calendar objects,
map the until property value to an iCalendar
DATE (effectively removing the time component). To convert a DATE-typed UNTIL
from iCalendar, set the time components of the LocalDate value to
23:59:59. If the iCalendar UNTIL value is a
UTC date time, convert it to the local time in the JSCalendar calendar
object time zone.
relatedTo
RELATED-TO property.
replyTo
An iCalendar ORGANIZER with a mailto: URI mapped to the
imip method, or any other
URI mapped to the other
method. Mapping multiple methods is implementation-specific.
sequence
SEQUENCE property.
start
See .
status
STATUS property.
timeZone
See .
timeZones
Each entry in the property maps to a VTIMEZONE in the embedding VCALENDAR component.
title
SUMMARY property.
uid
UID property.
updated
DTSTAMP and LAST-MODIFIED properties.
useDefaultAlerts
Implementation-specific.
virtualLocations
See .
JSEvent and JSTask objects share the start,
timeZone and isAllDay
properties to express their occurrence in time.
The following table defines how to map these properties:
Property
iCalendar counterpart
start and non-null timeZone
The start property value maps to
an iCalendar DTSTART of type local DATE-TIME and the
timeZone value to its TZID
parameter. If the time zone is Etc/UTC,
then the start time may alternatively map to an iCalendar
UTC DATE-TIME without a TZID parameter.
start and isAllDay is true
The start property value maps to
an iCalendar DTSTART property value of type DATE. When mapping
from iCalendar, the time component of the
start property value is zero.
start and null timeZone and isAllDay is false
The start property value maps
to an iCalendar DTSTART of type local DATE-TIME and no TZID
parameter.
The iCalendar counterpart for JSCalendar Location objects is the iCalendar
LOCATION property, or implementation-specific.
Property
iCalendar counterpart
coordinates
GEO property.
description
Implementation-specific.
linkIds
Implementation-specific.
name
LOCATION property value.
rel
Implementation-specific.
timeZone
Implementation-specific.
uri
The LOCATION ALTREP parameter.
The iCalendar counterpart for JSCalendar VirtualLocation objects is the iCalendar
CONFERENCE property.
Property
iCalendar counterpart
description
Implementation-specific.
name
LABEL parameter.
uri
CONFERENCE property value.
The following table outlines translation of JSCalendar participants.
An iCalendar ORGANIZER maps to replyTo
and a participant with role owner. If
an ATTENDEE with the same CAL-ADDRESS value exists, then it maps
to the same participant as the ORGANIZER participant. Other participants
map to ATTENDEEs.
Property
iCalendar counterpart
attendance
ROLE parameter values REQ-PARTICIPANT, OPT-PARTICIPANT and
NON-PARTICIPANT.
delegatedFrom
DELEGATED-FROM parameter
delegatedTo
DELEGATED-TO parameter
email
EMAIL parameter, if
defined. Otherwise the CAL-ADDRESS property value, if it is a mailto: URI.
expectReply
RSVP parameter
kind
CUTYPE parameter
linkIds
Implementation-specific.
locationId
Implementation-specific.
memberOf
MEMBER parameter
name
CN parameter
participationStatus
PARTSTAT parameter
roles
ROLE parameter.
scheduleSequence
SEQUENCE property of the participant's latest iMIP message
scheduleUpdated
DTSTAMP property of the participant's latest iMIP message
sendTo
A CAL-ADDRESS with a mailto: URI maps to the
JSCalendar imip method, any other
URI to the other
method. Mapping multiple methods is implementation-specific.
Mapping custom or unknown properties between JSCalendar and iCalendar
is implementation-specific. Implementations might use vendor-extension
properties, which could
also serve as basis for discussion for a JSCalendar standard extension.
Alternatively, an implementation could preserve iCalendar properties
and components in JSCalendar by use of a vendor-extension
property formatted as jCal data.
The same security considerations as for apply.
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.
Task Extensions to iCalendar
Task Extensions to iCalendar
Support for iCalendar Relationships