FastMail

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

FastMail

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

Bedework Commercial Services

226 3rd Street Troy NY 12180 United States of America mdouglass@bedework.com http://bedework.com

Applications Calendaring extensions JSON iCalendar calendar events date time This document provides the required methods for converting JSCalendar from and to iCalendar.

This is still very much a work in progress. There are implementations of the mapping but there may be changes over the coming weeks.

The JSCalendar data format is used to represent calendar data, and is meant as an alternative to the widely deployed iCalendar data format. While new calendaring services and applications might use JSCalendar as their main data format to exchange calendaring data, they are likely to interoperate with services and clients that just support iCalendar. Similarly, existing calendaring data is stored in iCalendar format in databases and other calendar stores, and providers and users might want to represent this data also in JSCalendar. Lastly, there is a requirement to preserve custom iCalendar properties that have no equivalent in JSCalendar when converting between these formats. To support these use cases, this document provides the required approach when converting JSCalendar data from and to iCalendar.

JSCalendar and iCalendar have a lot of semantics in common, but they are not interchangeable formats: JSCalendar contains a richer data model to express calendar information such as event locations and participants. while future iCalendar extensions may allow a direct mapping, for now there may be no representation directly in iCalendar of some properties. These values may have to be extracted from a full copy of the iCalendar format provided as a property in the JSCalendar data. iCalendar may contain arbitrary, non-standardised data with custom properties/attributes. These will be translated using the same approach as jCal. iCalendar has some obsolete features that have been removed from JSCalendar due to not being useful and/or supported in the real world (e.g. custom email alerts to send to random people). Translating these may lose some of the original fidelity. Implementations may use a custom property to store data that could not be mapped directly in either direction in the original or a custom format, however this is not interoperable. Accordingly, this document defines a canonical translation between iCalendar and JSCalendar, and implementations MUST follow the approaches specified here when iCalendar data is represented in JSCalendar and vice-versa. This document defines mappings for the following specifications. Therefore all of these specifications MUST be implemented to follow this specification.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in .

FRACTIONAL This parameter is used to contain a value with fractional seconds for time values and durations. FRACTIONAL MUST NOT be used in date-time calculations or comparisons in  iCalendar. It is meant to preserve time precision on time values and duration with sub-second precision, without increasing the time value range within iCalendar. This parameter MAY be specified on properties of type DATE-TIME or DURATION. It MUST be a valid iCalendar DATE-TIME or DURATION value with the addition of fractional seconds. The value MUST NOT be negative for durations but MAY be negative for alarm triggers. iCalendar implementations SHOULD ignore this parameter in date time arithmetic. Implementations MUST ignore presence of the FRACTIONAL parameter on RECURRENCE-ID properties when determining recurrence overrides. Applications receiving a property with a FRACTIONAL parameter MUST ensure its value is consistent with the value of the property. The property value must match: - a positive FRACTIONAL value rounded up to the next non-fractional second or - a negative FRACTIONAL value rounded down the next non-fractional second If the values do not match the the application MUST assume that the property value has been updated by an application that is unaware of the FRACTIONAL parameter. The parameter should be ignored in this case.

This parameter is defined by the following notation: fractional-param = DATE-TIME or DURATION

