JSCalendar: Converting from and to iCalendar

JSCalendar: Converting from and to iCalendar Fastmail

PO Box 234 Collins St West Melbourne VIC 8007 Australia rsto@fastmailteam.com https://www.fastmail.com

Applications Calendaring extensions JSON iCalendar JSCalendar calendar events date time This document defines how to convert calendaring information between the JSCalendar and iCalendar data formats. It considers every JSCalendar and iCalendar element registered at IANA at the time of publication. It defines conversion rules for all elements that are common to both formats, as well as how convert arbitrary or unknown JSCalendar and iCalendar elements. This document is unfinished. The term TBD stands for any unknown item.

Introduction

Notational Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here. The ABNF definitions in this document use the notations of . ABNF rules not defined in this document either are defined in or .

Scope and Goals This document outlines how to convert calendaring information between the iCalendar and JSCalendar data formats. It describes which elements are common to both, but also highlights where the two formats differ. For each common element, it defines a conversion rule and includes an example how to convert this element. All iCalendar and JSCalendar elements currently registered at IANA are in scope, but not all of these elements are common to both formats. For elements that have no counterpart in the other format, it is the goal of this document to define how to preserve them during conversion, but in general it is not the goal to achieve this by defining new standard elements. Instead, this document defines special-purpose properties to preserve arbitrary elements. These conversion-specific properties are defined in Section for iCalendar, and Sections and for JSCalendar. further outlines the discrepancies between the two formats.

How to Read the Examples Later sections contain examples that illustrate how to convert between the iCalendar and JSCalendar data formats. The notation of these examples is such that their main points should be clear to the reader, but their contents can also be parsed for automated testing. The authors of this document implemented a tool that extracts these examples for interoperation testing. The following sections define the notation for such examples.

iCalendar Examples An iCalendar example contains either an extract or a complete representation of iCalendar data. It always represents an iCalendar object, even if the example only depicts non-VCALENDAR components or properties. An example that only contains iCalendar properties implicitly represents a VEVENT component that is part of a VCALENDAR component. An example that only contains one or more non-VCALENDAR components implicitly represents a VCALENDAR component that contains them. Implicit components are assumed to contain mandatory properties with some value, but the actual value is irrelevant for the main point of the example. Notably, if an implicit component includes an ATTENDEE but not an ORGANIZER property, then an ORGANIZER property implicitly is present, too. The same applies for an example with an ORGANIZER but no ATTENDEE property. contains three examples, all of which represent the same iCalendar data. In the first example, both the VEVENT component and VCALENDAR component are implicit. In the second example, only the VCALENDAR component and its mandatory properties are implicit. The third example depicts a complete VCALENDAR component, nothing is implicit.

Examples for implicit and explicit iCalendar component notation A line containing just the value ... stands for any other properties that might be present in a component but are irrelevant for this example. This includes mandatory properties as described for implicit components. The line ... at the end of the example additionally stands for any END content lines to complete components that started with BEGIN content lines, and any of their missing mandatory properties. illustrates this as an alternative representation for the examples of .

Example for additional properties and component ENDs represented by ... A line starting with a single space represents the continuation of a folded content line (). illustrates this.

Example for a folded content line

JSCalendar Examples A JSCalendar example always represents a Group object, even if the example only depicts one of the Group entries or properties. JSCalendar objects are depicted either explicitly or implicitly. An explicit JSCalendar object starts and ends with braces. An implicit JSCalendar object omits braces, it only consists of JSON name/value pairs, separated by comma. An implicit JSCalendar object is assumed to be of type Event, unless it contains the @type property with a different value. It is assumed to contain all mandatory properties with some value; if they are not depicted, their actual value is irrelevant for the main point of the example. illustrates this with multiple examples, all of which represent the same JSCalendar data. The first example contains an implicit JSCalendar object of type Event. The second example contains an implicit JSCalendar object with a @type property. The third example contains an explicit Event object but the Group object containing it is omitted. The fourth example contains the full Group object, nothing is omitted.

Examples for implicit and explicit JSCalendar object notation A property with name "..." and value "" stands for additional properties that might be present in a JSCalendar object, but which are irrelevant for this example. This includes mandatory properties. illustrates this as an alternative representation for the examples of .

Example for additional properties represented by ...

Converting iCalendar to JSCalendar

General rules

iCalendar Objects allows for an iCalendar stream to contain one or more iCalendar objects. In contrast, this specification only defines conversion for streams consisting of a single iCalendar object. Converting streams of multiple iCalendar objects is implementation-specific. All following sections of this document use the terms "iCalendar object" and "VCALENDAR component" interchangeably. The VCALENDAR component converts to a Group object. Its properties convert as follows: Properties of the VCALENDAR component

Name	Reference	Group property	See	Note
CATEGORIES		keywords
COLOR		color
CONCEPT		categories
CREATED		created
DESCRIPTION		description
LAST-MODIFIED		updated
LINK		links
METHOD		entries/*/method
NAME		title
PRODID		prodId, entries/*/prodId
SOURCE		source
UID		uid
URL		links

Its components convert as follows: Components of the VCALENDAR component

Name	Reference	Group property	See	Note
VEVENT		entries
VTIMEZONE		timeZones
VTODO		entries

Other properties or components MAY be converted to the iCalComponent property of the Group object. The following example illustrates how to convert the VCALENDAR component:

Converting the VCALENDAR component

Recurring Components Components in an iCalendar object generally convert to distinct JSCalendar objects. For example, two VEVENT components with different UID property values in the same iCalendar object convert to two separate Event objects in the Group object's entries. This rule does not apply to recurrence overrides, defined as follows. A VEVENT (or VTODO) component is a recurrence override if it has the RECURRENCE-ID property set, and the iCalendar object contains a VEVENT (or VTODO) component that does not have the RECURRENCE-ID but the RRULE property set, and the UID property values of the two components are equal. The component without the RECURRENCE-ID property is in that case referred to as the "main component". The main component converts to an entry in the Group object's entries property. The recurrence override converts to the recurrenceOverrides property of the converted main component. Its RECURRENCE-ID property value converts to the key in the recurrenceOverrides property. The value of the recurrenceOverrides property at that key is the PatchObject that transform the converted main component into the converted recurrence override. The recurrenceId and recurrenceIdTimeZone properties MUST NOT be set in the PatchObject. The following example illustrates how to convert a main component and its recurrence override:

Converting VEVENT recurrence overrides A VEVENT (or VTODO) component is a stand-alone recurrence instance if it has the RECURRENCE-ID property set and the iCalendar object does not contain its related main component. Each stand-alone recurrence instance converts to a distinct Event (or Task) object in the Group object's entries property. The recurrenceId property MUST be set, the recurrenceIdTimeZone property MUST be set if not "null". The converted objects sort in order of appearance of the iCalendar components. The following example illustrates how to convert stand-alone recurrence instances:

Converting VEVENT recurrence instances

JSCalendar Ids JSCalendar generally uses JSON objects to represent a collection of same-typed values. The keys are of type Id, the values are JSCalendar object types. If an iCalendar element converts to a value in such a collection, then an implementation needs to choose an identifier as key. This document defines the new JSCALID parameter and JSCALID property, which allow to set a JSCalendar Id value when converting from JSCalendar to iCalendar. If they are set on a property or the component, then its value MUST be used as key when converting that element from iCalendar to JSCalendar. If no such parameter or property is set, then an implementation is free to choose any identifier, as long the following requirements are met:

