]> Fastmail

PO Box 234 Collins St. West Melbourne VIC 8007 Australia rsto@fastmailteam.com

art calext calendars iCalendar JSCalendar 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)").

Introduction The JSCalendar format aims to be an alternative to the iCalendar 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 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 .

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 when, and only when, they appear in all capitals, as shown here.

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

Updated Properties

GEO Property This specification deprecates the "GEO" property and introduces the "COORDINATES" 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. They MAY additionally specify a "GEO" property in a "VEVENT" or "VTODO" component, in which case its "DERIVED" parameter 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 , 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.

Updated Components

VLOCATION component This document updates the definition of the "VLOCATION" component. It allows to specify the newly defined "COORDINATES" property at most once in a "VLOCATION" component. It appends the following to the "Format Definition" of the "VLOCATION" component, defined in : The "coord" ABNF is defined in .

New Properties

COORDINATES Property

Property Name:

COORDINATES

Purpose:

To represent a geographic location using the protocol-independent, extensible "geo" URI scheme.

Value Type:

URI -- no default

Property Parameters:

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

Conformance:

This property can be specified in a "VLOCATION" calendar component.

Description:

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 and updates.

Format Definition:

Example:

The following is an example of this property:

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

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:

Example:

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

Example:

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 in a "VCONFERENCE" or "VLOCALIZATION" calendar component.

Description:

This property associates a Uniform Resource Identifier 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" and "VLOCALIZATION" components. 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:

Example:

New Parameters

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 from its input string. This hash MUST NOT be used for cryptographic purposes and the security considerations of apply. The result of this hash is hex-encoded with all characters in lowercase.

Format Definition:

Example:

New Components

VCONFERENCE Component

Component Name:

VCONFERENCE

Purpose:

This component provides information about a virtual conference in addition to what is provided in the CONFERENCE property.

Conformance:

This component can be specified in any component that allows to specify the "CONFERENCE" property. It MAY occur multiple times, unless the "CONFERENCE" property is defined to occur only once for a specific component

Description:

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 specified in the "VCONFERENCE" component. The URI values MUST be equal character strings, as specified in . 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:

Example(s):

The following is an example of this component:

VLOCALIZATION Component

Component Name:

VLOCALIZATION

Purpose:

To provide internationalized and localized alternate text representations of calendar component elements.

Conformance:

This component can be specified in any component that allows to specify at least one property with the "LANGUAGE" parameter. It MAY occur multiple times, unless defined otherwise for a specific component.

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 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 . The URI value MUST be a valid URI in the "urn" scheme with namespace identifier "uuid" . 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" property at least once in the "VLOCALIZATION" component. The property value MUST be the "Property Set Digest" as defined in , 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:

Example(s):

The following is an example of this component:

Security Considerations This specification extends . The same security considerations as outlined in apply. In addition, refers to the security considerations of the MD5 Message-Digest Algorithm.

IANA Considerations TBD

References Normative References Informative References Fastmail Fastmail Fastmail

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