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 updates RFC 5545 ("iCalendar") and jscalendarbis ("JSCalendar") by defining new properties and parameters for JSCalendar and iCalendar conversion.

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 of how to convert that element. All iCalendar and JSCalendar elements currently registered at IANA are in scope, but not all of these elements are common to both formats. For elements that have no counterpart in the other format, it is the goal of this document to define how to preserve them during conversion, but in general it is not the goal to achieve this by defining new standard elements. Instead, this document updates and by defining iCalendar and JSCalendar elements to preserve elements that have no equivalent in the other format. These conversion-specific properties are defined in Section for iCalendar, 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 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. The following rules apply:

An example that only contains iCalendar properties implicitly represents a VEVENT component having these properties set and that is part of a VCALENDAR component.
An example that only contains one or more VEVENT, VTODO, VJOURNAL, FREEBUSY or VTIMEZONE components implicitly represents a VCALENDAR component that contains them. An example that only contains one or more other components implicitly represents a VEVENT component having these components set and that is part of a VCALENDAR components.
An example that only contains VEVENT or VTODO components implicitly represents a VCALENDAR component that contains them.
An example that only contains a VCALENDAR component but no contained components implicitly represents a VCALENDAR component that contains a VEVENT component.
Implicit components (those without a BEGIN and END, or omitted completely) are assumed to contain all mandatory properties with some value, but the actual value is irrelevant for the example.

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, but the value ... does not represent a property in a component for which at least one same-named property is explicitly stated for that component in the example. 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 are irrelevant for this example, including mandatory properties. The "..." property requires the "@type" property to be set. illustrates this as an alternative representation for the examples of .

Example for additional properties represented by ...

Lossy versus Lossless Conversion This document outlines how to convert iCalendar elements to JSCalendar elements, and the other way round. Many of these can be represented by standard elements in both formats, meaning that they are registered in the iCalendar and JSCalendar IANA registries and differ from the special-purpose elements introduced in and . Still, a number of elements in either format have no standard counterpart in the other. When converting between between iCalendar and JSCalendar, implementations MAY choose to only convert elements that have standard element in the target format, or aim to preserve as many elements as possible. When to choose between lossy and lossless conversion is implementation-specific. For example:

For lossy conversion, an implementation that internally stores calendar data in JSCalendar format might only want to convert to a subset of iCalendar elements for iMIP scheduling. In this case, it might not make use any of the conversion-specific iCalendar properties introduced in .
For lossless conversion, an implementation that internally stores calendar data in iCalendar format might want to convert without loss to JSCalendar when updating calendar events with JMAP. For that, it can use the conversion-specific properties defined in .

All the examples in this document illustrate lossless conversion, if not explicitly stated otherwise in the example.

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
ATTACH		links
CATEGORIES		keywords
COLOR		color
CONCEPT		categories
CREATED		created
DESCRIPTION		description
IMAGE		links
LAST-MODIFIED		updated
LINK		links
METHOD		entries/*/method
NAME		title
PRODID		prodId, entries/*/prodId
SOURCE		source
UID		uid

Its components convert as follows: Components of the VCALENDAR component

Name	Reference	Group property	See	Note
VEVENT		entries
VTODO		entries

Other properties or components MAY be converted to the "iCalendar" property of the Group object. The order of elements in the "entries" property is implementation-specific, e.g. entries need not be in the same order as their source components in the iCalendar object. The following example illustrates how to convert the VCALENDAR component:

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. As an exception to this rule, this does not apply to recurrence overrides, defined as follows. A VEVENT (or VTODO) component is a recurrence override if it has the RECURRENCE-ID property set, and the iCalendar object contains a VEVENT (or VTODO) component that does not have the RECURRENCE-ID but the RRULE property set, and the UID property values of the two components are equal. The component without the RECURRENCE-ID property is in that case referred to as the "main component". The main component converts to an entry in the Group object's entries property. The recurrence override converts to the "recurrenceOverrides" property of the converted main component. Its RECURRENCE-ID property value converts to the key in the "recurrenceOverrides" property. The value of the "recurrenceOverrides" property at that key is a PatchObject that transform the converted main component into the converted recurrence override. The recurrenceId and recurrenceIdTimeZone properties MUST NOT be set in the PatchObject. The following example illustrates how to convert a main component and its recurrence override:

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

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. If the JSID parameter or JSID property is set on a property or component, then its value MUST be used as key when converting that element from iCalendar to JSCalendar. In absence of the JSID parameter or property key generation is implementation-specific. Some sections later in this document describe key generation schemes for specific iCalendar elements by making use of UUID Version 5 with SHA1 hash. The Namespace ID to generate such keys is "7f1e1965-ae73-4454-b088-232c90730ce2". These key generation schemes are not mandatory, nor is making use of that particular Namespace ID when using UUID Version 5 (UUIDv5) as keys. Irrespective of the key generation scheme, all keys MUST be valid according to the definition of the Id type. For consistency, keys SHOULD be stable such that converting the same iCalendar data to JSCalendar multiple times produces the same keys.