iCalendar uses a line-folding mechanism to limit lines of data to a maximum line length (typically 75 octets) to ensure the maximum likelihood of preserving data integrity as it is transported via various means (e.g., email) -- see Section 3.1 of . iCalendar data uses an "escape" character sequence for text values and property parameter values. See Sections 3.1 and 3.3 of as well as [RFC6868]. There is a subtle difference in the number representations between JSON and iCalendar. While in iCalendar, a number may have leading zeros, as well as a leading plus sign; this is not the case in JSON. Numbers should be represented in whatever way needed for the underlying format. When converting from iCalendar to JSCalendar: First, iCalendar lines MUST be unfolded. Afterwards, any iCalendar escaping MUST be unescaped. Finally, JSON escaping, as described in Section 7 of , MUST be applied. The reverse order applies when converting from JSCalendar to iCalendar, which is further described in Section ?. iCalendar uses a base64 encoding for binary data. However, it does not restrict the encoding from being applied to non-binary value types. So, the following rules are applied when processing a property with the "ENCODING" property parameter set to "BASE64": If the property value type is "BINARY", the base64 encoding MUST be preserved. If the value type is not "BINARY", the "ENCODING" property parameter MUST be removed, and the value MUST be base64 decoded. When base64 encoding is used, it MUST conform to Section 4 of [RFC4648], which is the base64 method used in [RFC5545]. One key difference in the formatting of values used in iCalendar and JSCalendar is that, in JSCalendar, the specification uses date/time values aligned with the extended format of [ISO.8601.2004], which is more commonly used in Internet applications that make use of the JSON format. The sections of this document describing the various date and time formats contain more information on the use of the complete representation, reduced accuracy, or truncated representation.

This section is an alphabetic list of components and how they are mapped to JSCalendar. At present VFREEBUSY and VJOURNAL are not mapped in jscalendar.

An VALARM component is mapped to a member of a JSCalendar "alerts" object with a type of "Alert" and a small id.

The VALARM has a number of problems which are not carried over into JSCalendar. Clients tend to choose how, and in some cases when to notify the user. For example, if the user has a smart-watch they may get tapped on the wrist. The method of notification may depend on which device is being used and the context, for example a meeting or driving. Also, many clients are taking into consideration the travel time and notifying the user earlier if it seems necessary. Specifying that a client should send emails to all attendees is both annoying and dangerous. Attendees have their own preferences for how and when they should be notified. Accordingly, the specification only allows for "display" and "email" actions and - other than specifying when - does not allow much else. Clients and/or servers will generally use the associated event or task title as identification. User preferences generally indicate what actions they prefer. An ACTION property can take the defined values "AUDIO" / "DISPLAY" / "EMAIL" whereas the JSCalendar "action" property only supports "display" and "email". An "AUDIO" alarm SHOULD be mapped to a "display" alert. Any attachment MUST be ignored. The example VALARMs will be mapped as follows, assuming they are all in the same event:

Note that the ATTACH, ATTENDEE, DESCRIPTION, DURATION, REPEAT and SUMMARY properties have been dropped.

A VCALENDAR component may be mapped to a JSCalendar object with a type of "jsgroup".

Note that a single JSEvent or JSTask MAY be converted without a surrounding JSGroup if the VCALENDAR component only contains PRODID and CALSCALE properties. In this case the prddid can go in the JSEvent or JSTask. The CALSCALE property is dropped - there is no equivalence in JSCalendar.

A VEVENT component is mapped to a JSCalendar object with a type of "jsevent".

A VLOCATION component is mapped to a JSCalendar object with a type of "Location". Any properties within the VLOCATION must be mapped as described below.

A VTIMEZONE component is mapped to a member of a JSCalendar "timezones" object with a type of "TimeZone" and an id which follows the restrictions specified. The STANDARD and DAYLIGHT components map to JSCalendar TimeZoneRule objects as members of the Note that There is no current approach for defining standalone sets of timezones. Timezones defined in the IANA timezone database SHOULD NOT be redefined in the object. Only custom timezones will be defined.

A VTODO component is mapped to a JSCalendar object with a type of "jstask".

This section is an alphabetic list of and properties and how they are mapped to JSCalendar.

A ATTACH allows for two types of attachment: A uri value A binary value Both map to a JSCalendar "link" object with a "rel" of "enclosure" and the "href" set to the value of the property. If the FMTTYPE parameter is set then add a JSCalendar "contentType" property to the link object. For a binary value use a base64 data uri. For an example of a recurring event with ATTACH see

