Link Extension to Icalendar

The currently existing iCalendar standard lacks a general purpose method for referencing additional, external information relating to calendar components. This document proposes a method for referencing typed external information that can provide additional information about an iCalendar component. This new LINK property is closely aligned to the LINK header defined in In addition the RELTYPE parameter is extended to take new values defining temporal relationships, a GAP parameter is defined to provide lead and lag values and RELATED-TO is extended to allow URI values. These changes allows the RELATED-TO property to define a richer set of relationships useful for project management.

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 .

The LINK property defines a typed reference or relation to external meta-data or related resources. By providing type and format information as parameters, clients and servers are able to discover interesting references and make use of them, perhaps for indexing or the presentation of interesting links for the user. It is often necessary to relate calendar components. The current RELATED-TO property only allows for a UID which is inadequate for many purposes. Allowing other types may help but might raise a number of backward compatibility issues. The link property can link components in different collections or even on different servers. When publishing events it is useful to be able to refer back to the source of that information. The actual event may have been consumed from a feed or an ics file on a web site. A LINK property can provide a reference to the originator of the event. Project management tools often need to be able to specify the relationships between the various events and tasks which make up a project. This specification defines relation types for those purposes.

The actual reference value can take three forms specified by the type parameter The default type. This is a URI referring to the target. This allows for linking within a single collection and the value is assumed to be another component within that collection. An xpointer. In an XML environment it may be necessary to refer to an external XML artifact. The XPointer is defined in and allows addressing portions of XML documents.

defines two form of relation types, registered and extension. Registered relation types are added to a registry defined by while extension relation types are specified as unique unregistered URIs, (at least unregistered in the registry). The relation types defined here will be registered with IANA in accordance with the specifications in .

Relationship parameter type values are defined in section 3.2.15. of . This specification redefines that type to include the new values FINISHTOSTART, FINISHTOFINISH, STARTTOFINISH and STARTTOSTART.

This property parameter is defined by the following notation: reltypeparam = "RELTYPE" "=" ("PARENT" ; Parent relationship - Default / "CHILD" ; Child relationship / "SIBLING" ; Sibling relationship / "FINISHTOSTART" / "FINISHTOFINISH" / "STARTTOFINISH" / "STARTTOSTART" / iana-token ; Some other IANA-registered ; iCalendar relationship type / x-name) ; A non-standard, experimental ; relationship type This parameter can be specified on a property that references another related calendar. The parameter may specify the hierarchical relationship type of the calendar component referenced by the property when the value is PARENT, CHILD or SIBLING. It defines the temporal relationship when the value is one of FINISHTOSTART, FINISHTOFINISH, STARTTOFINISH or STARTTOSTART. If this parameter is not specified on an allowable property, the default relationship type is PARENT. Applications MUST treat x-name and iana-token values they don't recognize the same way as they would the PARENT value. Identifies the referenced calendar component is a superior of calendar component Indicates that the referenced calendar component is a subordinate of the calendar component. Indicates that the referenced calendar component is a peer of the calendar component. As soon as the Predecessor Interval finishes, the Successor Interval starts. For example, when sanding is complete, painting begins. The Successor Interval continues as long as the Predecessor Interval. For example, the concession stand stops serving 20 minutes after the end of the game. The start of the Predecessor controls the finish of the Successor. For example, the start of Attendee Check-in controls the end of the interval "Set up registration booth." The Predecessor Interval triggers the start of the second task. The Gap indicates the lag time. For example, 20 minutes after the caterer begins work, the dining lines are open.

REL To specify the relationship of data referenced by a LINK property.

This parameter is defined by the following notation: relparam = "REL" "=" ("SOURCE" ; Link to source of this component / DQUOTE uri DQUOTE / x-name ; Experimental reference type / iana-token) ; Other IANA registered type This parameter MUST be specified on all LINK properties, and defines the type of reference. This allows programs consuming this data to automatically scan for references they support. In addition to the values defined here any value defined in may be used. There is no default relation type. identifies the source of the event information. These relation types are registered in

GAP To specify the length of the gap, positive or negative between two temporally related components.

This parameter is defined by the following notation: gapparam = "GAP" "=" dur-value This parameter MAY be specified on the RELATED-TO property, and defines the duration of time between the predecessor and successor in an interval.