Timezone identifiers Converting temporal properties such as DTSTART, DTEND, and RECURRENCE-ID requires to not only determine the date and time of the property value, but also the timezone it references. If the property value type is DATE 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 type is DATE-TIME in FORM #2: DATE WITH UTC TIME then the timezone identifier is "Etc/UTC" in JSCalendar. If the property value 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 as follows: If the TZID parameter value is equal to a name in the IANA Time Zone Database then the timezone identifier is that verbatim name. Otherwise, how to convert the TZID parameter value is implementation-specific: software libraries such as the International Components for Unicode support converting Microsoft time zone names to IANA time zone identifiers. Alternatively, an implementation might determine the name of an IANA time zone which has identical time zone rules over the time span of the calendar object. Implementations MAY preserve a TZID parameter set to a non-IANA timezone identifier and its related VTIMEZONE by use of the "convertedProperties" and "components" properties (see ), but MUST NOT expect other implementations to consider them when processing the calendar object. 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. When converting from iCalendar to JSCalendar, 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. defines which iCalendar value type to choose when converting from JSCalendar to iCalendar.

Components

PARTICIPANT The PARTICIPANT component 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 key of the Participant object MUST be the value of the JSID property, if set. If no JSID property but the CALENDAR-ADDRESS property is set, then the key MAY be a UUIDv5 generated from the property value (see ). Otherwise, the key MAY be the UID property value. When converting to iCalendar, implementations MAY omit setting the JSID property if key matches the UUIDv5 of the CALENDAR-ADDRESS property value or the key matches the UID property, and the key is not part of a JSON pointer in any JSPTR parameter value. Its properties convert as follows: Properties of the PARTICIPANT component

Name	Reference	Participant property	See	Note
ATTACH		links
CALENDAR-ADDRESS		calendarAddress
DESCRIPTION		description
LINK		links
STYLED-DESCRIPTION		description
SUMMARY		name

Other properties or components MAY be converted to the "iCalendar" 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 in a VEVENT or VTODO component converts to an Alert object. The converted object is set in the "alerts" property of the Event or Task object. The key of the Alert object MUST be the value of the JSID property, if set. Otherwise, the key MAY be the value of the UID property. When converting to iCalendar, implementations MAY omit setting the JSID property if the key matches the value of the UID property, and the key is not part of a JSON pointer in any JSPTR parameter value. 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 "iCalendar" 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. 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
CONCEPT		categories
CONFERENCE		virtualLocations
CREATED		created
DESCRIPTION		description
DTEND		duration, endTimeZone
DTSTAMP		updated
DTSTART		start
DURATION		duration
EXDATE		recurrenceOverrides
GEO		locations
IMAGE		links
LAST-MODIFIED		updated
LINK		links
LOCATION		locations
ORGANIZER		organizerCalendarAddress
PRIORITY		priority
RDATE		recurrenceOverrides
RECURRENCE-ID		recurrenceId
RELATED-TO		relatedTo
RRULE		recurrenceRule
SEQUENCE		sequence
SHOW-WITHOUT-TIME		showWithoutTime
STATUS		status
STYLED-DESCRIPTION		description
SUMMARY		title
TRANSP		freeBusyStatus
UID		uid

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 "iCalendar" property of the Event object. VEVENT components with different UID property values in the same iCalendar object convert to different entries in the Group. They sort in the same order as in the VCALENDAR component. The following example illustrates how to convert the VEVENT component:

Converting the VEVENT component

VLOCATION The VLOCATION component in a VEVENT or VTODO component converts to a Location object. The converted object is set in the "locations" property of the Event or Task object. The key of the Location object MUST be the value of the JSID property, if set. Otherwise, the key MAY be the value of the UID property. When converting to iCalendar, implementations MAY omit setting the JSID property if the key matches the value of the UID property, and the key is not part of a JSON pointer in any JSPTR parameter value. Its properties convert as follows: Properties of the VLOCATION component

Name	Reference	Location property	See	Note
ATTACH		links
COORDINATES		coordinates
GEO		coordinates
IMAGE		links
LINK		links
LOCATION-TYPE		locationTypes
NAME		name

Other properties or components MAY be converted to the "iCalendar" 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

VTODO The VTODO component converts to a Task object. 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
CONCEPT		categories
CONFERENCE		virtualLocations
CREATED		created
DESCRIPTION		description
DTSTAMP		updated
DTSTART		start
DUE		due
DURATION		duration
ESTIMATED-DURATION		estimatedDuration
EXDATE		recurrenceOverrides
GEO		locations
IMAGE		links
LAST-MODIFIED		updated
LINK		links
LOCATION		locations
ORGANIZER		organizerCalendarAddress
PERCENT-COMPLETE		percentComplete
PRIORITY		priority
RDATE		recurrenceOverrides
RECURRENCE-ID		recurrenceId
RELATED-TO		relatedTo
RRULE		recurrenceRule
SEQUENCE		sequence
SHOW-WITHOUT-TIME		showWithoutTime
STYLED-DESCRIPTION		description
SUMMARY		title
TRANSP		freeBusyStatus
UID		uid

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 "iCalendar" property of the Task object. VTODO components with different UID property values in the same iCalendar object convert to different entries in the Group. They sort in the same order as in the VCALENDAR component. The following example illustrates how to convert the VTODO component:

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 iCalendar/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, PARTICIPANT, VLOCATION, or VCALENDAR component converts to a Link object. The converted object is set in the "links" property of the Event, Task, Participant, Location, or Group object. The key of the Link object MUST be the value of the JSID parameter, if set. If no JSID parameter is set, then the key MAY be the UUIDv5 generated from the property value (see ). When converting to iCalendar, implementations MAY omit setting the JSID parameter if the key matches the UUIDv5 of the ATTACH property value and the key is not part of a JSON pointer in any JSPTR parameter value. The ATTACH 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 MUST 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
LABEL		title
SIZE		size