The identifier MUST be a valid Id value.
The identifiers for the exact same iCalendar element MUST stay the same, irrespective of the order in which components, properties and parameters are processed.

Timezone identifiers Converting temporal properties such as DTSTART, DTEND, and RECURRENCE-ID requires to not only determine the date and time of the property value, but also the timezone it references. If the property value data type is DATE or DATE-TIME in FORM #1: DATE WITH LOCAL TIME then the timezone identifier is the JSON null value in JSCalendar. If the property value data type is DATE-TIME in FORM #2: DATE WITH UTC TIME then the timezone identifier is the string "Etc/UTC" in JSCalendar. If the property value data type is DATE-TIME in FORM #3: DATE WITH LOCAL TIME AND TIME ZONE REFERENCE then the timezone identifier is determined by the TZID parameter value: If the TZID parameter value is equal to a name in the IANA Time Zone Database then the timezone identifier is that verbatim name. If the TZID parameter value is unequal to an IANA timezone name then implementations MAY determine the name of an IANA timezone which has the same timezone rules over the timespan of the calendar object. Otherwise, the non-IANA timezone identifier is represented in JSCalendar as a string starting with the / (SLASH) character, followed by the TZID parameter value. The corresponding VTIMEZONE MUST be converted to the timeZones property with the prefixed identifier as key. See for an example.

DATE and DATE-TIME iCalendar provides the DATE and DATE-TIME value types to distinguish date-only from date-time values. JSCalendar only supports date-time values. A property value of type DATE-TIME converts to either a LocalDateTime or UTCDateTime, depending on the JSCalendar property definition. A DATE value type converts to a LocalDateTime with zero time.

Components

PARTICIPANT The PARTICIPANT component converts to a Participant object. Its properties convert as follows: Properties of the PARTICIPANT component

Name	Participant property	Note
ATTACH	links
CALENDAR-ADDRESS	calendarAddress
COMMENT	participationComment	Only one comment supported
DESCRIPTION	description
DTSTAMP	scheduleUpdated
GEO	locations
LINK	links
LOCATION	locations
PARTICIPANT-TYPE	roles
SEQUENCE	scheduleSequence
STRUCTURED-DATA	links
SUMMARY	name
URL	links

Its components convert as follows: Components of the PARTICIPANT component

Name	Reference	Participant property	See	Note
VLOCATION		locations

Other properties or components MAY be converted to the iCalComponent property of the Participant object. This includes mandatory properties such as UID. The following example illustrates how to convert the PARTICIPANT component:

Converting the PARTICIPANT component

VALARM The VALARM component converts to a Alert object. Its properties convert as follows: Properties of the VALARM component

Name	Alert property	Note
ACKNOWLEDGED	acknowledged
ACTION	action	Only if ACTION is EMAIL or DISPLAY.
RELATED-TO	relatedTo
TRIGGER	trigger

Other properties or components MAY be converted to the iCalComponent property of the Alert object. This includes mandatory properties such as ATTENDEE, DESCRIPTION, or SUMMARY. The following example illustrates how to convert the VALARM component:

Converting the VALARM component

VEVENT The VEVENT component converts to a Event object. VEVENT components with different UID property values in the same iCalendar object convert to different entries in the Group. They sort in the same order as in the VCALENDAR component. Its properties convert as follows: Properties of the VEVENT component

Name	Reference	Event property	See	Note
ATTACH		links
ATTENDEE		participants
CATEGORIES		keywords
CLASS		privacy
COLOR		color
COMMENT		participants/*/participationComment
CONCEPT		categories
CONFERENCE		virtualLocations
CREATED		created
DESCRIPTION		description
DTEND		duration
DTSTAMP		updated, scheduleUpdated
DTSTART		start
DURATION		duration
EXDATE		recurrenceOverrides
EXRULE		excludedRecurrenceRules
GEO		locations
IMAGE		links
LAST-MODIFIED		updated
LINK		links
LOCATION		locations
ORGANIZER		replyTo
PRIORITY		priority
RDATE		recurrenceOverrides
RECURRENCE-ID		recurrenceId
RELATED-TO		relatedTo
REQUEST-STATUS		requestStatus
RRULE		recurrenceRules
SEQUENCE		sequence
STATUS		status
STRUCTURED-DATA		links
STYLED-DESCRIPTION		description
SUMMARY		title
TRANSP		freeBusyStatus
UID		uid
URL		links

Its components convert as follows: Components of the VEVENT component

Name	Reference	Event property	See	Note
VALARM		alerts

Other properties or components MAY be converted to the iCalComponent property of the Event object. The following example illustrates how to convert the VEVENT component:

Converting the VEVENT component

VLOCATION The VLOCATION component converts to a Location object. Its properties convert as follows: Properties of the VLOCATION component

Name	Reference	Location property	See	Note
ATTACH		links
DESCRIPTION		description
GEO		coordinates
IMAGE		links
LINK		links
LOCATION-TYPE		locationTypes
NAME		name
STRUCTURED-DATA		links

Other properties or components MAY be converted to the iCalComponent property of the Location object. This includes mandatory properties such as UID. The following example illustrates how to convert the VLOCATION component:

Converting the VLOCATION component

VRESOURCE The VRESOURCE component converts to a Participant object. Its properties convert as follows: Properties of the VRESOURCE component

Name	Reference	Participant property	See	Note
ATTACH		links
DESCRIPTION		description
GEO		locations
IMAGE		links
LINK		links
NAME		name
STRUCTURED-DATA		links

Converting the VRESOURCE component

VTIMEZONE The VTIMEZONE component converts to a TimeZone object. Its properties convert as follows: Properties of the VTIMEZONE component

Name	Reference	TimeZone property	See	Note
LAST-MODIFIED		updated
TZID		tzId
TZID-ALIAS-OF		aliases
TZUNTIL		validUntil
TZURL		url

Its components convert as follows: Components of the VTIMEZONE component

Name	Reference	TimeZone property	See	Note
DAYLIGHT		daylight	In this section
STANDARD		standard	In this section

Other properties or components MAY be converted to the iCalComponent property of the TimeZone object. The DAYLIGHT component and STANDARD component convert to a TimeZoneRule object. Their properties convert as follows: Properties of the DAYLIGHT or STANDARD component

Name	Reference	TimeZoneRule property	See	Note
COMMENT		comments
DTSTART		start
RDATE		recurrenceOverrides
RRULE		recurrenceRules
TZNAME		names
TZOFFSETFROM		offsetFrom
TZOFFSETTO		offsetTo

Other properties or components MAY be converted to the iCalComponent property of the TimeZoneRule object. The following example illustrates how to convert the VTIMEZONE component:

Converting the VTIMEZONE component

VTODO The VTODO component converts to a Task object. VTODO components with different UID property values in the same iCalendar object convert to different entries in the Group. They sort in the same order as in the VCALENDAR component. Its properties convert as follows: Properties of the VTODO component

Name	Reference	Task property	See	Note
ATTACH		links
ATTENDEE		participants
CATEGORIES		keywords
CLASS		privacy
COLOR		color
COMMENT		participants/*/participationComment
CONCEPT		categories
CONFERENCE		virtualLocations
CREATED		created
DESCRIPTION		description
DTSTAMP		updated, scheduleUpdated
DTSTART		start
DUE		due
DURATION		duration
EXDATE		recurrenceOverrides
EXRULE		excludedRecurrenceRules
GEO		locations
IMAGE		links
LAST-MODIFIED		updated
LINK		links
LOCATION		locations
ORGANIZER		replyTo
PERCENT-COMPLETE		percentComplete
PRIORITY		priority
RDATE		recurrenceOverrides
RECURRENCE-ID		recurrenceId
RELATED-TO		relatedTo
REQUEST-STATUS		requestStatus
RRULE		recurrenceRules
SEQUENCE		sequence
STRUCTURED-DATA		links
STYLED-DESCRIPTION		description
SUMMARY		title
TRANSP		freeBusyStatus
UID		uid
URL		links

