Internet-Draft iCalendar JSCalendar Extensions May 2025
Stepanek Expires 14 November 2025 [Page]
Workgroup:
calext
Published:
Intended Status:
Standards Track
Expires:
Author:
R. Stepanek
Fastmail

iCalendar Format Extensions for JSCalendar

Abstract

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)").

Status of This Memo

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 14 November 2025.

▲

Table of Contents

1. Introduction

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].

1.1. Notational Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

1.2. ABNF Notations

The ABNF definitions in this document use the notations of [RFC5234]. ABNF rules not defined in this document are defined in either [RFC5234] (such as the ABNF for CRLF, WSP, DQUOTE, VCHAR, ALPHA, and DIGIT) or [RFC5545].

2. Updated Properties

2.1. GEO Property

This specification modifies the definition of the "GEO" property to also allow "geo" URI values [RFC5870] as property values. The following additions are made to the definition of this property, originally specified in Section 3.8.1.6 of [RFC5545]:

Value Type (replaces original):
The default value type for this property is FLOAT, the value MUST be two SEMICOLON-separated FLOAT values. The value type can also be set to URI, in which case the VALUE parameter MUST be set.
Description (in addition to original):

A Uniform Resource Identifier for Geographic Locations ("geo" URI) allows for richer semantics than the FLOAT value, such as defining geographic altitude, location uncertainty or the coordinate's reference system. The GEO property value MAY be of type URI to contain such coordinates. Property values of type URI MUST be valid according to the "geo" URI scheme syntax defined in Section 3.3 of [RFC5870].

Format Definition (replaces original):
geo         = geofloat / geouri

geofloat    = "GEO" geoparam ":" geovalue CRLF

geoparam    = *(";" other-param)

;Latitude and Longitude components
geovalue    = float ";" float

geouri      = "GEO" geouriparam ":" uri CRLF

geouriparam = *(
               ;
               ; 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)
               ;
               )
Example(s):

The following are examples of this property:

GEO:37.386013;-122.082932

GEO;VALUE=URI:geo:48.198634,16.371648;crs=wgs84;u=40

3. New Properties

3.1. DIGEST Property

Property Name:
DIGEST
Purpose:
To represent the result of a hash function or a checksum.
Value Type:
TEXT
Property Parameters:
The "HASH" parameter (Section 4.1) MUST be specified exactly once on this property. The "LANGUAGE" parameter MUST NOT be specified on this property. Other IANA and non-standard parameters MAY be specified on this property.
Conformance:
This property can be specified once in a "VLOCALIZATION" calendar component.
Description:

This property represents the result of a hash function or checksum algorithm. The semantics and purpose of its property value MUST be defined for each calendar component which allows to specify the "DIGEST" property. See the definition of the "VLOCALIZATION" component (Section 5.2) for an example.

This document defines the "Property Set Digest", which is the result of applying the hash function specified in the "HASH" parameter to a set of iCalendar properties. This digest is created as follows, all strings MUST be UTF-8 encoded and in Unicode Normalization Form NFC [UNorm]:

  1. For each property in the set, reorder its parameters in ascending order by comparing its parameter names, breaking ties by parameter value. Parameter names and parameter values in form "paramtext" compare in uppercase, parameter values in form "quoted-string" compare case-sensitively.
  2. For each sorted property, generate an unfolded content line. Every content line ends with the CRLF sequence.
  3. Sort the resulting content line strings in ascending order, then concatenate them to a single string, preserving their CRLF endings.
  4. Apply the hash function to the string and set the result as the "DIGEST" property value.

The Property Set Digest can produce different digests for property sets that are semantically equivalent. This is because it does not enforce setting or removing default parameter values, or the "VALUE" parameter, or applying any other iCalendar-specific normalization. As a result, differing digests only indicate that something changed in the property set, but if this change is significant depends on the semantics of the calendar component that specifies using the "DIGEST" property.

Format Definition:
digest      = "DIGEST" digestparam ":" TEXT CRLF

digestparam = *(
               ;
               ; The following is REQUIRED,
               ; but MUST NOT occur more than once.
               ;
               (";" hashparam )
               ;
               ; The following is OPTIONAL,
               ; and MAY occur more than once.
               ;
               (";" other-param)
               ;
               )
Example:
DIGEST;HASH=MD5:a16d6a19dd1d5c3baf591276eff96433

3.2. SHOW-WITHOUT-TIME Property

Property Name:
SHOW-WITHOUT-TIME
Purpose:
To indicate that the exact time span is not important when displaying this calendar object.
Value Type:
BOOLEAN -- no default
Property Parameters:
IANA and non-standard parameters can be specified on this property.
Conformance:
This property can be specified once in a "VEVENT" or "VTODO" calendar component.
Description:

This indicates that the exact time span is not important to display to the user when rendering this calendar object. An example of this is an event that conceptually occurs all 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 and/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 characteristics 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.