Remarks: 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 the calendarAddress property of the Participant object. The key of the Participant object MUST be the value of the JSID parameter, if set. If no JSID parameter is set, then the key MAY be the UUIDv5 generated from the property value (see ). When converting to iCalendar, implementations MAY omit setting the JSID parameter if the key matches the UUIDv5 of the ATTENDEE property value and the key is not part of a JSON pointer in any JSPTR parameter value. An ATTENDEE property and a PARTICIPANT component in the same iCalendar component convert to the same Participant object, if their converted calendarAddress property values are equal. How to deal with conflicting values is implementation-specific. The ATTENDEE property parameters convert as follows: Parameters of the ATTENDEE property

Name	Participant Property	Note
CN	name
CUTYPE	kind	ROOM converts to "location"
DELEGATED-FROM	delegatedFrom
DELEGATED-TO	delegatedTo
EMAIL	email
MEMBER	memberOf
PARTSTAT	participationStatus
ROLE	roles	OWNER role defined in
RSVP	expectReply
SENT-BY	sentBy

The PARTSTAT of an ATTENDEE property in a VTODO component converts not only to the "participationStatus" property of the Participant object, but also to its progress property if the PARTSTAT parameter value is specific for VTODO components: Converting the PARTSTAT parameter in a VTODO component to Participant properties

PARTSTAT	participationStatus	progress
NEEDS-ACTION	needs-action
ACCEPTED	accepted
DECLINED	declined
TENTATIVE	tentative
DELEGATED	delegated
COMPLETED	accepted	completed
IN-PROCESS	accepted	in-process
FAILED	accepted	failed

The following examples illustrate how to convert the ATTENDEE property:

Converting the ATTENDEE property

Converting the ATTENDEE property and PARTICIPANT component

Converting the ATTENDEE property with a VTODO-specific participation status

Converting the ATTENDEE property with the OWNER role

CALENDAR-ADDRESS The CALENDAR-ADDRESS property in a PARTICIPANT component converts to the "calendarAddress" property of the Participant object. Implementations MAY preserve the fact that a Participant object's "calendarAddress" property converted from the CALENDAR-ADRESS property of a PARTICIPANT component, rather than an ATTENDEE property. In this case, they MUST add an entry for the "calendarAddress" property in the "iCalendar/convertedProperties" 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 iCalendar/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

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. The key of the VirtualLocation object MUST be the value of the JSID parameter, if set. If no JSID parameter is set, then the key MAY be the UUIDv5 generated from the property value (see ). When converting to iCalendar, implementations MAY omit setting the JSID parameter if the key matches the UUIDv5 of the CONFERENCE property value and the key is not part of a JSON pointer in any JSPTR parameter value. 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

COORDINATES The COORDINATES property in a VLOCATION component converts to the "coordinates" property of the Location object. The following example illustrates how to convert the COORDINATES property:

Converting the COORDINATES 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, or PARTICIPANT component converts to the "description" property of the Event, Task, Group, 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 "iCalendar" 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. If the value type of the DTEND property is DATE, then the duration is the number of days or weeks between the DTSTART and DTEND property values. If the value type is DATE-TIME, then the duration is the timespan between 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 it converts to the "endTimeZone" property of the Event. Implementations MAY preserve the fact that the duration got determined by the DTEND property. How to do this depends on the timezone identifiers of the DTSTART and DTEND properties: If the time zone identifiers are not equal, then the presence of the "endTimeZone" property implies that it converted from the DTEND property. If the time zone identifiers are equal, then implementations MAY set the "iCalendar" 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". The following examples illustrate how to convert the DTEND property:

Converting the DTEND property with different timezone

Converting the DTEND property with same 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. The following examples illustrate how to convert the DTSTAMP property:

Converting the DTSTAMP property in a VEVENT component

DTSTART The DTSTART property in a VEVENT or VTODO component converts to the "start" property of the Event or Task object (Sections 5.1.1 and 5.2.2 of ). 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.

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

Converting the DTSTART property with a non-IANA TZID parameter

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 it contains both the DUE and DTSTART properties and the timezone identifier of the DUE property differs from that of the DTSTART property, then the "due" date-time property value MUST be relative to the time zone of DTSTART. If the value type of the DUE property is DATE, then the value of the "showWithoutTime" property 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

Converting the DUE property with value type DATE in combination with DTSTART

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

ESTIMATED-DURATION The ESTIMATED-DURATION property in a VTODO component converts to the "estimatedDuration" property of the Task object. The following example illustrates how to convert the ESTIMATED-DURATION property:

Converting the ESTIMATED-DURATION

EXDATE The EXDATE property in a VEVENT or VTODO component converts to a PatchObject value. 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" member to "true" and MUST NOT set any other property. The following example illustrates how to convert the EXDATE property:

Converting the EXDATE property

