Internet-Draft | iCalendar Relationships | January 2022 |
Douglass | Expires 27 July 2022 | [Page] |
This specification updates the iCalendar RELATED-TO property by adding new relation types and introduces new iCalendar properties LINK, CONCEPT and REFID to allow better linking and grouping of iCalendar components and related data.¶
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 27 July 2022.¶
Copyright (c) 2022 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.¶
iCalendar entities defined in [RFC5545] often need to be related to each other or to associated meta-data. The specifications below support relationships of the following forms:¶
The iCalendar [RFC5545] RELATED-TO property has no support for temporal relationships as used by standard project management tools.¶
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 allow the RELATED-TO property to define a richer set of relationships useful for project management.¶
This specification defines a new REFID property which allows arbitrary groups of entities to be associated with the same key value.¶
REFID is used to identify a key allowing the association of components that are related to the same object and retrieval of a component based on this key. Two examples of how this may be used are to identify the tasks associated with a given project without having to communicate the task structure of the project, and to group all tasks associated to a specific package in a package delivery system.¶
As such, the presence of a REFID property imparts no meaning to the component. It is merely a key to allow retrieval. This is distinct from categorisation which, while allowing grouping also adds meaning to the component to which it is attached.¶
The name CONCEPT is used by the Simple Knowledge Organization System defined in [W3C.REC-skos-reference-20090818]. The term "concept" more accurately defines what we often mean by a category. It's not the text string that is important but the meaning attached to it. For example, the term "football" can mean very different sports.¶
The introduction of CONCEPT allows a more structured approach to categorization, with the possibility of namespaced and path-like values. Unlike REFID the CONCEPT property imparts some meaning. It is assumed that the value of this property will reference a well defined category.¶
The current [RFC5545] CATEGORY property is used as a free form 'tagging' field. As such it is difficult to establish formal relationships between components based on their category.¶
Rather than attempt to add semantics to the CATEGORY property it seems best to continue its usage as an informal tag and establish a new CONCEPT property with more constraints.¶
The currently existing iCalendar standard [RFC5545] 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 [RFC8288]¶
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 also often necessary to reference calendar components in other collections. For example, a VEVENT might refer to a VTODO from which it was derived. The PARENT, SIBLING and CHILD relationships defined for the RELATED-TO property only allow for a UID which is inadequate for many purposes. Allowing other value types for those relationships may help but would cause 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.¶
Beyond the need to relate elements temporally, project management tools often need to be able to specify the relationships between the various events and tasks which make up a project. The LINK property provides such a mechanism.¶
The LINK property MUST NOT be treated as just another attachment. The ATTACH property defined in [RFC5545] is being extended to handle server-side management and stripping of inline data. Clients may choose to handle attachments differently from the LINK property as they are often an integral part of the message - for example, the agenda.¶
To facilitate offline display the link type may identify important pieces of data which should be downloaded in advance.¶
In general, the calendar entity should be self explanatory without the need to download referenced meta-data such as a web page.¶
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.¶
The actual reference value can take three forms specified by the type parameter¶
[RFC8288] defines two forms of relation type: registered and extension. Registered relation types are added to the Link Relations registry as specified in Section 2.1.1 of [RFC8288]. Extension relation types, defined in Section 2.1.2 of [RFC8288], are specified as unique URIs that are not registered in the registry.¶
The relation types defined in Section 6.1 will be registered with IANA in accordance with the specifications in [RFC8288].¶
This section defines the usual temporal relationships for use with the RELTYPE parameter defined in Section 3.2.15 of [RFC5545]: FINISHTOSTART, FINISHTOFINISH, STARTTOFINISH or STARTTOSTART.¶
The [RFC5545] RELATED-TO property with one or more of these temporal relationships will be present in the predecessor entity and will refer to the successor entity.¶
The GAP parameter (see Section 6.2) specifies the lead or lag time between the predecessor and the successor. In the description of each temporal relationship below we refer to Task-A, which contains and controls the relationship, and Task-B the target of the relationship.¶
Task-B cannot start until Task-A finishes. For example, when sanding is complete, painting can begin.¶
============ | Task-A |--+ ============ | | V ============ | Task-B | ============
For example, if the goal is to prepare a meal, we start the potatoes, then the meat then the peas but they should all be cooked at the same time.¶
================== | Task-A |--+ ================== | | ============ | | Task-B |<-+ ============
The start of Task-A (which occurs after Task-B) controls the finish of Task-B. For example, ticket sales (Task-B) end when the game starts (Task-A).¶
============ +--| Task-A | | ============ | ============ | | Task-B |<-+ ============
The start of Task-A triggers the start of Task-B, that is Task-B can start anytime after Task-A starts.¶
============ +--| Task-A | | ============ | | ============ +->| Task-B | ============
This section defines the additional relationships below:¶
This parameter is defined by the following notation:¶
linkrelparam = "LINKREL" "=" ("SOURCE" ; Link to source of this component / DQUOTE uri DQUOTE / iana-token) ; Other IANA registered type¶
This parameter is defined by the following notation:¶
gapparam = "GAP" "=" dur-value¶
This specification defines the following new value types to be used with the VALUE property parameter:¶
This property is defined by the following notation:¶
concept = "CONCEPT" conceptparam ":" uri CRLF conceptparam = *(";" other-param)¶
The following is an example of this property. It points to a server acting as the source for the calendar object.¶
CONCEPT:http://example.com/event-types/arts/music¶
This property is defined by the following notation:¶
link = "LINK" linkparam ":" ( uri / ; for VALUE=REFERENCE uri / ; for VALUE=URI text ) ; for VALUE=TEXT CRLF linkparam = ; the elements herein may appear in any order, ; and the order is not significant. (";" "VALUE" "=" ("REFERENCE" / "URI" / "TEXT")) 1*(";" linkrelparam) (";" fmttypeparam) (";" labelparam) (";" langparam) *(";" other-param)¶
The LINK property parameters map to [RFC8288] attributes as follows:¶
The following is an example of this property which provides a reference to the source for the calendar object.¶
LINK;LINKREL=SOURCE;LABEL=Venue;VALUE=URI:http://example.com/events¶
The following is an example of this property which provides a reference to an entity from which this one was derived. The link relation is a vendor defined value¶
LINK;LINKREL="https://example.com/linkrel/derivedFrom";VALUE=URI: http://example.com/tasks/01234567-abcd1234.ics¶
The following is an example of this property which provides a reference to a fragment of an XML document. The link relation is a vendor defined value¶
LINK;LINKREL="https://example.com/linkrel/costStructure"; VALUE=REFERENCE: http://example.com/xmlDocs/bidFramework.xml #xpointer(descendant::CostStruc/range-to(following::CostStrucEND[1]))¶
This property is defined by the following notation:¶
refid = "REFID" refidparam ":" text CRLF refidparam = *(";" other-param)¶
The following is an example of this property.¶
REFID:itinerary-2014-11-17¶
This specification updates the RELATED-TO property defined in Section 3.8.4.5 of [RFC5545].¶
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 allow the RELATED-TO property to define a richer set of relationships useful for project management.¶
Applications using the LINK property need to be aware of the risks entailed in using the URIs provided as values. See section 7 of [RFC3986] for a discussion of the security considerations relating to URIs.¶
In particular note section 7.1 "Reliability and Consistency" of [RFC3986] which points out the lack of a stability guarantee for referenced resources.¶
When the value is a REFERENCE type the targeted data is an XML document or portion thereof. Consumers need to be aware of the security issues related to XML processing - in particular those related to XML entities. See [RFC4918] - Section 20.6. Additionally note that the reference may be invalid or become so over time.¶
The CONCEPT and redefined RELATED-TO property have the same issues in that values may be URIs.¶
The following iCalendar property names have been added to the iCalendar Properties Registry defined in Section 8.3.2 of [RFC5545] IANA has also added a reference to this document where the properties originally defined in [RFC5545] have been updated by this document.¶
Property | Status | Reference |
---|---|---|
CONCEPT | Current | Section 8.1 |
LINK | Current | Section 8.2 |
REFID | Current | Section 8.3 |
RELATED-TO | Current | [RFC5545], Section 9.1 |
The following iCalendar property parameter names have been added to the iCalendar Parameters Registry defined in Section 8.3.3 of [RFC5545]¶
Parameter | Status | Reference |
---|---|---|
GAP | Current | Section 6.2 |
LINKREL | Current | Section 6.1 |
The following iCalendar property parameter names have been added to the iCalendar Value Data Types Registry defined in Section 8.3.4 of [RFC5545]¶
Value Data Type | Status | Reference |
---|---|---|
REFERENCE | Current | Section 7 |
UID | Current | Section 7 |
The following iCalendar "RELTYPE" values have been added to the iCalendar Relationship Types Registry defined in Section 8.3.8 of [RFC5545]¶
Relationship Type | Status | Reference |
---|---|---|
CONCEPT | Current | Section 5 |
DEPENDS-ON | Current | Section 5 |
FINISHTOFINISH | Current | Section 4 |
FINISHTOSTART | Current | Section 4 |
FIRST | Current | Section 5 |
REFID | Current | Section 5 |
STARTTOFINISH | Current | Section 4 |
STARTTOSTART | Current | Section 4 |
The following link relation values have been added to the Reference Types Registry defined in Section 6.2.2 of [RFC8288]¶
Name | Status | Reference |
---|---|---|
SOURCE | Current | Section 6.1 |
The author would like to thank the members of the Calendaring and Scheduling Consortium technical committees and the following individuals for contributing their ideas, support and comments:¶
Adrian Apthorp, Cyrus Daboo, Marten Gajda, Ken Murchison¶
The author would also like to thank CalConnect, the Calendaring and Scheduling Consortium for advice with this specification.¶