Its components convert as follows: Components of the VTODO component

Name	Reference	Task property	See	Note
VALARM		alerts

Other properties or components MAY be converted to the iCalComponent property of the Task object. The following example illustrates how to convert the VTODO component:

Converting the VTODO component

Properties

ACKNOWLEDGED The ACKNOWLEDGED property in a VALARM component converts to the acknowledged property of the Alert object. The following example illustrates how to convert the ACKNOWLEDGED property:

Converting the ACKNOWLEDGED property

ACTION The ACTION property in a VALARM component converts to the action property of the Alert object. Its values convert as follows: Values of the ACTION property

iCalendar value	JSCalendar value
DISPLAY	display
EMAIL	email

An ACTION property with value AUDIO or any other not listed in does not convert to the action property. Instead, the property converts to the iCalComponent/properties property of the Alert. The following examples illustrate how to convert the ACTION property:

Converting the ACTION property for value DISPLAY

Converting the ACTION property for value AUDIO

ATTACH The ATTACH property in a VEVENT, VTODO, VRESOURCE, PARTICIPANT, or VLOCATION component converts to a Link object. The converted object is set in the links property of the Event, Task, Participant, or Location object. The property value converts to the href property of the Link object. A value of type URI converts as-is. A value of type BINARY converts to a URI in the "data" URL scheme (. If the FMTTYPE parameter is set on the ATTACH property, then the parameter value SHOULD be set in the mediatype part of the data URL. The ATTACH property parameters convert as follows: Parameters of the ATTACH property

Name	Reference	Link Property	Note
FMTTYPE		contentType
SIZE		size

The following examples illustrate how to convert the ATTACH property:

Converting the ATTACH property with URI value

Converting the ATTACH property with BINARY value

ATTENDEE The ATTENDEE property in a VEVENT or VTODO component converts to a Participant object. The converted object is set in the participants property of the Event or Task object. The property value converts to both the calendarAddress and sendTo properties of the Participant object. If the CAL-ADDRESS value is in the "mailto" scheme, then it converts to the "imip" method in the sendTo property, otherwise it converts to the "other" method. The ATTENDEE property parameters convert as follows: Parameters of the ATTENDEE property

Name	Reference	Participant Property	Note
CN		name
CUTYPE		kind
DELEGATED-FROM		delegatedFrom
DELEGATED-TO		delegatedTo
DIR		links
EMAIL		email
MEMBER		memberOf
PARTSTAT		participationStatus
ROLE		roles
RSVP		expectReply
SCHEDULE-AGENT		scheduleAgent
SCHEDULE-FORCE-SEND		scheduleForceSend
SCHEDULE-STATUS		scheduleStatus

If no ROLE parameter is set, then the "attendee" role in the roles property MUST be set. Every calendar address value of the DELEGATED-FROM, DELEGATED-TO, or MEMBER parameters converts to the identifier of an Participant object. This identifier is determined by finding that Participant object in the participants property, which has a calendarAddress property value matching the parameter value. If no such Participant object exists after all properties and components have been converted, then a new Participant object having that calendarAddress property value is created. If multiple Participant objects match, then choosing the Participant identifier is implementation-specific. An ATTENDEE property and a PARTICIPANT component in the same iCalendar component convert to the same Participant object, if their converted calendarAddress property values are equal after URI normalization. How to deal with conflicting values when converting other Participant properties is implementation-specific. The following examples illustrate how to convert the ATTENDEE property:

Converting the ATTENDEE property

Converting the ATTENDEE property and PARTICIPANT component

CALENDAR-ADDRESS The CALENDAR-ADDRESS property in a PARTICIPANT component converts to the calendarAddress property of the Participant object. The following example illustrates how to convert the CALENDAR-ADDRESS property:

Converting the CALENDAR-ADDRESS property

CATEGORIES The CATEGORIES property in a VEVENT, VTODO, or VCALENDAR component converts to the keywords property of the Event, Task, or Group object. The list of category values converts to a set of keywords. The values convert case-sensitively. All CATEGORIES properties in the same iCalendar component convert to the keywords property in the JSCalendar object. The following example illustrates how to convert the CATEGORIES property:

Converting the CATEGORIES property

CLASS The CLASS property in a VEVENT or VTODO component converts to the privacy property of the Event or Task object. Its values convert as follows: Values of the CLASS property

iCalendar value	JSCalendar value
PUBLIC	public
PRIVATE	private
CONFIDENTIAL	secret

Any other value does not convert to the class property. Instead, the property converts to the iCalComponent/properties property of the JSCalendar object. The following example illustrates how to convert the CLASS property:

Converting the CLASS property

COLOR The COLOR property in a VEVENT, VTODO, or VCALENDAR component converts to the color property of the Event, Task, or Group object. Its value converts verbatim. The following examples illustrate how to convert the COLOR property:

Converting the COLOR property with color name

Converting the COLOR property with numeric value

COMMENT The COMMENT property in a DAYLIGHT or STANDARD component converts to the comments property of the TimeZoneRule object. The COMMENT property in a PARTICIPANT component converts to the participationComment property. The COMMENT property in an iTIP-scheduled VEVENT or VTODO component converts to the participationComment property of that Participant object, which represents the source of this scheduling message, if any. It otherwise converts to the iCalComponent/properties property of the Event or Task object. Multiple COMMENT properties in a DAYLIGHT or STANDARD component convert in order of appearance in the comments property. Converting multiple COMMENT properties to the single-valued participationComment property is implementation-specific. The following examples illustrate how to convert the COMMENT property:

Converting the COMMENT property in a DAYLIGHT component

Converting the COMMENT property in a PARTICIPANT component

CONCEPT The CONCEPT property in a VEVENT, VTODO, or VCALENDAR component converts to the categories property of the Event, Task, or Group object. The list of URI values converts to a set of URIs. Multiple occurrences of the CONCEPT property in the same iCalendar component convert to the same categories property in the JSCalendar object. The following example illustrates how to convert the CONCEPT property:

Converting the CONCEPT property

CONFERENCE The CONFERENCE property in a VEVENT or VTODO component converts to a VirtualLocation object. The converted object is set in the virtualLocations property of the Event or Task object. The property value converts to the uri property of the VirtualLocation object. Its parameters convert as follows: Parameters of the CONFERENCE property

Name	Reference	Property	Note
FEATURE		features
LABEL		name

The following example illustrates how to convert the CONFERENCE property:

Converting the CONFERENCE property

CREATED The CREATED property in a VEVENT, VTODO, or VCALENDAR component converts to the created property of the Event, Task, or Group object. The following example illustrates how to convert the CREATED property:

Converting the CREATED property

DESCRIPTION The DESCRIPTION property in a VEVENT, VTODO, VCALENDAR, VLOCATION, VRESOURCE, or PARTICIPANT component converts to the description property of the Event, Task, Group, Location, Link, or Participant object, unless its DERIVED parameter value is TRUE. If the DERIVED parameter value is TRUE, then the property does not convert to the description property. Instead, a non-derived STYLED-DESCRIPTION property is expected to contain the description. Implementations MAY preserve the property in the iCalComponent property. The following example illustrates how to convert the DESCRIPTION property:

Converting the DESCRIPTION property

DTEND The DTEND property in a VEVENT component converts to the duration property of the Event object. The duration is the timespan between the points in time of the DTSTART and DTEND property values when converted to UTC time. If the timezone identifier of the DTEND property differs from that of the DTSTART property, then the DTEND property also converts to a Location object. The timezone identifier converts to the timeZone property of the Location object. The relativeTo property of the Location is set to "end". The Location object is set in the locations property of the Event object. Implementations MAY preserve the fact that the duration got determined by the DTEND property. How to this depends on if the timezone identifiers of DTSTART and DTEND are equal. If the identifiers are equal, then implementations MUST set the iCalComponent property in the Event object and there add an entry for the path "duration" in the convertedProperties property. The value MUST be an ICalProperty object with the name property set to "dtend". If instead the timezone identifiers are not equal, then implementations MUST set the iCalProperty property of the Location object. The following examples illustrate how to convert the DTEND property:

Converting the DTEND property with same timezone

Converting the DTEND property with different timezone

Converting the DTEND property with DATE value type

DTSTAMP The DTSTAMP property in a VEVENT or VTODO component converts to the updated property of the Event or Task object. Both the LAST-MODIFIED and DTSTAMP properties convert to the updated property. If both are present in the same component, then the DTSTAMP property value has higher precedence. Implementations MAY in that case preserve the value of the LAST-MODIFIED property in the iCalComponent property. An Event or Task object which has the method property set might represent an iTIP reply of one of the participants in the object. In this case the value of the updated property in the Event or Task also converts to the scheduleUpdated property of that Participant object, which represents the participant from which the iTIP reply originated. The DTSTAMP property in a PARTICIPANT component converts to the scheduleUpdated property of the Participant object. The following examples illustrate how to convert the DTSTAMP property:

Converting the DTSTAMP property in a VEVENT component

Converting the DTSTAMP property in a PARTICIPANT component

DTSTART The DTSTART property in a VEVENT, VTODO, DAYLIGHT or STANDARD component converts to the start property of the Event, Task, or TimeZoneRule object. See how to convert DATE and DATE-TIME values. For VEVENT and VTODO components, the timezone identifier of the DTSTART property converts to the timeZone property of the Event or Task object. In addition, if the value type of the DTSTART property is DATE, then the value of the showWithoutTime property is "true". The following examples illustrate how to convert the DTSTART property for the VEVENT and VTODO components. See for examples how to convert the DTSTART property for the DAYLIGHT and STANDARD components.

Converting the DTSTART property with TZID parameter

Converting the DTSTART property with UTC time

Converting the DTSTART property with floating time

Converting the DTSTART property with value type DATE

DUE The DUE property in a VTODO component converts to the due property of the Task object. See how to convert DATE and DATE-TIME values. If the VTODO component does not contain a DTSTART property, then the timezone identifier of the DUE property converts to the timeZone property of the Task object. If instead the VTODO component contains both the DUE and DTSTART properties, then the timezone identifier of the DUE property does not convert to a standard JSCalendar element. The value of the due property MUST denote the date and time relative to the timezone of the DTSTART property. If the value type of the DUE property is DATE, then the value of the showWithoutTime property is "true". The following examples illustrate how to convert the DUE property:

Converting the DUE property with TZID parameter

Converting the DUE property with UTC time

Converting the DUE property with floating time

Converting the DUE property with value type DATE

DURATION The DURATION property in a VEVENT or VTODO component converts to the duration property of the Event or Task object. The following example illustrates how to convert the DURATION property:

Converting the DURATION

EXDATE The EXDATE property of value type DATE or DATE-TIME in a VEVENT or VTODO component converts to a PatchObject object. The converted object is set in the recurrenceOverrides property of the Event or Task object. The property value converts to the key in the recurrenceOverrides property value. See how to convert DATE and DATE-TIME values. The date-time MUST be relative to the timezone identified by the timeZone property of the Event or Task. The PatchObject value MUST set the excluded property to "true" and MUST NOT set any other property. An EXDATE property of value type PERIOD does not convert to a standard JSCalendar element. Implementations MAY convert it to the iCalComponent property of the Event or Task object. The following example illustrates how to convert the EXDATE property:

Converting the EXDATE property

EXRULE The EXRULE property in a VEVENT or VTODO component converts to a RecurrenceRule object. The converted object is set in the excludedRecurrenceRules property of the Event or Task. See for an example how to convert a recurrence rule.

GEO The GEO property in a VLOCATION component converts to the coordinates property. The GEO property in a VEVENT, VTODO, PARTICIPANT or VRESOURCE component converts to a Location object. The converted object is set in the locations property of the Event, Task, or Participant object. The pair of FLOAT values converts to an URI with the "geo" scheme. The first FLOAT value converts to the "coord-a" part of the URI, the second FLOAT value to the "coord-b" part. A preceding plus sign (+) of the FLOAT value MUST be omitted, a preceding minus sign (-) MUST be preserved. The third, altitude coordinate MUST NOT be set, unless its value is known. The following examples illustrate how to convert the GEO property:

Converting the GEO property in a VEVENT

Converting the GEO property in a VLOCATION

IMAGE The IMAGE property in a VEVENT, VTODO, VLOCATION, or VRESOURCE component converts to a Link object. The converted object is set in the links property of the Event, Task, Location, or Participant object. The property value converts to the href property of the Link object. A value of type URI converts as-is. See how to convert a BINARY value. If the DISPLAY parameter is set, then the "rel" property of the Link object MUST be set to "icon". Its parameters convert as follows: Parameters of the IMAGE property

Name	Reference	Property	Note
DISPLAY		display
FMTTYPE		contentType
SIZE		size

Implementations MAY preserve the fact that the Link object got converted from an IMAGE property. To so, they MUST set the iCalProperty on the Link object. The following example illustrates how to convert the IMAGE property:

Converting the IMAGE property

LAST-MODIFIED The LAST-MODIFIED property in a VEVENT, VTODO, VCALENDAR, or VTIMEZONE component converts to the updated property of the Event, Task, Group, or TimeZone object. Both the LAST-MODIFIED and DTSTAMP properties convert to the updated property. If both are present in the same component, then the DTSTAMP property value has higher precedence. Implementations MAY in that case preserve the value of the LAST-MODIFIED property in the iCalComponent property. The following example illustrates how to convert the LAST-MODIFIED property:

Converting the IMAGE property

LINK The LINK property in a VEVENT, VTODO, VCALENDAR, VRESOURCE, PARTICIPANT, or VLOCATION component converts to a Link object under the following conditions:

The property value type is URI.
The LINKREL parameter either is not set, or the parameter value is a registered relation type as defined in .

The converted object is set in the links property of the Event, Task, Group, Participant, or Location object. The LINK property value converts to the href property of the Link object. Its parameters convert as follows: Parameters of the LINK property

Name	Reference	Property	Note
FMTTYPE		contentType
LABEL		title
LINKREL		rel

A LINK property with a value type other than URI or an unregistered LINK parameter value does not convert to a standard JSCalendar element. Implementations MAY convert it to the iCalComponent property. The following examples illustrate how to convert the LINK property:

Converting the LINK property to a Link object

Converting the LINK property to iCalComponent

LOCATION The LOCATION property in a VEVENT, VTODO, or PARTICIPANT component converts to a Location object, unless its DERIVED parameter value is TRUE. The converted object is set in the locations property of the Event, Task, or Participant object. The property value converts to the title property of the Location object. If the DERIVED parameter value is TRUE, then the property does not convert to a Location object. Instead, a VLOCATION component is expected to represent the location. Implementations MAY preserve the property in the iCalComponent property. The following example illustrates how to convert the LOCATION property:

Converting the LOCATION property

LOCATION-TYPE The LOCATION-TYPE property in a VLOCATION component converts to the locationTypes property. The list of location type values converts to a set of location types. The values convert case-sensitively. All LOCATION-TYPE properties in the same VLOCATION convert to the locationTypes property in the Location object. The following example illustrates how to convert the LOCATION-TYPE property:

Converting the LOCATION property

METHOD The METHOD property in a VCALENDAR component converts to the method property of all Event or Task objects that are listed in the Group object's entries property. The property value converts in lowercase. The following example illustrates how to convert the METHOD property:

Converting the METHOD property

NAME The NAME property in a VLOCATION or VRESOURCE component converts to the name property of the Location or Participant object. The NAME property in a VCALENDAR component converts to the title property of the Group object. The following examples illustrate how to convert the NAME property:

Converting the NAME property in a VCALENDAR component

Converting the NAME property in the VLOCATION and PARTICIPANT components

ORGANIZER The ORGANIZER property in a VEVENT or VTODO component converts to the replyTo property. In addition, it converts to a Participant object in the participants property. If the CAL-ADDRESS property value is in the "mailto" scheme, then it converts to the "imip" method in the replyTo property, otherwise it converts to the "other" method. The property value also converts to the calendarAddress property of the Participant object. The "owner" role is set in the roles property of the Participant. In contrast to the ATTENDEE property, the property value does not convert to the sendTo property of the Participant object. An ORGANIZER property, an ATTENDEE property, and a PARTICIPANT component in the same iCalendar component all convert to the same Participant object, if their converted calendarAddress property values are equal after URI normalization. How to deal with conflicting values when converting other Participant properties is implementation-specific. Implementations MAY preserve arbitrary parameters of the ORGANIZER property, in which case they MUST convert these to a "replyTo" entry in the convertedProperties property of the Event or Task object's iCalComponent property. The ORGANIZER property parameters convert as follows: Parameters of the ORGANIZER property

Name	Reference	Property	Note
CN		name
DIR		links

The following examples illustrate how to convert the ORGANIZER property:

Converting an ORGANIZER property

Converting an ORGANIZER and ATTENDEE property

PARTICIPANT-TYPE The PARTICIPANT-TYPE property in a PARTICIPANT component converts to the roles property of the Participant object. The property value converts in lowercase. The following example illustrates how to convert the PARTICIPANT-TYPE property:

Converting the PARTICIPANT-TYPE property

PERCENT-COMPLETE The PERCENT-COMPLETE property in a VTODO component converts to the percentComplete property of the Task object. A Task object which has the method property set might represent an iTIP reply of one of the participants in the object. In this case the value of the percentComplete property in the Task also converts to the percentComplete of that Participant object, which represents the participant from which the iTIP reply originated. The PERCENT-COMPLETE property in a PARTICIPANT component converts to the percentComplete property of the Participant object. The following examples illustrate how to convert the PERCENT-COMPLETE property:

Converting the PERCENT-COMPLETE property in a VEVENT component

Converting the PERCENT-COMPLETE property in a PARTICIPANT component

PRIORITY The PRIORITY property in a VEVENT or VTODO component converts to the priority property of the Event or Task object. The following example illustrates how to convert the PRIORITY property:

Converting the PRIORITY property

PRODID The PRODID property in a VCALENDAR component converts to the prodId property of the Group object, and to the prodId property of all Event or Task objects that are listed in the Group object's entries property. The property value converts verbatim. The following example illustrates how to convert the PRODID property:

Converting the PRODID property

RDATE The RDATE property of type DATE or DATE-TIME in a VEVENT, VTODO, DAYLIGHT or STANDARD component converts to a PatchObject object. The converted object is set in the recurrenceOverrides property of the Event, Task, or TimeZoneRule object. The property value converts to the key in the recurrenceOverrides property value. See how to convert DATE and DATE-TIME values. For Event Task objects, the date-time MUST be relative to the timezone identified by the timeZone property, for TimeZoneRule objects the date-time is relative to the UTC offset specified in the offsetFrom property. The PatchObject value MUST be an empty JSON object. An RDATE property of value type PERIOD does not convert to a standard JSCalendar element. Implementations MAY convert it to the iCalComponent property of the Event, Task, or TimeZoneRule object. The following example illustrates how to convert the RDATE property:

Converting the RDATE property

RECURRENCE-ID The RECURRENCE-ID property in a VEVENT or VTODO component converts to the recurrenceId property of the Event or Task object. The timezone identifier of the RECURRENCE-ID property converts to the recurrenceIdTimeZone property. See how to convert DATE and DATE-TIME values. The RANGE parameter does not convert to a standard JSCalendar element. Implementations MAY preserve it in the iCalComponent property. See for further requirements and examples.

RELATED-TO The RELATED-TO property in a VEVENT, VTODO, or VALARM component converts to a Relation object. The converted object is set in the relatedTo property of the Event or Task object, or the Alert object. The property value in a VEVENT or VTODO converts as-is to the key of the Relation object in the relatedTo property. The property value in a VALARM converts to the same value as the key of that Alert object, which represents the VALARM component having that property value set in the UID property. Any RELTYPE parameters convert to the relations property in that Relation object. The parameter values convert in lowercase. The GAP parameter does not convert a standard JSCalendar element. Implementations MAY convert it to the iCalProperty property of the Relation object. The following examples illustrate how to convert the RELATED-TO property:

Converting the RELATED-TO property in a VEVENT

Converting the RELATED-TO property in a VALARM

REQUEST-STATUS The REQUEST-STATUS property in a VEVENT or VTODO component converts to the requestStatus property of the Event or Task object. The following example illustrates how to convert the REQUEST-STATUS property:

Example: Converting the REQUEST-STATUS property

Converting the REQUEST-STATUS property

RRULE The RRULE property in a VEVENT, VTODO, DAYLIGHT or STANDARD component converts to a RecurrenceRule object. The converted object is set in the recurrenceRules property of the Event, Task, or TimeZoneRule object. The RECUR value data type converts to a RecurrenceRule object as follows: Converting the RECUR value type to a RecurrenceRule object

RRULE field	RecurrenceRule property
FREQ	frequency
UNTIL	until
COUNT	count
INTERVAL	interval
BYSECOND	bySecond
BYMINUTE	byMinute
BYHOUR	byHour
BYDAY	byDay
BYMONTHDAY	byMonthDay
BYYEARDAY	byYearDay
BYWEEKNO	byWeekNo
BYMONTH	byMonth
BYSETPOS	bySetPosition
WKST	firstDayOfWeek
RSCALE	rscale
SKIP	skip

The string values of the FREQ, WKST, RSCALE convert to lowercase. The UNTIL part in a VEVENT or VTODO converts to a LocalDateTime value relative to the timezone of the Event or Task, or to floating time for the TimeZoneRule object. The following example illustrates how to convert the RRULE property:

Example for converting the RRULE property

SEQUENCE The SEQUENCE property in a VEVENT or VTODO component converts to the sequence property of the Event or Task object. The SEQUENCE property in a PARTICIPANT component converts to the scheduleSequence property of the Participant object. The following example illustrates how to convert the SEQUENCE property:

Example for converting the SEQUENCE property

STATUS The STATUS property in a VEVENT component converts to the status property of the Event object. The STATUS property in a VTODO component converts to the progress property of the Task object. The property value converts in lowercase. The following examples illustrate how to convert the STATUS property:

Example for converting the STATUS property in a VEVENT component

Example for converting the STATUS property in a VTODO component

SOURCE The SOURCE property in a VCALENDAR component converts to the source property. The following example illustrates how to convert the SOURCE property:

Example for converting the SOURCE property

STRUCTURED-DATA The STRUCTURED-DATA property of type URI or BINARY in a VEVENT, VTODO, VCALENDAR, VRESOURCE, PARTICIPANT, or VLOCATION component converts to a Link object. The converted object is set in the links property of the Event, Task, Group, Participant, or Location object. The property value converts to the href property of the Link object. A value of type URI converts as-is. See how to convert a BINARY value. Its parameters convert as follows: Parameters of the STRUCTURED-DATA property

Name	Reference	Property	Note
FMTTYPE		contentType

Implementations MAY preserve the fact that the Link object got converted from a STRUCTURED-DATA property. To so, they MUST set the iCalProperty on the Link object. The following example illustrates how to convert the STRUCTURED-DATA property:

Converting the STRUCTURED-DATA property

STYLED-DESCRIPTION The STYLED-DESCRIPTION property in a VEVENT or VTODO component converts to the description property under the following conditions:

The property value type MUST be TEXT.
The FMTTYPE parameter either MUST NOT not be set, or its value MUST be a media type with top-level type "text".
Its DERIVED parameter value MUST NOT be TRUE.

If the DERIVED parameter value is TRUE, then the property does not convert to the description property. Instead, an non-derived STYLED-DESCRIPTION property or the DESCRIPTION property is expected to contain the description. Implementations MAY preserve the property in the iCalComponent property. Its parameters convert as follows: Parameters of the STYLED-DESCRIPTION property

Name	Reference	Property	Note
FMTTYPE		descriptionContentType

The following example illustrates how to convert the STYLED-DESCRIPTION property:

Converting the STYLED-DESCRIPTION property hello,world ]]> hello,world", "descriptionContentType": "text/html" ]]>

