calext R. Stepanek Internet-Draft Fastmail Intended status: Standards Track 13 May 2025 Expires: 14 November 2025 iCalendar Format Extensions for JSCalendar draft-stepanek-icalendar-jscalendar-extensions-00 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. Copyright Notice 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. Stepanek Expires 14 November 2025 [Page 1] Internet-Draft iCalendar JSCalendar Extensions May 2025 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 2 1.2. ABNF Notations . . . . . . . . . . . . . . . . . . . . . 3 2. Updated Properties . . . . . . . . . . . . . . . . . . . . . 3 2.1. GEO Property . . . . . . . . . . . . . . . . . . . . . . 3 3. New Properties . . . . . . . . . . . . . . . . . . . . . . . 4 3.1. DIGEST Property . . . . . . . . . . . . . . . . . . . . . 4 3.2. SHOW-WITHOUT-TIME Property . . . . . . . . . . . . . . . 5 3.3. URI Property . . . . . . . . . . . . . . . . . . . . . . 7 4. New Parameters . . . . . . . . . . . . . . . . . . . . . . . 8 4.1. HASH Parameter . . . . . . . . . . . . . . . . . . . . . 8 5. New Components . . . . . . . . . . . . . . . . . . . . . . . 9 5.1. VCONFERENCE Component . . . . . . . . . . . . . . . . . . 9 5.2. VLOCALIZATION Component . . . . . . . . . . . . . . . . . 11 6. Security Considerations . . . . . . . . . . . . . . . . . . . 13 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 13 8.1. Normative References . . . . . . . . . . . . . . . . . . 13 9. Informative References . . . . . . . . . . . . . . . . . . . 14 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 15 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 15 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. Stepanek Expires 14 November 2025 [Page 2] Internet-Draft iCalendar JSCalendar Extensions May 2025 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") / ; Stepanek Expires 14 November 2025 [Page 3] Internet-Draft iCalendar JSCalendar Extensions May 2025 ; 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. Stepanek Expires 14 November 2025 [Page 4] Internet-Draft iCalendar JSCalendar Extensions May 2025 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 Stepanek Expires 14 November 2025 [Page 5] Internet-Draft iCalendar JSCalendar Extensions May 2025 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. Stepanek Expires 14 November 2025 [Page 6] Internet-Draft iCalendar JSCalendar Extensions May 2025 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 Stepanek Expires 14 November 2025 [Page 7] Internet-Draft iCalendar JSCalendar Extensions May 2025 "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 Stepanek Expires 14 November 2025 [Page 8] Internet-Draft iCalendar JSCalendar Extensions May 2025 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. Stepanek Expires 14 November 2025 [Page 9] Internet-Draft iCalendar JSCalendar Extensions May 2025 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 Stepanek Expires 14 November 2025 [Page 10] Internet-Draft iCalendar JSCalendar Extensions May 2025 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 Stepanek Expires 14 November 2025 [Page 11] Internet-Draft iCalendar JSCalendar Extensions May 2025 "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: Stepanek Expires 14 November 2025 [Page 12] Internet-Draft iCalendar JSCalendar Extensions May 2025 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, April 1992, . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, . Stepanek Expires 14 November 2025 [Page 13] Internet-Draft iCalendar JSCalendar Extensions May 2025 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/RFC5234, January 2008, . [RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and Scheduling Core Object Specification (iCalendar)", RFC 5545, DOI 10.17487/RFC5545, September 2009, . [RFC5870] Mayrhofer, A. and C. Spanring, "A Uniform Resource Identifier for Geographic Locations ('geo' URI)", RFC 5870, DOI 10.17487/RFC5870, June 2010, . [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, March 2011, . [RFC7986] Daboo, C., "New Properties for iCalendar", RFC 7986, DOI 10.17487/RFC7986, October 2016, . [RFC8141] Saint-Andre, P. and J. Klensin, "Uniform Resource Names (URNs)", RFC 8141, DOI 10.17487/RFC8141, April 2017, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [RFC9562] Davis, K., Peabody, B., and P. Leach, "Universally Unique IDentifiers (UUIDs)", RFC 9562, DOI 10.17487/RFC9562, May 2024, . 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, 12 May 2025, . [I-D.stepanek-jscalendarbis] Jenkins, N.M. and R. Stepanek, "JSCalendar: A JSON Representation of Calendar Data", Work in Progress, Stepanek Expires 14 November 2025 [Page 14] Internet-Draft iCalendar JSCalendar Extensions May 2025 Internet-Draft, draft-stepanek-jscalendarbis, 12 May 2025, . [UNorm] UTS #15, Unicode Normalization Forms, . Acknowledgments The descriptions of Canada Day in the example in Section 5.2 were copied from the English Wikipedia website (https://en.wikipedia.org/wiki/Canada_Day) which makes the text available under the Creative Commons Attribution-ShareAlike 4.0 License (https://en.wikipedia.org/wiki/ Wikipedia:Text_of_the_Creative_Commons_Attribution- ShareAlike_4.0_International_License). Author's Address Robert Stepanek Fastmail PO Box 234 Collins St. West Melbourne VIC 8007 Australia Email: rsto@fastmailteam.com Stepanek Expires 14 November 2025 [Page 15]