Format Definition:
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)
               ;
               )
Example:
SHOW-WITHOUT-TIME;VALUE=BOOLEAN:TRUE

3.3. URI Property

Property Name:
URI
Purpose:
To associate a Uniform Resource Identifier (URI) with a calendar component.
Value Type:
URI -- no default
Property Parameters:
The "LANGUAGE" parameter MUST NOT be specified on this property. Other IANA and non-standard parameters can be specified on this property.
Conformance:
This property can be specified once in a "VCONFERENCE" calendar component.
Description:

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.

Format Definition:
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)
            ;
            )
Example:
URI;VALUE=URI:urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6

4. New Parameters

4.1. HASH Parameter

Parameter Name:
HASH
Purpose:
To specify a hash function for a hash digest.
Description:

In context of the "DIGEST" property, this parameter specifies the hash function that was used to create the property value. Any parameter value is allowed, it is not an enumerated value to allow future parameter values incorporate parameters for hash functions. The same case sensitivity as for other parameters value applies: "paramtext" values are case-insensitive, "quoted-string" values are case-sensitive. This document defines the semantics for the following parameter value:

Parameter Value:
MD5 (case-insensitive)
Description
This produces the MD5 Message-Digest [RFC1321] from its input string. This hash MUST NOT be used for cryptographic purposes and the security considerations of [RFC6151] apply. The result of this hash is hex-encoded with all characters in lowercase.
Format Definition:
hashparam = "HASH" "=" param-value *("," param-value)
Example:
DIGEST;HASH=MD5:a16d6a19dd1d5c3baf591276eff96433

5. New Components

5.1. VCONFERENCE Component

Component Name:
VCONFERENCE
Purpose:
This component provides additional information about a virtual conference specified in the CONFERENCE property [RFC7986] (Section 5.11).
Conformance:
This component can be specified multiple times in any component that allows to specify the "CONFERENCE" property.
Description:

This component augments information provided by the "CONFERENCE" property for a virtual meeting or conference. Specifically, this specification adds support for long-form plain text and rich-text descriptions, which can not feasibly 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 3.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.

Format Definition:
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
Example(s):

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

5.2. VLOCALIZATION Component

Component Name:
VLOCALIZATION
Purpose:
To provide internationalized and localized alternate text representations of calendar component elements.
Conformance:
This component can be specified multiple times in any component that allows to specify at least one property with the "LANGUAGE" parameter.
Description:

This component provides internationalized and localized alternate text representations of properties specified in a calendar component. Its main purpose is for use with descriptive elements such as the "SUMMARY" or "DESCRIPTION" properties, but it MAY be used with any property on which the "LANGUAGE" parameter can be set.

A "VLOCALIZATION" component MUST contain one or more properties which each MUST specify exactly once the "LANGUAGE" parameter. The "LANGUAGE" parameter values MAY differ between properties. The component MUST specify the "URI" property (Section 3.3) exactly once. A calendar component that contains the "VLOCALIZATION" component is then localized to a specific human language by replacing all its properties where the "ALTREP" parameter value matches the "URI" property value of the "VLOCALIZATION" with those properties in the "VLOCALIZATION" component, for which the "LANGUAGE" parameter value matches the language tag of the target human language.

The localized calendar component MUST be valid, e.g. mandatory properties MUST be set. The URI values of the "ALTREP" parameter and "URI" property MUST be compared as character strings, as specified in Section 6 of [RFC3986]. The URI value MUST be a valid URI in the "urn" scheme [RFC8141] with namespace identifier "uuid" [RFC9562].

The "VLOCALIZATION" component SHOULD only contain properties for which a property of the same name also is specified in the non-localized component, e.g. a "VLOCALIZATION" component is only meant to provide alternate text representations, not to add new content.

Implementations that are unaware of the "VLOCALIZATION" component might change property values in the non-localized component, inadvertently invalidating the contents of the localized properties. To mitigate this, implementations MUST specify the "DIGEST" (Section 3.1) property at least once in the "VLOCALIZATION" component. The property value MUST be the "Property Set Digest" as defined in Section 3.1, where the property set consists of all those properties in the non-localized component, for which the "ALTREP" parameter value matches the "URI" property value of the "VLOCALIZATION" component. The "ALTREP" parameter is part of the hashed property. Multiple "DIGEST" properties MUST each specify a different "HASH" parameter value.

Implementations MUST consider a "VLOCALIZATION" component as outdated, if the "DIGEST" property value does not match the expected digest. How to handle outdated localizations is implementation-specific, but implementations MUST not preserve "VLOCALIZATION" components with outdated "DIGEST" property values.