SUMMARY The SUMMARY property in a VEVENT or VTODO component converts to the title property. The SUMMARY property in a PARTICIPANT component converts to the name property. The following examples illustrate how to convert the SUMMARY property:

Converting the SUMMARY property in a VEVENT

Converting the SUMMARY property in a PARTICIPANT

TRANSP The TRANSP property in a VEVENT or VTODO component converts to the freeBusyStatus property. Its values convert as follows: Values of the TRANSP property

iCalendar value	JSCalendar value
OPAQUE	busy
TRANSPARENT	free

The following example illustrates how to convert the TRANSP property:

Converting the TRANSP property

TRIGGER The TRIGGER property in a VALARM component converts to either an AbsoluteTrigger or OffsetTrigger object. The converted object is set in the trigger property of the Alert object. A property of value type DURATION converts an OffsetTrigger object. The property value converts to its offset property. A value of type DATE-TIME converts to an AbsoluteTrigger object. The property value converts to its when property. Its parameters convert as follows: Parameters of the TRIGGER property

Name	Reference	Property	Note
RELATED		relativeTo	If VALUE=DURATION

The following examples illustrate how to convert the TRIGGER property:

Converting the TRIGGER property to an OffsetTrigger

Converting the TRIGGER property to an AbsoluteTrigger