An ATTENDEE maps to the JSCalendar "participant" property with a JSCalendar "role" of "attendee". The value for role should always be set. In the simplest case a JSCalendar "participant" property will be created and added to the JSCalendar "participants" property. The value of the ATTENDEE property is used to add an "imip" method to the JSCalendar "sendTo" property. The value of the entry will be the ATTENDEE property value. For example:

The attendee parameters are mapped to JSCalendar "participant" properties as follows: The value of the CN parameter is used to set the JSCalendar "name" property. This maps on to the JSCalendar "kind" property as follows: "individual" "group" "resource" "location" No value Any other value should be converted to lower case and assigned to the JSCalendar "kind" property. Split the value at any commas and add each resulting element to the JSCalendar "delegatedFrom" property Split the value at any commas and add each resulting element to the JSCalendar "delegatedFrom" property If non-null look in the participant "links" property for a JSCalendar "link" property with an href with the same value as the DIR parameter. You may need to search the current override and the master. If none is found create a new one with the JSCalendar "href" property set to the value of the DIR parameter and the JSCalendar "rel" property set to "alternate" set the JSCalendar "language" property to the value of the LANG parameter. If this is set there should be a corresponding ATTENDEE object with a value equal to the value of the member parameter. If not it is appropriate to skip this parameter. If there is a corresponding ATTENDEE then there should be a corresponding JSCalendar "participant" property. This suggests that CUTYPE=GROUP ATTENDEE properties should be processed ahead of the others. Locate the JSCalendar "participant" property for the group. This may be in the current override or in the master. Add the id to the current participants JSCalendar "memberOf" property. If the PARTSTAT parameter is set and is not "NEEDS-ACTION" then set the JSCalendar "participationStatus" property to the lower-cased value of the PARTSTAT. This is mapped to the JSCalendar "roles" property as follows: "attendee" and "chair" "attendee" "attendee" and "optional" "informational" Any other value should be converted to lower case and added to the JSCalendar "roles" property. If the value of the RSVP parameter is TRUE set the JSCalendar "expectReply" property to "true" otherwise omit it. If the value is "CLIENT" (ignoring case) set the JSCalendar "scheduleAgent" property to "client" otherwise omit it. Set the JSCalendar "scheduleForceSend" property to the lower-cased value of the SCHEDULE-FORCE-SEND parameter. Split the value at any commas and add each resulting element to the JSCalendar "scheduleStatus" property. The value of the SENT-BY parameter is used to set the JSCalendar "invitedBy" property.

A CALSCALE has no equivalence in JSCalendar. It is ignored.

These map on to the JSCalendar "keywords" property with each category being the key to an entry.

Maps to the "privacy" property. The iCalendar property value maps to the JSCalendar value as follows: "secret" "private" "public" verbatim copy

Maps to the "color" property. Copy the verbatim value.

There is no direct mapping for this property which may appear multiple times in . For a scheduling reply it is presumably a message by the participant so the value or values should be used to set the JSCalendar "participantComment" property.

Set the JSCalendar "progress" property to "completed" and the "progressUpdated" property to the reformatted date/time.

This property may appear multiple times in components. Each instance of the property is mapped on to a member of the JSCalendar "categories" property.

Maps to a "VirtualLocation" object. The property value maps to the "uri" property of the virtual location. Mapping parameters: Maps to the "features" property of the virtual location. Maps to the "name" property of the virtual location. No mapping.

The CONTACT property is mapped on to a participant object with a "roles" property of "contact" and an "order" property of 1 (one). This defines the participant as a primary contact. Mapping parameters: Use the same process as for the ATTENDEE DIR parameter: create a link property with the "rel" property set to "alternate" and the "href" property set to the value of the ALTREP parameter. Then add the link to the participants "links" property. Set the participants "language" property. For an example see

The CREATED property is mapped on to a "created" property with a json formatted form of the date. Example:

Copy the value, preprocessed according to into the "description" property. Mapping parameters: No mapping. Use the "locale" property. Example:

If the DTSTART is a DATE only property then add the JSCalendar showWithoutTime property with the value set to "true". The JSCalendar "start" property is set with zero time values. If the DTSTART has a TZID parameter then set the JSCalendar "timeZone" property to the value of TZID. If the DTSTART has a UTC value then set the JSCalendar "timeZone" property to the value "Etc/UTC". The JSCalendar "start" property is set without any UTC indicator. JSCalendar has no equivalent to DTEND. If the component has a DTEND then calculate a value for "DURATION" from that property and DTSTART and proceed as below. If the DTEND has a TZID parameter with a value that differs from the DTSTART TZID parameter then a "location" object should be created with a "relativeTo" property set to "end" and a "timezone" property set to the value of the "TZID" parameter. Note that a task is not required to have a DTSTART so the JSCalendar "timezone" property needs to be set from the DUE property. Convert a DURATION property to the JSCalendar duration. Example - DTSTART and DTEND in same timezone:

Example - DTSTART and DTEND in different timezone:

Example - 3 day event:

Create a patch object with the recurrence id set from the EXDATE value. Add a single JSCalendar "excluded" property with the value set to true. There MUST NOT be any other properties set - other than "@type".

Maps to the "excludedRecurrenceRules" property. Also see .

The mapping depends on whether or not the component is a scheduling entity. The DTSTAMP and LAST-MODIFIED properties have essentially the same meaning. If both are present use the value of the latest for the "updated" property. Otherwise set from whichever is present. DTSTAMP should be used to set the "ScheduleUpdated" property in the "participant" object for the attendee. If present LAST-MODIFIED should be used to set the "updated" property - otherwise set it from the DTSTAMP.

Maps to a Location object, with only the "coordinates" property set. Note that the JSCalendar coordinates property value MUST be a valid "geo" URI, so replace the ";" character in the iCalendar value with "," and prepend the resulting string with "geo:".

Maps to a Link object with the iCalendar property value mapped to the location "href" property, and the "rel" property set to "icon". For a binary value use a base64 data uri in the "href" property. Mapping parameters: No mapping. Maps to the "contentType" property of the Link object. Maps to the "display" property of the Link object. The property values "BADGE", "GRAPHIC", "FULLSIZE" and "THUMBNAIL" map to their lower-case equivalent in JSCalendar.

If any "VLOCATION" components are present, then the "LOCATION" property should be ignored. To map the property create a "locations" property with a single "location" and set the "description" property to the value of the "LOCATION" property. Mapping parameters: Maps to a Link object in the Location "links" property, with the "href" property set to the parameter value.

Maps to the "method" property of the JSCalendar object. The JSCalendar property value is the lowercase equivalent of the iCalendar property value.

Maps to the "replyTo" property of the JSCalendar object. An iCalendar property value in the "mailto:" URI scheme, maps to the "imip" method, any other value maps to the "other" method. If the iCalendar component also contains an ATTENDEE with the same calendar user address then map that ATTENDEE as defined in and add the "owner" role to the Participant "roles" property. Otherwise, use the ORGANIZER property to map to a Participant object. The "roles" property of the Participant MUST only contain the "owner" role and the "expectReply" property value MUST be "false". Any iCalendar parameters map as defined for ATTENDEE. TBD: SENT-BY parameter. Example.

For all methods other than REPLY (or no method), the PERCENT-COMPLETE applies to the VTODO as a whole. In this case it the value is used to set the JSCalendar "percentComplete" property in the task object.

PERCENT-COMPLETE in a REPLY is used to indicate the level of completeness of the ATTENDEE. There should only be a single ATTENDEE in the VTODO object. As ever recurrences complicate matters. For a non-recurring event or an override that contains the single participant, set the JSCalendar "percentComplete" property in the JSCalendar "participant" object representing the attendee.

In the case of an override with the participant appearing in the master then add a patch to the override.

Simply copy value into the JSCalendar "priority" property.