Format Definition:
vlocalizationc = "BEGIN" ":" "VLOCALIZATION" CRLF
                 *(
                  ;
                  ; The following is REQUIRED,
                  ; but MUST NOT occur more than once.
                  ;
                  uriprop
                  ;
                  ; The following is REQUIRED,
                  ; and MAY occur more than once.
                  ; "HASH" parameter values MUST differ.
                  ;
                  digest
                  ;
                  ; The following are OPTIONAL,
                  ; and MAY occur more than once.
                  ; At least one MUST have the
                  ; "LANGUAGE" parameter set.
                  ;
                  x-prop / iana-prop
                  ;
                  )
                 "END" ":" "VLOCALIZATION" CRLF
Example(s):

The following is an example of this component:

DTSTART;VALUE=DATE:20250701
SUMMARY;LANGUAGE="en-ca"
 ;ALTREP="urn:uuid:cd92c017-f7b0-4ac1-a852-c1d28ab172e5"
 :Canada Day
DESCRIPTION;LANGUAGE="en-ca"
 ;ALTREP="urn:uuid:cd92c017-f7b0-4ac1-a852-c1d28ab172e5"
 :Canada Day celebrates the anniversary of Canadian Confederation
 which occurred on July 1, 1867.
BEGIN:VLOCALIZATION
URI;VALUE=URI:urn:uuid:cd92c017-f7b0-4ac1-a852-c1d28ab172e5
DIGEST;HASH=MD5:863f0708251b33990b43830a8ca754e4
SUMMARY;LANGUAGE="fr-ca"
 :Fête du Canada
DESCRIPTION;LANGUAGE="fr-ca"
 :La Fête du Canada est un jour férié commémorant la date de
 formation du Canada le 1er juillet 1867.
END:VLOCALIZATION

6. Security Considerations

This specification extends [RFC5545]. The same security considerations as outlined in Section 7 of [RFC5545] apply. In addition, Section 4.1 refers to the security considerations of the MD5 Message-Digest Algorithm.

7. IANA Considerations

TBD

8. References

8.1. Normative References

[RFC1321]
Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, DOI 10.17487/RFC1321, , <https://www.rfc-editor.org/info/rfc1321>.
[RFC2119]
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/info/rfc2119>.
[RFC3986]
Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, , <https://www.rfc-editor.org/info/rfc3986>.
[RFC5234]
Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/RFC5234, , <https://www.rfc-editor.org/info/rfc5234>.
[RFC5545]
Desruisseaux, B., Ed., "Internet Calendaring and Scheduling Core Object Specification (iCalendar)", RFC 5545, DOI 10.17487/RFC5545, , <https://www.rfc-editor.org/info/rfc5545>.
[RFC5870]
Mayrhofer, A. and C. Spanring, "A Uniform Resource Identifier for Geographic Locations ('geo' URI)", RFC 5870, DOI 10.17487/RFC5870, , <https://www.rfc-editor.org/info/rfc5870>.
[RFC6151]
Turner, S. and L. Chen, "Updated Security Considerations for the MD5 Message-Digest and the HMAC-MD5 Algorithms", RFC 6151, DOI 10.17487/RFC6151, , <https://www.rfc-editor.org/info/rfc6151>.
[RFC7986]
Daboo, C., "New Properties for iCalendar", RFC 7986, DOI 10.17487/RFC7986, , <https://www.rfc-editor.org/info/rfc7986>.
[RFC8141]
Saint-Andre, P. and J. Klensin, "Uniform Resource Names (URNs)", RFC 8141, DOI 10.17487/RFC8141, , <https://www.rfc-editor.org/info/rfc8141>.
[RFC8174]
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/info/rfc8174>.
[RFC9562]
Davis, K., Peabody, B., and P. Leach, "Universally Unique IDentifiers (UUIDs)", RFC 9562, DOI 10.17487/RFC9562, , <https://www.rfc-editor.org/info/rfc9562>.

9. Informative References

[I-D.ietf-calext-jscalendar-icalendar]
Stepanek, R., "JSCalendar: Converting from and to iCalendar", Work in Progress, Internet-Draft, draft-ietf-calext-jscalendar-icalendar, , <https://datatracker.ietf.org/doc/draft-ietf-calext-jscalendar-icalendar/>.
[I-D.stepanek-jscalendarbis]
Jenkins, N.M. and R. Stepanek, "JSCalendar: A JSON Representation of Calendar Data", Work in Progress, Internet-Draft, draft-stepanek-jscalendarbis, , <https://datatracker.ietf.org/doc/draft-stepanek-jscalendarbis/>.
[UNorm]
UTS #15, Unicode Normalization Forms, <https://www.unicode.org/reports/tr15/>.

Acknowledgments

The descriptions of Canada Day in the example in Section 5.2 were copied from the English Wikipedia website which makes the text available under the Creative Commons Attribution-ShareAlike 4.0 License.

Author's Address

Robert Stepanek
Fastmail
PO Box 234
Collins St. West
Melbourne VIC 8007
Australia