TZID The TZID property in a VTIMEZONE component converts to the tzId property. See for an example.

TZID-ALIAS-OF The TZID-ALIAS-OF property in a VTIMEZONE component converts to an entry in the aliases property of the TimeZone object. See for an example.

TZNAME The TZNAME property in a DAYLIGHT or STANDARD component converts to an entry in the names property of the TimeZoneRule object. See for an example.

TZOFFSETFROM The TZOFFSETFROM property in a DAYLIGHT or STANDARD component converts to the offsetFrom property of the TimeZoneRule object. See for an example.

TZOFFSETTO The TZOFFSETTO property in a DAYLIGHT or STANDARD component converts to the offsetTo property of the TimeZoneRule object. See for an example.

TZUNTIL The TZUNTIL property in a VTIMEZONE component converts to the validUntil property. See how to convert DATE and DATE-TIME values. See for an example.

TZURL The TZURL property in a VTIMEZONE component converts to the url property of the TimeZone object. See for an example.

UID The UID property in a VEVENT, VTODO, or VCALENDAR component converts to the uid property. The following example illustrates how to convert the UID property:

Converting the UID property

URL The URL property in a VEVENT, VTODO, VCALENDAR, or PARTICIPANT component converts to a Link object. The converted object is set in the links property of the Event, Task, Group, or Participant object. The property value converts to the href property of the Link object. Implementations MAY preserve the fact that the Link object got converted from an URL property. To so, they MUST set the iCalProperty on the Link object. The following example illustrates how to convert the URL property:

Converting the IMAGE property

Converting JSCalendar to iCalendar

Alert The Alert object converts to a VALARM component. Its properties convert as follows: Properties of the Alert object

Name	Property (or other)	See
acknowledged	ACKNOWLEDGED
action	ACTION
relatedTo	RELATED-TO	, and remarks below
trigger	TRIGGER

Remarks:

The value of the RELATED-TO property is the UID property value of that VALARM component, to which the related Alert object converts to. Consequently, the UID property for such a VALARM MUST be set, otherwise the UID property SHOULD be set.

Event and Task The Event object converts to a VEVENT component, the Task object converts to a VTODO component. The following table defines how to convert properties that are common to both the Event and Task object types. and later in this section define how to convert properties specific to either Event or Task objects. Properties of the Event and Task object

Name	Property (or other)	See
alerts	VALARM (component)	Alert object
categories	CONCEPT
color	COLOR
created	CREATED
description	DESCRIPTION, or STYLED-DESCRIPTION	, , and remarks below
descriptionContentType	FMTTYPE (parameter) of STYLED-DESCRIPTION	, and remarks below
excluded		, and remarks about recurrenceOverrides below
excludedRecurrenceRules	EXRULE
freeBusyStatus	TRANSP
keywords	CATEGORIES
links	ATTACH, or other	Link object
locale	TBD
localizations	TBD
locations	LOCATION, GEO, or VLOCATION (component)	Location object
method	METHOD of iCalendar object	, and Group object
participants	ATTENDEE, or PARTICIPANT (component)	Participant object
priority	PRIORITY
privacy	CLASS
prodId	PRODID of iCalendar object	, and Group object
recurrenceId	RECURRENCE-ID
recurrenceIdTimeZone	TZID (parameter) of RECURRENCE-ID
recurrenceOverrides	RDATE, EXDATE or recurrence override component	, and remarks below
recurrenceRules	RRULE
relatedTo	RELATED-TO
replyTo	ORGANIZER	, and remarks below
requestStatus	REQUEST-STATUS
sentBy	TBD
sequence	SEQUENCE
showWithoutTime	TBD
start	DTSTART
timeZone	TZID (parameter) of DTSTART and DUE	,
timeZones	VTIMEZONE (component) of iCalendar object	TimeZone object
title	SUMMARY
uid	UID
updated	DTSTAMP, and LAST-MODIFIED	,
useDefaultAlerts	TBD
virtualLocations	CONFERENCE

