JSCalendar: Converting from and to iCalendar

2.1.1. iCalendar Objects

Section 3.4 of [RFC5545] 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 [RFC5545] (Section 3.4) converts to a Group object [RFC8984] (Section 2.3).¶

Its properties convert as follows:¶

Its components convert as follows:¶

Other properties or components MAY be converted to the iCalComponent property (Section 5.1.1) of the Group object.¶

The following example illustrates how to convert the VCALENDAR component:¶

BEGIN:VCALENDAR
UID:41aa02b6-42d0-4f45-8cb4-8b5075be2e14
BEGIN:VEVENT
...

{
  "...": "",
  "@type": "Group",
  "entries": [
    {
      "...": "",
      "@type": "Event"
    }
  ],
  "uid": "41aa02b6-42d0-4f45-8cb4-8b5075be2e14"
}

2.1.2. Recurring Components

Components in an iCalendar object generally convert to distinct JSCalendar objects. For example, two VEVENT components with different UID property values in the same iCalendar object convert to two separate Event objects in the Group object's entries. This rule does not apply to recurrence overrides, defined as follows.¶

A VEVENT (or VTODO) component is a recurrence override if it has the RECURRENCE-ID property set, and the iCalendar object contains a VEVENT (or VTODO) component that does not have the RECURRENCE-ID but the RRULE property set, and the UID property values of the two components are equal. The component without the RECURRENCE-ID property is in that case referred to as the "main component".¶

The main component converts to an entry in the Group object's entries property.¶

The recurrence override converts to the recurrenceOverrides property of the converted main component. Its RECURRENCE-ID property value converts to the key in the recurrenceOverrides property. The value of the recurrenceOverrides property at that key is the PatchObject that transform the converted main component into the converted recurrence override. The recurrenceId and recurrenceIdTimeZone properties MUST NOT be set in the PatchObject.¶

The following example illustrates how to convert a main component and its recurrence override:¶

BEGIN:VCALENDAR
BEGIN:VEVENT
UID:F4257E1D-5461-4EF6-840F-9DFC653EB559
RRULE:FREQ=DAILY
DTSTART;TZID=Europe/Berlin:20240101T140000
...
END:VEVENT
BEGIN:VEVENT
UID:F4257E1D-5461-4EF6-840F-9DFC653EB559
RECURRENCE-ID;TZID=Europe/Berlin:20240202T140000
DTSTART;TZID=Europe/Berlin:20240202T160000
...
END:VEVENT
END:VCALENDAR

{
  "...": "",
  "@type": "Group",
  "entries": [
    {
      "...": "",
      "@type": "Event",
      "recurrenceOverrides": {
        "2024-02-02T14:00:00": {
          "start": "2024-02-02T16:00:00"
        }
      },
      "recurrenceRules": [
        {
          "@type": "RecurrenceRule",
          "frequency": "daily"
        }
      ],
      "start": "2024-01-01T14:00:00",
      "timeZone": "Europe/Berlin",
      "uid": "F4257E1D-5461-4EF6-840F-9DFC653EB559"
    }
  ]
}

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

The following example illustrates how to convert stand-alone recurrence instances:¶

BEGIN:VCALENDAR
BEGIN:VEVENT
UID:F4257E1D-5461-4EF6-840F-9DFC653EB559
RECURRENCE-ID;TZID=Europe/Berlin:20240202T140000
DTSTART;TZID=Europe/Berlin:20240202T160000
...
END:VEVENT
BEGIN:VEVENT
UID:F4257E1D-5461-4EF6-840F-9DFC653EB559
RECURRENCE-ID;TZID=Europe/Berlin:20240103T140000
DTSTART;TZID=Europe/Berlin:20240103T160000
...
END:VEVENT
END:VCALENDAR

{
  "...": "",
  "@type": "Group",
  "entries": [
    {
      "...": "",
      "@type": "Event",
      "recurrenceId": "2024-02-02T14:00:00",
      "recurrenceIdTimeZone": "2024-02-02T14:00:00",
      "start": "2024-02-02T16:00:00",
      "timeZone": "Europe/Berlin",
      "uid": "F4257E1D-5461-4EF6-840F-9DFC653EB559"
    },
    {
      "...": "",
      "@type": "Event",
      "recurrenceId": "2024-01-03T14:00:00",
      "recurrenceIdTimeZone": "2024-02-02T14:00:00",
      "start": "2024-01-03T14:00:00",
      "timeZone": "Europe/Berlin",
      "uid": "F4257E1D-5461-4EF6-840F-9DFC653EB559"
    }
  ]
}

2.1.3. JSCalendar Ids

JSCalendar generally uses JSON objects to represent a collection of same-typed values. The keys are of type Id [RFC8984] (Section 1.4.1), the values are JSCalendar object types. If an iCalendar element converts to a value in such a collection, then an implementation needs to choose an identifier as key.¶

This document defines the new JSCALID (Section 4.1.1) parameter and JSCALID property (Section 4.2.1), which allow to set a JSCalendar Id value when converting from JSCalendar to iCalendar. If they are set on a property or the component, then its value MUST be used as key when converting that element from iCalendar to JSCalendar. If no such parameter or property is set, then an implementation is free to choose any identifier, as long the following requirements are met:¶

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

2.1.4. Timezone identifiers

Converting temporal properties such as DTSTART, DTEND, and RECURRENCE-ID requires to not only determine the date and time of the property value, but also the timezone it references.¶

If the property value data type is DATE [RFC5545] (Section 3.3.4) or DATE-TIME in FORM #1: DATE WITH LOCAL TIME [RFC5545] (Section 3.3.5) then the timezone identifier is the JSON null value in JSCalendar.¶

If the property value data type is DATE-TIME in FORM #2: DATE WITH UTC TIME [RFC5545] (Section 3.3.5) then the timezone identifier is the string "Etc/UTC" in JSCalendar.¶

If the property value data type is DATE-TIME in FORM #3: DATE WITH LOCAL TIME AND TIME ZONE REFERENCE [RFC5545] (Section 3.3.5) then the timezone identifier is determined by the TZID parameter value:¶

If the TZID parameter value is equal to a name in the IANA Time Zone Database [TZDB] then the timezone identifier is that verbatim name.¶

If the TZID parameter value is unequal to an IANA timezone name then implementations MAY determine the name of an IANA timezone which has the same timezone rules over the timespan of the calendar object. Otherwise, the non-IANA timezone identifier is represented in JSCalendar as a string starting with the / (SLASH) character, followed by the TZID parameter value. The corresponding VTIMEZONE MUST be converted to the timeZones property with the prefixed identifier as key. See Figure 14 for an example.¶

2.1.5. DATE and DATE-TIME

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

2.2.1. PARTICIPANT

The PARTICIPANT component [RFC9073] (Section 7.1) converts to a Participant object [RFC8984] (Section 4.4.6).¶

Its properties convert as follows:¶

Its components convert as follows:¶

Other properties or components MAY be converted to the iCalComponent property (Section 5.1.1) of the Participant object. This includes mandatory properties such as UID [RFC5545] (Section 3.8.4.7).¶

The following example illustrates how to convert the PARTICIPANT component:¶

BEGIN:VEVENT
BEGIN:PARTICIPANT
UID:47AD2E1C-49D4-45DF-BD83-8398ACC7D8E2
STRUCTURED-DATA;VALUE=URI:
 http://dir.example.com/vcard/contacts/contact1.vcf
PARTICIPANT-TYPE:CONTACT
DESCRIPTION:A contact
END:PARTICIPANT
...

{
  "...": "",
  "@type": "Event",
  "participants": {
    "p32": {
      "@type": "Participant",
      "description": "A contact",
      "iCalComponent": {
        "name": "participant",
        "properties": [
          [
            "uid",
            {},
            "text",
            "47AD2E1C-49D4-45DF-BD83-8398ACC7D8E2"
          ]
        ]
      },
      "links": {
        "l4": {
          "@type": "Link",
          "href": "http://dir.example.com/vcard/contacts/contact1.vcf"
        }
      },
      "roles": {
        "contact": true
      }
    }
  }
}

2.2.2. VALARM

The VALARM component [RFC5545] (Section 3.6.6) converts to a Alert object [RFC8984] (Section 4.5.2).¶

Its properties convert as follows:¶

Other properties or components MAY be converted to the iCalComponent property (Section 5.1.1) of the Alert object. This includes mandatory properties such as ATTENDEE [RFC5545] (Section 3.8.4.1), DESCRIPTION [RFC5545] (Section 3.8.1.5), or SUMMARY [RFC5545] (Section 3.8.1.12).¶