TITLE To provide a human readable title.

This parameter is defined by the following notation: titleparam = "TITLE" "=" text This parameter MAY be specified on all LINK properties, and provides a human readable label, perhaps for icons or links..

This specification defines a new value to be used with the VALUE property parameter: VALUE=UID indicates that the associated value is the UID for a component. VALUE=REFERENCE indicates that the associated value is an xpointer referencing an associated XML artifact.

LINK This property provides a reference to external information about a component. URI, TEXT or REFERENCE Non-standard, reference type or format type parameters can be specified on this property. This property MAY be specified in any iCalendar component. When used in a component the value of this property points to additional information related to the component. For example, it may reference the originating web server.

This property is defined by the following notation: link = "LINK" linkparam ":" ( ":" uri ) / ( ";" "VALUE" "=" "REFERENCE" ":" text ) CRLF linkparam = *( ; the following is MANDATORY ; and MAY occur more than once (";" relparam) / ; the following are MANDATORY ; but MUST NOT occur more than once (";" gapparam) / (";" fmttypeparam) / (";" titleparam) / ; the following is OPTIONAL ; and MAY occur more than once (";" xparam) )

The following is an example of this property. It points to a server acting as the source for the event. LINK;REL=SOURCE;TITLE=The Egg: http://example.com/events

RELATED-TO This property is used to represent a relationship or reference between one calendar component and another. The definition here extends the definition in Section 3.8.4.5. of by allowing URI values adn a GAP parameter. URI or TEXT Non-standard, reference type, gap, value or format type parameters can be specified on this property. This property MAY be specified in any iCalendar component. By default or when VALUE=UID is specified, the property value consists of the persistent, globally unique identifier of another calendar component. This value would be represented in a calendar component by the "UID" property. By default, the property value points to another calendar component that has a PARENT relationship to the referencing object. The "RELTYPE" property parameter is used to either explicitly state the default PARENT relationship type to the referenced calendar component or to override the default PARENT relationship type and specify either a CHILD or SIBLING relationship or a temporal relationship. The PARENT relationship indicates that the calendar component is a subordinate of the referenced calendar component. The CHILD relationship indicates that the calendar component is a superior of the referenced calendar component. The SIBLING relationship indicates that the calendar component is a peer of the referenced calendar component. The FINISHTOSTART, FINISHTOFINISH, STARTTOFINISH or STARTTOSTART relationships define temporal relationships as specified in the reltype parameter definition. Changes to a calendar component referenced by this property can have an implicit impact on the related calendar component. For example, if a group event changes its start or end date or time, then the related, dependent events will need to have their start and end dates changed in a corresponding way. Similarly, if a PARENT calendar component is cancelled or deleted, then there is an implied impact to the related CHILD calendar components. This property is intended only to provide information on the relationship of calendar components. It is up to the target calendar system to maintain any property implications of this relationship.

This property is defined by the following notation: related = "RELATED-TO" relparam ( ":" text ) / ( ";" "VALUE" "=" "UID" ":" uid ) ( ";" "VALUE" "=" "URI" ":" uri ) CRLF relparam = *( ; ; The following are OPTIONAL, ; but MUST NOT occur more than once. ; (";" reltypeparam) / (";" gapparam) / ; ; The following is OPTIONAL, ; and MAY occur more than once. ; (";" other-param) ; )

The following are examples of this property. RELATED-TO:jsmith.part7.19960817T083000.xyzMail@example.com RELATED-TO:19960401-080045-4000F192713-0052@example.com RELATED-TO;VALUE=URI;RELTYPE=STARTTOFINISH: http://example.com/caldav/user/jb/cal/ 19960401-080045-4000F192713.ics

Applications using the LINK property need to be aware of the risks entailed in using the URIs provided as values. See [RFC3986] for a discussion of the security considerations relating to URIs.

The author would like to thank Chuck Norris of eventful.com for his work which led to the development of this RFC. The author would also like to thank the members of the Calendaring and Scheduling Consortium public events technical committee and the following individuals for contributing their ideas and support: Cyrus Daboo, Dan Mendell The authors would also like to thank the Calendaring and Scheduling Consortium for advice with this specification.