Internet-Draft iCalendar Relationships March 2022
Douglass Expires 23 September 2022 [Page]
Workgroup:
Network Working Group
Internet-Draft:
draft-ietf-calext-ical-relations-11
Updates:
5545 (if approved)
Published:
Intended Status:
Standards Track
Expires:
Author:
M. Douglass
Bedework

Support for iCalendar Relationships

Abstract

This specification updates the iCalendar RELATED-TO property defined in RFC5545 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.

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 23 September 2022.

▲

Table of Contents

1. Introduction

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:

Structured iCalendar:
iCalendar entities can be related to each other in some structured way, for example as parent, sibling, before, after.
Grouped iCalendar:
iCalendar entities can be related to each other as a group. CATEGORIES are often used for this purpose but are problematic for application developers due to their lack of consistency and use as a free-form tag.
Linked:
Entities can be linked to other entities such as vcards through a URI and associated REL and FMTTYPE parameters.

1.1. Structured iCalendar relationships

The iCalendar [RFC5545] RELATED-TO property has no support for temporal relationships as used by 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.

1.2. Grouped iCalendar relationships

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 all related to the referring, aggregating component and the retrieval of components based on this key. For example, this may be used to identify the tasks associated with a given project without having to communicate the task structure of the project. A further example is the grouping of all sub-tasks associated with the delivery of 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.

1.3. Concept relationships

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. These values have some meaning to those who apply them but not necessarily to any consumer. 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.

1.4. Linked relationships

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 [RFC8288] which defines the generic concept of Web Linking as well as its expression in the HTTP LINK header field.

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.

Calendar components are often grouped into collections to represent a calendar or a series of tasks, for example [RFC4791]' (CalDAV) calendar collections.

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] has been extended by [RFC8607] to handle server-side management and stripping of inline data and to provide additional data about the attachment (size, filename etc).

Additionally clients may choose to handle attachments differently from the LINK property as attachments are often an integral part of the message - for example, the agenda.

1.5. Caching and offline use

In general, the calendar entity should be self explanatory without the need to download referenced meta-data such as a web page.

However, to facilitate offline display the link type may identify important pieces of data which should be downloaded in advance.

1.6. Conventions Used in This Document

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 notation used in this memo to (re-)define iCalendar elements is the ABNF notation of [RFC5234] as used by [RFC5545]. Any syntax elements shown below that are not explicitly defined in this specification come from iCalendar [RFC5545].

4. New temporal RELTYPE Parameter values

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 (a negative value) or lag (a positive value) 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. This is indicated by the direction of the arrow in the diagrams below.

Also each relationship may be modified by the addition of a GAP parameter to the relationship which applies to the targeted component.

RELTYPE=FINISHTOSTART:

Task-B cannot start until Task-A finishes. For example, when painting is complete, carpet-laying can begin.


            ============
            |  Task-A  |
            ============
                       |
                       V
                       ============
                       |  Task-B  |
                       ============
Figure 1: Finish to start relationship
RELTYPE=FINISHTOFINISH:
Task-B can only be completed after Task-A is finished. The related tasks may run in parallel before completion.

For example, in the development of two related pieces of software, e.g. the api and the implementation, the design of the implementation (B) cannot be completed until the design of the api (A) has been completed.


                    ==================
                    |     Task-A     |--+
                    ==================  |
                                        |
                          ============  |
                          |  Task-B  |<-+
                          ============
Figure 2: Finish to finish relationship
RELTYPE=STARTTOFINISH:

The start of Task-A (which occurs after Task-B) controls the finish of Task-B. For example, ticket sales (Task-B) end after the game starts (Task-A).


                           ============
                        +--|  Task-A  |
                        |  ============
                        +---------+
                    ============  |
                    |  Task-B  |<-+
                    ============
Figure 3: Start to finish relationship
RELTYPE=STARTTOSTART:

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  |
                    ============
Figure 4: Start to start relationship

5. Additional New RELTYPE Parameter Values

This section defines the additional relationships below:

RELTYPE=FIRST:
Indicates that the referenced calendar component is the first in a series the referencing calendar component is part of.
RELTYPE=NEXT:
Indicates that the referenced calendar component is the next in a series the referencing calendar component is part of.
RELTYPE=DEPENDS-ON:
Indicates that the current calendar component depends on the referenced calendar component in some manner. For example a task may be blocked waiting on the other, referenced, task.
RELTYPE=REFID:
Establishes a reference from the current component to components with a REFID property which matches the value given in the associated RELATED-TO property.
RELTYPE=CONCEPT:
Establishes a reference from the current component to components with a CONCEPT property which matches the value given in the associated RELATED-TO property.

Note that the relationship types of PARENT, CHILD and SIBLING establish a hierarchical relationship. The new types of FIRST and NEXT are an ordering relationship.

6. New Property Parameters

Parameter name:
LINKREL
Purpose:
To specify the relationship of data referenced by a LINK property.
Format Definition:

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
Description:
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. There is no default relation type.
In addition to the value defined here any link relation in the link registry established by [RFC8288], or new link relations, may be used.
It is expected that link relation types seeing significant usage in calendaring will have the calendaring usage described in an RFC.
LINKREL=SOURCE:
identifies the source of the event information.
Registration:
These relation types are registered in [RFC8288]

6.2. Gap

Parameter name:
GAP
Purpose:
To specify the length of the gap, positive or negative, between two components with a temporal relationship.
Format Definition:

This parameter is defined by the following notation where dur-value is defined in section 3.3.6 of [RFC5545]. :

  gapparam      = "GAP" "=" dur-value
Description:
This parameter MAY be specified on the RELATED-TO property, and defines the duration of time between the predecessor and successor in an interval. When positive it defines the lag time between a task and its logical successor. When negative it defines the lead time.

An example of lag time might be if task A is "paint the room" and task B is "lay the carpets" then task A may be related to task B with RELTYPE=FINISHTOSTART with a gap of 1 day - long enough for the paint to dry.


            ====================
            |  Paint the room  |--+
            ====================  |
                                  |(lag of one day)
                                  |
                                  |  ===============
                                  +->| lay carpet  |
                                     ===============
Figure 5: Finish to start relationship with lag

For an example of lead time, in constructing a two storey building the electrical work must be done before painting. However the painter can move in to the first floor as the electricians move upstairs.


            =====================
            |  Electrical work  |--+
            =====================  |
                     +-------------+
                     |(lead of estimated time)
                     |  ==================
                     +->|    Painting    |
                        ==================
Figure 6: Finish to start relationship with lead

7. New Value Data Types

This specification defines the following new value types to be used with the VALUE property parameter:

UID
VALUE=UID indicates that the associated value is the UID for a component.
XML-REFERENCE
VALUE=XML-REFERENCE indicates that the associated value references an associated XML artifact and is a URI with an XPointer anchor value. The XPointer is defined in [W3C.WD-xptr-xpointer-20021219] and its use as an anchor is defined in [W3C.REC-xptr-framework-20030325].

8. New Properties

8.1. Concept

Property name:
CONCEPT
Purpose:
This property defines the formal categories for a calendar component.
Value type:
URI
Property Parameters:
IANA, and non-standard parameters can be specified on this property.
Conformance:
This property can be specified zero or more times in any iCalendar component.
Description:
This property is used to specify formal categories or classifications of the calendar component. The values are useful in searching for a calendar component of a particular type and category.
This categorization is distinct from the more informal "tagging" of components provided by the existing CATEGORIES property. It is expected that the value of the CONCEPT property will reference an external resource which provides information about the categorization.
In addition, a structured URI value allows for hierarchical categorization of events.
Possible category resources are the various proprietary systems, for example Library of Congress, or an open source of categorisation data.
Format Definition:

This property is defined by the following notation:

  concept        =  "CONCEPT" conceptparam ":"
                        uri CRLF

  conceptparam = *(";" other-param)
Example:

The following is an example of this property. It points to a server acting as the source for the calendar object.

  CONCEPT:https://example.com/event-types/arts/music

8.3. Refid

Property name:
REFID
Purpose:
This property value acts as a key for associated iCalendar entities.
Value type:
TEXT
Property Parameters:
Non-standard parameters can be specified on this property.
Conformance:
This property can be specified zero or more times in any iCalendar component.
Description:
The value of this property is free-form text that creates an identifier for associated components. All components that use the same REFID value are associated through that value and can be located or retrieved as a group. For example, all of the events in a travel itinerary would have the same REFID value, so as to be grouped together.
Format Definition:

This property is defined by the following notation:

  refid      = "REFID" refidparam ":" text CRLF


  refidparam      = *(";" other-param)
The current link registry
Example:

The following is an example of this property.

  REFID:itinerary-2014-11-17

9. Updates to RFC 5545

This specification updates the RELATED-TO property defined in Section 3.8.4.5 of [RFC5545]. The contents of Section 9.1 replace that section.

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.

10. Security Considerations

All of the security considerations of section 7 pf [RFC5545] apply to this specification.

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 an XML-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.

Extremely large values for the GAP parameter may lead to unexpected behavior.

11. IANA Considerations

11.1. iCalendar Property Registrations

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.

Table 1
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

11.2. iCalendar Property Parameter Registrations

The following iCalendar property parameter names have been added to the iCalendar Parameters Registry defined in Section 8.3.3 of [RFC5545].

Table 2
Parameter Status Reference
GAP Current Section 6.2
LINKREL Current Section 6.1

11.3. iCalendar Value Data Type Registrations

The following iCalendar property parameter names have been added to the iCalendar Value Data Types Registry defined in Section 8.3.4 of [RFC5545].

Table 3
Value Data Type Status Reference
XML-REFERENCE Current Section 7
UID Current Section 7

11.4. iCalendar RELTYPE Value Registrations

The following iCalendar "RELTYPE" values have been added to the iCalendar Relationship Types Registry defined in Section 8.3.8 of [RFC5545].

Table 4
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
NEXT Current Section 5
REFID Current Section 5
STARTTOFINISH Current Section 4
STARTTOSTART Current Section 4

11.5. New Reference Type Registration

The following link relation values have been added to the Reference Types Registry defined in Section 6.2.2 of [RFC8288].

Table 5
Name Status Reference
SOURCE Current Section 6.1

12. Acknowledgements

The author would like to thank the members of CalConnect, 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.

13. References

13.1. Informative References

[RFC4791]
Daboo, C., Desruisseaux, B., and L. Dusseault, "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, DOI 10.17487/RFC4791, , <https://www.rfc-editor.org/info/rfc4791>.
[RFC8607]
Daboo, C., Quillaud, A., and K. Murchison, Ed., "Calendaring Extensions to WebDAV (CalDAV): Managed Attachments", RFC 8607, DOI 10.17487/RFC8607, , <https://www.rfc-editor.org/info/rfc8607>.

13.2. Normative References

[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>.
[RFC4918]
Dusseault, L., Ed., "HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)", RFC 4918, DOI 10.17487/RFC4918, , <https://www.rfc-editor.org/info/rfc4918>.
[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>.
[RFC7986]
Daboo, C., "New Properties for iCalendar", RFC 7986, DOI 10.17487/RFC7986, , <https://www.rfc-editor.org/info/rfc7986>.
[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>.
[RFC8288]
Nottingham, M., "Web Linking", RFC 8288, DOI 10.17487/RFC8288, , <https://www.rfc-editor.org/info/rfc8288>.
[W3C.REC-skos-reference-20090818]
Miles, A. and S. Bechhofer, "SKOS Simple Knowledge Organization System Reference", World Wide Web Consortium Recommendation REC-skos-reference-20090818, , <https://www.w3.org/TR/2009/REC-skos-reference-20090818>.
[W3C.REC-xptr-framework-20030325]
Grosso, P., Maler, E., Marsh, J., and N. Walsh, "XPointer Framework", World Wide Web Consortium Recommendation REC-xptr-framework-20030325, , <https://www.w3.org/TR/2003/REC-xptr-framework-20030325>.
[W3C.WD-xptr-xpointer-20021219]
DeRose, S., Daniel, R., and E. Maler, "XPointer xpointer() Scheme", World Wide Web Consortium WD WD-xptr-xpointer-20021219, , <http://www.w3.org/TR/2002/WD-xptr-xpointer-20021219>.

Author's Address

Michael Douglass
Bedework
226 3rd Street
Troy, NY 12180
United States of America
URI: https://bedework.com