GEO A GEO property with the DERIVED parameter value "TRUE" does not convert to JSCalendar. For non-derived GEO properties, the following rules apply: The GEO property in a VEVENT or VTODO component converts to a Location object. If the VEVENT or VTODO component also contains the LOCATION property, then the GEO and LOCATION properties convert to the same Location object. The converted object is set in the "locations" property of the Event or Task object. The key of the Location object MUST be the value of the JSID parameter, if set. If no JSID parameter is set, then the key MAY be the UUIDv5 generated from the property value (see ). When converting to iCalendar, implementations MAY omit setting the JSID parameter if the key matches the UUIDv5 of the GEO property value and the key is not part of a JSON pointer in any JSPTR parameter value. The GEO property in a VLOCATION component converts to the "coordinates" property of the Location object. The pair of FLOAT values converts to a 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 optional "coord-c" part of the URI MUST be omitted. Implementations MAY preserve the fact that the coordinates converted from a GEO property by setting the JSON pointer path to the "coordinates" property in the "iCalendar/convertedProperties" property. If the GEO property converted from a VEVENT or VTODO component, then the "iCalendar" property MUST be that of the Event or Task object, for the VLOCATION component it MUST be the "iCalendar" property of the Location object. The following examples illustrate how to convert the GEO property.

Converting the GEO property in a VEVENT. The JSID parameter is set to simplify testing.

Converting the GEO and LOCATION properties in a VEVENT. The JSID parameters are set to simplify testing.

Converting the GEO property in a VLOCATION

IMAGE The IMAGE property in a VEVENT, VTODO, VLOCATION, PARTICIPANT, or VCALENDAR component converts to a Link object. The converted object is set in the "links" property of the Event, Task, Location, Participant, or Group object. The key of the Link object MUST be the value of the JSID parameter, if set. If no JSID parameter is set, then the key MAY be the UUIDv5 generated from the property value (see ). When converting to iCalendar, implementations MAY omit setting the JSID parameter if the key matches the UUIDv5 of the IMAGE property value and the key is not part of a JSON pointer in any JSPTR parameter value. The IMAGE 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 IMAGE property

Name	Reference	Property	Note
DISPLAY		display
FMTTYPE		contentType
LABEL		title
SIZE		size

The following example illustrates how to convert the IMAGE property:

Converting the IMAGE property

LAST-MODIFIED The LAST-MODIFIED property in a VCALENDAR component converts to the "updated" property of the Group object. The LAST-MODIFIED property in a VEVENT or VTODO component does not convert to the "updated" property of the Event or Task object. Implementations MAY instead preserve the LAST-MODIFIED property in the "iCalendar" property. The following example illustrates how to convert the LAST-MODIFIED property:

Converting the IMAGE property

LINK A LINK property with value type URI in a VEVENT, VTODO, PARTICIPANT, VLOCATION, or VCALENDAR component converts to a Link object. The converted object is set in the "links" property of the Event, Task, Participant, Location, or Group object. The key of the Link object MUST be the value of the JSID parameter, if set. If no JSID parameter is set, then the key MAY be the UUIDv5 generated from the property value (see ). When converting to iCalendar, implementations MAY omit setting the JSID parameter if the key matches the UUIDv5 of the LINK property value and the key is not part of a JSON pointer in any JSPTR parameter value. The LINK property value converts to the "href" property of the Link object. The LINK property parameters convert as follows: Parameters of the LINK property

Name	Reference	Link Property	Note
FMTTYPE		contentType
LABEL		title
LINKREL		rel

A LINK property with any other value type does not convert to a standard JSCalendar element. Implementations MAY convert it to the "iCalendar" property. The following example illustrates how to convert the LINK property:

Converting the LINK property

LOCATION The LOCATION property in a VEVENT or VTODO 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 or Task. The key of the Location object MUST be the value of the JSID parameter, if set. If no JSID parameter is set, then the key MAY be the UUIDv5 generated from the property value (see ). When converting to iCalendar, implementations MAY omit setting the JSID parameter if the key matches the UUIDv5 of the LOCATION property value and the key is not part of a JSON pointer in any JSPTR parameter value. The LOCATION property value converts to the "title" property of the Location object. If the calendar component contains multiple VLOCATION components, then the LOCATION property also converts to the "mainLocationId" property of the Event or Task object. If the LOCATION property does not have the DERIVED parameter set to TRUE, then the "mainLocationId" is set to the key of the Location object of the LOCATION property. If instead the LOCATION property is derived and its property value matches the NAME property value of a VLOCATION component, then the "mainLocationId" is the identifier of the Location object of that VLOCATION component. The following example illustrates how to convert the LOCATION property:

Converting the LOCATION property The following example illustrates how to convert the LOCATION property and multiple VLOCATION components:

Converting the LOCATION property and multiple VLOCATION components

LOCATION-TYPE The LOCATION-TYPE property in a VLOCATION component converts to the "locationTypes" property of the Location object. The list of location type values converts to a set of location types. The values convert case-sensitively. All LOCATION-TYPE properties in the same VLOCATION convert to the "locationTypes" property in the Location object. 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 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. If the LANGUAGE parameter is set, then the parameter value converts to the "locale" property of the same 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 component

