| Network Working Group | M. Douglass |
| Internet-Draft | Spherical Cow Group |
| Updates: 5545 (if approved) | October 30, 2019 |
| Intended status: Standards Track | |
| Expires: May 2, 2020 |
Support for Series in iCalendar
draft-ietf-calext-icalendar-series-00
This specification updates [RFC5545] by defining a new repeating set of events known as a series. This differs from recurrences in that each instance is a separate entity with a parent relationship to a specified template entity.
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 May 2, 2020.
Copyright (c) 2019 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 Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
Since iCalendar was first defined there has been only one standard way to express a repeating set of events - the recurrence. This defined a master event, a set of rules for computing the instances and a way of overriding certain instances.
This approach works well enough in certain situations but has many problems which need to be addressed.
This specification introduces a new approach to repeating patterns of entities which avoids some of the problems.
The recurrence rules specify how instances are to be computed. These rules provide a set of keys - the RECURRENCE-IDs - and an instance can be created with the calculated start date/time and a copy of the duration (or calculated end date/time).
The specification allows for overrides. These are handled by supplying a complete replacement for the instance with a RECURRENCE-ID property matching that of the instance being overridden. This may change any of the properties (except the UID) - including start, end or duration.
If a long lived recurrence is heavily overridden it becomes very cumbersome. The master plus overrides is considered a single resource in most circumstances (however iTip allows the delivery of a single instance in certain situations).
Simple meetings can become heavily modifed recurrences through adding the weeks agenda to the description, changing of attendees etc.
There are approaches being considered to mitigate some of these issues which mostly involve only storing differences. Depending on the actual changes this may be more or less succesful. However recurrences are still awkward to deal with.
This can lead to some very difficult problems to resolve. In the case of a heavily modified meeting it may be difficult to impossible to determine which override applies to the newly modified event.
For example, a weekly book-reading is moved from Monday to Friday. There are weeks of scheduled events in the future. Do we move them all forward to the next instance or skip one and move them back? If it becomes bi-weekly rather than weekly do we drop every other or just space them out more?
To be sure - some of these problems are not totally resolved by a series approach but they become more tractable. An approach on how to mitigate these problems is defined later on in this specification.
The [RFC5545] THISANDFUTURE range is poorly supported. Splitting is what a number of implementations use to avoid changing overrrides in the past.
The recurring event is split into 2, one being the truncated original the other being a new recurring event starting at the time of the THISANDFUTURE override.
There is left the problem of relating the two, this can be accomplished by use of the RELATED-TO property but that is not standardized.
A series is a, generally regularly, repeating sets of events or tasks each instance of which is usually, but not always, different in some respect. Examples may be a library running an after-school reading program which usually, takes place at the same time each week but always differs in the book or author being studied.
In recurrences an instances is a calculated 'virtual' object, unless overridden. It has the same UID as the master and a RECURRENCE-ID which is always one of the calculated set.
In a series, a specified number of instances are created ahead of time each with their own unique UID. They are all related to the master using a SERIES-MASTER relation type defined in this specification. Each instance acts as an individual component as far as retrieval and searching is concerned.
Each instance and master is identified as a member of the full series by the SERIES-UID property. The value of this property is the same in all members of the series even when splits have occurred.
As instances are created a LAST-SERIES-ID property is added or updated in the master to indicate which instance was last created. When there are SXDATE properties this property value may represent an instance which cannot be created. It merely represents the latest calculated date.
This property allows generated instances to be deleted without the addition of SXDATE properties to the master. The SXDATE only indicates future instances which MUST NOT be created.
As time goes on more instances are created either by the server or by a client when it inspects the current state of the series. The number of instances may be based on time or a count.
For example, an organization may allow rooms to be booked only 4 weeks ahead. Thus a series may be set up which has that 4 week set of events in the future. Each will have the room as an attendee ensuring that at least the room is booked at the regular time.
This does not prevent a client or server from creating dummy events out into the future as a guide for people managing their calendars. The application or server merely has to ensure that those dummy events are marked as such and are read-only.
To facilitate this there is a new SITEM-STATUS property which may be used to mark such an instance.
If it becomes necessary to modify the series rules or the master start then the series is always split at the point of the modification.
When a series is split the previous master is modifed to truncate the current series at the last generated instance and a parameter SPLIT=YES is added to the series rule to indicate that this master is now split.
The split may result in a number of instances related to the old series but overlapping the new. It is up to the implementation to decide what should be done with these but this usually requires a degree of interaction with a human (or very intelligent robot). The application may offer to copy them into the corresponding new instances - if these can be easily determined, offer to delete all of them or let the user manually copy information and delete.
The new series master is related to the old master by the new series master having a RELATED-TO property with RELTYPE=SERIES-MASTER pointing at the previous master. In that way a backwards chain of series masters may be created
A series master is identified in much the same way as a recurrence master. It will contain an SRULE and 0 or more SDATE properties or 1 or more SDATE properties. Additionally it may contain 0 or more SXDATE properties to exclude instances.
As noted above, if the series was split it may contain a RELATED-TO property with RELTYPE=SERIES-MASTER and a value of the previous series master.
The master will also contain a LAST-SERIES-ID if any instances have been calculated and perhaps generated.
It is important to note that the series master is NOT a member of the series. This makes it easier for services to filter out series masters.
A series instance is identified by having a SERIES-ID property which is calculated in the same manner as a RECURRENCE-ID. It MUST also contain a RELATED-TO property with RELTYPE=SERIES-MASTER and a value being the UID of the series master.
As noted above, if the series was split it may contain a RELATED-TO property with RELTYPE=SERIES-MASTER and a value being the UID of the previous series master.
Relationship parameter type values are defined in section 3.2.15. of [RFC5545]. This specification augments that parameter to include the new relationship values SERIES-MASTER
This property parameter is respecified as follows:
reltypeparam = "RELTYPE" "="
("PARENT" ; Parent relationship - Default
/ "CHILD" ; Child relationship
/ "SIBLING" ; Sibling relationship
/ "DEPENDS-ON" ; refers to previous task
/ "REFID" ; Relationship based on REFID
/ "STRUCTURED-CATEGORY"
; Relationship based on STRUCTURED-CATEGORY
/ "FINISHTOSTART" ; Temporal relationship
/ "FINISHTOFINISH" ; Temporal relationship
/ "STARTTOFINISH" ; Temporal relationship
/ "STARTTOSTART" ; Temporal relationship
/ "SERIES-MASTER" ; link to the master component
/ iana-token ; Some other IANA-registered
; iCalendar relationship type
/ x-name) ; A non-standard, experimental
; relationship type
============
| Task-A |--+
============ |
|
V
============
| Task-B |
============
Figure 1: Finish to start relationship
============
| Task-A |--+
============ |
|
============ |
| Task-B |<-+
============
Figure 2: Finish to finish relationship
============
+--| Task-A |
| ============
|
============ |
| Task-B |<-+
============
Figure 3: Start to finish relationship
============
+--| Task-A |
| ============
|
| ============
+->| Task-B |
============
Figure 4: Start to start relationship
This parameter is defined by the following notation:
splitparam = "SPLIT" "="
("YES" ; The series is split
/ "NO" ; The series is not split (default)
/ x-name ; Experimental reference type
/ iana-token) ; Other IANA registered type
This parameter is defined by the following notation:
lookahead-countparam = "LOOKAHEAD-COUNT" "=" 1*DIGIT
This parameter is defined by the following notation:
lookahead-periodparam = "LOOKAHEAD-PERIOD" "="
DQUOTE dur-value DQUOTE
The SERIES-ID, LAST-SERIES-ID, SDATE and SXDATE properties are identical in form and in the parameters they take.
All must conform in form to the DTSTART property of the master component. Only the SDATE may specify a time which is not part of the calculated series.
The SRULE property value is identical in form to the RRULE property defined in [RFC5545]. The LOOKAHEAD-COUNT and LOOKAHEAD-PERIOD parameters indicate how many instances should be generated in advance.
An agent, either the server or a client, will periodically extend the set of instances. The number of such generated instances is limited by:
The starting point for the calculation is the DTSTART of the master component or the LAST-SERIES-ID if it exists in the master. In both cases the instance represented by that date is NOT generated as part of the intance set and the actual instance may have been excluded by an SXDATE property but the starting date is still valid.
The starting date/time property defines the first instance in the next batch of series members. Note that the starting property value MUST match the pattern of the series rule, if specified. For example, if the rule specifies every Wednesday the starting date MUST be a Wednesday.
The end date/time of the set will be provided by the UNTIL part of the rule, the LOOKAHEAD-PERIOD or by a system maxima.
A set of date/time values can be generated within those contraints. As each date/time value is generated it can be ignored if it is one of the SXDATE values.
Generation of values can terminate when the size of the result exceeds that given by the COUNT rule element, the LOOKAHEAD-COUNT value or any systm limit.
Any SDATE values that fall within the current range and are not in the set of SXDATE values can be added and the result truncated again to match the size limits.
Finally, any date/time values that have already been generated and are present as SERIES-ID values should be removed from the set. What remains is the new set of members to extend the current series.
The last of those values becomes the new value for the LAST-SERIES-ID property in the series master.
As noted above the "SXDATE" property can be used to exclude the value specified in the master. This leads to a complication as the master needs to be preserved as a container for the values which define the series. This is flagged by adding a DELETED-MASTER element to the SERIES-STATUS property.
This property is defined by the following notation:
seruid = "SERIES-UID" seruidparam ":" text CRLF
seruidparam = *(";" other-param)
The following is an example of this property:
SERIES-UID:123e4567-e89b-12d3-a456-426655440000
This property is defined by the following notation:
sxdate = "SXDATE" sxdtparam ":" sxdtval *("," sxdtval) CRLF
sxdtparam = *(
;
; The following are OPTIONAL,
; but MUST NOT occur more than once.
;
(";" "VALUE" "=" ("DATE-TIME" / "DATE")) /
;
(";" tzidparam) /
;
; The following is OPTIONAL,
; and MAY occur more than once.
;
(";" other-param)
;
)
sxdtval = date-time / date
;Value MUST match value type
The following is an example of this property:
SXDATE:19960402T010000Z,19960403T010000Z,19960404T010000Z
This property is defined by the following notation:
sdate = "SDATE" sdtparam ":" sdtval *("," sdtval) CRLF
sdtparam = *(
;
; The following are OPTIONAL,
; but MUST NOT occur more than once.
;
(";" "VALUE" "=" ("DATE-TIME" / "DATE" / "PERIOD")) /
(";" tzidparam) /
;
; The following is OPTIONAL,
; and MAY occur more than once.
;
(";" other-param)
;
)
sdtval = date-time / date
;Value MUST match value type
The following are examples of this property:
SDATE:19970714T123000Z
SDATE;TZID=America/New_York:19970714T083000
SDATE;VALUE=PERIOD:19960403T020000Z/19960403T040000Z,
19960404T010000Z/PT3H
SDATE;VALUE=DATE:19970101,19970120,19970217,19970421
19970526,19970704,19970901,19971014,19971128,19971129,19971225
This property is defined by the following notation:
serid = "SERIES-ID" sidparam ":" sidval CRLF
sidparam = *(
;
; The following are OPTIONAL,
; but MUST NOT occur more than once.
;
(";" "VALUE" "=" ("DATE-TIME" / "DATE")) /
(";" tzidparam) /
;
; The following is OPTIONAL,
; and MAY occur more than once.
;
(";" other-param)
;
)
sidval = date-time / date
;Value MUST match value type
The following are examples of this property:
SERIES-ID;VALUE=DATE:19960401
SERIES-ID;TZID=America/New_York:20170120T120000
This property is defined by the following notation:
last-series-i = "LAST-SERIES-ID" lastseriesidparam /
(
";" "VALUE" "=" "TEXT"
":" text
)
(
";" "VALUE" "=" "REFERENCE"
":" text
)
(
";" "VALUE" "=" "URI"
":" uri
)
CRLF
lastseriesidparam = *(
; the following is MANDATORY
; and MAY occur more than once
(";" relparam) /
; the following are MANDATORY
; but MUST NOT occur more than once
(";" fmttypeparam) /
(";" labelparam) /
; labelparam is defined in ...
; 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 calendar object.
LINK;REL=SOURCE;LABEL=The Egg:http://example.com/events
This property is defined by the following notation:
srule = "SRULE" srulparam ":" recur CRLF
sruleparam = *(
; the following are OPTIONAL
; but MUST NOT occur more than once
(";" lookahead-countparam) /
(";" lookahead-periodparam) /
; the following is OPTIONAL
; and MAY occur more than once
(";" xparam)
)
This property is defined by the following notation:
sitem-status = "SITEM-STATUS" sisparam ":" SISvalue CRLF
sisparam = *(";" other-param)
sisvalue = "DUMMY" ; This item is generated as an indication of where
; an item might appear when it is generated
/ iana-token
/ x-name
The following is an example of this property.
SITEM-STATUS:DUMMY
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;RELTYPE=SERIES-MASTER:19960401-080045-4000F192713
Any clients following the approach specified in [RFC5545] are expected to ignore any properties, parameters or components they don't recognize.
For such clients the series appears to be an unconnected set of components. They all have their own unique UIDS. If the client updates an instance this should be identical in effect to an update carried out by a client aware of the new properties.
Updates MUST preserve the SERIES-ID, LAST-SERIES-ID, SRULE, SDATE and SXDATE properties. A client which does not do so is in violation of [RFC5545].
There are two possible problem areas: first we must prevent series unaware clients from updating the masters and secondly we must prevent attempts to update dummy instances.
Both case are handled by the definition of a new header field : "ICAL-SERIES". The presence of this header field in requests from a client indicates that it is aware of this specification. In the absence of the header servers MUST NOT send master template items.
In the case of an absent header servers MUST refuse to accept updates to dummy items - e.g. with an HTTP forbidden status in CalDAV.
This specification may extend Caldav by adding reports to return all members of a series given the series master UID. This could be handled by the current query mechanism but it is likely to be sufficiently frequently used that a special query is appropriate.
It is also likely we will want a CalDAV operation to split a series and generate the additional members of the series as a single atomic operation.
Clients and servers should take care to limit the number of generated instances to a reasonable value. This can be a relatively small value.
The following iCalendar property names have been added to the iCalendar Properties Registry defined in Section 8.3.2 of [RFC5545]
| Property | Status | Reference |
|---|---|---|
| LAST-SERIES-ID | Current | Section 6.6 |
| SERIES-ID | Current | Section 6.5 |
| SERIES-UID | Current | Section 6.2 |
| SDATE | Current | Section 6.4 |
| SRULE | Current | Section 6.7 |
| SXDATE | Current | Section 6.3 |
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 |
|---|---|---|
| LOOKAHEAD-COUNT | Current | Section 5.2 |
| LOOKAHEAD-PERIOD | Current | Section 5.3 |
| SPLIT | Current | Section 5.1 |
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 |
|---|---|---|
| SERIES-ID | Current | Section 4 |
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:
The author would also like to thank the Calendaring and Scheduling Consortium for advice with this specification.
| [I-D.daboo-caldav-attachments] | Daboo, C. and A. Quillaud, "CalDAV Managed Attachments", Internet-Draft draft-daboo-caldav-attachments-03, February 2014. |
| [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. |
| [RFC5545] | Desruisseaux, B., "Internet Calendaring and Scheduling Core Object Specification (iCalendar)", RFC 5545, DOI 10.17487/RFC5545, September 2009. |
| [RFC5988] | Nottingham, M., "Web Linking", RFC 5988, DOI 10.17487/RFC5988, October 2010. |
| [RFC7986] | Daboo, C., "New Properties for iCalendar", RFC 7986, DOI 10.17487/RFC7986, October 2016. |
| [W3C.REC-xml-20060816] | Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E. and F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fourth Edition)", World Wide Web Consortium Recommendation REC-xml-20060816, August 2006. |
| [W3C.WD-xptr-xpointer-20021219] | DeRose, S., Daniel, R. and E. Maler, "XPointer xpointer() Scheme", World Wide Web Consortium WD WD-xptr-xpointer-20021219, December 2002. |
2018-01-01 MD Better descriptions - LAST-SESSION-ID.
2017-09-30 MD Minor updates: better backward compatibility.
2017-02-12 MD Initial version