The following example illustrates how to convert the VALARM component:¶

BEGIN:VEVENT
BEGIN:VALARM
TRIGGER:-PT30M
ACTION:DISPLAY
DESCRIPTION:Breakfast meeting
END:VALARM
...

{
  "...": "",
  "@type": "Event",
  "alerts": {
    "a8": {
      "@type": "Alert",
      "iCalComponent": {
        "name": "valarm",
        "properties": [
          [
            "description",
            {},
            "text",
            "Breakfast meeting"
          ]
        ]
      },
      "trigger": {
        "@type": "OffsetTrigger",
        "offset": "-PT30M"
      },
      "action": "display"
    }
  }
}

2.2.3. VEVENT

The VEVENT component [RFC5545] (Section 3.6.1) converts to a Event object [RFC8984] (Section 2.1).¶

VEVENT components with different UID property values in the same iCalendar object convert to different entries in the Group. They sort in the same order as in the VCALENDAR component.¶

Its properties convert as follows:¶

Its components convert as follows:¶

Other properties or components MAY be converted to the iCalComponent property (Section 5.1.1) of the Event object.¶

The following example illustrates how to convert the VEVENT component:¶

BEGIN:VCALENDAR
BEGIN:VEVENT
UID:DE935D01-3DF7-4201-B61A-D77D05C8B21A
DTSTART:20060102T030405Z
...
END:VEVENT
BEGIN:VEVENT
UID:60BE3D6E-6383-473A-BCF1-3C43EA1FA571
...
END:VEVENT
END:VCALENDAR

{
  "...": "",
  "@type": "Group",
  "entries": [
    {
      "@type": "Event",
      "showWithoutTime": false,
      "start": "2006-01-02T03:04:05",
      "timeZone": "Etc/UTC",
      "uid": "DE935D01-3DF7-4201-B61A-D77D05C8B21A",
      "...": ""
    },
    {
      "@type": "Event",
      "uid": "60BE3D6E-6383-473A-BCF1-3C43EA1FA571",
      "...": ""
    }
  ]
}

2.2.4. VLOCATION

The VLOCATION component [RFC9073] (Section 7.2) converts to a Location object [RFC8984] (Section 4.2.5).¶

Its properties convert as follows:¶

Other properties or components MAY be converted to the iCalComponent property (Section 5.1.1) of the Location object. This includes mandatory properties such as UID [RFC5545] (Section 3.8.4.7).¶

The following example illustrates how to convert the VLOCATION component:¶

BEGIN:VLOCATION
UID:4954DC22-5BD6-4E98-844D-0302982F54AC
NAME:The venue
STRUCTURED-DATA;VALUE=URI:
 http://dir.example.com/venues/big-hall.vcf
END:VLOCATION

"locations": {
  "e4": {
    "@type": "Location",
    "name": "The venue",
    "links": {
      "21": {
        "@type": "Link",
        "href": "http://dir.example.com/venues/big-hall.vcf",
        "iCalProperty": {
          "@type": "ICalProperty",
          "name": "structured-data"
        }
      }
    },
    "iCalComponent": {
      "@type": "ICalComponent",
      "properties": [
        [
          "uid",
          {},
          "text",
          "4954DC22-5BD6-4E98-844D-0302982F54AC"
        ]
      ]
    }
  }
}

2.2.5. VRESOURCE

The VRESOURCE component [RFC9073] (Section 7.3) converts to a Participant object [RFC8984] (Section 4.4.6).¶

Its properties convert as follows:¶

Other properties or components MAY be converted to the iCalComponent property (Section 5.1.1) of the Participant object. This includes mandatory properties such as UID [RFC5545] (Section 3.8.4.7).¶

The following example illustrates how to convert the VRESOURCE component:¶

BEGIN:VEVENT
BEGIN:VRESOURCE
UID:456789-abcdef-98765432
NAME:The projector
RESOURCE-TYPE:projector
STRUCTURED-DATA;VALUE=URI:http://dir.example.com/projectors/3d.vcf
END:VRESOURCE
...

{
  "...": "",
  "@type": "Event",
  "participants": {
    "p2": {
      "@type": "Participant",
      "description": "A contact",
      "iCalComponent": {
        "name": "participant",
        "properties": [
          [
            "uid",
            {},
            "text",
            "456789-abcdef-98765432"
          ],
          [
            "resource-type",
            {},
            "text",
            "projector"
          ]
        ]
      },
      "kind": "resource",
      "links": {
        "l4": {
          "@type": "Link",
          "href": "http://dir.example.com/projectors/3d.vcf"
        }
      },
      "name": "The projector"
    }
  }
}

2.2.6. VTIMEZONE

The VTIMEZONE component [RFC5545] (Section 3.6.5) converts to a TimeZone object [RFC8984] (Section 4.7.2).¶

Its properties convert as follows:¶

Its components convert as follows:¶

Other properties or components MAY be converted to the iCalComponent property (Section 5.1.1) of the TimeZone object.¶

The DAYLIGHT component [RFC5545] (Section 3.6.5) and STANDARD component [RFC5545] (Section 3.6.5) convert to a TimeZoneRule object [RFC8984] (Section 4.7.2).¶

Their properties convert as follows:¶

Other properties or components MAY be converted to the iCalComponent property (Section 5.1.1) of the TimeZoneRule object.¶

The following example illustrates how to convert the VTIMEZONE component:¶

BEGIN:VCALENDAR
BEGIN:VTIMEZONE
TZID:CustomTz
TZID-ALIAS-OF:Puerto_Rico
TZID-ALIAS-OF:America/Anguilla
LAST-MODIFIED:20240909T122233Z
TZUNTIL:20080709T000000Z
TZURL:https://example.com/tz/CustomTz.ics
BEGIN:DAYLIGHT
TZNAME:AWT
TZOFFSETFROM:-0400
TZOFFSETTO:-0300
DTSTART:19420503T000000
END:DAYLIGHT
BEGIN:DAYLIGHT
TZNAME:APT
TZOFFSETFROM:-0300
TZOFFSETTO:-0300
DTSTART:19450814T200000
END:DAYLIGHT
BEGIN:STANDARD
TZNAME:AST
TZOFFSETFROM:-0300
TZOFFSETTO:-0400
DTSTART:19450930T020000
END:STANDARD
END:VTIMEZONE
BEGIN:VEVENT
DTSTART;TZID=CustomTz:20080708T130000
...

{
  "...": "",
  "@type": "Group",
  "entries": [
    {
      "...": "",
      "@type": "Event",
      "start": "2008-07-08T13:00:00",
      "timeZone": "/CustomTz"
    }
  ],
  "timeZones": {
    "/CustomTz": {
      "@type": "TimeZone",
      "aliases": {
        "Puerto_Rico": true,
        "America/Anguilla": true
      },
      "validUntil": "2008-07-09T00:00:00Z",
      "daylight": [
        {
          "@type": "TimeZoneRule",
          "offsetFrom": "-0400",
          "offsetTo": "-0300",
          "start": "1942-05-03T00:00:00",
          "names": {
            "AWT": true
          }
        },
        {
          "@type": "TimeZoneRule",
          "offsetFrom": "-0300",
          "offsetTo": "-0300",
          "start": "1945-08-14T20:00:00",
          "names": {
            "APT": true
          }
        }
      ],
      "standard": [
        {
          "@type": "TimeZoneRule",
          "offsetFrom": "-0300",
          "offsetTo": "-0400",
          "start": "1945-09-30T02:00:00",
          "names": {
            "AST": true
          }
        }
      ],
      "tzId": "CustomTz",
      "updated": "2024-09-09T12:22:33Z",
      "url": "https://example.com/tz/CustomTz.ics"
    }
  }
}

2.2.7. VTODO

The VTODO component [RFC5545] (Section 3.6.2) converts to a Task object [RFC8984] (Section 2.2).¶

VTODO components with different UID property values in the same iCalendar object convert to different entries in the Group. They sort in the same order as in the VCALENDAR component.¶

Its properties convert as follows:¶

Its components convert as follows:¶

Other properties or components MAY be converted to the iCalComponent property (Section 5.1.1) of the Task object.¶

The following example illustrates how to convert the VTODO component:¶

BEGIN:VCALENDAR
BEGIN:VTODO
UID:83C80482-806D-41C4-8029-E438F793005D
DUE:20060102T030405Z
...

{
  "...": "",
  "@type": "Group",
  "entries": [
    {
      "...": "",
      "@type": "Task",
      "due": "2006-01-02T03:04:05",
      "timeZone": "Etc/UTC",
      "uid": "83C80482-806D-41C4-8029-E438F793005D"
    }
  ]
}

