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 [jscalendarbis] (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 order of elements in the "entries" property is implementation-specific, e.g. entries need not be in the same order as their source components in the iCalendar object.¶

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

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. As an exception to this rule, this does not apply to recurrence overrides, defined as follows.¶

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

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

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

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

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"
        }
      },
      "recurrenceRule": {
        "@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 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:20240103T170000
...
END:VEVENT
END:VCALENDAR

{
  "@type": "Group",
  "entries": [
    {
      "...": "",
      "@type": "Event",
      "recurrenceId": "2024-02-02T14:00:00",
      "recurrenceIdTimeZone": "Europe/Berlin",
      "start": "2024-02-02T16:00:00",
      "timeZone": "Europe/Berlin",
      "uid": "F4257E1D-5461-4EF6-840F-9DFC653EB559"
    },
    {
      "...": "",
      "@type": "Event",
      "recurrenceId": "2024-01-03T14:00:00",
      "recurrenceIdTimeZone": "Europe/Berlin",
      "start": "2024-01-03T17: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 [jscalendarbis] (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 JSID (Section 4.2.1) parameter and JSID property (Section 4.1.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 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 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 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. Otherwise, how to convert the TZID parameter value is implementation-specific: software libraries such as the International Components for Unicode support converting Microsoft time zone names to IANA time zone identifiers. Alternatively, finding an IANA time zone for which the time zone offset changes match those of the custom time zone over the span of the event or task is typically possible.¶

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 [jscalendarbis] (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 PARTICIPANT component:¶

BEGIN:PARTICIPANT
UID:47AD2E1C-49D4-45DF-BD83-8398ACC7D8E2
DESCRIPTION:A participant
...
END:PARTICIPANT

"participants": {
  "p32": {
    "@type": "Participant",
    "description": "A participant",
    "iCalComponent": {
      "@type": "ICalComponent",
      "name": "participant",
      "properties": [
        [
          "uid",
          {},
          "text",
          "47AD2E1C-49D4-45DF-BD83-8398ACC7D8E2"
        ]
      ]
    }
  }
}

2.2.2. VALARM

The VALARM component [RFC5545] (Section 3.6.6) converts to an Alert object [jscalendarbis] (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:VALARM
TRIGGER:-PT30M
ACTION:DISPLAY
DESCRIPTION:Breakfast meeting
END:VALARM

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

2.2.3. VCONFERENCE

The VCONFERENCE component [icaljscalexts] (Section 6.1) converts to a VirtualLocation object [jscalendarbis] (Section 4.2.7). It MUST convert to the same VirtualLocation to which its related CONFERENCE property (Section 2.3.10) converts. If no related CONFERENCE property is set in the calendar component, then implementations MUST NOT convert the VCONFERENCE component.¶

Its properties convert as follows:¶

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

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

BEGIN:VCONFERENCE
URI;VALUE=URI:https://chat.example.com/x?id=123456
STYLED-DESCRIPTION;VALUE=TEXT;FMTTYPE=text/html:<body>Click <a href="https://ch
 at.example.com/client">here</a> to download the client...</body>
...
END:VCONFERENCE
CONFERENCE;VALUE=URI;FEATURE=AUDIO,VIDEO;
 LABEL=Team meeting:https://chat.example.com/x?id=123456

"virtualLocations": {
  "1": {
    "@type": "VirtualLocation",
    "name": "Team meeting",
    "description": "<body>Click <a href=\"https://chat.example.com/client\">here</a> to download the client...</body>",
    "descriptionContentType": "text/html",
    "uri": "https://chat.example.com/x?id=123456",
    "features": {
      "audio": true,
      "video": true
    }
  }
}

2.2.4. VEVENT

The VEVENT component [RFC5545] (Section 3.6.1) converts to a Event object [jscalendarbis] (Section 2.1). 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.¶

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

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

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",
      "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.5. VLOCATION

The VLOCATION component [RFC9073] (Section 7.2) converts to a Location object [jscalendarbis] (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",
    "iCalComponent": {
      "@type": "ICalComponent",
      "name": "vlocation",
      "properties": [
        [
          "structured-data",
          {},
          "uri",
          "http://dir.example.com/venues/big-hall.vcf"
        ],
        [
          "uid",
          {},
          "text",
          "4954DC22-5BD6-4E98-844D-0302982F54AC"
        ]
      ]
    }
  }
}

2.2.6. VTODO

The VTODO component [RFC5545] (Section 3.6.2) converts to a Task object [jscalendarbis] (Section 2.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 Task object.¶

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

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

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 [jscalendarbis] (Section 4.5.2) of the Alert object.¶

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

BEGIN:VEVENT
BEGIN:VALARM
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 [jscalendarbis] (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 11 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
ACTION:DISPLAY
...

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

BEGIN:VEVENT
BEGIN:VALARM
ACTION:AUDIO
...

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

2.3.3. ATTACH

The ATTACH property [RFC5545] (Section 3.8.1.1) in a VEVENT, VTODO, PARTICIPANT, VLOCATION, or VCALENDAR component converts to a Link object [jscalendarbis] (Section 1.4.11). The converted object is set in the "links" property of the Event, Task, Participant, Location, or Group 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 MUST be set in the "mediatype" part of the data URL.¶

The ATTACH property parameters convert as follows:¶

Remarks:¶

• The LINKREL parameter value is defined to be either an URI or an "iana-token" [RFC5545] (Section 3.1). Only parameter values of form "iana-token" convert to the "rel" property of the Link object. The values convert to lowercase.¶

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 [jscalendarbis] (Section 4.4.6). The converted object is set in the "participants" property of the Event or Task object. The property value converts to the calendarAddress property of the Participant object.¶

An ATTENDEE property and a PARTICIPANT component in the same iCalendar component convert to the same Participant object, if their converted calendarAddress property values are equal. How to deal with conflicting values is implementation-specific.¶

The ATTENDEE property parameters convert as follows:¶

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

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

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

ATTENDEE;RSVP=TRUE;PARTSTAT=TENTATIVE;CN=Henry Cabot:mailto:hcabot@example.com
ORGANIZER:mailto:organizer@example.com

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

BEGIN:PARTICIPANT
CALENDAR-ADDRESS:mailto:foo@example.com
DESCRIPTION:some description
...
END:PARTICIPANT
ATTENDEE;RSVP=TRUE;PARTSTAT=TENTATIVE:mailto:foo@example.com
ORGANIZER:mailto:organizer@example.com

"participants": {
  "23": {
    "@type": "Participant",
    "calendarAddress": "mailto:foo@example.com",
    "participationStatus": "tentative",
    "expectReply": true,
    "description": "some description",
    "...": ""
  },
  "o4": {
    "@type": "Participant",
    "calendarAddress": "mailto:organizer@example.com",
    "...": ""
  }
},
"organizerCalendarAddress": "mailto:organizer@example.com"

BEGIN:VTODO
ATTENDEE;RSVP=TRUE;PARTSTAT=COMPLETED:mailto:foo@example.com
ORGANIZER:mailto:organizer@example.com
...

"@type": "Task",
"participants": {
  "1": {
    "@type": "Participant",
    "calendarAddress": "mailto:foo@example.com",
    "participationStatus": "accepted",
    "progress": "completed",
    "expectReply": true,
    "...": ""
  },
  "o": {
    "@type": "Participant",
    "calendarAddress": "mailto:organizer@example.com",
    "...": ""
  }
},
"organizerCalendarAddress": "mailto:organizer@example.com"

2.3.5. CALENDAR-ADDRESS

The CALENDAR-ADDRESS property [RFC9073] (Section 6.4) in a PARTICIPANT component converts to the "calendarAddress" property [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 [jscalendarbis] (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 [jscalendarbis] (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 [jscalendarbis] (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. CONCEPT

The CONCEPT property [RFC9253] (Section 8.1) in a VEVENT, VTODO, or VCALENDAR component converts to the "categories" property [jscalendarbis] (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.10. CONFERENCE

The CONFERENCE property [RFC7986] (Section 5.11) in a VEVENT or VTODO component converts to a VirtualLocation object [jscalendarbis] (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.¶

The CONFERENCE property and a VCONFERENCE component convert to the same VirtualLocation, if the CONFERENCE property value matches the URI property value of the VCONFERENCE component. Also see Section 2.2.3.¶

Its parameters convert as follows:¶

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

CONFERENCE;VALUE=URI;FEATURE=AUDIO,VIDEO;
 LABEL="Web video chat, access code=76543"
 :https://chat.example.com/audio?id=123456

"virtualLocations": {
  "b2": {
    "@type": "VirtualLocation",
    "name": "Web video chat, access code=76543",
    "uri": "https://chat.example.com/audio?id=123456",
    "features": {
      "audio": true,
      "video": true
    }
  }
}

2.3.11. COORDINATES

The COORDINATES property [icaljscalexts] (Section 4.1) in a VLOCATION component converts to the "coordinates" property [jscalendarbis] (Section 4.2.5) of the Location object.¶

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

BEGIN:VEVENT
GEO;DERIVED=TRUE:48.198634;16.371648
BEGIN:VLOCATION
COORDINATES;VALUE=URI:geo:48.198634,16.371648;crs=wgs84;u=40
...

"locations": {
  "1": {
    "@type": "Location",
    "coordinates": "geo:48.198634,16.371648;crs=wgs84;u=40",
    "...": ""
  }
}

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 [jscalendarbis] (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, or PARTICIPANT component converts to the "description" property [jscalendarbis] (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).¶

If the LANGUAGE parameter is set and the DESCRIPTION property is set in a VEVENT or VTODO component, then the parameter value converts to the "locale" property of the Event or Task object, unless the SUMMARY property in the same component has the LANGUAGE parameter set.¶

If the LANGUAGE parameter is set and the DESCRIPTION property is set in a VCALENDAR component, then the parameter value converts to the "locale" property of the Group object, unless the NAME property in the same component has the LANGUAGE parameter set.¶

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

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

"description": "Their pancakes 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 [jscalendarbis] (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 it converts to the "endTimeZone" property of the Event.¶

Implementations MAY preserve the fact that the duration got determined by the DTEND property. How to do this depends on the timezone identifiers of the DTSTART and DTEND properties: If the time zone identifiers are not equal, then the presence of the "endTimeZone" property implies that it converted from the DTEND property. If the time zone identifiers are equal, then implementations MAY set the "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".¶

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

DTSTART;TZID=Europe/Berlin:20241017T130000
DTEND;TZID=Asia/Bangkok:20241018T040000

"start": "2024-10-17T13:00:00",
"timeZone": "Europe/Berlin",
"duration": "PT10H",
"endTimeZone": "Asia/Bangkok"

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

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

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

"start": "2024-01-02T00:00:00",
"timeZone": null,
"duration": "P5D",
"showWithoutTime": true,
"iCalComponent": {
  "@type": "ICalComponent",
  "name": "vevent",
  "convertedProperties": {
    "duration": {
      "@type": "ICalProperty",
      "name": "dtend"
    }
  }
}

2.3.15. DTSTAMP

The DTSTAMP property [RFC5545] (Section 3.8.7.2) in a VEVENT or VTODO component converts to the "updated" property [jscalendarbis] (Section 4.1.6) of the Event or Task 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",
      "...": ""
    }
  ],
  "...": ""
}

2.3.16. DTSTART

The DTSTART property [RFC5545] (Section 3.8.2.4) in a VEVENT or VTODO component converts to the "start" property [jscalendarbis] (Section 4.7.2) of the Event or Task 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 [jscalendarbis] (Section 4.2.4) is "true".¶

The following examples illustrate how to convert the DTSTART property for the VEVENT and VTODO 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 [jscalendarbis] (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 it contains both the DUE and DTSTART properties and the timezone identifier of the DUE property differs from that of the DTSTART property, then the "due" date-time property value MUST be relative to the time zone of DTSTART.¶

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

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

BEGIN:VTODO
DUE;TZID=Europe/Berlin:20240921T105302

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

BEGIN:VTODO
DUE:20240921T105302Z

"@type": "Task",
"due": "2024-09-21T10:53:02",
"timeZone": "Etc/UTC",
"showWithoutTime": false

BEGIN:VTODO
DUE:20240921T105302

"@type": "Task",
"due": "2024-09-21T10:53:02",
"timeZone": null,
"showWithoutTime": false

BEGIN:VTODO
DUE;VALUE=DATE:20240921

"@type": "Task",
"due": "2024-09-21T00:00:00",
"timeZone": null,
"showWithoutTime": true

BEGIN:VTODO
DTSTART;VALUE=DATE:20250220
DUE;VALUE=DATE:20250221

"@type": "Task",
"start": "2025-02-20T00:00:00",
"due": "2025-02-21T00:00:00",
"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 [jscalendarbis] (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. ESTIMATED-DURATION

The ESTIMATED-DURATION property [ical-tasks] (Section 12.1) in a VTODO component converts to the "estimatedDuration" property [jscalendarbis] (Section 5.2.3) of the Task object.¶

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

BEGIN:VTODO
ESTIMATED-DURATION:P2D

"@type": "Task",
"estimatedDuration": "P2D"

2.3.20. EXDATE

The EXDATE property [RFC5545] (Section 3.8.5.1) in a VEVENT or VTODO component converts to a PatchObject value [jscalendarbis] (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" member to "true" and MUST NOT set any other property.¶

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",
"recurrenceRule": {
  "@type": "RecurrenceRule",
  "frequency": "monthly"
},
"recurrenceOverrides": {
  "2023-08-01T13:00:00": {
    "excluded": true
  }
}

2.3.21. GEO

A GEO property with the DERIVED parameter value "TRUE" does not convert to JSCalendar. For non-derived GEO properties, the following rules apply:¶

The GEO property [RFC5545] (Section 3.8.1.6) in a VEVENT or VTODO component converts to a Location object [jscalendarbis] (Section 4.2.5). If the VEVENT or VTODO component also contains the LOCATION property (Section 2.3.25), then the GEO and LOCATION properties convert to the same Location object. The converted object is set in the "locations" property of the Event or Task object.¶

The GEO property [RFC5545] (Section 3.8.1.6) in a PARTICIPANT component converts to a Location object [jscalendarbis] (Section 4.2.5). The converted object is set in the "locations" property of the Participant object.¶

The GEO property [RFC5545] (Section 3.8.1.6) in a VLOCATION component converts to the "coordinates" property [jscalendarbis] (Section 4.2.5) of the Location object.¶

The pair of FLOAT values converts to a 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 optional "coord-c" part of the URI MUST be omitted.¶

Implementations MAY preserve the fact that the Location "coordinates" property converted from a GEO property. How to do so depends on how the GEO property converted to a Location object:¶

• If the GEO property converted from a VLOCATION component, then implementations MAY add a path to the "coordinates" property in the "iCalComponent/convertedProperties" property of the Location object.¶
• Otherwise, implementations MAY set the "iCalProperty" property of the Location object. Alternatively they MAY add a "iCalComponent" property to the object that contains this Location object in its "locations" property, and point to the "coordinates" property in the "convertedProperties" property.¶

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",
    "iCalProperty": {
      "@type": "ICalProperty",
      "name": "geo"
    },
    "...": ""
  }
}

LOCATION:Taj Mahal
GEO:27.175;78.041944

"locations": {
  "2": {
    "@type": "Location",
    "name": "Taj Mahal",
    "coordinates": "geo:27.175,78.041944",
    "...": ""
  }
}

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",
    "iCalComponent": {
      "@type": "ICalComponent",
      "name": "vlocation",
      "convertedProperties": {
        "coordinates": {
          "@type": "ICalProperty",
          "name": "geo"
        }
      }
    }
  }
}

2.3.22. IMAGE

The IMAGE property [RFC7986] (Section 5.10) in a VEVENT, VTODO, VLOCATION, PARTICIPANT, or VCALENDAR component converts to a Link object [jscalendarbis] (Section 1.4.11). The converted object is set in the "links" property of the Event, Task, Location, Participant, or Group 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:¶

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

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

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

2.3.23. LAST-MODIFIED

The LAST-MODIFIED property [RFC5545] (Section 3.8.7.3) in a VCALENDAR component converts to the "updated" property [jscalendarbis] (Section 4.1.6) of the Group object.¶

The LAST-MODIFIED property [RFC5545] (Section 3.8.7.3) in a VEVENT or VTODO component does not convert to the "updated" property [jscalendarbis] (Section 4.1.6) of the Event or Task object. Implementations MAY instead preserve the LAST-MODIFIED property in the "iCalComponent" property.¶

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

BEGIN:VCALENDAR
LAST-MODIFIED:20240914T231257Z
...

"@type": "Group",
"updated": "2024-09-14T23:12:57Z"

2.3.24. LINK

A LINK property [RFC9253] (Section 8.2) with value type URI in a VEVENT, VTODO, PARTICIPANT, VLOCATION, or VCALENDAR component converts to a Link object [jscalendarbis] (Section 1.4.11). The converted object is set in the "links" property of the Event, Task, Participant, Location, or Group object.¶

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

The LINK property parameters convert as follows:¶

Remarks:¶

• The LINKREL parameter value is defined to be either an URI or an "iana-token" [RFC5545] (Section 3.1). Only parameter values of form "iana-token" convert to the "rel" property of the Link object. The values convert to lowercase.¶

A LINK property with any other value type does not convert to a standard JSCalendar element. Implementations MAY convert it to the "iCalComponent" property (Section 5.1.1).¶

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

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

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

2.3.25. LOCATION

The LOCATION property [RFC5545] (Section 3.8.1.7) in a VEVENT or VTODO component converts to a Location object [jscalendarbis] (Section 4.2.5), unless its DERIVED parameter value is TRUE. The converted object is set in the "locations" property of the Event or Task. 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 convert to a Location object.¶

If the calendar component contains multiple VLOCATION components, then the LOCATION property also converts to the "mainLocationId" property of the Event or Task object. If the LOCATION property is not derived, then the identifier of its Location object is set in the "mainLocationId". If instead the LOCATION property is derived and its property value matches the NAME property value of a VLOCATION component, then the "mainLocationId" property value matches the identifier of the Location object to which that VLOCATION component converts to.¶

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

LOCATION:Conference Room - F123\, Bldg. 002

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

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

LOCATION;DERIVED=TRUE:Fred's Bar
BEGIN:VLOCATION
JSID:1
NAME:Fred's Bar
LOCATION-TYPE:bar
...
END:VLOCATION
BEGIN:VLOCATION
JSID:2
NAME:XYZ Parking
LOCATION-TYPE:parking
GEO:40.71427;-74.00597
...
END:VLOCATION

"locations": {
  "1": {
    "@type": "Location",
    "name": "Fred's Bar",
    "...": ""
  },
  "2": {
    "@type": "Location",
    "name": "XYZ Parking",
    "...": ""
  }
},
"mainLocationId": "1"

2.3.26. LOCATION-TYPE

The LOCATION-TYPE property [RFC9073] (Section 6.1) in a VLOCATION component converts to the "locationTypes" property [jscalendarbis] (Section 4.2.5) of the Location object.¶

The list of location type values converts to a set of location types. The values convert case-sensitively. All LOCATION-TYPE properties in the same VLOCATION convert to the "locationTypes" property in the Location object.¶

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

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 [jscalendarbis] (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 component converts to the "name" property of the Location [jscalendarbis] (Section 4.2.5) or Participant [jscalendarbis] (Section 4.4.6) object.¶

The NAME property [RFC7986] (Section 5.1) in a VCALENDAR component converts to the "title" property [jscalendarbis] (Section 4.2.1) of the Group object. If the LANGUAGE parameter is set, then the parameter value converts to the "locale" property [jscalendarbis] (Section 4.2.9) of the same object.¶

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

BEGIN:VCALENDAR
NAME;LANGUAGE=de:Feiertage Deutschland 2025
...

{
  "@type": "Group",
  "title": "Feiertage Deutschland 2025",
  "locale": "de",
  "...": ""
}

BEGIN:VEVENT
BEGIN:VLOCATION
NAME:Room B
...
END:VLOCATION
...

"locations": {
  "1": {
    "@type": "Location",
    "name": "Room B",
    "iCalComponent": {
      "@type": "ICalComponent",
      "name": "vlocation"
    }
  }
}

2.3.29. ORGANIZER

The ORGANIZER property [RFC5545] (Section 3.8.4.3) in a VEVENT or VTODO component converts to the "organizerCalendarAddress" property [jscalendarbis] (Section 4.4.4) of the Event or Task object and to a Participant object in the "participants" property [jscalendarbis] (Section 4.4.6). The ORGANIZER property value converts to the "calendarAddress" property of the Participant, the "owner" role is set in Participant "roles" property.¶

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

The 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

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

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

"organizerCalendarAddress": "mailto:foo@example.com",
"participants": {
  "a": {
    "@type": "Participant",
    "calendarAddress": "mailto:foo@example.com",
    "name": "Jane Doe",
    "participationStatus": "accepted",
    "roles": {
      "attendee": true,
      "owner": true
    },
    "expectReply": false
  },
  "b": {
    "@type": "Participant",
    "calendarAddress": "mailto:bar@example.com",
    "expectReply": true,
    "...": ""
  }
}

2.3.30. PERCENT-COMPLETE

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

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

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

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

2.3.31. PRIORITY

The PRIORITY property [RFC5545] (Section 3.8.1.9) in a VEVENT or VTODO component converts to the "priority" property [jscalendarbis] (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.32. PRODID

The PRODID property [RFC5545] (Section 3.7.3) in a VCALENDAR component converts to the "prodId" property [jscalendarbis] (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.33. RDATE

A RDATE property [RFC5545] (Section 3.8.5.2) with value type DATE or DATE-TIME in a VEVENT or VTODO component converts to a PatchObject value [jscalendarbis] (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 object. The PatchObject value MUST be an empty JSON object.¶

A RDATE property with value type PERIOD does not convert to a standard JSCalendar element. Implementations MAY convert it to the "iCalComponent" property (Section 5.1.1) of the Event or Task 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",
"recurrenceRule": {
  "@type": "RecurrenceRule",
  "frequency": "monthly"
},
"recurrenceOverrides": {
  "2023-08-05T17:00:00": {}
}

2.3.34. RECURRENCE-ID

The RECURRENCE-ID property [RFC5545] (Section 3.8.4.4) in a VEVENT or VTODO component converts to the "recurrenceId" property [jscalendarbis] (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.35. RELATED-TO

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

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

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
JSID:alert1
TRIGGER:-PT15M
DESCRIPTION:Event reminder
ACTION:DISPLAY
ACKNOWLEDGED:20210302T151514Z
END:VALARM
...
BEGIN:VALARM
UID:DE7B5C34-83FF-47FE-BE9E-FF41AE6DD097
JSID:alert2
TRIGGER;VALUE=DATE-TIME:20210302T152000Z
RELATED-TO;RELTYPE=SNOOZE:8297C37D-BA2D-4476-91AE-C1EAA364F8E1
DESCRIPTION:Event reminder
ACTION:DISPLAY
END:VALARM
...

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

2.3.36. RRULE

The RRULE property [RFC5545] (Section 3.8.5.3) in a VEVENT or VTODO component converts to a RecurrenceRule object [jscalendarbis] (Section 4.3.3). The converted object is set in the "recurrenceRule" property of the Event or Task object.¶

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

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

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

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

"recurrenceRule": {
  "@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.37. SEQUENCE

The SEQUENCE property [RFC5545] (Section 3.8.7.4) in a VEVENT or VTODO component converts to the "sequence" property [jscalendarbis] (Section 4.1.7) of the Event or Task object.¶

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

SEQUENCE:3

"sequence": 3

2.3.38. SHOW-WITHOUT-TIME

The SHOW-WITHOUT-TIME property [icaljscalexts] (Section 4.2) in a VEVENT or VTODO component converts to the "showWithoutTime" property [jscalendarbis] (Section 4.2.4) of the Event or Task object. As outlined in the definition of the SHOW-WITHOUT-TIME property, the property MUST be ignored if the temporal value type of the VEVENT or VTODO component is DATE, or if the property value is "FALSE".¶

The following example illustrates how to convert the SHOW-WITHOUT-TIME property:¶

DTSTART;TZID=America/Chicago:20250521T080000
DURATION:PT12H
SHOW-WITHOUT-TIME;VALUE=BOOLEAN:TRUE

"start": "2025-05-21T08:00:00",
"timeZone": "America/Chicago",
"duration": "PT12H",
"showWithoutTime": true

2.3.39. STATUS

The STATUS property [RFC5545] (Section 3.8.1.11) in a VEVENT component converts to the "status" property [jscalendarbis] (Section 5.1.3) of the Event object. The STATUS property in a VTODO component converts to the "progress" property [jscalendarbis] (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.40. SOURCE

The SOURCE property [RFC7986] (Section 5.8) in a VCALENDAR component converts to the "source" property [jscalendarbis] (Section 5.3.2) of the Group object.¶

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.41. STYLED-DESCRIPTION

The STYLED-DESCRIPTION property [RFC9073] (Section 6.5) in a PARTICIPANT, VLOCATION, VEVENT or VTODO component converts to the "description" property [jscalendarbis] (Section 4.2.2) of the Participant, Location, Event or Task object under the following conditions:¶

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

If these conditions are not met, implementations MAY preserve the property in the "iCalComponent" property (Section 5.1.1).¶

If the LANGUAGE parameter is set and the STYLED-DESCRIPTION property is set in a VEVENT or VTODO component, then the parameter value converts to the "locale" property of the Event or Task object, unless the SUMMARY or DESCRIPTION properties in the same component have the LANGUAGE parameter set.¶

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.42. SUMMARY

The SUMMARY property [RFC5545] (Section 3.8.1.12) in a VEVENT or VTODO component converts to the "title" property [jscalendarbis] (Section 4.2.1) of the Event or Task object. If the LANGUAGE parameter is set, then the parameter value converts to the "locale" property [jscalendarbis] (Section 4.2.9) of the same object.¶

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

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

SUMMARY:Birthday Party

"title": "Birthday Party"

SUMMARY;LANGUAGE=fr:Fête d'anniversaire

"title": "Fête d'anniversaire",
"locale": "fr"

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

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

2.3.43. TRANSP

The TRANSP property [RFC5545] (Section 3.8.2.7) in a VEVENT or VTODO component converts to the "freeBusyStatus" property [jscalendarbis] (Section 4.4.2) of the Event or Task object.¶

Its values convert as follows:¶

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

TRANSP:TRANSPARENT

"freeBusyStatus": "free"

2.3.44. 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 [jscalendarbis] (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.45. UID

The UID property [RFC5545] (Section 3.8.4.7) in a VEVENT, VTODO, or VCALENDAR component converts to the "uid" property [jscalendarbis] (Section 4.1.2) of the Event, Task, or Group object.¶

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

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

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

4.1.1. JSID

Property Name:

JSID¶

Purpose:

This property preserves the identifier of a JSCalendar object value in iCalendar.¶

Value type:

TEXT; also see "Format Definition" below for value restrictions.¶

Property Parameters:

IANA and non-standard property parameters can be specified on this property.¶

Conformance:

This property can be specified at most once in any calendar component.¶

Description:

This property specifies the JSON object key of the JSCalendar object to which an iCalendar component converts to. For example, this property set in a VALARM component within a VEVENT component defines the key of the Alert object value in the Event object's "alerts" property (see Figure 83).¶

The value of the JSID property MUST be a valid object key according to the definition of the JSCalendar property to which the component converts to.¶

Format Definition:

This property is defined by the following notation:¶

jsid-prop = "JSID" *(";" other-param) ":" TEXT CRLF

¶

Example(s):

The following example illustrates how to convert the JSID property set in a VALARM component.¶

BEGIN:VEVENT
...
BEGIN:VALARM
JSID:myalert1
...
END:VALARM

"@type": "Event",
"alerts": {
  "myalert1": {
    "@type": "Alert",
    "...": ""
  }
}

4.1.2. JSPROP

Property Name:

JSPROP¶

Purpose:

This property represents a JSCalendar property in iCalendar.¶

Value type:

TEXT; also see "Format Definition" below for value restrictions.¶

Property Parameters:

The JSPTR parameter (Section 4.2.2) MUST be specified on this property. Other IANA and non-standard property parameters can be specified on this property.¶

Conformance:

This property can be specified multiple times in any calendar component.¶

Description:

This property converts an arbitrary JSCalendar property from and to iCalendar. The iCalendar property value is the JSON-encoded value of the JSCalendar property, represented as a TEXT value. The JSON value MUST NOT be the null value, and it SHOULD NOT contain insignificant whitespace as defined in Section 2 of [RFC8259]. The value of the JSPTR parameter points to the JSCalendar property within the JSCalendar object.¶

The root of the JSON pointer is always the JSCalendar object to which the calendar component converts to, even if the JSON pointer starts with the SOLIDUS (U+002F) character. The pointer MUST NOT reference into an array.¶

All JSPROP properties in a calendar component together form a PatchObject [jscalendarbis] (Section 1.4.9): the JSPTR parameter of a JSPROP property corresponds to a key in the PatchObject, the property value corresponds to the JSON value for that key. When converting from iCalendar to JSCalendar, the PatchObject MUST only be applied after all other iCalendar elements of the component have been converted. Only new properties are allowed to be set, a JSON pointer in the PatchObject that points to an existing property MUST be ignored.¶

Format Definition:

This property is defined by the following notation:¶

jsprop = "JSPROP" jsprop-param ":" TEXT CRLF

jsprop-param  = *(
          ; The following are MANDATORY and MUST NOT
          ; occur more than once
          ( ";" jsptr-param )
          ;
          ; The following is OPTIONAL
          ; and MAY occur more than once.
          ;
          (";" other-param)
          ;
          )

¶

Example(s):

The following example illustrates how to convert a JSPROP property with a JSON boolean value¶

JSPROP;JSPTR="example.com:foo":true

"example.com:foo": true

The following example illustrates how to convert a JSPROP property with a JSON object value¶

JSPROP;JSPTR="example.com:foo":{"bar":1234\,"baz":"bam"}

"example.com:foo": {
  "bar": 1234,
  "baz": "bam"
}

The following example illustrates how to convert a JSPROP property that points to a property within a JSCalendar Alert. The JSON pointer in the JSPTR parameter is relative to the Alert object.¶

BEGIN:VEVENT
...
BEGIN:VALARM
JSPROP;JSPTR="example.com:foo":"bar"
...
END:VALARM

"@type": "Event",
"alerts": {
  "a1": {
    "@type": "Alert",
    "example.com:foo": "bar",
    "...": ""
  }
}

The following example illustrates how to convert a JSPROP property that points to a property within a JSCalendar Link. The JSON pointer in the JSPTR parameter is relative to the Event object because the Link object converts to an iCalendar property. The JSID parameter (Section 4.2.1) on the ATTACH property ensures that the JSON path remains valid during conversion.¶

BEGIN:VEVENT
...
ATTACH;JSID=mylink1:https://www.rfc-editor.org/rfc/rfc8984.html
JSPROP;JSPTR="links/mylink1/example.com:foo":"bar"
...

"@type": "Event",
"links": {
  "mylink1": {
    "@type": "Link",
    "example.com:foo": "bar",
    "...": ""
  }
}

4.2.1. JSID

Parameter Name:

JSID¶

Format Definition:

jsid-param  = "JSID" "=" param-value

¶

Description:

This parameter specifies the JSON object key of the JSCalendar object to which an iCalendar property converts to. For example, this parameter set on an ATTACH property within a VEVENT component defines the key of the Link object value in the Event object's "links" property (see below for an example).¶

The value of the JSID parameter MUST be a valid key according to the definition of the JSCalendar property to which the property that this parameter is set on converts to. Typically, this requires the value to be a valid Id [jscalendarbis] (Section 1.4.1).¶

Example(s):

ATTACH;JSID=mylink1:https://example.com

"links": {
  "mylink1": {
    "@type": "Link",
    "href": "https://example.com"
  }
}

¶

4.2.2. JSPTR

Parameter Name:

JSPTR¶

Format Definition:

jsptr-param  = "JSPTR" "=" quoted-string

¶

Description:

This parameter is specified on a JSPROP (Section 4.1.2) property. Its value is a JSON pointer [RFC6901] that points to a JSCalendar property.¶

Description:

This parameter has a single value that MUST be a valid JSON pointer as defined in [RFC6901]. The value MUST be quoted to preserve its case-sensitivity and it MUST NOT contain the DQUOTE character. See Section 3.2 of [RFC5545] for how to format parameter values.¶

Example(s):

JSPROP;JSPTR="example.com:foo":"bar"

¶

For further examples, see Section 4.1.2.¶

5.1.1. iCalComponent

Name:

iCalComponent¶

Context:

Any JSCalendar object¶

Type:

ICalComponent (optional)¶

Description

This contains information about an iCalendar component that got converted to JSCalendar. It allows for preserving 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 which did not convert to standard JSCalendar elements. 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 [jscalendarbis]. 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.33).¶

properties: *[][] (optional)

This contains properties of the iCalendar component which did not convert to standard JSCalendar elements. The value MUST be a list of iCalendar properties formatted in jCal as defined in Section 3.4 of [RFC7265].¶

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

BEGIN:VEVENT
SUMMARY;X-FOO=bar:test
...
X-BAR:bam
...
BEGIN:X-BAZ
UID:507A08F9-81D8-4D16-9480-D6D75E977943
END:X-BAZ
...

{
  "@type": "Event",
  "title": "test",
  "iCalComponent": {
    "@type": "ICalComponent",
    "name": "vevent",
    "convertedProperties": {
      "title": {
        "@type": "ICalProperty",
        "name": "summary",
        "parameters": {
          "x-foo": "bar"
        }
      }
    },
    "properties": [
      [
        "x-bar",
        {},
        "unknown",
        "bam"
      ]
    ],
    "components": [
      [
        "x-baz",
        [
          [
            "uid",
            {},
            "text",
            "507A08F9-81D8-4D16-9480-D6D75E977943"
          ]
        ],
        []
      ]
    ]
  },
  "...": ""
}

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 a JSCalendar object. It allows for preserving 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].¶

The example in Figure 90 describes how to convert an unknown parameter to the "iCalProperty" property. The ATTACH property converts to a Link object. To preserve the unknown "X-FOO" parameter, the "iCalProperty" property is set on the Link object.¶

ATTACH;X-FOO=bar:https://example.com/example.jpg

"links": {
  "l1": {
    "@type": "Link",
    "href": "https://example.com/example.jpg",
    "iCalProperty": {
      "@type": "ICalProperty",
      "name": "attach",
      "parameters": {
        "x-foo": "bar"
      }
    }
  }
}