ORGANIZER The ORGANIZER property in a VEVENT or VTODO component converts to the "organizerCalendarAddress" property of the Event or Task object. It also converts to a Participant object in the "participants" property, if any of its parameters convert to a Participant object property (see ), or if none of the ATTENDEE properties in the iCalendar component have the ROLE parameter set to "OWNER". The ORGANIZER property value converts to the "calendarAddress" property of the Participant, the "owner" role is set in Participant "roles" property. The key of the Participant object MUST be the value of the JSID parameter, if set. If no JSID parameter is set, then the key MAY be the UUIDv5 generated from the ORGANIZER property value (see ). When converting to iCalendar, implementations MAY omit setting the JSID parameter if the key matches the UUIDv5 of the ORGANIZER property value and the key is not part of a JSON pointer in any JSPTR parameter value. The ORGANIZER property parameters convert to the Participant object as follows: Parameters of the ORGANIZER property

Name	Reference	Property	Note
CN		name
EMAIL		email
SENT-BY		sentBy

An ORGANIZER property, an ATTENDEE property, and a PARTICIPANT component in the same iCalendar component all convert to the same Participant object, if their converted calendarAddress property values are equal. How to deal with conflicting property values is implementation-specific. The following examples illustrate how to convert the ORGANIZER property:

Converting an ORGANIZER property

Converting an ORGANIZER and its related ATTENDEE property

Converting an ORGANIZER property with CN parameter and another participant having the 'owner' role set

Converting an ORGANIZER property with another participant having the 'owner' role set

PERCENT-COMPLETE The PERCENT-COMPLETE property in a VTODO component converts to the "percentComplete" property of the Task object. The following examples illustrate how to convert the PERCENT-COMPLETE property:

Converting the PERCENT-COMPLETE property in a VTODO 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. Implementations MAY additionally convert it also 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 A RDATE property with value type DATE or DATE-TIME in a VEVENT or VTODO component converts to a PatchObject value. 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 object. The PatchObject value MUST be an empty JSON object. A RDATE property with value type PERIOD does not convert to a standard JSCalendar element. Implementations MAY convert it to the "iCalendar" property of the Event or Task 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 iCalendar 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 id of the Relation object in the "relatedTo" property. The property value in a VALARM converts to the same value as the id of that Alert object, which represents the VALARM component having that property value set in the UID property. Any RELTYPE parameters convert to the "relation" property in that Relation object. The parameter values convert in lowercase. 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

RRULE The RRULE property in a VEVENT or VTODO component converts to a RecurrenceRule object. The converted object is set in the "recurrenceRule" property of the Event or Task object. The RECUR value type converts to a RecurrenceRule object as follows: 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 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 following example illustrates how to convert the SEQUENCE property:

Example for converting the SEQUENCE property

SHOW-WITHOUT-TIME The SHOW-WITHOUT-TIME property in a VEVENT or VTODO component converts to the "showWithoutTime" property of the Event or Task object. As outlined in the definition of the SHOW-WITHOUT-TIME property, the property MUST be ignored if the temporal value type of the VEVENT or VTODO component is DATE, or if the property value is "FALSE". The following example illustrates how to convert the SHOW-WITHOUT-TIME property:

Example for converting the SHOW-WITHOUT-TIME 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 of the Group object. The following example illustrates how to convert the SOURCE property:

Example for converting the SOURCE property

STYLED-DESCRIPTION The STYLED-DESCRIPTION property in a PARTICIPANT, VEVENT or VTODO component converts to the "description" property of the Participant, Event or Task object under the following conditions:

The property value type MUST be TEXT.
The FMTTYPE parameter either MUST NOT be set, or its value MUST be a media type with top-level type "text".
Its DERIVED parameter value MUST NOT be TRUE. If the value is TRUE, then another property in the same component is expected to contain the description.

If these conditions are not met, implementations MAY preserve the property in the "iCalendar" 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 of the Event or Task object. If the LANGUAGE parameter is set, then the parameter value converts to the "locale" property of the same object. The SUMMARY property in a PARTICIPANT component converts to the "name" property of the Participant object. The following examples illustrate how to convert the SUMMARY property:

Converting the SUMMARY property in a VEVENT

Converting the SUMMARY property with LANGUAGE parameter 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 of the Event or Task object. 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

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

Converting the UID 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 MAY be set.

Other properties MAY be converted to JSPROP properties in the VALARM component.

Event and Task The Event object converts to a VEVENT component, the Task object converts to a VTODO component. In the iCalendar component, the value data types of the DTSTART, DUE and RECURRENCE-ID properties all MUST be of the same form, either DATE, or DATE WITH LOCAL TIME, or DATE WITH UTC TIME (see ). It MUST be DATE if the "showWithoutTime" property value is "true", the "timeZone" property value is null, and the time component is zero in the values of the "start", due", "duration", "estimatedDuration", "recurrenceId" properties, and the "until" property of the RecurrenceRule object, and in any key of the "recurrenceOverrides" property value. Otherwise, it MAY be DATE WITH UTC TIME if the "timeZone" property value is "Etc/UTC" and the "endTimeZone" property value is null. It MUST be DATE WITH LOCAL TIME in all other cases. 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
freeBusyStatus	TRANSP
keywords	CATEGORIES
links	ATTACH, or other	Link object
locale	LANGUAGE (parameter) of SUMMARY property	, ,
locations	LOCATION, GEO, or VLOCATION (component)	Location object
mainLocationId	LOCATION	Location object
method	METHOD of iCalendar object	, and Group object
organizerCalendarAddress	ORGANIZER
participants	ATTENDEE, or PARTICIPANT (component)	Participant object
priority	PRIORITY
privacy	CLASS
prodId	PRODID of iCalendar object	, and Group object
progress	STATUS
recurrenceId	RECURRENCE-ID
recurrenceIdTimeZone	TZID (parameter) of RECURRENCE-ID
recurrenceOverrides	RDATE, EXDATE or recurrence override component	, and remarks below
recurrenceRule	RRULE
relatedTo	RELATED-TO
sequence	SEQUENCE
showWithoutTime	SHOW-WITHOUT-TIME	, and remarks below
timeZone	TZID (parameter) of DTSTART and DUE	,
title	SUMMARY
uid	UID
updated	DTSTAMP, and LAST-MODIFIED	,
virtualLocations	CONFERENCE