2.3.1. ACKNOWLEDGED

The ACKNOWLEDGED property [RFC9074] (Section 6.1) in a VALARM component converts to the acknowledged property [RFC8984] (Section 4.5.2) of the Alert object.¶

The following example illustrates how to convert the ACKNOWLEDGED property:¶

BEGIN:VEVENT
BEGIN:VALARM
TRIGGER:-PT5M
ACTION:DISPLAY
ACKNOWLEDGED:20241002T114703Z
...

"alerts": {
  "a": {
    "@type": "Alert",
    "acknowledged": "2024-10-02T11:47:03Z",
    "...": ""
  }
}

2.3.2. ACTION

The ACTION property [RFC5545] (Section 3.8.6.1) in a VALARM component converts to the action property [RFC8984] (Section 4.5.2) of the Alert object.¶

Its values convert as follows:¶

An ACTION property with value AUDIO or any other not listed in Table 15 does not convert to the action property. Instead, the property converts to the iCalComponent/properties property (Section 5.1.1) of the Alert.¶

The following examples illustrate how to convert the ACTION property:¶

BEGIN:VEVENT
BEGIN:VALARM
TRIGGER:-PT5M
ACTION:DISPLAY
...

"alerts": {
  "a": {
    "@type": "Alert",
    "action": "display",
    "...": ""
  }
}

BEGIN:VEVENT
BEGIN:VALARM
TRIGGER:-PT5M
ACTION:AUDIO
...

"alerts": {
  "a": {
    "@type": "Alert",
    "iCalComponent": {
      "name": "valarm",
      "properties": [
        [
          "action",
          {},
          "text",
          "AUDIO"
        ]
      ]
    },
    "...": ""
  }
}

2.3.3. ATTACH

The ATTACH property [RFC5545] (Section 3.8.1.1) in a VEVENT, VTODO, VRESOURCE, PARTICIPANT, or VLOCATION component converts to a Link object [RFC8984] (Section 1.4.11). The converted object is set in the links property of the Event, Task, Participant, or Location object.¶