Remarks:

The descriptionContentType property value determines if to convert the description property to the DESCRIPTION or STYLED-DESCRIPTION property. A description of content type "text/plain" converts to the DESCRIPTION property. Any other description converts to a STYLED-DESCRIPTION; in this case, a plain text version of the rich-text description SHOULD be set in the DESCRIPTION property and its DERIVED parameter MUST be set to "TRUE".
The entries in the recurrenceOverrides property convert depending on the contents of the patch object value. A patch object that sets the excluded property to "true" converts to an EXDATE property for the date-time of that recurrence instance. An empty patch object converts to an RDATE property. Any other patch object converts to a recurrence override component in the embedding VCALENDAR component.
The replyTo property converts to the ORGANIZER property. If the replyTo property value only defines a single scheduling method then the URI value of that method converts to the ORGANIZER property value. If the replyTo property defines multiple scheduling methods, and a Participant object with a calendarAddress property value matching one of the replyTo URIs exists in the same Event or Task, then the URI matching the calendarAddress property converts to the ORGANIZER property value. Otherwise choosing the ORGANIZER property value is implementation-specific. TBD how to convert other replyTo methods.

Properties specific to the Event object type convert to iCalendar properties as follows: Properties of the Event object

Name	Reference	Property (or other)	See
duration		DURATION, or DTEND	,
status		STATUS

Properties specific to the Task object type convert to iCalendar properties as follows: Properties of the Task object

Name	Reference	Property (or other)	See
due		DUE
estimatedDuration		TBD
percentComplete		PERCENT-COMPLETE
progress		STATUS
progressUpdated		TBD

Group The Group object converts to a VCALENDAR component. Its properties convert as follows: Properties of the Group object

Name	Property (or other)	See
categories	CONCEPT
color	COLOR
created	CREATED
entries	VEVENT or VTODO (component)	Event and Task object, and remarks below
keywords	CATEGORIES
links	ATTACH, or other	Link object
locale	TBD
prodId	PRODID	, and remarks below
source	SOURCE
title	NAME
uid	UID
updated	LAST-MODIFIED

Remarks:

The prodId property value of the Group object is expected to be equal to the prodId property value of all the Group entries. They all convert to the same, single PRODID property in the VCALENDAR component. How to convert unequal prodId property values is implementation-specific.
The method property value in all the Group entries is expected to be equal. How to convert entries with unequal method property values is implementation-specific.

Link The Link object converts either an ATTACH property, an IMAGE property, a LINK property, a STRUCTURED-DATA property, or an URL property. Which iCalendar property to choose is implementation-specific. As a guideline:

Choose IMAGE, if the display property is set or the rel property value is "icon".
Choose LINK, if the rel property is set to any other value.
Choose URL, if only the href property is set and its value links to a dynamic rendition of the calendar object.
TBD - Choose STRUCTURED-DATA, if the schema property is set.
Choose ATTACH otherwise.

The href property converts to the iCalendar property value. The other Link properties convert as follows: Properties of the Link object

Name	Parameter (or other)	See
cid	TBD
contentType	FMTTYPE
display	DISPLAY
rel	LINKREL	, and remarks below
size	SIZE
title	TBD

Remarks:

The LINKREL parameter SHOULD be omitted if the Link object converts to an IMAGE property and the rel property value is "icon".

Location The Location object converts to either a LOCATION, GEO, or DTEND property, or it converts to a VLOCATION component. Which iCalendar element to choose is implementation-specific. As a guideline:

Choose LOCATION, if only the title property is set and the iCalendar component not already contains a LOCATION property. The title property converts to the LOCATION property value.
Choose GEO, if only the coordinates property is set the iCalendar component not already contains a GEO property. The coordinates property converts to the GEO property value. TBD - How to convert arbitrary geo: URIs?
Choose DTEND, if the embedding object is an Event, only the timeZone and the relativeTo properties are set, the relativeTo property value is "end" and the iCalendar component not already contains a DTEND property. The timeZone property converts to the TZID parameter of the DTEND property. The duration of the embedding Event object determines the DTEND property value.
Choose the VLOCATION component otherwise.

Implementations MAY convert one of the Location objects that convert to a VLOCATION also to the LOCATION property; converting the title or description property to the LOCATION property value is a reasonable choice. The DERIVED parameter MUST be set on the LOCATION property. The properties convert to a VLOCATION component as follows: Properties of the Location object

Name	Property (or other)	See
coordinates	GEO
description	DESCRIPTION
links	ATTACH, or other	Link object
locationTypes	LOCATION-TYPE
name	NAME
relativeTo	TBD
timeZone	TBD

Participant The Participant object either converts to one of an ATTENDEE property, a PARTICIPANT component, or a VRESOURCE component; or it converts to both an ATTENDEE property and a PARTICIPANT component:

It converts to an ATTENDEE property if at least one of the calendarAddress or sendTo properties is set. The calendarAddress property converts to the ATTENDEE property value, if set; otherwise one of the scheduling methods in the sendTo property converts to the ATTENDEE property value.
It converts to a PARTICIPANT component if it converts to an ATTENDEE property but not all of its properties convert to ATTENDEE property parameters as depicted in . In this case the CALENDAR-ADDRESS property value of the PARTICIPANT MUST be set to the ATTENDEE property value. Alternatively, the Participant object also converts to a PARTICIPANT component if it does not convert to an ATTENDEE property but its kind property value is unequal to "resource".
It converts to a VRESOURCE component if it does not convert to an ATTENDEE property and its kind property value is "resource".

The following Participant properties convert to the ATTENDEE property. How to convert these properties if the Participant does not convert to an ATTENDEE is implementation-specific. Properties of the Participant object that convert to the ATTENDEE property