Remarks:

The "descriptionContentType" property value determines if the "description" property converts to the DESCRIPTION or STYLED-DESCRIPTION property. A description of content type "text/plain" converts to the DESCRIPTION property. Any other description converts to the STYLED-DESCRIPTION property, in which case a plain text version of the rich-text description MAY be set additionally in the DESCRIPTION property, having its DERIVED parameter set to "TRUE". How to derive plain text from rich-text is implementation-specific.
The entries in the "recurrenceOverrides" property convert depending on the contents of the PatchObject value. A PatchObject that sets the "excluded" member to "true" converts to an EXDATE property for the date-time of that recurrence instance. An empty PatchObject converts to an RDATE property. Any other PatchObject converts to a recurrence override component in the embedding VCALENDAR component.
The "showWithoutTime" property only converts to the SHOW-WITHOUT-TIME property if the value data type of the DTSTART or DUE properties is of form DATE WITH UTC TIME or DATE WITH LOCAL TIME.

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	,
endTimeZone		TZID parameter of DTEND	,
start	,	DTSTART
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)
due		DUE
estimatedDuration		ESTIMATED-DURATION
percentComplete		PERCENT-COMPLETE
progress		STATUS
start	,	DTSTART

Other properties MAY be converted to JSPROP properties in the VEVENT or VTODO component.

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
description	DESCRIPTION, or STYLED-DESCRIPTION	, , and remarks below
entries	VEVENT or VTODO (component)	Event and Task object, and remarks below
keywords	CATEGORIES
links	ATTACH, or other	Link object
locale	LANGUAGE (parameter) of either NAME, or DESCRIPTION (in order of preference)	,
prodId	PRODID	, and remarks below
source	SOURCE
title	NAME
uid	UID
updated	LAST-MODIFIED

Remarks:

The "descriptionContentType" property value determines if the "description" property converts to the DESCRIPTION or STYLED-DESCRIPTION property. A description of content type "text/plain" converts to the DESCRIPTION property. Any other description converts to the STYLED-DESCRIPTION property, in which case a plain text version of the rich-text description MAY be set additionally in the DESCRIPTION property, having its DERIVED parameter set to "TRUE". How to derive plain text from rich-text is implementation-specific.
The prodId property value of the Group object is expected to be equal to the "prodId" property value of all the Group entries. They all convert to the same, single PRODID property in the VCALENDAR component. How to convert unequal prodId property values is implementation-specific.
The method property value in all the Group entries is expected to be equal. How to convert entries with unequal method property values is implementation-specific.

Other properties MAY be converted to JSPROP properties in the VCALENDAR component.

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

Choose the iCalendar property name indicated in the iCalendar of the JSCalendar object that contains this Link object, if set.
Choose IMAGE, if the "display" property is set.
Choose LINK, if the "rel" 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
contentType	FMTTYPE
display	DISPLAY	, and remarks below
rel	LINKREL
size	SIZE
title	LABEL

Other properties MAY be converted to JSPROP properties in the same component to which the Link object converts to as a property.

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

If the "iCalendar" property on the Location object is set, or the parent JSCalendar object contains an entry for that Location in the "convertedProperties" property of its "iCalendar" property, then convert the object back to the named iCalendar component or property.
Choose LOCATION if the key of the Location object in the "locations" property matches the "mainLocationId" property, or if the "name" property is set and the iCalendar component does not already contain a LOCATION property. The "name" property converts to the LOCATION property value.
Choose the VLOCATION component otherwise.

Implementations MAY convert one of the Location objects to both a VLOCATION component and the LOCATION and GEO properties of the component that contains the VLOCATION component. In this case, the DERIVED parameter MUST be set on the LOCATION and GEO properties with value "TRUE". The properties convert to a VLOCATION component as follows: Properties of the Location object

Name	Property (or other)	See
coordinates	COORDINATES	,
links	ATTACH, or other	Link object
locationTypes	LOCATION-TYPE
name	NAME

Other properties MAY be converted to JSPROP properties in the VLOCATION component, or the component which the Location converts to as a property.

Participant The Participant object converts to an ATTENDEE property and PARTICIPANT component, unless it is fully represented by the ORGANIZER property:

It if fully represented by the ORGANIZER property if its "calendarAddress" property value matches the "organizerCalendarAddress" property value, and it does not have any role but the "owner" role set, and it only has properties set that convert to ORGANIZER parameters (see ).
Otherwise, it converts to an ATTENDEE property if the "calendarAddress" property is set. The "calendarAddress" converts to the ATTENDEE property value.
It converts to a PARTICIPANT component if any of the Participant properties in are set. If the Participant object also converts to an ATTENDEE property, then the CALENDAR-ADDRESS property value of the PARTICIPANT component MUST match the ATTENDEE property value.