The property value converts to the href property of the Link object. A value of type URI converts as-is. A value of type BINARY converts to a URI in the "data" URL scheme ([RFC2397]. If the FMTTYPE parameter is set on the ATTACH property, then the parameter value SHOULD be set in the mediatype part of the data URL.¶

The ATTACH property parameters convert as follows:¶

The following examples illustrate how to convert the ATTACH property:¶

ATTACH:https://example.com/foo.pdf

"links": {
  "a": {
    "@type": "Link",
    "href": "https://example.com/foo.pdf"
  }
}

ATTACH;ENCODING=BASE64;VALUE=BINARY;FMTTYPE=image/png:iVBORw
 0KGgoAAAANSUhEUgAAAAEAAAABAQAAAAA3bvkkAAAAAmJLR0QAAd2KE6QAA
 AAKSURBVAjXY2gAAACCAIHdQ2r0AAAAAElFTkSuQmCC

"links": {
  "a": {
    "@type": "Link",
    "href": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABAQAAAAA3bvkkAAAAAmJLR0QAAd2KE6QAAAAKSURBVAjXY2gAAACCAIHdQ2r0AAAAAElFTkSuQmCC",
    "contentType": "image/png"
  }
}

2.3.4. ATTENDEE

The ATTENDEE property [RFC5545] (Section 3.8.4.1) in a VEVENT or VTODO component converts to a Participant object [RFC8984] (Section 4.4.6). The converted object is set in the participants property of the Event or Task object.¶

The property value converts to both the calendarAddress and sendTo properties of the Participant object. If the CAL-ADDRESS value is in the "mailto" scheme, then it converts to the "imip" method in the sendTo property, otherwise it converts to the "other" method.¶

The ATTENDEE property parameters convert as follows:¶

If no ROLE parameter is set, then the "attendee" role in the roles property MUST be set.¶

Every calendar address value of the DELEGATED-FROM, DELEGATED-TO, or MEMBER parameters converts to the identifier of an Participant object. This identifier is determined by finding that Participant object in the participants property, which has a calendarAddress property value matching the parameter value. If no such Participant object exists after all properties and components have been converted, then a new Participant object having that calendarAddress property value is created. If multiple Participant objects match, then choosing the Participant identifier is implementation-specific.¶

An ATTENDEE property and a PARTICIPANT component in the same iCalendar component convert to the same Participant object, if their converted calendarAddress property values are equal after URI normalization [RFC3986] (Section 6). How to deal with conflicting values when converting other Participant properties is implementation-specific.¶

The following examples illustrate how to convert the ATTENDEE property:¶

ATTENDEE;PARTSTAT=TENTATIVE;CN=Henry Cabot:mailto:hcabot@example.com

"participants": {
  "p3": {
    "@type": "Participant",
    "calendarAddress": "mailto:hcabot@example.com",
    "name": "Henry Cabot",
    "participationStatus": "tentative",
    "roles": {
      "attendee": true
    },
    "sendTo": {
      "imip": "mailto:hcabot@example.com"
    }
  },
  "o4": {
    "...": ""
  }
}

BEGIN:PARTICIPANT
CALENDAR-ADDRESS:mailto:foo@example.com
DTSTAMP:20230723T125201Z
...
END:PARTICIPANT
ATTENDEE;PARTSTAT=TENTATIVE:mailto:foo@example.com

"participants": {
  "23": {
    "@type": "Participant",
    "calendarAddress": "mailto:foo@example.com",
    "participationStatus": "tentative",
    "scheduleUpdated": "2023-07-23T12:52:01Z",
    "...": ""
  },
  "o4": {
    "...": ""
  }
}

2.3.5. CALENDAR-ADDRESS

The CALENDAR-ADDRESS property [RFC9073] (Section 6.4) in a PARTICIPANT component converts to the calendarAddress property [I-D.ietf-jmap-calendars] (Section 5.1.1) of the Participant object.¶

The following example illustrates how to convert the CALENDAR-ADDRESS property:¶

BEGIN:PARTICIPANT
CALENDAR-ADDRESS:mailto:foo@example.com
...

"participants": {
  "a2": {
    "@type": "Participant",
    "calendarAddress": "mailto:foo@example.com",
    "...": ""
  }
}

2.3.6. CATEGORIES

The CATEGORIES property [RFC5545] (Section 3.8.1.2) in a VEVENT, VTODO, or VCALENDAR component converts to the keywords property [RFC8984] (Section 4.2.9) 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:¶

CATEGORIES:APPOINTMENT,EDUCATION
CATEGORIES:meeting

"keywords": {
  "APPOINTMENT": true,
  "EDUCATION": true,
  "meeting": true
}

2.3.7. CLASS

The CLASS property [RFC5545] (Section 3.8.1.3) in a VEVENT or VTODO component converts to the privacy property [RFC8984] (Section 4.4.3) of the Event or Task object.¶

Its values convert as follows:¶

Any other value does not convert to the class property. Instead, the property converts to the iCalComponent/properties property (Section 5.1.1) of the JSCalendar object.¶

The following example illustrates how to convert the CLASS property:¶

CLASS:PRIVATE

"privacy": "private"

2.3.8. COLOR

The COLOR property [RFC7986] (Section 5.9) in a VEVENT, VTODO, or VCALENDAR component converts to the color property [RFC8984] (Section 4.2.11) of the Event, Task, or Group object.¶

Its value converts verbatim.¶

The following examples illustrate how to convert the COLOR property:¶

COLOR:maroon

"color": "maroon"

COLOR:#ffa07a

"color": "#ffa07a"

2.3.9. COMMENT

The COMMENT property [RFC5545] (Section 3.8.1.4) in a DAYLIGHT or STANDARD component converts to the comments property [RFC8984] (Section 4.7.2) of the TimeZoneRule object.¶

The COMMENT property [RFC5545] (Section 3.8.1.4) in a PARTICIPANT component converts to the participationComment property [RFC8984] (Section 4.4.6).¶

The COMMENT property [RFC5545] (Section 3.8.1.4) in an iTIP-scheduled [RFC5546] VEVENT or VTODO component converts to the participationComment property [RFC8984] (Section 4.4.6) of that Participant object, which represents the source of this scheduling message, if any. It otherwise converts to the iCalComponent/properties property (Section 5.1.1) of the Event or Task object.¶

Multiple COMMENT properties in a DAYLIGHT or STANDARD component convert in order of appearance in the comments property. Converting multiple COMMENT properties to the single-valued participationComment property is implementation-specific.¶

The following examples illustrate how to convert the COMMENT property:¶

BEGIN:VCALENDAR
BEGIN:VTIMEZONE
TZID:NonIana
BEGIN:DAYLIGHT
TZOFFSETFROM:-0400
TZOFFSETTO:-0300
DTSTART:20010503T000000
COMMENT:take note of this
COMMENT:and this
END:DAYLIGHT
END:VTIMEZONE
...

{
  "@type": "Group",
  "timeZones": {
    "/NonIana": {
      "@type": "TimeZone",
      "daylight": [
        {
          "@type": "TimeZoneRule",
          "comments": [
            "take note of this",
            "and this"
          ],
          "...": ""
        }
      ],
      "...": ""
    }
  },
  "...": ""
}

BEGIN:PARTICIPANT
UID:127ABD62-D07A-4F39-AA62-530E37A8DF78
COMMENT:I'll think about it
...

"participants": {
  "g2": {
    "@type": "Participant",
    "participationComment": "I'll think about it",
    "...": ""
  }
}

2.3.10. CONCEPT

The CONCEPT property [RFC9253] (Section 8.1) in a VEVENT, VTODO, or VCALENDAR component converts to the categories property [RFC8984] (Section 4.2.10) 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:¶

CONCEPT:https://example.com/event-types/arts/music
CONCEPT:https://example.com/event-types/arts/literature

"categories": {
  "https://example.com/event-types/arts/music": true,
  "https://example.com/event-types/arts/literature": true
}

2.3.11. CONFERENCE

The CONFERENCE property [RFC7986] (Section 5.11) in a VEVENT or VTODO component converts to a VirtualLocation object [RFC8984] (Section 4.2.6). The converted object is set in the virtualLocations property of the Event or Task object.¶

The property value converts to the uri property of the VirtualLocation object.¶

Its parameters convert as follows:¶

The following example illustrates how to convert the CONFERENCE property:¶

CONFERENCE;VALUE=URI;FEATURE=AUDIO,VIDEO;
 LABEL=Attendee dial-in:https://chat.example.com/audio?id=123456

"virtualLocations": {
  "b2": {
    "@type": "VirtualLocation",
    "name": "Attendee dial-in",
    "uri": "https://chat.example.com/audio?id=123456",
    "features": {
      "audio": true,
      "video": true
    }
  }
}

2.3.12. CREATED

The CREATED property [RFC5545] (Section 3.8.7.1) in a VEVENT, VTODO, or VCALENDAR component converts to the created property [RFC8984] (Section 4.1.5) of the Event, Task, or Group object.¶

The following example illustrates how to convert the CREATED property:¶

CREATED:20240329T133000Z

"created": "2024-03-29T13:30:00Z"

2.3.13. DESCRIPTION

The DESCRIPTION property [RFC5545] (Section 3.8.1.5) in a VEVENT, VTODO, VCALENDAR, VLOCATION, VRESOURCE, or PARTICIPANT component converts to the description property [RFC8984] (Section 4.2.2) of the Event, Task, Group, Location, Link, or Participant object, unless its DERIVED parameter value is TRUE.¶

If the DERIVED parameter value is TRUE, then the property does not convert to the description property. Instead, a non-derived STYLED-DESCRIPTION property is expected to contain the description. Implementations MAY preserve the property in the iCalComponent property (Section 5.1.1).¶

The following example illustrates how to convert the DESCRIPTION property:¶

DESCRIPTION:The pancakes there are delicious\; they are fluffy and sweet.

"description": "The pancakes there are delicious; they are fluffy and sweet."

2.3.14. DTEND

The DTEND property [RFC5545] (Section 3.8.2.2) in a VEVENT component converts to the duration property [RFC8984] (Section 5.1.2) of the Event object.¶

The duration is the timespan between the points in time of the DTSTART and DTEND property values when converted to UTC time.¶

If the timezone identifier (Section 2.1.4) of the DTEND property differs from that of the DTSTART property, then the DTEND property also converts to a Location object. The timezone identifier converts to the timeZone property of the Location object. The relativeTo property of the Location is set to "end". The Location object is set in the locations property of the Event object.¶

Implementations MAY preserve the fact that the duration got determined by the DTEND property. How to this depends on if the timezone identifiers of DTSTART and DTEND are equal. If the identifiers are equal, then implementations MUST set the iCalComponent property (Section 5.1.1) in the Event object and there add an entry for the path "duration" in the convertedProperties property. The value MUST be an ICalProperty object with the name property set to "dtend". If instead the timezone identifiers are not equal, then implementations MUST set the iCalProperty property (Section 5.1.2) of the Location object.¶

The following examples illustrate how to convert the DTEND property:¶

DTSTART;TZID=Australia/Melbourne:20241002T130000
DTEND;TZID=Australia/Melbourne:20241002T140000

"start": "2024-10-02T13:00:00",
"timeZone": "Australia/Melbourne",
"duration": "PT1H",
"iCalComponent": {
  "convertedProperties": {
    "duration": {
      "@type": "ICalProperty",
      "name": "dtend"
    }
  }
}

DTSTART;TZID=Europe/Berlin:20241017T130005
DTEND;TZID=Asia/Bangkok:20241018T020325

"start": "2024-10-17T13:00:05",
"timeZone": "Europe/Berlin",
"duration": "PT9H20M",
"locations": {
  "l5": {
    "timeZone": "Asia/Bangkok",
    "relativeTo": "end",
    "iCalProperty": {
      "@type": "ICalProperty",
      "name": "dtend"
    }
  }
}

DTSTART;VALUE=DATE:20240102
DTEND;VALUE=DATE:20240112

"start": "2024-01-02T00:00:00",
"timeZone": null,
"duration": "P1W2D",
"showWithoutTime": true

2.3.15. DTSTAMP

The DTSTAMP property [RFC5545] (Section 3.8.7.2) in a VEVENT or VTODO component converts to the updated property [RFC8984] (Section 4.1.6) of the Event or Task object.¶

Both the LAST-MODIFIED and DTSTAMP properties convert to the updated property. If both are present in the same component, then the DTSTAMP property value has higher precedence. Implementations MAY in that case preserve the value of the LAST-MODIFIED property in the iCalComponent property.¶

An Event or Task object which has the method property set might represent an iTIP reply of one of the participants in the object. In this case the value of the updated property in the Event or Task also converts to the scheduleUpdated property [RFC8984] (Section 4.4.6) of that Participant object, which represents the participant from which the iTIP reply originated.¶

The DTSTAMP property in a PARTICIPANT component converts to the scheduleUpdated property [RFC8984] (Section 4.4.6) of the Participant object.¶

The following examples illustrate how to convert the DTSTAMP property:¶

BEGIN:VCALENDAR
METHOD:REPLY
BEGIN:VEVENT
DTSTAMP:20240304T132000Z
...

{
  "@type": "Group",
  "entries": [
    {
      "@type": "Event",
      "method": "reply",
      "updated": "2024-03-04T13:20:00Z",
      "...": ""
    }
  ],
  "...": ""
}

BEGIN:VEVENT
BEGIN:PARTICIPANT
DTSTAMP:20240304T132000Z
...

"participants": {
  "f4": {
    "@type": "Participant",
    "scheduleUpdated": "2024-03-04T13:20:00Z",
    "...": ""
  }
}

2.3.16. DTSTART

The DTSTART property [RFC5545] (Section 3.8.2.4) in a VEVENT, VTODO, DAYLIGHT or STANDARD component converts to the start property [RFC8984] (Section 4.7.2) of the Event, Task, or TimeZoneRule object.¶

See Section 2.1.5 how to convert DATE and DATE-TIME values.¶

For VEVENT and VTODO components, the timezone identifier (Section 2.1.4) 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 [RFC8984] (Section 4.2.4) is "true".¶

The following examples illustrate how to convert the DTSTART property for the VEVENT and VTODO components. See Section 2.2.6 for examples how to convert the DTSTART property for the DAYLIGHT and STANDARD components.¶

DTSTART;TZID=Europe/Berlin:20240921T105302

"start": "2024-09-21T10:53:02",
"timeZone": "Europe/Berlin",
"showWithoutTime": "false"

DTSTART:20240921T105302Z

"start": "2024-09-21T10:53:02",
"timeZone": "Etc/UTC",
"showWithoutTime": "false"

DTSTART:20240921T105302

"start": "2024-09-21T10:53:02",
"timeZone": null,
"showWithoutTime": "false"

DTSTART;VALUE=DATE:20240921

"start": "2024-09-21T00:00:00",
"timeZone": null,
"showWithoutTime": "true"

2.3.17. DUE

The DUE property [RFC5545] (Section 3.8.2.3) in a VTODO component converts to the due property [RFC8984] (Section 5.2.1) of the Task object.¶

See Section 2.1.5 how to convert DATE and DATE-TIME values.¶

If the VTODO component does not contain a DTSTART property, then the timezone identifier (Section 2.1.4) of the DUE property converts to the timeZone property of the Task object. If instead the VTODO component contains both the DUE and DTSTART properties, then the timezone identifier of the DUE property does not convert to a standard JSCalendar element. The value of the due property MUST denote the date and time relative to the timezone of the DTSTART property.¶

If the value type of the DUE property is DATE, then the value of the showWithoutTime property [RFC8984] (Section 4.2.4) is "true".¶

The following examples illustrate how to convert the DUE property:¶

DUE;TZID=Europe/Berlin:20240921T105302

"due": "2024-09-21T10:53:02",
"timeZone": "Europe/Berlin",
"showWithoutTime": "false"

DUE:20240921T105302Z

"start": "2024-09-21T10:53:02",
"timeZone": "Etc/UTC",
"showWithoutTime": "false"

DUE:20240921T105302

"start": "2024-09-21T10:53:02",
"timeZone": null,
"showWithoutTime": "false"

DUE;VALUE=DATE:20240921

"start": "2024-09-21T00:00:00",
"timeZone": null,
"showWithoutTime": "true"

2.3.18. DURATION

The DURATION property [RFC5545] (Section 3.8.2.5) in a VEVENT or VTODO component converts to the duration property [RFC8984] (Section 5.1.2) of the Event or Task object.¶

The following example illustrates how to convert the DURATION property:¶

DURATION:PT1H

"duration": "PT1H"

2.3.19. EXDATE

The EXDATE property [RFC5545] (Section 3.8.5.1) of value type DATE or DATE-TIME in a VEVENT or VTODO component converts to a PatchObject object [RFC8984] (Section 1.4.9). 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 Section 2.1.5 how to convert DATE and DATE-TIME values. The date-time MUST be relative to the timezone identified by the timeZone property of the Event or Task. The PatchObject value MUST set the excluded property to "true" and MUST NOT set any other property.¶

An EXDATE property of value type PERIOD does not convert to a standard JSCalendar element. Implementations MAY convert it to the iCalComponent property (Section 5.1.1) of the Event or Task object.¶

The following example illustrates how to convert the EXDATE property:¶

DTSTART:20230101T130000Z
RRULE:FREQ=MONTHLY
EXDATE:20230801T130000Z

"start": "2023-01-01T13:00:00",
"timeZone": "Etc/UTC",
"recurrenceRules": [
  {
    "@type": "RecurrenceRule",
    "frequency": "monthly"
  }
],
"recurrenceOverrides": {
  "2023-08-01T13:00:00": {
    "excluded": true
  }
}

2.3.20. EXRULE

The EXRULE property [RFC2445] (Section 4.8.5.2) in a VEVENT or VTODO component converts to a RecurrenceRule object [RFC8984] (Section 4.3.3). The converted object is set in the excludedRecurrenceRules property of the Event or Task.¶

See Section 2.3.38 for an example how to convert a recurrence rule.¶

2.3.21. GEO

The GEO property [RFC5545] (Section 3.8.1.6) in a VLOCATION component converts to the coordinates property [RFC8984] (Section 4.2.5).¶

The GEO property [RFC5545] (Section 3.8.1.6) in a VEVENT, VTODO, PARTICIPANT or VRESOURCE component converts to a Location object [RFC8984] (Section 4.2.5). The converted object is set in the locations property of the Event, Task, or Participant object.¶

The pair of FLOAT values converts to an URI with the "geo" scheme [RFC5870]. The first FLOAT value converts to the "coord-a" part of the URI, the second FLOAT value to the "coord-b" part. A preceding plus sign (+) of the FLOAT value MUST be omitted, a preceding minus sign (-) MUST be preserved. The third, altitude coordinate MUST NOT be set, unless its value is known.¶

The following examples illustrate how to convert the GEO property:¶

GEO:+45.5;-93.3

"locations": {
  "d4": {
    "@type": "Location",
    "coordinates": "geo:45.5,-93.3"
  }
}

BEGIN:VEVENT
BEGIN:VLOCATION
NAME:Eiffel Tower
GEO:48.858222;2.2945
...

"locations": {
  "2": {
    "@type": "Location",
    "name": "Eiffel Tower",
    "coordinates": "geo:48.858222,2.2945"
  }
}

2.3.22. IMAGE

The IMAGE property [RFC7986] (Section 5.10) in a VEVENT, VTODO, VLOCATION, or VRESOURCE component converts to a Link object [RFC8984] (Section 1.4.11). The converted object is set in the links property of the Event, Task, Location, or Participant object.¶

The property value converts to the href property of the Link object. A value of type URI converts as-is. See Section 2.3.3 how to convert a BINARY value. If the DISPLAY parameter is set, then the "rel" property of the Link object MUST be set to "icon".¶

Its parameters convert as follows:¶

Implementations MAY preserve the fact that the Link object got converted from an IMAGE property. To so, they MUST set the iCalProperty (Section 5.1.2) on the Link object.¶

The following example illustrates how to convert the IMAGE property:¶

IMAGE;VALUE=URI;DISPLAY=BADGE;FMTTYPE=image/png:
 https://example.com/images/party.png

"links": {
  "4": {
    "@type": "Link",
    "href": "https://example.com/images/party.png",
    "display": "badge",
    "rel": "icon",
    "contentType": "image/png",
    "iCalProperty": {
      "@type": "ICalProperty",
      "name": "image"
    }
  }
}

2.3.23. LAST-MODIFIED

The LAST-MODIFIED property [RFC5545] (Section 3.8.7.3) in a VEVENT, VTODO, VCALENDAR, or VTIMEZONE component converts to the updated property [RFC8984] (Section 4.1.6) of the Event, Task, Group, or TimeZone object.¶

Both the LAST-MODIFIED and DTSTAMP properties convert to the updated property. If both are present in the same component, then the DTSTAMP property value has higher precedence. Implementations MAY in that case preserve the value of the LAST-MODIFIED property in the iCalComponent property.¶

The following example illustrates how to convert the LAST-MODIFIED property:¶

LAST-MODIFIED:20240914T231257Z

"updated": "2024-09-14T23:12:57Z"

2.3.24. LINK

The LINK property [RFC9253] (Section 8.2) in a VEVENT, VTODO, VCALENDAR, VRESOURCE, PARTICIPANT, or VLOCATION component converts to a Link object [RFC8984] (Section 1.4.11) under the following conditions:¶

• The property value type is URI.¶
• The LINKREL parameter either is not set, or the parameter value is a registered relation type as defined in [RFC8288] (Section 2.1.1).¶

The converted object is set in the links property of the Event, Task, Group, Participant, or Location object. The LINK property value converts to the href property of the Link object.¶

Its parameters convert as follows:¶

A LINK property with a value type other than URI or an unregistered LINK parameter value does not convert to a standard JSCalendar element. Implementations MAY convert it to the iCalComponent property (Section 5.1.1).¶

The following examples illustrate how to convert the LINK property:¶

LINK;LABEL=Venue;VALUE=URI:https://example.com/events

"links": {
  "l1": {
    "@type": "Link",
    "href": "https://example.com/events",
    "title": "Venue"
  }
}

BEGIN:VEVENT
LINK;LINKREL="https://example.com/linkrel/costStructure";
 VALUE=XML-REFERENCE:
 https://example.com/xmlDocs/bidFramework.xml#xpointer(id("cost"))
...

"iCalComponent": {
  "@type": "ICalComponent",
  "name": "vevent",
  "properties": [
    [
      "link",
      {
        "linkrel": "https://example.com/linkrel/costStructure"
      },
      "xml-reference",
      "https://example.com/xmlDocs/bidFramework.xml#xpointer(id(\"cost\"))"
    ]
  ]
}

2.3.25. LOCATION

The LOCATION property [RFC5545] (Section 3.8.1.7) in a VEVENT, VTODO, or PARTICIPANT component converts to a Location object [RFC8984] (Section 4.2.5), unless its DERIVED parameter value is TRUE. The converted object is set in the locations property of the Event, Task, or Participant object.¶

The property value converts to the title property of the Location object.¶

If the DERIVED parameter value is TRUE, then the property does not convert to a Location object. Instead, a VLOCATION component is expected to represent the location. Implementations MAY preserve the property in the iCalComponent property (Section 5.1.1).¶

The following example illustrates how to convert the LOCATION property:¶

LOCATION:Conference Room - F123\, Bldg. 002

"locations": {
  "f45": {
    "@type": "Location",
    "title": "Conference Room - F123, Bldg. 002"
  }
}

2.3.26. LOCATION-TYPE

The LOCATION-TYPE property [RFC9073] (Section 6.1) in a VLOCATION component converts to the locationTypes property [RFC8984] (Section 4.2.5).¶

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:¶

BEGIN:VEVENT
BEGIN:VLOCATION
LOCATION-TYPE:hotel,restaurant
LOCATION-TYPE:bar
...

"locations": {
  "1": {
    "@type": "Location",
    "locationTypes": {
      "bar": true,
      "hotel": true,
      "restaurant": true
    },
    "...": ""
  }
}

2.3.27. METHOD

The METHOD property [RFC5545] (Section 3.7.2) in a VCALENDAR component converts to the method property [RFC8984] (Section 4.1.8) 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:¶

BEGIN:VCALENDAR
METHOD:REQUEST
BEGIN:VEVENT
...

{
  "@type": "Group",
  "entries": [
    {
      "@type": "Event",
      "method": "request",
      "...": ""
    }
  ],
  "...": ""
}

2.3.28. NAME

The NAME property [RFC7986] (Section 5.1) in a VLOCATION or VRESOURCE component converts to the name property of the Location [RFC8984] (Section 4.2.5) or Participant [RFC8984] (Section 4.4.6) object.¶

The NAME property [RFC7986] (Section 5.1) in a VCALENDAR component converts to the title property [RFC8984] (Section 4.2.1) of the Group object.¶

The following examples illustrate how to convert the NAME property:¶

BEGIN:VCALENDAR
NAME:Company Vacation Days
...

{
  "@type": "Group",
  "title": "Company Vacation Days",
  "...": ""
}

BEGIN:VEVENT
BEGIN:PARTICIPANT
NAME:John Doe
...
END:PARTICIPANT
BEGIN:VLOCATION
NAME:Fred's Bar
...
END:VLOCATION
...

"locations": {
  "1": {
    "@type": "Location",
    "name": "Fred's Bar",
    "...": ""
  }
},
"participants": {
  "1": {
    "@type": "Participant",
    "name": "John Doe",
    "...": ""
  }
}

2.3.29. ORGANIZER

The ORGANIZER property [RFC5545] (Section 3.8.4.3) in a VEVENT or VTODO component converts to the replyTo property [RFC8984] (Section 4.4.4). In addition, it converts to a Participant object in the participants property [RFC8984] (Section 4.4.6).¶

If the CAL-ADDRESS property value is in the "mailto" scheme, then it converts to the "imip" method in the replyTo property, otherwise it converts to the "other" method. The property value also converts to the calendarAddress property of the Participant object. The "owner" role is set in the roles property of the Participant. In contrast to the ATTENDEE property, the property value does not convert to the sendTo property of the Participant object.¶

An ORGANIZER property, an ATTENDEE property, and a PARTICIPANT component in the same iCalendar component all convert to the same Participant object, if their converted calendarAddress property values are equal after URI normalization [RFC3986] (Section 6). How to deal with conflicting values when converting other Participant properties is implementation-specific.¶

Implementations MAY preserve arbitrary parameters of the ORGANIZER property, in which case they MUST convert these to a "replyTo" entry in the convertedProperties property of the Event or Task object's iCalComponent property (Section 5.1.1).¶

The ORGANIZER property parameters convert as follows:¶

The following examples illustrate how to convert the ORGANIZER property:¶

ORGANIZER:mailto:foo@example.com
...
ATTENDEE;RSVP=TRUE;PARTSTAT=NEEDS-ACTION:mailto:bar@example.com

"replyTo": {
  "imip": "mailto:foo@example.com"
},
"participants": {
  "a": {
    "@type": "Participant",
    "calendarAddress": "mailto:foo@example.com",
    "roles": {
      "owner": true
    }
  },
  "b": {
    "@type": "Participant",
    "...": ""
  }
}

ORGANIZER:mailto:foo@example.com
ATTENDEE;RSVP=FALSE;PARTSTAT=ACCEPTED;CN="Jane Doe":mailto:foo@example.com
...
ATTENDEE;RSVP=TRUE;PARTSTAT=NEEDS-ACTION:mailto:bar@example.com

"replyTo": {
  "imip": "mailto:foo@example.com"
},
"participants": {
  "a": {
    "@type": "Participant",
    "calendarAddress": "mailto:foo@example.com",
    "name": "Jane Doe",
    "participationStatus": "accepted",
    "roles": {
      "attendee": true,
      "owner": true
    },
    "sendTo": {
      "imip": "mailto:foo@example.com"
    }
  },
  "b": {
    "@type": "Participant",
    "...": ""
  }
}

2.3.30. PARTICIPANT-TYPE

The PARTICIPANT-TYPE property [RFC9073] (Section 6.2) in a PARTICIPANT component converts to the roles property [RFC8984] (Section 4.4.6) of the Participant object.¶

The property value converts in lowercase.¶

The following example illustrates how to convert the PARTICIPANT-TYPE property:¶

BEGIN:PARTICIPANT
PARTICIPANT-TYPE:CONTACT
CALENDAR-ADDRESS:mailto:foo@example.com
...
END:PARTICIPANT
ATTENDEE;RSVP=YES;PARTSTAT=NEEDS-ACTION:mailto:foo@example.com

"participants": {
  "a": {
    "@type": "Participant",
    "roles": {
      "attendee": true,
      "contact": true
    },
    "...": ""
  },
  "b": {
    "...": ""
  }
}

2.3.31. PERCENT-COMPLETE

The PERCENT-COMPLETE property [RFC5545] (Section 3.8.1.8) in a VTODO component converts to the percentComplete property [RFC8984] (Section 5.2.4) of the Task object.¶

A Task object which has the method property set might represent an iTIP reply of one of the participants in the object. In this case the value of the percentComplete property in the Task also converts to the percentComplete [RFC8984] (Section 4.4.6) of that Participant object, which represents the participant from which the iTIP reply originated.¶

The PERCENT-COMPLETE property in a PARTICIPANT component converts to the percentComplete property [RFC8984] (Section 4.4.6) of the Participant object.¶

The following examples illustrate how to convert the PERCENT-COMPLETE property:¶

BEGIN:VCALENDAR
METHOD:REPLY
BEGIN:VTODO
PERCENT-COMPLETE:53
...

{
  "@type": "Group",
  "entries": [
    {
      "@type": "Task",
      "method": "reply",
      "percentComplete": 53,
      "...": ""
    }
  ],
  "...": ""
}

BEGIN:VTODO
BEGIN:PARTICIPANT
PERCENT-COMPLETE:78
...

"@type": "Task",
"participants": {
  "f4": {
    "@type": "Participant",
    "percentComplete": 78,
    "...": ""
  }
}

2.3.32. PRIORITY

The PRIORITY property [RFC5545] (Section 3.8.1.9) in a VEVENT or VTODO component converts to the priority property [RFC8984] (Section 4.4.1) of the Event or Task object.¶

The following example illustrates how to convert the PRIORITY property:¶

PRIORITY:3

"priority": 3

2.3.33. PRODID

The PRODID property [RFC5545] (Section 3.7.3) in a VCALENDAR component converts to the prodId property [RFC8984] (Section 4.1.4) of the Group object, and to the prodId property of all Event or Task objects that are listed in the Group object's entries property.¶

The property value converts verbatim.¶

The following example illustrates how to convert the PRODID property:¶

BEGIN:VCALENDAR
PRODID:-//BAZ//bam//EN
BEGIN:VEVENT
...

{
  "@type": "Group",
  "prodId": "-//BAZ//bam//EN",
  "entries": [
    {
      "@type": "Event",
      "prodId": "-//BAZ//bam//EN",
      "...": ""
    }
  ],
  "...": ""
}

2.3.34. RDATE

The RDATE property [RFC5545] (Section 3.8.5.2) of type DATE or DATE-TIME in a VEVENT, VTODO, DAYLIGHT or STANDARD component converts to a PatchObject object [RFC8984] (Section 1.4.9). The converted object is set in the recurrenceOverrides property of the Event, Task, or TimeZoneRule object.¶

The property value converts to the key in the recurrenceOverrides property value. See Section 2.1.5 how to convert DATE and DATE-TIME values. For Event Task objects, the date-time MUST be relative to the timezone identified by the timeZone property, for TimeZoneRule objects the date-time is relative to the UTC offset specified in the offsetFrom property. The PatchObject value MUST be an empty JSON object.¶

An RDATE property of value type PERIOD does not convert to a standard JSCalendar element. Implementations MAY convert it to the iCalComponent property (Section 5.1.1) of the Event, Task, or TimeZoneRule object.¶

The following example illustrates how to convert the RDATE property:¶

DTSTART:20230101T130000Z
RRULE:FREQ=MONTHLY
RDATE:20230805T170000Z

"start": "2023-01-01T13:00:00",
"timeZone": "Etc/UTC",
"recurrenceRules": [
  {
    "@type": "RecurrenceRule",
    "frequency": "monthly"
  }
],
"recurrenceOverrides": {
  "2023-08-05T17:00:00": {}
}

2.3.35. RECURRENCE-ID

The RECURRENCE-ID property [RFC5545] (Section 3.8.4.4) in a VEVENT or VTODO component converts to the recurrenceId property [RFC8984] (Section 4.3.1) of the Event or Task object. The timezone identifier (Section 2.1.4) of the RECURRENCE-ID property converts to the recurrenceIdTimeZone property.¶

See Section 2.1.5 how to convert DATE and DATE-TIME values.¶

The RANGE parameter [RFC5545] (Section 3.2.13) does not convert to a standard JSCalendar element. Implementations MAY preserve it in the iCalComponent (Section 5.1.1) property.¶

See Section 2.1.2 for further requirements and examples.¶

2.3.36. RELATED-TO

The RELATED-TO property [RFC5545] (Section 3.8.4.5) in a VEVENT, VTODO, or VALARM component converts to a Relation object [RFC8984] (Section 1.4.10). The converted object is set in the relatedTo property of the Event or Task object [RFC8984] (Section 4.1.3), or the Alert object [RFC8984] (Section 4.5.2).¶

The property value in a VEVENT or VTODO converts as-is to the key of the Relation object in the relatedTo property. The property value in a VALARM converts to the same value as the key of that Alert object, which represents the VALARM component having that property value set in the UID property. Any RELTYPE parameters convert to the relations property in that Relation object. The parameter values convert in lowercase.¶

The GAP parameter [RFC9253] (Section 6.2) does not convert a standard JSCalendar element. Implementations MAY convert it to the iCalProperty property (Section 5.1.2) of the Relation object.¶

The following examples illustrate how to convert the RELATED-TO property:¶

BEGIN:VEVENT
RELATED-TO;RELTYPE=PARENT:4E05861C-A0C9-46AC-9A66-760FC1E0E167
RELATED-TO:4120A9B1-1133-4AC0-9185-C4C8396048ED
...

"relatedTo": {
  "4E05861C-A0C9-46AC-9A66-760FC1E0E167": {
    "@type": "Relation",
    "relation": {
      "parent": true
    }
  },
  "4120A9B1-1133-4AC0-9185-C4C8396048ED": {
    "@type": "Relation"
  }
}

BEGIN:VEVENT
...
BEGIN:VALARM
UID:8297C37D-BA2D-4476-91AE-C1EAA364F8E1
TRIGGER:-PT15M
DESCRIPTION:Event reminder
ACTION:DISPLAY
ACKNOWLEDGED:20210302T151514Z
END:VALARM
...
BEGIN:VALARM
UID:DE7B5C34-83FF-47FE-BE9E-FF41AE6DD097
TRIGGER;VALUE=DATE-TIME:20210302T152000Z
RELATED-TO;RELTYPE=SNOOZE:8297C37D-BA2D-4476-91AE-C1EAA364F8E1
DESCRIPTION:Event reminder
ACTION:DISPLAY
END:VALARM
...

"alerts": {
  "1": {
    "@type": "Alert",
    "trigger": {
      "@type": "OffsetTrigger",
      "offset": "-PT15M"
    },
    "...": ""
  },
  "2": {
    "@type": "Alert",
    "trigger": {
      "@type": "AbsoluteTrigger",
      "when": "2021-03-02T15:20:00Z"
    },
    "relatedTo": {
      "1": {
        "relation": {
          "snooze": true
        }
      }
    },
    "...": ""
  }
}

2.3.37. REQUEST-STATUS

The REQUEST-STATUS property [RFC5545] (Section 3.8.8.3) in a VEVENT or VTODO component converts to the requestStatus property [RFC8984] (Section 4.4.7) of the Event or Task object.¶

The following example illustrates how to convert the REQUEST-STATUS property:¶

REQUEST-STATUS:2.0;Success

"requestStatus": "2.0;Success"

2.3.38. RRULE

The RRULE property [RFC5545] (Section 3.8.5.3) in a VEVENT, VTODO, DAYLIGHT or STANDARD component converts to a RecurrenceRule object [RFC8984] (Section 4.3.3). The converted object is set in the recurrenceRules property of the Event, Task, or TimeZoneRule object.¶

The RECUR value data type converts to a RecurrenceRule object as follows:¶

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

The following example illustrates how to convert the RRULE property:¶

DTSTART;TZID=Europe/Berlin:20240101T010000
RRULE:FREQ=YEARLY
 ;INTERVAL=2
 ;BYMONTH=1
 ;BYDAY=SU
 ;BYHOUR=8,9
 ;BYMINUTE=30
 ;UNTIL=20240930T120000Z

"recurrenceRules": [
  {
    "@type": "RecurrenceRule",
    "frequency": "yearly",
    "interval": 2,
    "byMonth": [
      "1"
    ],
    "byDay": [
      {
        "@type": "NDay",
        "day": "su"
      }
    ],
    "byHour": [
      8,
      9
    ],
    "byMinute": [
      30
    ],
    "until": "2024-09-30T14:00:00"
  }
],
"start": "2024-01-01T01:00:00",
"timeZone": "Europe/Berlin"

2.3.39. SEQUENCE

The SEQUENCE property [RFC5545] (Section 3.8.7.4) in a VEVENT or VTODO component converts to the sequence property [RFC8984] (Section 4.1.7) of the Event or Task object. The SEQUENCE property in a PARTICIPANT component converts to the scheduleSequence property [RFC8984] (Section 4.4.6) of the Participant object.¶

The following example illustrates how to convert the SEQUENCE property:¶

SEQUENCE:3

"sequence": 3

2.3.40. STATUS

The STATUS property [RFC5545] (Section 3.8.1.11) in a VEVENT component converts to the status property [RFC8984] (Section 5.1.3) of the Event object. The STATUS property in a VTODO component converts to the progress property [RFC8984] (Section 5.2.5) of the Task object.¶

The property value converts in lowercase.¶

The following examples illustrate how to convert the STATUS property:¶

STATUS:TENTATIVE

"status": "tentative"

BEGIN:VTODO
STATUS:IN-PROCESS
...

{
  "@type": "Task",
  "progress": "in-process",
  "...": ""
}

2.3.41. SOURCE

The SOURCE property [RFC7986] (Section 5.8) in a VCALENDAR component converts to the source property [RFC8984] (Section 5.3.2).¶

The following example illustrates how to convert the SOURCE property:¶

BEGIN:VCALENDAR
SOURCE;VALUE=URI:https://example.com/holidays.ics
...

{
  "@type": "Group",
  "source": "https://example.com/holidays.ics",
  "...": ""
}

2.3.42. STRUCTURED-DATA

The STRUCTURED-DATA property [RFC9073] (Section 6.6) of type URI or BINARY in a VEVENT, VTODO, VCALENDAR, VRESOURCE, PARTICIPANT, or VLOCATION component converts to a Link object [RFC8984] (Section 1.4.11). The converted object is set in the links property of the Event, Task, Group, Participant, or Location object.¶

The property value converts to the href property of the Link object. A value of type URI converts as-is. See Section 2.3.3 how to convert a BINARY value.¶

Its parameters convert as follows:¶

Implementations MAY preserve the fact that the Link object got converted from a STRUCTURED-DATA property. To so, they MUST set the iCalProperty (Section 5.1.2) on the Link object.¶

The following example illustrates how to convert the STRUCTURED-DATA property:¶

STRUCTURED-DATA;FMTTYPE=application/ld+json;
 SCHEMA="https://schema.org/FlightReservation";
 ENCODING=BASE64;VALUE=BINARY:InRydW5jYXRlZC4uLiIK

"links": {
  "@type": "Link",
  "contentType": "application/ld+json",
  "href": "data:application/ld+json;base64,InRydW5jYXRlZC4uLiIK",
  "iCalProperty": {
    "@type": "ICalProperty",
    "name": "structured-data",
    "parameters": {
      "schema": "https://schema.org/FlightReservation"
    },
    "valueType": "binary"
  }
}

2.3.43. STYLED-DESCRIPTION

The STYLED-DESCRIPTION property [RFC9073] (Section 6.5) in a VEVENT or VTODO component converts to the description property [RFC8984] (Section 4.2.2) under the following conditions:¶

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

If the DERIVED parameter value is TRUE, then the property does not convert to the description property. Instead, an non-derived STYLED-DESCRIPTION property or the DESCRIPTION property is expected to contain the description. Implementations MAY preserve the property in the iCalComponent property (Section 5.1.1).¶

Its parameters convert as follows:¶

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

STYLED-DESCRIPTION;VALUE=TEXT;FMTTYPE=text/html:
 <!DOCTYPE html><html><body>hello,<b>world</b></body></html>

"description": "<!DOCTYPE html><html><body>hello,<b>world</b></body></html>",
"descriptionContentType": "text/html"

2.3.44. SUMMARY

The SUMMARY property [RFC5545] (Section 3.8.1.12) in a VEVENT or VTODO component converts to the title property [RFC8984] (Section 4.2.1).¶

The SUMMARY property [RFC5545] (Section 3.8.1.12) in a PARTICIPANT component converts to the name property [RFC8984] (Section 4.2.5).¶

The following examples illustrate how to convert the SUMMARY property:¶

SUMMARY:Birthday Party

"title": "Birthday Party"

BEGIN:VEVENT
BEGIN:PARTICIPANT
SUMMARY:John
...

"participants": {
  "1": {
    "@type": "Participant",
    "name": "John",
    "...": ""
  }
}

2.3.45. TRANSP

The TRANSP property [RFC5545] (Section 3.8.2.7) in a VEVENT or VTODO component converts to the freeBusyStatus property [RFC8984] (Section 4.4.2).¶

Its values convert as follows:¶

The following example illustrates how to convert the TRANSP property:¶

TRANSP:TRANSPARENT

"freeBusyStatus": "free"

2.3.46. TRIGGER

The TRIGGER property [RFC5545] (Section 3.8.6.3) in a VALARM component converts to either an AbsoluteTrigger or OffsetTrigger object. The converted object is set in the trigger property [RFC8984] (Section 4.5.2) 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:¶

The following examples illustrate how to convert the TRIGGER property:¶

BEGIN:VEVENT
...
BEGIN:VALARM
TRIGGER;RELATED=END:PT5M
...

"alerts": {
  "2d": {
    "@type": "Alert",
    "trigger": {
      "@type": "OffsetTrigger",
      "offset": "PT5M",
      "relativeTo": "end"
    },
    "...": ""
  }
}

BEGIN:VEVENT
...
BEGIN:VALARM
TRIGGER;VALUE=DATE-TIME:20250302T010203Z
...

"alerts": {
  "14": {
    "@type": "Alert",
    "trigger": {
      "@type": "AbsoluteTrigger",
      "when": "2025-03-02T01:02:03Z"
    },
    "...": ""
  }
}

2.3.47. TZID

The TZID property [RFC5545] (Section 3.8.3.1) in a VTIMEZONE component converts to the tzId property [RFC8984] (Section 4.7.2).¶

See Figure 14 for an example.¶

2.3.48. TZID-ALIAS-OF

The TZID-ALIAS-OF property [RFC7808] (Section 7.2) in a VTIMEZONE component converts to an entry in the aliases property [RFC8984] (Section 4.7.2) of the TimeZone object.¶

See Figure 14 for an example.¶

2.3.49. TZNAME

The TZNAME property [RFC5545] (Section 3.8.3.2) in a DAYLIGHT or STANDARD component converts to an entry in the names property [RFC8984] (Section 4.7.2) of the TimeZoneRule object.¶

See Figure 14 for an example.¶

2.3.50. TZOFFSETFROM

The TZOFFSETFROM property [RFC5545] (Section 3.8.3.3) in a DAYLIGHT or STANDARD component converts to the offsetFrom property [RFC8984] (Section 4.7.2) of the TimeZoneRule object.¶

See Figure 14 for an example.¶

2.3.51. TZOFFSETTO

The TZOFFSETTO property [RFC5545] (Section 3.8.3.4) in a DAYLIGHT or STANDARD component converts to the offsetTo property [RFC8984] (Section 4.7.2) of the TimeZoneRule object.¶

See Figure 14 for an example.¶

2.3.52. TZUNTIL

The TZUNTIL property [RFC7808] (Section 7.1) in a VTIMEZONE component converts to the validUntil property [RFC8984] (Section 4.7.2).¶

See Section 2.1.5 how to convert DATE and DATE-TIME values.¶

See Figure 14 for an example.¶

2.3.53. TZURL

The TZURL property [RFC5545] (Section 3.8.3.5) in a VTIMEZONE component converts to the url property [RFC8984] (Section 4.7.2) of the TimeZone object.¶

See Figure 14 for an example.¶

2.3.54. UID

The UID property [RFC5545] (Section 3.8.4.7) in a VEVENT, VTODO, or VCALENDAR component converts to the uid property [RFC8984] (Section 4.1.2).¶

The following example illustrates how to convert the UID property:¶

UID:5ACEA86F-40CF-47EE-9CCA-7C85588A589F

"uid": "5ACEA86F-40CF-47EE-9CCA-7C85588A589F"

2.3.55. URL

The URL property [RFC5545] (Section 3.8.4.6) in a VEVENT, VTODO, VCALENDAR, or PARTICIPANT component converts to a Link object [RFC8984] (Section 1.4.11). The converted object is set in the links property of the Event, Task, Group, or Participant object.¶

The property value converts to the href property of the Link object.¶

Implementations MAY preserve the fact that the Link object got converted from an URL property. To so, they MUST set the iCalProperty (Section 5.1.2) on the Link object.¶

The following example illustrates how to convert the URL property:¶

URL:https://example.com/calendar/birtdays.ics

"links": {
  "3": {
    "@type": "Link",
    "href": "https://example.com/calendar/birtdays.ics",
    "iCalProperty": {
      "@type": "ICalProperty",
      "name": "url"
    }
  }
}

4.1.1. JSCALID

TBD¶

4.2.1. JSCALID

TBD¶

4.2.2. JSPROP

TBD¶

5.1.1. iCalComponent

Name:

iCalComponent¶

Context:

Any JSCalendar object¶

Type:

ICalComponent (optional)¶

Description

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

An ICalComponent object has the following properties:¶

@type: String (mandatory)

This specifies the type of this object. This MUST be ICalComponent.¶

name: String (mandatory)

This is the name of the iCalendar component in lowercase.¶

components: *[][] (optional)

This contains subcomponents of the iCalendar component. The value MUST be a list of iCalendar components formatted in jCal as defined in Section 3.3 of [RFC7265].¶

convertedProperties: String[ICalProperty] (optional)

This contains conversion-related information about the component's properties that got partially or fully converted to JSCalendar. Each key defines the path to a property of the JSCalendar object on which the iCalComponent property is set on. The value for each key contains information about the iCalendar property which converted to the object property located at that key (see Section 5.1.2).¶

The key MUST be a valid key of a PatchObject as defined in Section 1.4.9 of [RFC8984]. The key MUST NOT point into a nested property, unless there is no way to otherwise preserve the iCalendar property elements. For example, if a VEVENT contains an ATTENDEE property, then any iCalendar information about the ATTENDEE property MUST be set in the iCalProperty property of the converted Participant object (see Section 2.3.4). In contrast, information about a RDATE property contained in a VEVENT would be located by a key pointing into the recurrenceOverrides property of the Event object (see Section 2.3.34).¶

properties: *[][] (optional)

This contains properties of the iCalendar component. The value MUST be a list of iCalendar properties formatted in jCal as defined in Section 3.4 of [RFC7265].¶

5.1.2. iCalProperty

Name:

iCalProperty¶

Context:

Any JSCalendar object¶

Type:

ICalProperty (optional)¶

Description:

This contains conversion-related information about an iCalendar property that got partially or fully converted to JSCalendar. It allows to preserve the name of the iCalendar property and some or all of its parameters.¶

An ICalProperty object has the following properties:¶

@type: String (mandatory)

This specifies the type of this object. This MUST be ICalProperty.¶

name: String (mandatory)

This is the name of the iCalendar property in lowercase.¶

valueType: String (optional)

This is the name of the iCalendar property value type in lowercase.¶

parameters: String[String] (optional)

This contains parameters of the iCalendar property. The value MUST comply with iCalendar parameters formatted in jCal as defined in Section 3.5 of [RFC7265].¶

5.1.3. locations (Participant)

Name:

locations¶

Context

Participant¶

Type:

Id[Location] (optional)¶

Description:

This represents locations associated with the participant. In contrast to the locationId property, this allows to associate multiple locations with the Participant object. It also allow to more clearly express that a location just is relevant for a single participant.¶