For a vcalendar JSGroup object with multiple JSEvent and/or JSTask object the VCALENDAR PRODID is mapped to a JSCalendar "prodid" property in the group. When mapping to a single JSEvent and/or JSTask object the VCALENDAR PRODID is mapped to a JSCalendar "prodid" property in the group

Refer to for information on mapping recurrence ids.

This is mapped to the JSCalendar "relatedTo" property which is a map of relations with the target UID as the keys. The iCalendar relation is by default a PARENT relationship. There is no default for JSCalendar so the relationship must be explicitly specified. The RELTYPE parameter values map to their lowercase equivalents in the "relation" property. Also note that the iCalendar relationship types are not identical. CHILD and PARENT map to JSCalendar "child" and "parent" but the best match for iCalendar SIBLING is "next"

Copy the value into the JSCalendar "requestStatus" property.

The RESOURCES property value is a comma-separated list of resources. First split this into the separate resource names and then each resource is mapped on a participant object with a "kind" property of "resource" and the "name" property set to the resource name. Mapping parameters: Use the same process as for the ATTENDEE DIR parameter: create a link property with the "rel" property set to "alternate" and the "href" property set to the value of the ALTREP parameter. Then add the link to the participants "links" property. Set the participants "language" property. For an example see

If the RDATE has a RANGE=THISANDFUTURE parameter then the recurrence MUST be split at this RDATE. Truncate the original object before this RDATE, create a new master representing the object and link them by setting the jscalendar "relatedTo" property in both. Otherwise create a patch object with the recurrence id set from the RDATE value. If the instance has overrides the differences will also be set in the object.

Each RRULE is converted to an object in the JSCalendar "recurrenceRules" property. Each entry has the type "RecurrenceRule".

The recurrence rule object has one property for each element of the recurrence rule. The iCalendar rule has to be parsed out and the individual jscalendar property values set. Most take the same type but there are exceptions. Copy into the jscalendar "frequency" property converted to lowercase. If present and not 1 copy into the jscalendar "interval" property. If present copy into the jscalendar "rscale" property converted to lowercase. If present copy into the jscalendar "skip" property converted to lowercase. If present copy into the jscalendar "firstDayOfWeek" property converted to lowercase. If present each element becomes an entry in the jsCalendar "byDay" propety. This is an array of NDay objects which may have 2 properties: The two character weekday abbreviation. If the weekday abbreviation is preceded by a signed integer value set the jscalendar "nthOfPeriod" property.

If present each element will be an element in the jscalendar "byMonthDay" property. If present each element will be an element in the jscalendar "byMonth" property. Note that the iCalendar values are numeric but the JSCalendar values are strings. This is because of the possible "L" suffix for leap months. If present each element will be an element in the jscalendar "byYearDay" property. If present each element will be an element in the jscalendar "byWeekNo" property. If present each element will be an element in the jscalendar "byHour" property. If present each element will be an element in the jscalendar "byMinute" property. If present each element will be an element in the jscalendar "bySecond" property. If present each element will be an element in the jscalendar "bySetPosition" property. If present set in the jscalendar "count" property. If present set the jscalendar "until" property with the appropriately reformatted value. If the is no time part append a 0 time and reformat as a jscalendar local date/time. Some examples:

Copy the value into the JSCalendar "sequence" property.

For a VEVENT copy the lower-cased value into the JSCalendar "status" property. For a VTODO copy the lower-cased value into the JSCalendar "progress" property.

This property is mapped on to a JSCalendar "link" object with the value mapped on to the JSCalendar "href" property in a manner depending on the "STRUCTURED-DATA" "VALUE" parameter: Copy the value as a data uri either as plain text or by encoding as a base64 value. If plain text the value may need escaping as per . Copy the value as a data uri speifying base64 encoding. Copy the value as-is into the href. The "STRUCTURED-DATA" "SCHEMA" parameter is mapped on to a JSCalendar "schema" property within the link object. The "STRUCTURED-DATA" "FMTTYPE" parameter is mapped on to a JSCalendar "contentType" property within the link object. For example:

Copy the value into the JSCalendar "title" property. Mapping parameters: No mapping. Use the "locale" property.

If the value of the TRANSP property (ignoring case) is "opaque" set the JSCalendar "freeBusyStatus" property to the value "busy". Otherwise set the JSCalendar "freeBusyStatus" property to the value "free".

Copy the value into the JSCalendar "uid" property.

Maps to a Link object in the JSCalendar object's "links" property, with the URL property value mapped to the Link "href" property.

A simple object with overrides will be converted to a jsCalendar master event with the rules, recurrence dates and exclusion dates translated appropriately. Overrides MUST be mapped on to a jsCalendar patch object and added to the "recurrenceOverrides" property of the master event with the key being the value of the iCalendar RECURRENCE-ID translated to a json format. Any override property with the same value as the master SHOULD be ommitted. Remaining properties MAY be added in full. Where appropriate, differences SHOULD be expressed as a patch. This can result in a significant reduction in size for objects with small changes to overrides, for example changing the participation status of an attendee.

When inviting an attendee to a single instance of a recurring event, only that override should be sent to the attendee. In this case the override should be a complete jsCalendar object with the type set to the type of the master. Additionally, there MUST be a recurrenceId property set to the value of the recurrence id for that override. If the timezone of the start of the instance is different from the master value, then there must also be a "recurrenceIdTimeZone" property set to the start timezone of the master.

This section provides more complete examples of translating from to JSCalendar. As usual note that json string values may be split because of line width limits. This is not legal json.

This is an example of a recurring event with overrides. The first override removes an ATTACH property and adds an ATTACH property. The second override removes all ATTACH properties.

This example shows the conversion of a simple event with a single CONTACT property in JSCalendar.

TBD

In this more complex example there is no ORGANIZER or ATTENDEEs in the master event. There are overrides which invite one or more attendees. For one overrride the ORGANIZER is also an ATTENDEE. In the other that is not the case. This is reflected in the "roles" property for the organizer. Note that each override has its own "participants" property and the first has a links property to handle the DIR parameter on one attendee.

The same security considerations as for apply.

None.

The authors would like to thank the members of CalConnect for their valuable contributions. This specification originated from the work of the API technical committee of CalConnect, the Calendaring and Scheduling Consortium.

This section is an alphabetic list of all JSCalendar property types that map on to components.

A JSCalendar object with a type of "jsevent" is mapped on to a VEVENT component. If it is a single VEVENT then a VCALENDAR component must surround it and the JSCalendar "prodid" property will be converted to a PRODID.

When converting multiple JSEvent or JSTask objects the surrounding VCALENDAR object must have a PRODID set from either the JSGroup "prodid" or generated.

A JSCalendar object with a type of "jsgroup" is mapped on to a VCALENDAR component.

A JSCalendar object with a type of "jstask" is mapped on to a VTODO component. If it is a single VTODO then a VCALENDAR component must surround it and the JSCalendar "prodid" property will be converted to a PRODID.

When converting multiple JSEvent or JSTask objects the surrounding VCALENDAR object must have a PRODID set from either the JSGroup "prodid" or generated.

The JSCalendar TimeZone objects within a "timezones" property are mapped on to VTIMEZONE components within the surrounding VCALENDAR component. Each mapped TimeZone MUST only appear once.

When converting multiple JSEvent or JSTask objects the surrounding VCALENDAR object must have a PRODID set from either the JSGroup "prodid" or generated.

JSCalendar locations should be mapped on to VLOCATION components. Additionally, for backwards compatibility, a location should be mapped on to a LOCATION property. This property should be mapped from the only location or the one related to the start.