The following Participant properties convert to parameters of the ATTENDEE property. How to convert these if the Participant "calendarAddress" property is not set 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	, and remarks below
expectReply	RSVP
kind	CUTYPE
memberOf	MEMBER
name	CN	, and remarks below
participationStatus	PARTSTAT
progress	PARTSTAT	, and remarks below
roles	ROLE	, and remarks below
sentBy	SENT-BY	, and remarks below

Remarks:

The "owner" role needs not convert to the ROLE parameter of the ATTENDEE property if the Participant object converts to both the ATTENDEE and ORGANIZER property.
The "name", "email" and "sentBy" properties also convert to parameters of the ORGANIZER property, if the Participant converts to the ORGANIZER property.
The progress property converts to the PARTSTAT parameter as outlined in .

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

Name	Property (or other)	See
description	DESCRIPTION, or STYLED-DESCRIPTION	, , and remarks below
descriptionContentType	FMTTYPE (parameter) of STYLED-DESCRIPTION
links	ATTACH, or other	Link object
name	SUMMARY
percentComplete	PERCENT-COMPLETE

Other properties MAY be converted to JSPROP properties in the PARTICIPANT component, or the component which the Participant converts to as a property.

VirtualLocation The VirtualLocation object converts to a CONFERENCE property. The "uri" property converts to the CONFERENCE property value. The following properties convert to parameters of the CONFERENCE property: Properties of the VirtualLocation object

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

Updates to iCalendar

New Properties

JSID

Property Name:: JSID
Purpose:: This property preserves the identifier of a JSCalendar object value in iCalendar.
Value type:: TEXT; also see "Format Definition" below for value restrictions.
Property Parameters:: IANA and non-standard property parameters can be specified on this property.
Conformance:: This property can be specified at most once in any calendar component.
Description:: This property specifies the JSON object key of the JSCalendar object to which an iCalendar component converts to. For example, this property set in a VALARM component within a VEVENT component defines the key of the Alert object value in the Event object's "alerts" property (see ). The value of the JSID property MUST be a valid object key according to the definition of the JSCalendar property to which the component converts to.
Format Definition:: This property is defined by the following notation:
Example(s):: The following example illustrates how to convert the JSID property set in a VALARM component.
Converting the JSID property of a VALARM component

JSPROP

Property Name:: JSPROP
Purpose:: This property represents a JSCalendar property in iCalendar.
Value type:: TEXT; also see "Format Definition" below for value restrictions.
Property Parameters:: The JSPTR parameter MUST be specified on this property. Other IANA and non-standard property parameters can be specified on this property.
Conformance:: This property can be specified multiple times in any calendar component.
Description:: This property converts an arbitrary JSCalendar property from and to iCalendar. The iCalendar property value is the JSON-encoded value of the JSCalendar property, represented as a TEXT value. The JSON value MUST NOT be the null value, and it SHOULD NOT contain insignificant whitespace as defined in . The value of the JSPTR parameter points to the JSCalendar property within the JSCalendar object and MUST NOT start with the SOLIDUS (U+002F) character. The pointer MUST NOT reference into an array. All JSPROP properties in a calendar component together form a PatchObject: the JSPTR parameter of a JSPROP property corresponds to a key in the PatchObject, the property value corresponds to the JSON value for that key. When converting from iCalendar to JSCalendar, the PatchObject MUST only be applied after all other iCalendar elements of the component have been converted. Only new properties are allowed to be set, a JSON pointer in the PatchObject that points to an existing property MUST be ignored.
Format Definition:: This property is defined by the following notation:
Example(s):: The following example illustrates how to convert a JSPROP property with a JSON boolean value
Converting the JSPROP property with a JSON boolean value
The following example illustrates how to convert a JSPROP property with a JSON object value
Converting the JSPROP property with a JSON object value
The following example illustrates how to convert a JSPROP property that points to a property within a JSCalendar Alert. The JSON pointer in the JSPTR parameter is relative to the Alert object.
Converting the JSPROP property within a VALARM component
The following example illustrates how to convert a JSPROP property that points to a property within a JSCalendar Link. The JSON pointer in the JSPTR parameter is relative to the Event object because the Link object converts to an iCalendar property. The JSID parameter on the ATTACH property ensures that the JSON path remains valid during conversion.
Converting the JSPROP property within a Link object

New Parameters

JSID

Parameter Name:: JSID
Format Definition:
Description:: This parameter specifies the JSON object key of the JSCalendar object to which an iCalendar property converts to. For example, this parameter set on an ATTACH property within a VEVENT component defines the key of the Link object value in the Event object's "links" property (see below for an example). The value of the JSID parameter MUST be a valid key according to the definition of the JSCalendar property to which the property that this parameter is set on converts to. Typically, this requires the value to be a valid Id.
Example(s):: Converting the JSID parameter on an ATTACH property

JSPTR

