| Internet-Draft | iCalendar JSCalendar Extensions | May 2025 |
| Stepanek | Expires 22 November 2025 | [Page] |
This document defines a set of new elements for iCalendar and extends the use of existing ones. Their main purpose is to extend the semantics of iCalendar with elements defined in JSCalendar, but the new definitions also aim to be useful within just the iCalendar format. This document updates RFC 5545 ("Internet Calendaring and Scheduling Core Object Specification (iCalendar)").¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 22 November 2025.¶
Copyright (c) 2025 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
The JSCalendar [I-D.stepanek-jscalendarbis] format aims to be an alternative to the iCalendar [RFC5545] format for representation of calendaring data. As such, it introduces new semantics that are not covered in the current definition of iCalendar and its various extensions. Converting calendaring data between the two formats is defined in [I-D.ietf-calext-jscalendar-icalendar] with the goal of not losing any semantics during conversion. To achieve this, this document defines new elements iCalendar and extends existing definitions. Doing so, it follows the recommendations for introducing new iCalendar elements as specified in Section 3 of [RFC7986].¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
This specification deprecates the "GEO" property and introduces the "COORDINATES" (Section 4.1) property to replace it. Implementations SHOULD NOT use the "GEO" property to represent spatial coordinates. Instead, they SHOULD specify the "COORDINATES" property in a "VLOCATION" component [RFC9073] (Section 7.2). They MAY additionally specify a "GEO" property in a "VEVENT" or "VTODO" component, in which case its "DERIVED" parameter [RFC9073] (Section 5.3) MUST have value "TRUE".¶
The remainder of this section documents the rationale for deprecating the "GEO" property:¶
The "GEO" property definition dates back to 1998, a time at which multiple internet protocols and data formats incorporated spatial coordinates in slightly different formats, making interoperability difficult. This got addressed in 2010 in [RFC5870], which introduced a Uniform Resource Identifier (URI) for geographic locations. The 'geo' URI scheme not only improves interoperability but also allows for richer information than the "GEO" property value, e.g. it supports specifying the location altitude and the spatial uncertainty of the coordinates.¶
Alternatively to deprecating, this specification could have updated the "GEO" property to allow its property value type to be URI. This turned out to not interoperate, as implementations tended to reject such iCalendar data as invalid. This was regardless if the "GEO" property was specified in a "VEVENT" component, or if it was specified in iCalendar components that were unsupported by the implementation (e.g. an implementation that was unaware of the "VLOCATION" component still rejected the "GEO" property with value type URI in that component as invalid). Introducing a new property turned out to better interoperate with such systems.¶
This document updates the definition of the "VLOCATION" component. It allows to specify the newly defined "COORDINATES" property (Section 4.1) at most once in a "VLOCATION" component. It appends the following to the "Format Definition" of the "VLOCATION" component, defined in Section 7.2 of [RFC9073]:¶
locprop /= *(
;
; The following is OPTIONAL
; but MUST NOT occur more than once.
;
coord
;
)
¶
The "coord" ABNF is defined in Section 4.1.¶
This property represents spatial (geographic) coordinates. In contrast to the the "GEO" property, this property allows to represent not only latitude and longitude but also altitude of a location. In addition, it supports to indicate the uncertainty of the coordinates, is interoperable with other internet standards making use of spatial information, and is extensible, such as for use with other coordinate reference systems. The property value MUST a URI in the "geo" URI scheme, as defined in [RFC5870] and updates.¶
coord = "COORDINATES" coordparam ":" uri CRLF
coordparam = *(
;
; The following is REQUIRED,
; but MUST NOT occur more than once.
;
(";" "VALUE" "=" "URI") /
;
; The following is OPTIONAL,
; and MAY occur more than once.
;
(";" other-param)
;
)
¶
The following is an example of this property:¶
COORDINATES;VALUE=URI:geo:48.198634,16.371648;crs=wgs84;u=40¶
This indicates that the exact time span is not important to display when rendering this calendar object. An example of this is an event that occurs over a full or almost full day, but in contrast to a DATE value is limited to a specific time zone or business hours. While the time component is important for free-busy calculations and checking for scheduling clashes, calendars may choose to display it as an all-day event, or display the object separately to other objects to enhance the user's view of their schedule.¶
This property only is for presentation purposes, it does not have any impact on the temporal span or value type of a calendar object.¶
This property MAY be specified on VEVENT components where the DTSTART property is of type DATE-TIME, or in VTODO components where either the DTSTART or DUE property is specified and has type DATE-TIME. In all other cases it MUST NOT be set. If this property is set, its property value MUST be "TRUE", e.g. it MUST be omitted rather than having value "FALSE".¶
Implementations that are unaware of the "SHOW-WITHOUT-TIME" property might inadvertently preserve this property when changing a calendar object's temporal type from DATE-TIME to DATE. Implementations SHOULD therefore ignore rather than reject the incorrectly specified SHOW-WITHOUT-TIME property. They MUST NOT preserve the ill-specified property in the calendaring data.¶
showwt = "SHOW-WITHOUT-TIME" showwtparam ":" "TRUE" CRLF
showwtparam = *(
;
; The following is REQUIRED,
; but MUST NOT occur more than once.
;
(";" "VALUE" "=" "BOOLEAN") /
;
; The following is OPTIONAL,
; and MAY occur more than once.
;
(";" other-param)
;
)
¶
SHOW-WITHOUT-TIME;VALUE=BOOLEAN:TRUE¶
This property associates a Uniform Resource Identifier [RFC3986] with a calendar component. In contrast to the "UID" property, which defines its values to be of type TEXT, this property requires its value to be a syntactically valid URI. In contrast to the "URL" property, this property neither provides a dynamic rendition of the associated calendar component, nor does it locate a resource - it only identifies the calendar component.¶
The semantics and purpose of this identifier MUST be defined for each calendar component containing the "URI" property. This document defines the semantics of the "URI" property for the "VCONFERENCE" component. Similarly, future iCalendar extensions might consider using the "URI" property in cases where associating calendaring data by use of the "UID" and "RELATED-TO" properties is not possible.¶
uriprop = "URI" uriparam ":" uri CRLF
uriparam = *(
;
; The following is REQUIRED,
; but MUST NOT occur more than once.
;
(";" "VALUE" "=" "URI") /
;
; The following is OPTIONAL,
; and MAY occur more than once.
;
(";" other-param)
;
)
¶
URI;VALUE=URI:urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6¶
This component augments information provided by the "CONFERENCE" property for a virtual meeting or conference. Specifically, this specification adds support for long-form text and rich-text descriptions, which can not be provided in the "LABEL" parameter of the "CONFERENCE" property.¶
A "VCONFERENCE" component by itself does not represent a virtual meeting and it does not replace information provided by the "CONFERENCE" property. Instead, a calendar component that specifies the "VCONFERENCE" component MUST also specify a "CONFERENCE" property, and that "CONFERENCE" property value MUST match the value of the "URI" property (Section 4.3) specified in the "VCONFERENCE" component. The URI values MUST be equal character strings, as specified in Section 6 of [RFC3986].¶
A "VCONFERENCE" component MAY contain one "DESCRIPTION" property and multiple "STYLED-DESCRIPTION" properties, but one of them MUST NOT specify the "DERIVED" parameter and all others MUST specify the "DERIVED" parameter (e.g. it must have one and only one non-derived description). For future extensibility, this specification does not define the "DESCRIPTION" or "STYLED-DESCRIPTION" properties to be mandatory, but a "VCONFERENCE" component MUST contain at least one property other than the "URI" property.¶
Implementations that are unaware of the "VCONFERENCE" component might inadvertently preserve this component when removing its related "CONFERENCE" property from the calendar object. Changing the URI value of the "CONFERENCE" property is in this context considered a removal followed by inserting a new element. Implementations SHOULD therefore ignore rather than reject such incorrectly specified "VCONFERENCE" components. They MUST NOT preserve the ill-specified component in the calendaring data.¶
vconfc = "BEGIN" ":" "VCONFERENCE" CRLF
*(
;
; The following are REQUIRED,
; but MUST NOT occur more than once.
;
uriprop /
;
; The following are OPTIONAL,
; but MUST NOT occur more than once.
;
description /
;
; The following are OPTIONAL,
; and MAY occur more than once
;
styleddescription
;
;
; The following are OPTIONAL,
; and MAY occur more than once.
;
x-prop / iana-prop
;
)
"END" ":" "VCONFERENCE" CRLF
¶
The following is an example of this component:¶
BEGIN:VCONFERENCE URI;VALUE=URI:https://chat.example.com/x?id=123456 DESCRIPTION:This is the first in a series of sessions:\n ... END:VCONFERENCE CONFERENCE;VALUE=URI;FEATURE=AUDIO,VIDEO; LABEL=Product Brainstorming Session:https://chat.example.com/x?id=123456¶
This specification extends [RFC5545]. The same security considerations as outlined in Section 7 of [RFC5545] apply.¶