Name	Parameter (or other)	See
delegatedFrom	DELEGATED-FROM
delegatedTo	DELEGATED-TO
email	EMAIL
expectReply	RSVP
kind	CUTYPE
invitedBy	TBD
memberOf	MEMBER
name	CN
participationStatus	PARTSTAT
roles	ROLE, or PARTICIPANT-TYPE property of the PARTICIPANT component	, , and remarks below
scheduleAgent	SCHEDULE-AGENT
scheduleForceSend	SCHEDULE-FORCE-SEND
scheduleSequence	TBD
scheduleStatus	SCHEDULE-STATUS
scheduleUpdated	TBD
sendTo	TBD
sentBy	TBD

Remarks:

The "optional" role converts to the "OPT-PARTICIPANT" ROLE parameter value, the "chair" role to "CHAIR", "informational" to "NON-PARTICIPANT". The "attendee" role does convert to the ROLE parameter, it is implied by the ATTENDEE property. The "owner" role does not convert to the ROLE parameter, if the property value of the ATTENDEE is equal to the value of the ORGANIZER property in the same component. All other roles require a PARTICIPANT component and convert to the PARTICIPANT-TYPE property in that component.

The following Participant properties convert to the PARTICIPANT or VRESOURCE component: Properties of the Participant object that convert to the PARTICIPANT or VRESOURCE component

Name	Property (or other)	See
description	DESCRIPTION
language	TBD
links	ATTACH, or other	Link object
locationId	TBD
name	NAME
participationComment	COMMENT
percentComplete	PERCENT-COMPLETE
progress	TBD
progressUpdated	TBD
roles	PARTICIPANT-TYPE

TimeZone The TimeZone object converts to a VTIMEZONE component. Its properties convert as follows: Properties of the TimeZone object

Name	Property (or other)	See
aliases	TZID-ALIAS-OF
daylight	DAYLIGHT (component)	TimeZoneRule below
standard	STANDARD (component)	TimeZoneRule below
tzId	TZID
url	TZURL
validUntil	TZUNTIL

The TimeZoneRule object converts to a DAYLIGHT or STANDARD component. Its properties convert as follows: Properties of the TimeZoneRule object

Name	Reference	Property (or other)	See
comments		COMMENT
names		TZNAME
offsetFrom		TZOFFSETFROM
offsetTo		TZOFFSETTO
recurrenceOverrides		RDATE
recurrenceRules		RRULE
start		DTSTART

VirtualLocation The VirtualLocation object converts to a CONFERENCE property. The uri property converts to the CONFERENCE property value. Its other properties convert as follows: Properties of the VirtualLocation object

Name	Reference	Parameter (or other)	See
description		TBD
features		FEATURE
name		LABEL

Updates to iCalendar

New iCalendar parameters

JSCALID TBD

New iCalendar properties

JSCALID TBD

JSPROP TBD

Updates to JSCalendar

New JSCalendar properties

iCalComponent

Name:

iCalComponent

Context:

Any JSCalendar object

Type:

ICalComponent (optional)

Description

This contains information about an iCalendar component that got partially or fully converted to JSCalendar. It allows to preserve the name of the iCalendar component and some or all of its properties and subcomponents. An ICalComponent object has the following properties:

@type: String (mandatory): This specifies the type of this object. This MUST be ICalComponent.
name: String (mandatory): This is the name of the iCalendar component in lowercase.
components: *[][] (optional): This contains subcomponents of the iCalendar component. The value MUST be a list of iCalendar components formatted in jCal as defined in .
convertedProperties: String[ICalProperty] (optional): This contains conversion-related information about the component's properties that got partially or fully converted to JSCalendar. Each key defines the path to a property of the JSCalendar object on which the iCalComponent property is set on. The value for each key contains information about the iCalendar property which converted to the object property located at that key (see ). The key MUST be a valid key of a PatchObject as defined in . The key MUST NOT point into a nested property, unless there is no way to otherwise preserve the iCalendar property elements. For example, if a VEVENT contains an ATTENDEE property, then any iCalendar information about the ATTENDEE property MUST be set in the iCalProperty property of the converted Participant object (see ). In contrast, information about a RDATE property contained in a VEVENT would be located by a key pointing into the recurrenceOverrides property of the Event object (see ).
properties: *[][] (optional): This contains properties of the iCalendar component. The value MUST be a list of iCalendar properties formatted in jCal as defined in .

iCalProperty

Name:

iCalProperty

Context:

Any JSCalendar object

Type:

ICalProperty (optional)

Description:

This contains conversion-related information about an iCalendar property that got partially or fully converted to JSCalendar. It allows to preserve the name of the iCalendar property and some or all of its parameters. An ICalProperty object has the following properties:

@type: String (mandatory): This specifies the type of this object. This MUST be ICalProperty.
name: String (mandatory): This is the name of the iCalendar property in lowercase.
valueType: String (optional): This is the name of the iCalendar property value type in lowercase.
parameters: String[String] (optional): This contains parameters of the iCalendar property. The value MUST comply with iCalendar parameters formatted in jCal as defined in .

locations (Participant)

Name:: locations
Context: Participant
Type:: Id[Location] (optional)
Description:: This represents locations associated with the participant. In contrast to the locationId property, this allows to associate multiple locations with the Participant object. It also allow to more clearly express that a location just is relevant for a single participant.

IANA Considerations

References Normative References IANA Time Zone Database Informative References JMAP for Calendars Fastmail Spherical Cow Group

Discrepancies between iCalendar and JSCalendar This section highlights iCalendar and JSCalendar elements for which no conversion rule to a standard element is defined in this document. This is informational; implementations MAY convert these elements, for example by use of the special-purpose properties defined in this document, or some vendor-specific extension properties. Alternatively newer standards might define new standard elements and register them at IANA.

Unsupported iCalendar Elements

Components The following components do not convert to a standard element in JSCalendar:

AVAILABLE
VAVAILABILITY
VFREEBUSY
VJOURNAL

Properties by Component The following components are defined to contain the listed properties. But these properties do not convert to a standard JSCalendar element.

PARTICIPANT

CATEGORIES
CONTACT
CREATED
LAST-MODIFIED
PRIORITY
RELATED-TO
REQUEST-STATUS
RESOURCES
STATUS
STYLED-DESCRIPTION
UID

VALARM

ATTACH
ATTENDEE
DESCRIPTION
DURATION
PROXIMITY
REPEAT
STYLED-DESCRIPTION
SUMMARY
UID

VCALENDAR

CALSCALE
REFRESH-INTERVAL
VERSION

VEVENT

CONTACT
REFID
RESOURCES

VLOCATION

VRESOURCE

RESOURCE-TYPE
UID

VTODO

COMPLETED
CONTACT
REFID
RESOURCES

Properties by Value Type The following properties convert to a standard JSCalendar element for some other value type, but they do not for the listed value types.

LINK

XML-REFERENCE

RDATE

PERIOD

STRUCTURED-DATA

TEXT

Parameters by Property The following properties are defined to contain the listed parameters. But these parameters do not convert to a standard JSCalendar element.

ATTACH

FILENAME
MANAGED-ID

ATTENDEE

SENT-BY
LANGUAGE