JSCalendar participants will be mapped on to different iCalendar properties and components depending on their jsCalendar role values. A participant with a role containing "contact" MUST be mapped on to an iCalendar CONTACT property and SHOULD also be mapped on to a PARTICIPANT component which provides a better mapping. A participant with a role containing "owner" MUST be mapped on to an iCalendar ORGANIZER property and SHOULD also be mapped on to a PARTICIPANT component which provides a better mapping. A participant with a role containing any of "attendee", "optional" or "informational" MUST be mapped on to an iCalendar ATTENDEE property and SHOULD also be mapped on to a PARTICIPANT component which provides a better mapping. A more complete mapping may be achieved by creating a PARTICIPANT component. For all properties the participants jsCalendar "language" property, if present, is mapped on to the iCalendar "LANG" property parameter. For all properties if the participant contains a jsCalendar "link" with a "rel" of "alternate" then the value of the link is used for the iCalendar "ALTREP" property parameter. Where do we get the cua?

The sections following this one are all the original ones from draft 1 writen by Robert/Neil - there for reference.

A JSEvent maps to the the iCalendar VEVENT component type . The following tables maps the JSEvent-specific properties to iCalendar: Property iCalendar counterpart duration DURATION property. If the VEVENT contains a DTEND property, the this maps to the duration property as the time span between DTSTART and DTEND when converting the respective time points to the UTC time zone. Fractional seconds SHOULD be preserved with the SUBSECOND parameter.

A JSTask object maps to the iCalendar VTODO component type . The following tables maps the JSTask-specific properties to iCalendar: Property iCalendar counterpart due Maps to the DUE property. See . estimatedDuration ESTIMATED-DURATION property in the RFC draft , or the DURATION property otherwise. Fractional seconds SHOULD be preserved with the SUBSECOND parameter. statusUpdatedAt COMPLETED property. The JSTask status property MUST have value completed. Fractional seconds SHOULD be preserved with the SUBSECOND parameter. progress PARTSTAT and COMPLETED properties, including the definitions in the RFC draft . status STATUS property, including the definitions in the RFC draft .

A JSGroup maps to a iCalendar VCALENDAR containing VEVENT or VTODO components. Property iCalendar counterpart entries VEVENT and VTODO components embedded in a VCALENDAR component. source SOURCE property.

This section contains recommendations how to map JSCalendar from and to iCalendar. It lists all common JSCalendar object properties in alphabetical order. Property iCalendar counterpart @type Determined by the iCalendar component type: jsevent for VEVENT, jstask for VTODO, jsgroup for VCALENDAR. alerts Each entry maps to a VALARM component. The action property maps to iCalendar ACTION, where both iCalendar DISPLAY and AUDIO values map to the display action. An EMAIL value maps to a JSCalendar email action. relativeTo and offset map to the TRIGGER property. categories CONCEPT property, defined in . color COLOR property, as specified in . created CREATED property. Fractional seconds SHOULD be preserved with the SUBSECOND parameter. description DESCRIPTION property. descriptionContentType Implementation-specific. excluded EXDATE property. Fractional seconds SHOULD be preserved with the SUBSECOND parameter. freeBusyStatus TRANSP property. invitedBy Implementation-specific. keywords CATEGORIES property, as specified in . links ATTACH (), URL or IMAGE () properties with URI value types map to the the Link href. The FMTTYPE parameter maps to type, the SIZE parameter to size. Mapping other properties is implementation-specific. locale LANGUAGE parameter of the SUMMARY or DESCRIPTION property. localizations Implementation-specific. locations See . method METHOD property of the embedding VCALENDAR. participants See . priority PRIORITY property. privacy CLASS property. prodId PRODID property. recurrenceOverrides RDATE and EXDATE properties, and any VEVENT or VTODO instances with a recurrence-id and same UID as the mapped main object. If the DTSTART property defines a SUBSECOND parameter, but the RECURRENCE-ID of a recurrence instance does not, then use the SUBSECOND parameter value of DTSTART to determine the recurrence override time stamp. recurrenceRule RRULE property. For all-day calendar objects, map the until property value to an iCalendar DATE (effectively removing the time component). To convert a DATE-typed UNTIL from iCalendar, set the time components of the LocalDateTime value to 23:59:59. If the iCalendar UNTIL value is a UTC date time, convert it to the local time in the JSCalendar calendar object time zone. To convert to iCalendar where the DTSTART or DUE property is of type DATE, omit the time component of the LocalDateTime value. relatedTo RELATED-TO property. replyTo An iCalendar ORGANIZER with a mailto: URI mapped to the imip method, or any other URI mapped to the other method. Mapping multiple methods is implementation-specific. sequence SEQUENCE property. showWithoutTime Implementation-specific. start Maps to the DTSTART property. See . status STATUS property. timeZone Maps to the TZID parameter. See . timeZones Each entry in the property maps to a VTIMEZONE in the embedding VCALENDAR component. title SUMMARY property. uid UID property. updated DTSTAMP and LAST-MODIFIED properties. Fractional seconds SHOULD be preserved with the SUBSECOND parameter. useDefaultAlerts Implementation-specific. virtualLocations See .