Parameter Name:: JSPTR
Format Definition:
Description:: This parameter is specified on a JSPROP property. Its value is a JSON pointer that points to a JSCalendar property.
Description:: This parameter has a single value that MUST be a valid JSON pointer as defined in . The value MUST be quoted to preserve its case-sensitivity and it MUST NOT contain the DQUOTE character. See for how to format parameter values.
Example(s):: For further examples, see .

Updates to JSCalendar

New Properties

iCalendar

Name:

iCalendar

Context:

Any JSCalendar object

Type:

ICalComponent (optional)

Description

This property contains information about iCalendar data that got converted to this JSCalendar object. It allows for preserving the name of iCalendar elements, such as a component's name, properties and subcomponents. This specification defines the ICalComponent object type for converting iCalendar components to a JSCalendar object. Future specifications MAY define additional value types for this property. An ICalComponent object has the following properties:

@type: String: This specifies the type of this object. This MUST be ICalComponent, if set.
name: String (mandatory): This is the name of the iCalendar component in lowercase.
components: *[][] (optional): This contains subcomponents of the iCalendar component which did not convert to standard JSCalendar elements. The value MUST be a list of iCalendar components formatted in jCal as defined in .
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 JSCalendar element. The value for each key contains information about the iCalendar property which converted to the JSCalendar element located at that key. Unless otherwise defined for a specific iCalendar property, the path points to that JSCalendar object property to which the iCalendar property value converted to. The key MUST be a valid key of a PatchObject as defined in . The key MAY point to the key in a nested object if the element at that key was converted from an iCalendar property of the component for which the "iCalendar" property is set. It MUST NOT point into nested objects otherwise.
properties: *[][] (optional): This contains properties of the iCalendar component which did not convert to standard JSCalendar elements. The value MUST be a list of iCalendar properties formatted in jCal as defined in .

An ICalProperty object has the following properties:

@type: String: This specifies the type of this object. This MUST be ICalProperty, if set.
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|String[]] (optional): This contains parameters of the iCalendar property. The value MUST comply with iCalendar parameters formatted in jCal as defined in .

The example in describes how to convert unknown iCalendar elements to the "iCalendar" property. The "X-FOO" parameter set on the SUMMARY property illustrates how to preserve an unknown iCalendar parameter on a property that does convert to a standard JSCalendar element. The "X-BAR" property and "X-BAZ" component illustrate how to convert entirely unknown iCalendar elements.

Converting unknown iCalendar elements to the iCalendar property

IANA Considerations

Changes to the "iCalendar Element Registries" IANA will add the following entries to the "Properties" registry:

Property: JSID
Status: Current
Reference

Property: JSPROP
Status: Current
Reference

IANA will add the following entries to the "Parameters" registry:

Parameter: JSID
Status: Current
Reference

Parameter: JSPTR
Status: Current
Reference

Changes to the "JSCalendar Registries" IANA will add the following entries to the "JSCalendar Properties" registry:

Property Name: iCalendar
Property Type: ICalComponent
Property Context: Event, Location, Participant, Task
Reference
Intended Usage: common
Is Per-User: no
Change Controller: IETF

Property Name: iCalendar
Property Type: ICalComponent
Property Context: Alert
Reference
Intended Usage: common
Is Per-User: yes
Change Controller: IETF

References Normative References IANA Time Zone Database Informative References JMAP for Calendars Fastmail Spherical Cow Group Task Extensions to iCalendar Bedework Commercial Services DHL Express JSCalendar: A JSON Representation of Calendar Data Fastmail Fastmail iCalendar Format Extensions for JSCalendar Fastmail

Discrepancies between iCalendar and JSCalendar This section highlights iCalendar and JSCalendar elements for which no conversion rule to a standard element is defined in this document. This is informational and only complete at the time of publication of this document. Implementations MAY choose to convert the following elements, for example using the properties defined in and , or they might convert them to some vendor-specific extension properties. Later RFC documents might also define new standard elements and register them at IANA, either extending this list of inconvertible elements, or rather reduce it by introducing a standard element to convert to.

Unsupported iCalendar Elements

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

AVAILABLE
VAVAILABILITY
VFREEBUSY
VJOURNAL
VRESOURCE
VTIMEZONE
VSTATUS

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
COMMENT
CONTACT
CREATED
LAST-MODIFIED
LINK
LOCATION
PARTICIPANT-TYPE
PRIORITY
REASON
RELATED-TO
REQUEST-STATUS
RESOURCES
STATUS
STRUCTURED-DATA
UID
URL

VALARM

ATTACH
ATTENDEE
DESCRIPTION
DURATION
PROXIMITY
REPEAT
STYLED-DESCRIPTION
SUMMARY
UID

VCALENDAR

CALSCALE
LINK
REFRESH-INTERVAL
URL
VERSION

VEVENT

COMMENT
CONTACT
LINK
REFID
REQUEST-STATUS
RESOURCES
STRUCTURED-DATA
URL

VLOCATION

DESCRIPTION
LINK
UID
STRUCTURED-DATA
STYLED-DESCRIPTION

VTODO

COMMENT
COMPLETED
CONTACT
LINK
REFID
REQUEST-STATUS
RESOURCES
STRUCTURED-DATA
TASK-MODE
URL

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

PARTICIPANT

VLOCATION

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.

RDATE

PERIOD

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

DIR
SCHEDULE-AGENT
SCHEDULE-FORCE-SEND
SCHEDULE-STATUS
SENT-BY
LANGUAGE