draft-ietf-calext-icalendar-series-01.txt   draft-ietf-calext-icalendar-series-02.txt 
Network Working Group M. Douglass Network Working Group M. Douglass
Internet-Draft Bedework Internet-Draft 14 October 2020
Updates: 5545 (if approved) July 28, 2020
Intended status: Standards Track Intended status: Standards Track
Expires: January 29, 2021 Expires: 17 April 2021
Support for Series in iCalendar Support for Series in iCalendar
draft-ietf-calext-icalendar-series-01 draft-ietf-calext-icalendar-series-02
Abstract Abstract
This specification updates [RFC5545] by defining a new repeating set This document updates [RFC5545] by defining a new repeating set of
of events known as a series. This differs from recurrences in that events known as a series. This differs from recurrences in that each
each instance is a separate entity with a parent relationship to a instance is a separate entity with a parent relationship to a
specified template entity. specified template entity.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on January 29, 2021. This Internet-Draft will expire on 17 April 2021.
Copyright Notice Copyright Notice
Copyright (c) 2020 IETF Trust and the persons identified as the Copyright (c) 2020 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents (https://trustee.ietf.org/
(https://trustee.ietf.org/license-info) in effect on the date of license-info) in effect on the date of publication of this document.
publication of this document. Please review these documents Please review these documents carefully, as they describe your rights
carefully, as they describe your rights and restrictions with respect and restrictions with respect to this document. Code Components
to this document. Code Components extracted from this document must extracted from this document must include Simplified BSD License text
include Simplified BSD License text as described in Section 4.e of as described in Section 4.e of the Trust Legal Provisions and are
the Trust Legal Provisions and are provided without warranty as provided without warranty as described in the Simplified BSD License.
described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 2
2. Overrides and iCalendar recurrences . . . . . . . . . . . . . 3 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2.1. Changing the master start or the recurrence rules . . . . 3 3. Terms and definitions . . . . . . . . . . . . . . . . . . . . 3
2.2. Splitting recurrences . . . . . . . . . . . . . . . . . . 4 4. Overrides and iCalendar recurrences . . . . . . . . . . . . . 3
3. Series . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 4.1. Changing the master start or the recurrence rules . . . . 3
3.1. Modifying series patterns and splitting . . . . . . . . . 5 4.2. Splitting recurrences . . . . . . . . . . . . . . . . . . 4
3.2. The series master . . . . . . . . . . . . . . . . . . . . 5 5. Series . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
3.3. The series instances . . . . . . . . . . . . . . . . . . 6 5.1. Modifying series patterns and splitting . . . . . . . . . 5
4. Redefined Relation Type Value . . . . . . . . . . . . . . . . 6 5.2. The series master . . . . . . . . . . . . . . . . . . . . 6
5. New Property Parameters . . . . . . . . . . . . . . . . . . . 9 5.3. The series instances . . . . . . . . . . . . . . . . . . 6
5.1. Split . . . . . . . . . . . . . . . . . . . . . . . . . . 9 6. Redefined Relation Type Value . . . . . . . . . . . . . . . . 6
5.2. Lookahead count . . . . . . . . . . . . . . . . . . . . . 10 7. New Property Parameters . . . . . . . . . . . . . . . . . . . 9
5.3. Lookahead period . . . . . . . . . . . . . . . . . . . . 10 7.1. Split . . . . . . . . . . . . . . . . . . . . . . . . . . 9
6. New Properties . . . . . . . . . . . . . . . . . . . . . . . 11 7.2. Lookahead count . . . . . . . . . . . . . . . . . . . . . 10
6.1. Generating Series members . . . . . . . . . . . . . . . . 11 7.3. Lookahead period . . . . . . . . . . . . . . . . . . . . 10
6.2. Series UID . . . . . . . . . . . . . . . . . . . . . . . 12 8. New Properties . . . . . . . . . . . . . . . . . . . . . . . 11
6.3. Series-exception-date . . . . . . . . . . . . . . . . . . 13 8.1. General . . . . . . . . . . . . . . . . . . . . . . . . . 11
6.4. Series-date . . . . . . . . . . . . . . . . . . . . . . . 14 8.2. Generating Series members . . . . . . . . . . . . . . . . 11
6.5. Series-id . . . . . . . . . . . . . . . . . . . . . . . . 16 8.3. Series UID . . . . . . . . . . . . . . . . . . . . . . . 13
6.6. Last series id . . . . . . . . . . . . . . . . . . . . . 17 8.4. Series-exception-date . . . . . . . . . . . . . . . . . . 13
6.7. Series Rule . . . . . . . . . . . . . . . . . . . . . . . 19 8.5. Series-date . . . . . . . . . . . . . . . . . . . . . . . 15
6.8. SITEM-STATUS Property . . . . . . . . . . . . . . . . . . 21 8.6. Series-id . . . . . . . . . . . . . . . . . . . . . . . . 16
7. Redefined RELATED-TO Property . . . . . . . . . . . . . . . . 21 8.7. Last series ID . . . . . . . . . . . . . . . . . . . . . 18
7.1. RELATED-TO . . . . . . . . . . . . . . . . . . . . . . . 21 8.8. Series Rule . . . . . . . . . . . . . . . . . . . . . . . 21
8. Backwards compatibility . . . . . . . . . . . . . . . . . . . 23 9. Redefined RELATED-TO Property . . . . . . . . . . . . . . . . 22
9. CalDAV extensions . . . . . . . . . . . . . . . . . . . . . . 24 9.1. RELATED-TO . . . . . . . . . . . . . . . . . . . . . . . 22
10. Security Considerations . . . . . . . . . . . . . . . . . . . 24 10. Backwards compatibility . . . . . . . . . . . . . . . . . . . 24
11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24 11. CalDAV extensions . . . . . . . . . . . . . . . . . . . . . . 25
11.1. iCalendar Property Registrations . . . . . . . . . . . . 24 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25
11.2. iCalendar Property Parameter Registrations . . . . . . . 25 12.1. iCalendar Property Registrations . . . . . . . . . . . . 25
11.3. iCalendar RELTYPE Value Registrations . . . . . . . . . 25 12.2. iCalendar Property Parameter Registrations . . . . . . . 26
12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 25 12.3. iCalendar RELTYPE Value Registrations . . . . . . . . . 26
13. Normative References . . . . . . . . . . . . . . . . . . . . 26 13. Normative references . . . . . . . . . . . . . . . . . . . . 26
Appendix A. Points for discussion . . . . . . . . . . . . . . . 26 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 26
Appendix B. Change log . . . . . . . . . . . . . . . . . . . . . 27
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 27
1. Introduction 1. Acknowledgements
Since iCalendar was first defined there has been only one standard The authors would like to thank the members of the Calendaring and
way to express a repeating set of events - the recurrence. This Scheduling Consortium (CalConnect) for contributing their ideas and
defined a master event, a set of rules for computing the instances support.
and a way of overriding certain instances.
2. Introduction
Since iCalendar was first defined there has been only one 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 This approach works well enough in certain situations but has many
problems which need to be addressed. problems which need to be addressed.
This specification introduces a new approach to repeating patterns of This specification introduces a new approach to repeating patterns of
entities which avoids some of the problems. entities which avoids some of the problems.
2. Overrides and iCalendar recurrences 3. Terms and definitions
No terms and definitions are listed in this document.
4. Overrides and iCalendar recurrences
The recurrence rules specify how instances are to be computed. These The recurrence rules specify how instances are to be computed. These
rules provide a set of keys - the RECURRENCE-IDs - and an instance rules provide a set of keys - the RECURRENCE-ID - and an instance can
can be created with the calculated start date/time and a copy of the be created with the calculated start date/time and a copy of the
duration (or calculated end date/time). duration (or calculated end date/time).
The specification allows for overrides. These are handled by The specification allows for overrides. These are handled by
supplying a complete replacement for the instance with a RECURRENCE- supplying a complete replacement for the instance with a RECURRENCE-
ID property matching that of the instance being overridden. This may ID property matching that of the instance being overridden. This may
change any of the properties (except the UID) - including start, end change any of the properties (except the UID) - including start, end
or duration. or duration.
If a long lived recurrence is heavily overridden it becomes very If a long lived recurrence is heavily overridden it becomes very
cumbersome. The master plus overrides is considered a single cumbersome. The master plus overrides is considered a single
resource in most circumstances (however iTip allows the delivery of a resource in most circumstances (iTip allows the delivery of a single
single instance in certain situations). instance in certain situations).
Simple meetings can become heavily modifed recurrences through adding Simple meetings can become heavily modified recurrences through
the weeks agenda to the description, changing of attendees etc. adding the weeks agenda to the description, changing of attendees
etc.
There are approaches being considered to mitigate some of these There are approaches being considered to mitigate some of these
issues which mostly involve only storing differences. Depending on issues which mostly involve only storing changes but recurrences are
the actual changes this may be more or less succesful. However still awkward to deal with.
recurrences are still awkward to deal with.
2.1. Changing the master start or the recurrence rules 4.1. Changing the master start or the recurrence rules
This can lead to some very difficult problems to resolve. In the This can lead to some very difficult problems to resolve. In the
case of a heavily modified meeting it may be difficult to impossible case of a heavily modified meeting it may be difficult to impossible
to determine which override applies to the newly modified event. to determine which override applies to the newly modified event.
For example, a weekly book-reading is moved from Monday to Friday. 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 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 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 it becomes bi-weekly rather than weekly do we drop every other or
just space them out more? just space them out more?
To be sure - some of these problems are not totally resolved by a To be sure - some of these problems are not totally resolved by a
series approach but they become more tractable. An approach on how series approach but they become more tractable.
to mitigate these problems is defined later on in this specification.
2.2. Splitting recurrences 4.2. Splitting recurrences
The [RFC5545] THISANDFUTURE range is poorly supported. Splitting is The [RFC5545] THISANDFUTURE range is poorly supported. Splitting is
what a number of implementations use to avoid changing overrrides in what a number of implementations use to avoid changing overrides in
the past. the past.
The recurring event is split into 2, one being the truncated original 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 the other being a new recurring event starting at the time of the
THISANDFUTURE override. THISANDFUTURE override.
There is left the problem of relating the two, this can be There is left the problem of relating the two, this can be
accomplished by use of the RELATED-TO property but that is not accomplished by use of the RELATED-TO property but that is not
standardized. standardized.
3. Series 5. Series
A series is a, generally regularly, repeating sets of events or tasks A series is a, generally regularly, repeating sets of events or tasks
each instance of which is usually, but not always, different in some each instance of which is usually, but not always, different in some
respect. Examples may be a library running an after-school reading respect. Examples may be a library running an after-school reading
program which usually, takes place at the same time each week but program which usually, takes place at the same time each week but
always differs in the book or author being studied. always differs in the book or author being studied.
In recurrences an instances is a calculated 'virtual' object, unless In recurrences an instances is a calculated 'virtual' object, unless
overridden. It has the same UID as the master and a RECURRENCE-ID overridden. It has the same UID as the master and a RECURRENCE-ID
which is always one of the calculated set. which is always one of the calculated set.
skipping to change at page 5, line 14 skipping to change at page 5, line 24
As time goes on more instances are created either by the server or by 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 a client when it inspects the current state of the series. The
number of instances may be based on time or a count. number of instances may be based on time or a count.
For example, an organization may allow rooms to be booked only 4 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 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 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. ensuring that at least the room is booked at the regular time.
This does not prevent a client or server from creating dummy events 5.1. Modifying series patterns and splitting
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.
3.1. Modifying series patterns and splitting
If it becomes necessary to modify the series rules or the master If it becomes necessary to modify the series rules or the master
start then the series is always split at the point of the start then the series is always split at the point of the
modification. modification.
When a series is split the previous master is modifed to truncate the When a series is split the previous master is modifed to truncate the
current series at the last generated instance and a parameter current series at the last generated instance and a parameter
SPLIT=YES is added to the series rule to indicate that this master is SPLIT=YES is added to the series rule to indicate that this master is
now split. now split.
skipping to change at page 5, line 46 skipping to change at page 6, line 5
degree of interaction with a human (or very intelligent robot). The degree of interaction with a human (or very intelligent robot). The
application may offer to copy them into the corresponding new application may offer to copy them into the corresponding new
instances - if these can be easily determined, offer to delete all of instances - if these can be easily determined, offer to delete all of
them or let the user manually copy information and delete. them or let the user manually copy information and delete.
The new series master is related to the old master by the new series The new series master is related to the old master by the new series
master having a RELATED-TO property with RELTYPE=SERIES-MASTER master having a RELATED-TO property with RELTYPE=SERIES-MASTER
pointing at the previous master. In that way a backwards chain of pointing at the previous master. In that way a backwards chain of
series masters may be created series masters may be created
3.2. The series master 5.2. The series master
A series master is identified in much the same way as a recurrence 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 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 or more SDATE properties. Additionally it may contain 0 or more
SXDATE properties to exclude instances. SXDATE properties to exclude instances.
As noted above, if the series was split it may contain a RELATED-TO 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 property with RELTYPE=SERIES-MASTER and a value of the previous
series master. series master.
The master will also contain a LAST-SERIES-ID if any instances have The master will also contain a LAST-SERIES-ID if any instances have
been calculated and perhaps generated. been calculated and perhaps generated.
It is important to note that the series master is NOT a member of the It is important to note that the series master is the first member of
series. This makes it easier for services to filter out series the series. Thus the first instance always occurs AFTER the series
masters. master.
3.3. The series instances 5.3. The series instances
A series instance is identified by having a SERIES-ID property which 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 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 contain a RELATED-TO property with RELTYPE=SERIES-MASTER and a value
being the UID of the series master. being the UID of the series master.
As noted above, if the series was split it may contain a RELATED-TO 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 property with RELTYPE=SERIES-MASTER and a value being the UID of the
previous series master. previous series master.
4. Redefined Relation Type Value 6. Redefined Relation Type Value
Relationship parameter type values are defined in section 3.2.15. of Relationship parameter type values are defined in [RFC5545]. This
[RFC5545]. This specification augments that parameter to include the specification augments that parameter to include the new relationship
new relationship values SERIES-MASTER values SERIES-MASTER.
Format Definition: Format Definition
This property parameter is respecified as follows: This property parameter is respecified as follows:
reltypeparam = "RELTYPE" "=" reltypeparam = "RELTYPE" "="
("PARENT" ; Parent relationship - Default ("PARENT" ; Parent relationship - Default
/ "CHILD" ; Child relationship / "CHILD" ; Child relationship
/ "SIBLING" ; Sibling relationship / "SIBLING" ; Sibling relationship
/ "DEPENDS-ON" ; refers to previous task / "DEPENDS-ON" ; refers to previous task
/ "REFID" ; Relationship based on REFID / "REFID" ; Relationship based on REFID
/ "STRUCTURED-CATEGORY" / "STRUCTURED-CATEGORY"
; Relationship based on STRUCTURED-CATEGORY ; Relationship based on STRUCTURED-CATEGORY
/ "FINISHTOSTART" ; Temporal relationship / "FINISHTOSTART" ; Temporal relationship
/ "FINISHTOFINISH" ; Temporal relationship / "FINISHTOFINISH" ; Temporal relationship
/ "STARTTOFINISH" ; Temporal relationship / "STARTTOFINISH" ; Temporal relationship
/ "STARTTOSTART" ; Temporal relationship / "STARTTOSTART" ; Temporal relationship
/ "SERIES-MASTER" ; link to the master component / "SERIES-MASTER" ; link to the master component
/ iana-token ; Some other IANA-registered / iana-token ; Some other IANA-registered
; iCalendar relationship type ; iCalendar relationship type
/ x-name) ; A non-standard, experimental / x-name) ; A non-standard, experimental
; relationship type ; relationship type
Description: This parameter can be specified on a property that Figure 1
references another related calendar component. The parameter may
specify the hierarchical relationship type of the calendar
component referenced by the property when the value is PARENT,
CHILD or SIBLING. 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.
This parameter defines the temporal relationship when the value is Description
one of the project management standard relationships
FINISHTOSTART, FINISHTOFINISH, STARTTOFINISH or STARTTOSTART.
This property will be present in the predecessor entity and will
refer to the successor entity. The GAP parameter 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.
RELTYPE=PARENT: See [RFC5545] section 3.2.15. This parameter can be specified on a property that references another
related calendar component. The parameter may specify the
hierarchical relationship type of the calendar component referenced
by the property when the value is PARENT, CHILD or SIBLING. 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.
RELTYPE=CHILD: See [RFC5545] section 3.2.15. This parameter defines the temporal relationship when the value is
one of the project management standard relationships FINISHTOSTART,
FINISHTOFINISH, STARTTOFINISH or STARTTOSTART. This property will be
present in the predecessor entity and will refer to the successor
entity. The GAP parameter specifies the lead or lag time between the
predecessor and the successor. In the description of each temporal
relationship below we refer toTask-A which contains and controls the
relationship and Task-B the target of the relationship.
RELTYPE=SIBLING: See [RFC5545] section 3.2.15. RELTYPE=PARENT See [RFC5545].
RELTYPE=DEPENDS-ON: Indicates that the current calendar component RELTYPE=CHILD See [RFC5545].
RELTYPE=SIBLING See [RFC5545].
RELTYPE=DEPENDS-ON Indicates that the current calendar component
depends on the referenced calendar component in some manner. For depends on the referenced calendar component in some manner. For
example a task may be blocked waiting on the other, referenced, example a task may be blocked waiting on the other, referenced,
task. task.
RELTYPE=REFID: Establishes a reference from the current component to RELTYPE=REFID Establishes a reference from the current component to
components with a REFID property which matches the value given in components with a REFID property which matches the value given in
the associated RELATED-TO property. the associated RELATED-TO property.
RELTYPE=SERIES-MASTER: Indicates that the current calendar component RELTYPE=SERIES-MASTER Indicates that the current calendar component
is bsed on the referenced calendar component. The value is a UID. is based on the referenced calendar component. The value is a
UID.
RELTYPE=STRUCTURED-CATEGORY: Establishes a reference from the RELTYPE=STRUCTURED-CATEGORY Establishes a reference from the current
current component to components with a STRUCTURED-CATEGORY component to components with a STRUCTURED-CATEGORY property which
property which matches the value given in the associated RELATED- matches the value given in the associated RELATED- TO property.
TO property.
RELTYPE=FINISHTOSTART: Task-B cannot start until Task-A finishes. RELTYPE=FINISHTOSTART
For example, when sanding is complete, painting can begin.
Task-B cannot start until Task-A finishes. For example, when sanding
is complete, painting can begin.
============ ============
| Task-A |--+ | Task-A |--+
============ | ============ |
| |
V V
============ ============
| Task-B | | Task-B |
============ ============
Figure 1: Finish to start relationship Figure 2: Finish to start relationship
RELTYPE=FINISHTOFINISH: Task-B cannot finish before Task-A is RELTYPE=FINISHTOFINISH
finished, that is the end of Task-A defines the end of Task-B.
For example, we start the potatoes, then the meat then the peas Task-B cannot finish before Task-A is finished, that is the end of
but they should all be cooked at the same time. Task-A defines the end of Task-B. For example, we start the
potatoes, then the meat then the peas but they should all be cooked
at the same time.
============ ============
| Task-A |--+ | Task-A |--+
============ | ============ |
| |
============ | ============ |
| Task-B |<-+ | Task-B |<-+
============ ============
Figure 2: Finish to finish relationship Figure 3: Finish to finish relationship
RELTYPE=STARTTOFINISH: The start of Task-A (which occurs after Task- RELTYPE=STARTTOFINISH
B) controls the finish of Task-B. For example, ticket sales
(Task-B) end when the game starts (Task-A). 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-A |
| ============ | ============
| |
============ | ============ |
| Task-B |<-+ | Task-B |<-+
============ ============
Figure 3: Start to finish relationship Figure 4: Start to finish relationship
RELTYPE=STARTTOSTART: The start of Task-A triggers the start of RELTYPE=STARTTOSTART
Task-B, that is Task-B can start anytime after Task-A starts.
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-A |
| ============ | ============
| |
| ============ | ============
+->| Task-B | +->| Task-B |
============ ============
Figure 4: Start to start relationship Figure 5: Start to start relationship
5. New Property Parameters 7. New Property Parameters
5.1. Split 7.1. Split
Parameter name: SPLIT Parameter name SPLIT
Purpose: To indicate a series has been split. Purpose To indicate a series has been split.
Format Definition: Format Definition
This parameter is defined by the following notation: This parameter is defined by the following notation:
splitparam = "SPLIT" "=" splitparam = "SPLIT" "="
("YES" ; The series is split ("YES" ; The series is split
/ "NO" ; The series is not split (default) / "NO" ; The series is not split (default)
/ x-name ; Experimental reference type / x-name ; Experimental reference type
/ iana-token) ; Other IANA registered type / iana-token) ; Other IANA registered type
Figure 6
Description: This parameter MAY be specified on the SRULE property Description This parameter MAY be specified on the SRULE property to
to indicate that the series has been split with SPLIT=YES. Once indicate that the series has been split with SPLIT=YES. Once
split is is probably innapropriate to modify the series further. split is is probably inappropriate to modify the series further.
5.2. Lookahead count 7.2. Lookahead count
Parameter name: LOOKAHEAD-COUNT Parameter name LOOKAHEAD-COUNT
Purpose: To specify the number of series instances that should be Purpose To specify the number of series instances that should be
generated in advance. generated in advance.
Format Definition: Format Definition
This parameter is defined by the following notation: This parameter is defined by the following notation:
lookahead-countparam = "LOOKAHEAD-COUNT" "=" 1*DIGIT lookahead-countparam = "LOOKAHEAD-COUNT" "=" 1*DIGIT
Description: This parameter MAY be specified on the SRULE property Figure 7
to indicate how many series instances should be generated in
advance.
An implementation is free to apply its own limts but MUST NOT Description
generate more than those defined by this parameter and/or the
LOOKAHEAD-PERIOD parameter.
If both the LOOKAHEAD-PERIOD and LOOKAHEAD-COUNT arameters are This parameter MAY be specified on the SRULE property to indicate how
supplied the result should be limited by both. many series instances should be generated in advance.
For example, if the LOOKAHEAD-PERIOD parameter would cause 8 An implementation is free to apply its own limts but MUST NOT
instances to be generated but LOOKAHEAD-COUNT specifies 4 then generate more than those defined by this parameter and/or the
only 4 instances will be generated. LOOKAHEAD-PERIOD parameter.
5.3. Lookahead period If both the LOOKAHEAD-PERIOD and LOOKAHEAD-COUNT arameters are
supplied the result should be limited by both.
Parameter name: LOOKAHEAD-PERIOD For example, if the LOOKAHEAD-PERIOD parameter would cause 8
instances to be generated but LOOKAHEAD-COUNT specifies 4 then only 4
instances will be generated.
Purpose: To specify a maximum period for which series instances 7.3. Lookahead period
Parameter name LOOKAHEAD-PERIOD
Purpose To specify a maximum period for which series instances
should be generated in advance. should be generated in advance.
Format Definition: Format Definition
This parameter is defined by the following notation: This parameter is defined by the following notation:
lookahead-periodparam = "LOOKAHEAD-PERIOD" "=" lookahead-periodparam = "LOOKAHEAD-PERIOD" "="
DQUOTE dur-value DQUOTE DQUOTE dur-value DQUOTE
Description: This parameter MAY be specified on the SRULE property Figure 8
to indicate how far in advance series instances should be
generated.
An implementation is free to apply its own limts but MUST NOT Description
generate more than those defined by this parameter and/or the
LOOKAHEAD-COUNT parameter.
If both the LOOKAHEAD-PERIOD and LOOKAHEAD-COUNT arameters are This parameter MAY be specified on the SRULE property to indicate how
supplied the result should be limited by both. far in advance series instances should be generated.
For example, if the LOOKAHEAD-PERIOD parameter would cause 8 An implementation is free to apply its own limts but MUST NOT
instances to be generated but LOOKAHEAD-COUNT specifies 4 then generate more than those defined by this parameter and/or the
only 4 instances will be generated. LOOKAHEAD-COUNT parameter.
The value is a quoted duration. If both the LOOKAHEAD-PERIOD and LOOKAHEAD-COUNT arameters are
supplied the result should be limited by both.
6. New Properties For example, if the LOOKAHEAD-PERIOD parameter would cause 8
instances to be generated but LOOKAHEAD-COUNT specifies 4 then only 4
instances will be generated.
The value is a quoted duration.
8. New Properties
8.1. General
The SERIES-ID, LAST-SERIES-ID, SDATE and SXDATE properties are The SERIES-ID, LAST-SERIES-ID, SDATE and SXDATE properties are
identical in form and in the parameters they take. identical in form and in the parameters they take.
All must conform in form to the DTSTART property of the master 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 component. Only the SDATE may specify a time which is not part of
the calculated series. the calculated series.
The SRULE property value is identical in form to the RRULE property The SRULE property value is identical in form to the RRULE property
defined in [RFC5545]. The LOOKAHEAD-COUNT and LOOKAHEAD-PERIOD defined in [RFC5545]. The LOOKAHEAD-COUNT and LOOKAHEAD-PERIOD
parameters indicate how many instances should be generated in parameters indicate how many instances should be generated in
advance. advance.
6.1. Generating Series members 8.2. Generating Series members
An agent, either the server or a client, will periodically extend the An agent, either the server or a client, will periodically extend the
set of instances. The number of such generated instances is limited set of instances. The number of such generated instances is limited
by: by:
Elements of the rule: The UNTIL or COUNT parts of the rule define Elements of the rule The UNTIL or COUNT parts of the rule define
when the series terminates. Thus a COUNT=100 specifies a maximum when the series terminates. Thus a COUNT=100 specifies a maximum
of 100 series members. of 100 series members.
Lookahead count: This specifies how many series memerbs can exist Lookahead count This specifies how many series members can exist
from the current date/time. Thus a LOOKAHEAD-COUNT=4 means a from the current date/time. Thus a LOOKAHEAD-COUNT=4 means a
maximum of 4 generated instances. maximum of 4 generated instances.
Lookahead period: This specifies how far into the future series Lookahead period This specifies how far into the future series
members can be generated. Thus a LOOKAHEAD-PERIOD="PT2M" means a members can be generated. Thus a LOOKAHEAD-PERIOD="PT2M" means a
maximum period of 2 months. maximum period of 2 months.
System limits: This client or server SHOULD also apply limits to System limits This client or server SHOULD also apply limits to
prevent a series from generating an overlarge set of members. prevent a series from generating an overlarge set of members.
The starting point for the calculation is the DTSTART of the master 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 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 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 of the instance set and the actual instance may have been excluded by
an SXDATE property but the starting date is still valid. an SXDATE property but the starting date is still valid.
The starting date/time property defines the first instance in the The starting date/time property defines the first instance in the
next batch of series members. Note that the starting property value next batch of series members. Note that the starting property value
MUST match the pattern of the series rule, if specified. For MUST match the pattern of the series rule, if specified. For
example, if the rule specifies every Wednesday the starting date MUST example, if the rule specifies every Wednesday the starting date MUST
be a Wednesday. be a Wednesday.
The end date/time of the set will be provided by the UNTIL part of 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. the rule, the LOOKAHEAD-PERIOD or by a system maxima.
A set of date/time values can be generated within those contraints. 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 As each date/time value is generated it can be ignored if it is one
of the SXDATE values. of the SXDATE values.
Generation of values can terminate when the size of the result Generation of values can terminate when the size of the result
exceeds that given by the COUNT rule element, the LOOKAHEAD-COUNT exceeds that given by the COUNT rule element, the LOOKAHEAD-COUNT
value or any systm limit. value or any system limit.
Any SDATE values that fall within the current range and are not in 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 the set of SXDATE values can be added and the result truncated again
to match the size limits. to match the size limits.
Finally, any date/time values that have already been generated and Finally, any date/time values that have already been generated and
are present as SERIES-ID values should be removed from the set. What 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. 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 The last of those values becomes the new value for the LAST-SERIES-ID
property in the series master. property in the series master.
As noted above the "SXDATE" property can be used to exclude the value 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 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 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. This is flagged by adding a DELETED-MASTER element to the
SERIES-STATUS property. SERIES-STATUS property.
6.2. Series UID 8.3. Series UID
Property name: SERIES-UID Property name SERIES-UID
Purpose: This property defines the persistent, globally unique
Purpose This property defines the persistent, globally unique
identifier for the full series. identifier for the full series.
Value Type: TEXT Value Type TEXT
Property Parameters: IANA and non-standard property parameters can Property Parameters IANA and non-standard property parameters can be
be specified on this property. specified on this property.
Conformance: This property MUST be specified in any "VEVENT", Conformance This property MUST be specified in any "VEVENT",
"VTODO", and "VJOURNAL" calendar components acting as a series "VTODO", and "VJOURNAL" calendar components acting as a series
master or series instance. master or series instance.
Description: The SERIES-UID MUST be globally unique. This value Description The SERIES-UID MUST be globally unique. This value
SHOULD be generated by following the recommendations in section SHOULD be generated by following the recommendations in [RFC7986].
5.3 of [RFC7986].
Format Definition: Format Definition
This property is defined by the following notation: This property is defined by the following notation:
seruid = "SERIES-UID" seruidparam ":" text CRLF seruid = "SERIES-UID" seruidparam ":" text CRLF
seruidparam = *(";" other-param) seruidparam = *(";" other-param)
Example: Figure 9
EXAMPLE
The following is an example of this property: The following is an example of this property:
SERIES-UID:123e4567-e89b-12d3-a456-426655440000 SERIES-UID:123e4567-e89b-12d3-a456-426655440000
6.3. Series-exception-date Figure 10
Property name: SXDATE 8.4. Series-exception-date
Purpose: This property defines the list of DATE-TIME exceptions for Property name SXDATE
Purpose This property defines the list of DATE-TIME exceptions for
series of events, to-dos or journal entries. series of events, to-dos or journal entries.
Value Type: The default value type for this property is DATE-TIME. Value Type The default value type for this property is DATE-TIME.
The value type can be set to DATE. The value type can be set to DATE.
Property Parameters: IANA, non-standard, value data type, and time Property Parameters IANA, non-standard, value data type, and time
zone identifier property parameters can be specified on this zone identifier property parameters can be specified on this
property. property.
Conformance: This property can be specified in "VEVENT", "VTODO", Conformance This property can be specified in "VEVENT", "VTODO", and
and "VJOURNAL" calendar components acting as the series master. "VJOURNAL" calendar components acting as the series master.
Description: The exception dates, if specified, are used when Description The exception dates, if specified, are used when
computing the instances of the series. They specify date/time computing the instances of the series. They specify date/time
values which are to be removed from the set of possible series values which are to be removed from the set of possible series
instances. instances.
Format Definition: Format Definition
This property is defined by the following notation: This property is defined by the following notation:
sxdate = "SXDATE" sxdtparam ":" sxdtval *("," sxdtval) CRLF sxdate = "SXDATE" sxdtparam ":" sxdtval *("," sxdtval) CRLF
sxdtparam = *( sxdtparam = *(
; ;
; The following are OPTIONAL, ; The following are OPTIONAL,
; but MUST NOT occur more than once. ; but MUST NOT occur more than once.
; ;
(";" "VALUE" "=" ("DATE-TIME" / "DATE")) / (";" "VALUE" "=" ("DATE-TIME" / "DATE")) /
; ;
(";" tzidparam) / (";" tzidparam) /
; ;
; The following is OPTIONAL, ; The following is OPTIONAL,
; and MAY occur more than once. ; and MAY occur more than once.
; ;
(";" other-param) (";" other-param)
; ;
) )
sxdtval = date-time / date sxdtval = date-time / date
;Value MUST match value type ;Value MUST match value type
Example: Figure 11
EXAMPLE
The following is an example of this property: The following is an example of this property:
SXDATE:19960402T010000Z,19960403T010000Z,19960404T010000Z SXDATE:19960402T010000Z,19960403T010000Z,19960404T010000Z
6.4. Series-date Figure 12
Property name: SDATE 8.5. Series-date
Purpose: This property defines the list of DATE-TIME values for Property name SDATE
Purpose This property defines the list of DATE-TIME values for
series of events, to-dos or journal entries. series of events, to-dos or journal entries.
Value Type: The default value type for this property is DATE-TIME. Value Type The default value type for this property is DATE-TIME.
The value type can be set to DATE. The value type can be set to DATE.
Property Parameters: IANA, non-standard, value data type, and time Property Parameters IANA, non-standard, value data type, and time
zone identifier property parameters can be specified on this zone identifier property parameters can be specified on this
property. property.
Conformance: This property can be specified in "VEVENT", "VTODO", Conformance This property can be specified in "VEVENT", "VTODO", and
and "VJOURNAL" calendar components acting as the series master. "VJOURNAL" calendar components acting as the series master.
Description: This property can appear along with the "SRULE" Description This property can appear along with the "SRULE" property
property to define a extra series occurrences. When they both to define a extra series occurrences. When they both appear in a
appear in a series master component, the instances are defined by series master component, the instances are defined by the union of
the union of occurrences defined by both the "SDATE" and "SRULE". occurrences defined by both the "SDATE" and "SRULE".
Purpose: Format Definition
This property is defined by the following notation: This property is defined by the following notation:
sdate = "SDATE" sdtparam ":" sdtval *("," sdtval) CRLF sdate = "SDATE" sdtparam ":" sdtval *("," sdtval) CRLF
sdtparam = *( sdtparam = *(
; ;
; The following are OPTIONAL, ; The following are OPTIONAL,
; but MUST NOT occur more than once. ; but MUST NOT occur more than once.
; ;
(";" "VALUE" "=" ("DATE-TIME" / "DATE" / "PERIOD")) / (";" "VALUE" "=" ("DATE-TIME" / "DATE" / "PERIOD")) /
(";" tzidparam) / (";" tzidparam) /
; ;
; The following is OPTIONAL, ; The following is OPTIONAL,
; and MAY occur more than once. ; and MAY occur more than once.
; ;
(";" other-param) (";" other-param)
; ;
) )
sdtval = date-time / date sdtval = date-time / date
;Value MUST match value type ;Value MUST match value type
Example: Figure 13
EXAMPLE
The following are examples of this property: The following are examples of this property:
SDATE:19970714T123000Z SDATE:19970714T123000Z
SDATE;TZID=America/New_York:19970714T083000 SDATE;TZID=America/New_York:19970714T083000
SDATE;VALUE=PERIOD:19960403T020000Z/19960403T040000Z, SDATE;VALUE=PERIOD:19960403T020000Z/19960403T040000Z,
19960404T010000Z/PT3H 19960404T010000Z/PT3H
SDATE;VALUE=DATE:19970101,19970120,19970217,19970421 SDATE;VALUE=DATE:19970101,19970120,19970217,19970421
19970526,19970704,19970901,19971014,19971128,19971129,19971225 19970526,19970704,19970901,19971014,19971128,19971129,19971225
6.5. Series-id Figure 14
Property name: SERIES-ID 8.6. Series-id
Purpose: This property is used in conjunction with the "UID" and Property name SERIES-ID
Purpose This property is used in conjunction with the "UID" and
"SEQUENCE" properties to identify a specific instance of a "SEQUENCE" properties to identify a specific instance of a
"VEVENT", "VTODO", or "VJOURNAL" calendar component in a series. "VEVENT", "VTODO", or "VJOURNAL" calendar component in a series.
The property value is the original value of the "DTSTART" property The property value is the original value of the "DTSTART" property
of the series instance before any changes occur. of the series instance before any changes occur.
Value type: The default value type is DATE-TIME. The value type can Value type The default value type is DATE-TIME. The value type can
be set to a DATE value type. This property MUST have the same be set to a DATE value type. This property MUST have the same
value type as the "DTSTART" property contained within the series value type as the "DTSTART" property contained within the series
component. Furthermore, this property MUST be specified as a date component. Furthermore, this property MUST be specified as a date
with local time if and only if the "DTSTART" property contained with local time if and only if the "DTSTART" property contained
within the series component is specified as a date with local within the series component is specified as a date with local
time. time.
Property Parameters: IANA, non-standard, value data type and time Property Parameters IANA, non-standard, value data type and time
zone identifier parameters can be specified on this property. zone identifier parameters can be specified on this property.
Conformance: This property can be specified zero or more times in Conformance This property can be specified zero or more times in any
any iCalendar component. iCalendar component.
Description: The SERIES-ID is the originally calculated value of the Description
DTSTART property based on the master identified by the RELATED-TO
property with a RELTYPE=SERIES-MASTER parameter.
The full series of components can only be retrieved by searching The SERIES-ID is the originally calculated value of the DTSTART
for all components with a matching RELATED-TO property. property based on the master identified by the RELATED-TO property
with a RELTYPE=SERIES-MASTER parameter.
If the value of the "DTSTART" property is a DATE type value, then The full series of components can only be retrieved by searching
the value MUST be the calendar date for the series instance. for all components with a matching RELATED-TO property.
The DATE-TIME value is set to the time when the original series Figure 15
instance would occur; meaning that if the intent is to change a
Friday meeting to Thursday, the DATE-TIME is still set to the
original Friday meeting.
The "SERIES-ID" property is used in conjunction with the "UID" and If the value of the "DTSTART" property is a DATE type value, then
"SEQUENCE" properties to identify a particular instance of an the value MUST be the calendar date for the series instance.
event, to-do, or journal in the series. For a given pair of "UID"
and "SEQUENCE" property values, the "SERIES-ID" value for a series
instance is fixed.
Format Definition: Figure 16
The DATE-TIME value is set to the time when the original series
instance would occur; meaning that if the intent is to change a
Friday meeting to Thursday, the DATE-TIME is still set to the
original Friday meeting.
Figure 17
The "SERIES-ID" property is used in conjunction with the "UID" and
"SEQUENCE" properties to identify a particular instance of an
event, to-do, or journal in the series. For a given pair of "UID"
and "SEQUENCE" property values, the "SERIES-ID" value for a series
instance is fixed.
Figure 18
Format Definition
This property is defined by the following notation: This property is defined by the following notation:
serid = "SERIES-ID" sidparam ":" sidval CRLF serid = "SERIES-ID" sidparam ":" sidval CRLF
sidparam = *( sidparam = *(
; ;
; The following are OPTIONAL, ; The following are OPTIONAL,
; but MUST NOT occur more than once. ; but MUST NOT occur more than once.
; ;
(";" "VALUE" "=" ("DATE-TIME" / "DATE")) / (";" "VALUE" "=" ("DATE-TIME" / "DATE")) /
(";" tzidparam) / (";" tzidparam) /
; ;
; The following is OPTIONAL, ; The following is OPTIONAL,
; and MAY occur more than once. ; and MAY occur more than once.
; ;
(";" other-param) (";" other-param)
; ;
) )
sidval = date-time / date sidval = date-time / date
;Value MUST match value type ;Value MUST match value type
Example: Figure 19
EXAMPLE
The following are examples of this property: The following are examples of this property:
SERIES-ID;VALUE=DATE:19960401 SERIES-ID;VALUE=DATE:19960401
SERIES-ID;TZID=America/New_York:20170120T120000 SERIES-ID;TZID=America/New_York:20170120T120000
6.6. Last series id Figure 20
Property name: LAST-SERIES-ID 8.7. Last series ID
Purpose: To specify the last calculated instance of the series. Property name LAST-SERIES-ID
When new instances are created they MUST have a SERIES-ID after
the value of this property.
In all respects this property is identical to SERIES-ID and is in Purpose
fact a copy of the SERIES-ID which would be present in the last
created instance (assuming it is not suppressed by an SXDATE).
Value type: DATE or DATE_TIME (the default). This has the same To specify the last calculated instance of the series. When new
instances are created they MUST have a SERIES-ID after the value of
this property.
In all respects this property is identical to SERIES-ID and is in
fact a copy of the SERIES-ID which would be present in the last
created instance (assuming it is not suppressed by an SXDATE).
Value type DATE or DATE_TIME (the default). This has the same
requirements as SERIES-ID. requirements as SERIES-ID.
Property Parameters: IANA, non-standard, value data type and time Property Parameters IANA, non-standard, value data type and time
zone identifier parameters can be specified on this property. zone identifier parameters can be specified on this property.
Conformance: This property MAY be specified in any iCalendar Conformance This property MAY be specified in any iCalendar
component. component.
Description: This property allows a client or server to delete the Description When used in a component the value of this property
trailing instances in a series without having them recreated by points to additional information related to the component. For
some other agent. example, it may reference the originating web server.
Format Definition: Format Definition
This property is defined by the following notation: This property is defined by the following notation:
last-series-i = "LAST-SERIES-ID" lastseriesidparam / last-series-i = "LAST-SERIES-ID" lastseriesidparam /
( (
";" "VALUE" "=" "TEXT" ";" "VALUE" "=" "TEXT"
":" text ":" text
) )
( (
";" "VALUE" "=" "REFERENCE" ";" "VALUE" "=" "REFERENCE"
":" text ":" text
) )
( (
";" "VALUE" "=" "URI" ";" "VALUE" "=" "URI"
":" uri ":" uri
) )
CRLF CRLF
lastseriesidparam = *( lastseriesidparam = *(
; the following is MANDATORY ; the following is MANDATORY
; and MAY occur more than once ; and MAY occur more than once
(";" relparam) / (";" relparam) /
; the following are MANDATORY ; the following are MANDATORY
; but MUST NOT occur more than once ; but MUST NOT occur more than once
(";" fmttypeparam) / (";" fmttypeparam) /
(";" labelparam) / (";" labelparam) /
; labelparam is defined in ... ; labelparam is defined in ...
; the following is OPTIONAL ; the following is OPTIONAL
; and MAY occur more than once ; and MAY occur more than once
(";" xparam) (";" xparam)
) )
Example: Figure 21
EXAMPLE
The following is an example of this property. It points to a server The following is an example of this property. It points to a server
acting as the source for the calendar object. acting as the source for the calendar object.
LINK;REL=SOURCE;LABEL=The Egg:http://example.com/events LINK;REL=SOURCE;LABEL=The Egg:http://example.com/events
6.7. Series Rule Figure 22
Property name: SRULE 8.8. Series Rule
Purpose: This property defines a rule or repeating pattern for a Property name RRULE
Purpose This property defines a rule or repeating pattern for a
series of events, to-dos or journal entries. series of events, to-dos or journal entries.
Value Type: RECUR Value Type RECUR
Property Parameters: IANA, non-standard, look-ahead count or date Property Parameters IANA, non-standard, look-ahead count or date
property parameters can be specified on this property. property parameters can be specified on this property.
Conformance: This property can be specified in any "VEVENT", Conformance This property can be specified in any "VEVENT", "VTODO",
"VTODO", and "VJOURNAL" calendar component. and "VJOURNAL" calendar component, but it SHOULD NOT be specified
more than once.
[RFC5545] states that the RRULE component SHOULD only appear once.
This is unduly limiting for those applications that require more
than one rule to specify the series. In fact, some complex rules
are better expressed as multiple rules. Recipients of iCalendar
data containing SRULE MUST support the occurrence of multiple
SRULEs.
Clients and servers MAY choose to reduce the number of SRULE Description
properties to 1. In reality many - if not most - clients are
unable to handle the full set of SRULE or RRULE features.
Description: The series rule, if specified, is used in computing the The series rule, if specified, is used in computing the instances to
instances to be generated for the series. These are generated by be generated for the series. These are generated by considering the
considering the master "DTSTART" property along with the "SRULE", master "DTSTART" property along with the "SRULE", "SDATE", and
"SDATE", and "SXDATE" properties contained within the series "SXDATE" properties contained within the series master. The
master. The "DTSTART" property defines the first instance in the "DTSTART" property defines the first instance in the recurrence set
recurrence set which is represented by that master event. which is represented by that master event.
Unlike the RRULE the "DTSTART" property MUST be synchronized with Unlike the RRULE the "DTSTART" property MUST be synchronized with the
the series rule, if specified. For example, if the DTSTART series rule, if specified. For example, if the DTSTARTS species a
specifies a date on Wednesday but the SRULE specifies every date on Wednesday but the SRULE specifies every Tuesday then a server
Tuesday then a server or client MUST reject the component. or client MUSt reject the component.
The final series is represented by gathering all of the start The final series is represented by gathering all of the start DATE-
DATE-TIME values generated by any of the specified "SRULE" and TIME values generated by any of the specified "SRULE" and "SDATE"
"SDATE" properties, and then excluding any start DATE-TIME values properties, and then excluding any start DATE-TIME values specified
specified by "SXDATE" properties. This implies that start DATE- by "SXDATE" properties. This implies that start DATE- TIME values
TIME values specified by "SXDATE" properties take precedence over specified by "SXDATE" properties take precedence over those specified
those specified by inclusion properties (i.e., "SDATE" and by inclusion properties (i.e., "SDATE" and "SRULE"). Where duplicate
"SRULE"). Where duplicate instances are generated by the "SRULE" instances are generated by the "SRULE" and "SDATE" properties, only
and "SDATE" properties, only one instance is considered. one instance is considered. Duplicate instances are ignored.
Duplicate instances are ignored.
The "DTSTART" property specified within the master iCalendar The "DTSTART" property specified within the master iCalendar object
object defines the first instance of the recurrence. In most defines the first instance of the recurrence. In most cases, a
cases, a "DTSTART" property of DATE-TIME value type used with a "DTSTART" property of DATE-TIME value type used with a series rule,
series rule, should be specified as a date with local time and should be specified as a date with local time and time zone reference
time zone reference to make sure all the recurrence instances to make sure all the recurrence instances start at the same local
start at the same local time regardless of time zone changes. time regardless of time zone changes.
If the duration of the series component is specified with the If the duration of the series component is specified with the "DTEND"
"DTEND" or "DUE" property, then the same exact duration will apply or "DUE" property, then the same exact duration will apply to all the
to all the members of the generated series. Else, if the duration members of the generated series. Else, if the duration of the series
of the series master component is specified with the "DURATION" master component is specified with the "DURATION" property, then the
property, then the same nominal duration will apply to all the same nominal duration will apply to all the members of the generated
members of the generated series and the exact duration of each series and the exact duration of each instance will depend on its
instance will depend on its specific start time. For example, specific start time. For example, series instances of a nominal
series instances of a nominal duration of one day will have an duration of one day will have an exact duration of more or less than
exact duration of more or less than 24 hours on a day where a time 24 hours on a day where a time zone shift occurs. The duration of a
zone shift occurs. The duration of a specific instance may be specific instance may be modified in an exception component or simply
modified in an exception component or simply by using an "SDATE" by using an "SDATE" property of PERIOD value type.
property of PERIOD value type.
Format Definition: Format Definition
This property is defined by the following notation: This property is defined by the following notation:
srule = "SRULE" srulparam ":" recur CRLF 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)
)
Examples: Refer to [RFC5545] for example of the use of RRULE which
has identical format.
6.8. SITEM-STATUS Property
Property name: SITEM-STATUS
Purpose: This property is used to define the status of a series
item.
Conformance: This property MAY be specified in any iCalendar series
item.
Description: An item may be generated to provide an indication to a
user or client of when an event may occur - even if that event is
outside of the generated period.
When this property is absent the series item is treated as a
concrete item which may be updated subject to the constraints of
the server/storage for the item.
Format Definition:
This property is defined by the following notation: sruleparam = *(
; the following are OPTIONAL
; but MUST NOT occur more than once
sitem-status = "SITEM-STATUS" sisparam ":" SISvalue CRLF (";" lookahead-countparam) /
(";" lookahead-periodparam) /
sisparam = *(";" other-param) ; the following is OPTIONAL
; and MAY occur more than once
sisvalue = "DUMMY" ; This item is generated as an indication of where (";" xparam)
; an item might appear when it is generated
/ iana-token
/ x-name
Example: )
The following is an example of this property. Figure 23
SITEM-STATUS:DUMMY EXAMPLE
7. Redefined RELATED-TO Property TODO - Say they are pretty much the same as RRULE but extra params
7.1. RELATED-TO 9. Redefined RELATED-TO Property
Property name: RELATED-TO 9.1. RELATED-TO
Purpose: This property is used to represent a relationship or Property name RELATED-TO
reference between one calendar component and others. The
definition here extends the definition in Section 3.8.4.5. of
[RFC5545] by including a section on RELTYPE=SERIES-MASTER.
Value type: URI, UID or TEXT Purpose This property is used to represent a relationship or
reference between one calendar component and another. The
definition here extends the definition in [RFC5545] by including a
section on RELTYPE=SERIES-MASTER.
Property Parameters: Relationship type, IANA and non-standard Value type URI, UID or TEXT
property parameters can be specified on this property.
Conformance: This property MAY be specified in any iCalendar Conformance This property MAY be specified in any iCalendar
component. component.
Description: By default or when VALUE=UID is specified, the property Description By default or when VALUE=UID is specified, the property
value consists of the persistent, globally unique identifier of value consists of the persistent, globally unique identifier of
another calendar component. This value would be represented in a another calendar component. This value would be represented in a
calendar component by the "UID" property. calendar component by the "UID" property.
By default, the property value points to another calendar By default, the property value points to another calendar
component that has a PARENT relationship to the referencing component that has a PARENT relationship to the referencing
object. The "RELTYPE" property parameter is used to either object. The "RELTYPE" property parameter is used to either
explicitly state the default PARENT relationship type to the explicitly state the default PARENT relationship type to the
referenced calendar component or to override the default PARENT referenced calendar component or to override the default PARENT
relationship type and specify either a CHILD or SIBLING relationship type and specify either a CHILD or SIBLING
skipping to change at page 23, line 7 skipping to change at page 23, line 50
example, if a group event changes its start or end date or time, example, if a group event changes its start or end date or time,
then the related, dependent events will need to have their start then the related, dependent events will need to have their start
and end dates changed in a corresponding way. Similarly, if a and end dates changed in a corresponding way. Similarly, if a
PARENT calendar component is cancelled or deleted, then there is PARENT calendar component is cancelled or deleted, then there is
an implied impact to the related CHILD calendar components. This an implied impact to the related CHILD calendar components. This
property is intended only to provide information on the property is intended only to provide information on the
relationship of calendar components. It is up to the target relationship of calendar components. It is up to the target
calendar system to maintain any property implications of this calendar system to maintain any property implications of this
relationship. relationship.
Format Definition: Format Definition This property is defined by the following
notation:
This property is defined by the following notation:
related = "RELATED-TO" relparam ( ":" text ) / related = "RELATED-TO" relparam ( ":" text ) /
( (
";" "VALUE" "=" "UID" ";" "VALUE" "=" "UID"
":" uid ":" uid
) )
( (
";" "VALUE" "=" "URI" ";" "VALUE" "=" "URI"
":" uri ":" uri
) )
CRLF CRLF
relparam = *( relparam = *(
; ;
; The following are OPTIONAL, ; The following are OPTIONAL,
; but MUST NOT occur more than once. ; but MUST NOT occur more than once.
; ;
(";" reltypeparam) / (";" reltypeparam) /
(";" gapparam) / (";" gapparam) /
; ;
; The following is OPTIONAL, ; The following is OPTIONAL,
; and MAY occur more than once. ; and MAY occur more than once.
; ;
(";" other-param) (";" other-param)
; ;
) )
Example: Figure 24
EXAMPLE
The following are examples of this property. The following are examples of this property.
RELATED-TO;RELTYPE=SERIES-MASTER:19960401-080045-4000F192713 RELATED-TO;RELTYPE=SERIES-MASTER:19960401-080045-4000F192713
8. Backwards compatibility Figure 25
10. Backwards compatibility
Any clients following the approach specified in [RFC5545] are Any clients following the approach specified in [RFC5545] are
expected to ignore any properties, parameters or components they expected to ignore any properties or parameters they don't recognize.
don't recognize.
For such clients the series appears to be an unconnected set of For such clients the series appears to be an unconnected set of
components. They all have their own unique UIDS. If the client components. They all have their own unique UIDS. If the client
updates an instance this should be identical in effect to an update updates an instance this should be identical in effect to an update
carried out by a client aware of the new properties. carried out by a client aware of the new properties.
Updates MUST preserve the SERIES-ID, LAST-SERIES-ID, SRULE, SDATE and 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 SXDATE properties. A client which does not do so is in violation of
[RFC5545]. [RFC5545].
There are two possible problem areas: first we must prevent series TODO - More text needed here...
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.
9. CalDAV extensions 11. CalDAV extensions
This specification may extend Caldav by adding reports to return all This specification may extend Caldav by adding reports to return all
members of a series given the series master UID. This could be members of a series given the series master UID. This could be
handled by the current query mechanism but it is likely to be handled by the current query mechanism but it is likely to be
sufficiently frequently used that a special query is appropriate. sufficiently frequently used that a special query is appropriate.
It is also likely we will want a CalDAV operation to split a series 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 and generate the additional members of the series as a single atomic
operation. operation. == Security Considerations
10. Security Considerations
Clients and servers should take care to limit the number of generated Clients and servers should take care to limit the number of generated
instances to a reasonable value. This can be a relatively small instances to a reasonable value. This can be a relatively small
value. value.
11. IANA Considerations 12. IANA Considerations
11.1. iCalendar Property Registrations 12.1. iCalendar Property Registrations
The following iCalendar property names have been added to the The following iCalendar property names have been added to the
iCalendar Properties Registry defined in Section 8.3.2 of [RFC5545] iCalendar Properties Registry defined in [RFC5545].
+----------------+---------+-------------+
+================+=========+=============+
| Property | Status | Reference | | Property | Status | Reference |
+================+=========+=============+
| LAST-SERIES-ID | Current | Section 8.7 |
+----------------+---------+-------------+ +----------------+---------+-------------+
| LAST-SERIES-ID | Current | Section 6.6 | | SERIES-ID | Current | Section 8.6 |
| SERIES-ID | Current | Section 6.5 | +----------------+---------+-------------+
| SERIES-UID | Current | Section 6.2 | | SERIES-UID | Current | Section 8.3 |
| SDATE | Current | Section 6.4 | +----------------+---------+-------------+
| SRULE | Current | Section 6.7 | | SDATE | Current | Section 8.5 |
| SXDATE | Current | Section 6.3 | +----------------+---------+-------------+
| SRULE | Current | Section 8.8 |
+----------------+---------+-------------+
| SXDATE | Current | Section 8.4 |
+----------------+---------+-------------+ +----------------+---------+-------------+
11.2. iCalendar Property Parameter Registrations Table 1
12.2. iCalendar Property Parameter Registrations
The following iCalendar property parameter names have been added to The following iCalendar property parameter names have been added to
the iCalendar Parameters Registry defined in Section 8.3.3 of the iCalendar Parameters Registry defined in [RFC5545].
[RFC5545]
+------------------+---------+-------------+ +==================+=========+=============+
| Parameter | Status | Reference | | Parameter | Status | Reference |
+==================+=========+=============+
| LOOKAHEAD-COUNT | Current | Section 7.2 |
+------------------+---------+-------------+ +------------------+---------+-------------+
| LOOKAHEAD-COUNT | Current | Section 5.2 | | LOOKAHEAD-PERIOD | Current | Section 7.3 |
| LOOKAHEAD-PERIOD | Current | Section 5.3 | +------------------+---------+-------------+
| SPLIT | Current | Section 5.1 | | SPLIT | Current | Section 7.1 |
+------------------+---------+-------------+ +------------------+---------+-------------+
11.3. iCalendar RELTYPE Value Registrations Table 2
12.3. iCalendar RELTYPE Value Registrations
The following iCalendar "RELTYPE" values have been added to the The following iCalendar "RELTYPE" values have been added to the
iCalendar Relationship Types Registry defined in Section 8.3.8 of iCalendar Relationship Types Registry defined in [RFC5545].
[RFC5545]
+-------------------+---------+-----------+ +===================+=========+===========+
| Relationship Type | Status | Reference | | Relationship Type | Status | Reference |
+===================+=========+===========+
| SERIES-ID | Current | Section 5 |
+-------------------+---------+-----------+ +-------------------+---------+-----------+
| SERIES-ID | Current | Section 4 |
+-------------------+---------+-----------+
12. Acknowledgements
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.
13. Normative References Table 3
[I-D.daboo-caldav-attachments]
Daboo, C. and A. Quillaud, "CalDAV Managed Attachments",
draft-daboo-caldav-attachments-03 (work in progress),
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,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 13. Normative references
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005,
<https://www.rfc-editor.org/info/rfc3986>.
[RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and [RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and
Scheduling Core Object Specification (iCalendar)", Scheduling Core Object Specification (iCalendar)", IETF
RFC 5545, DOI 10.17487/RFC5545, September 2009, RFC 5545, IETF RFC 5545, DOI 10.17487/RFC5545, September
<https://www.rfc-editor.org/info/rfc5545>. 2009, <https://www.rfc-editor.org/info/rfc5545>.
[RFC5988] Nottingham, M., "Web Linking", RFC 5988,
DOI 10.17487/RFC5988, October 2010,
<https://www.rfc-editor.org/info/rfc5988>.
[RFC7986] Daboo, C., "New Properties for iCalendar", RFC 7986, [RFC7986] Daboo, C., "New Properties for iCalendar", IETF RFC 7986,
DOI 10.17487/RFC7986, October 2016, IETF RFC 7986, DOI 10.17487/RFC7986, October 2016,
<https://www.rfc-editor.org/info/rfc7986>. <https://www.rfc-editor.org/info/rfc7986>.
[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,
<http://www.w3.org/TR/2006/REC-xml-20060816>.
[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,
<http://www.w3.org/TR/2002/WD-xptr-xpointer-20021219>.
Appendix A. Points for discussion
Splitting and linking: The spec currently only allows for backward
linking to previous masters. There is a parameter added to the
rule SPLIT=YES to indicate that the series was split
It makes sense to have a forward link to the new(er) series.
However, a client/server may not know what the UID is until after
data is stored. The new chain can be determined via a query so
perhaps we can leave it up to the protocols to figure out that
mechanism.
CalDAV queries: if there were a better more generalised query
language such an extensions might be unnecessary. Should we
define a query language specifically for calendaring?
Appendix B. Change log
2018-01-01 MD Better descriptions - LAST-SESSION-ID.
2017-09-30 MD Minor updates: better backward compatibility.
2017-02-12 MD Initial version
Author's Address Author's Address
Michael Douglass Michael Douglass
Bedework
226 3rd Street
Troy, NY 12180
USA
Email: mdouglass@bedework.com Email: mikeadouglass@gmail.com
URI: http://bedework.com
 End of changes. 218 change blocks. 
629 lines changed or deleted 565 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/