iCalendar defines two different time types, DATE and DATE-TIME, where the latter may occur in three forms (with local time, with UTC time, with local time and time zone reference). In contrast, JSCalendar does not define a distinct type for dates, and date times are defined with the LocalDateTime type only. A JSCalendar time maps to the iCalendar DATE type if all of the following criteria apply: The start (due) property value has zero time, or is not set. The duration (estimatedDuration) property value has zero time, or is a multiple of days or weeks, or is not set. The timeZone property value is null, or is not set. For all other cases, the time maps to an iCalendar DATE-TIME: With local time and time zone reference, if the timeZone property value is set and does not equal Etc/UTC. With UTC time, if the timeZone property value equals Etc/UTC. With local time, if the timeZone property value is null or not set. Fractional seconds SHOULD be preserved with the SUBSECOND parameter.

The iCalendar counterpart for JSCalendar Location objects is the iCalendar LOCATION property, or implementation-specific. Property iCalendar counterpart coordinates GEO property. description Implementation-specific. name LOCATION property value. rel Implementation-specific. timeZone Implementation-specific. uri The LOCATION ALTREP parameter. The iCalendar counterpart for JSCalendar VirtualLocation objects is the iCalendar CONFERENCE property. Property iCalendar counterpart description Implementation-specific. name LABEL parameter. uri CONFERENCE property value.

The following table outlines translation of JSCalendar participants. An iCalendar ORGANIZER maps to both the replyTo property and a participant with role owner. If an ATTENDEE with the same CAL-ADDRESS value exists, then it maps to the same participant as the ORGANIZER participant. Other participants map to ATTENDEEs. Property iCalendar counterpart attendance ROLE parameter values REQ-PARTICIPANT, OPT-PARTICIPANT and NON-PARTICIPANT. delegatedFrom DELEGATED-FROM parameter delegatedTo DELEGATED-TO parameter email EMAIL parameter, if defined. Otherwise the CAL-ADDRESS property value, if it is a mailto: URI. expectReply RSVP parameter kind CUTYPE parameter locationId Implementation-specific. memberOf MEMBER parameter name CN parameter participationStatus PARTSTAT parameter roles ROLE parameter. scheduleSequence SEQUENCE property of the participant's latest iMIP message scheduleUpdated DTSTAMP property of the participant's latest iMIP message sendTo A CAL-ADDRESS with a mailto: URI maps to the JSCalendar imip method, any other URI to the other method. Mapping multiple methods is implementation-specific.

Mapping custom or unknown properties between JSCalendar and iCalendar is implementation-specific. Implementations might use vendor-extension properties, which could also serve as basis for discussion for a JSCalendar standard extension. Alternatively, an implementation could preserve iCalendar properties and components in JSCalendar by use of a vendor-extension property formatted as jCal data.