idnits 2.17.1 draft-ietf-calext-icalendar-series-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 2 instances of too long lines in the document, the longest one being 6 characters in excess of 72. ** The abstract seems to contain references ([RFC5545]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). (Using the creation date from RFC5545, updated by this document, for RFC5378 checks: 2005-10-26) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (October 30, 2019) is 1633 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'I-D.daboo-caldav-attachments' is defined on line 1157, but no explicit reference was found in the text == Unused Reference: 'RFC2119' is defined on line 1162, but no explicit reference was found in the text == Unused Reference: 'RFC3986' is defined on line 1167, but no explicit reference was found in the text == Unused Reference: 'RFC5988' is defined on line 1177, but no explicit reference was found in the text ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) Summary: 3 errors (**), 0 flaws (~~), 6 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Douglass 3 Internet-Draft Spherical Cow Group 4 Updates: 5545 (if approved) October 30, 2019 5 Intended status: Standards Track 6 Expires: May 2, 2020 8 Support for Series in iCalendar 9 draft-ietf-calext-icalendar-series-00 11 Abstract 13 This specification updates [RFC5545] by defining a new repeating set 14 of events known as a series. This differs from recurrences in that 15 each instance is a separate entity with a parent relationship to a 16 specified template entity. 18 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at https://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on May 2, 2020. 35 Copyright Notice 37 Copyright (c) 2019 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (https://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 53 2. Overrides and iCalendar recurrences . . . . . . . . . . . . . 3 54 2.1. Changing the master start or the recurrence rules . . . . 3 55 2.2. Splitting recurrences . . . . . . . . . . . . . . . . . . 4 56 3. Series . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 57 3.1. Modifying series patterns and splitting . . . . . . . . . 5 58 3.2. The series master . . . . . . . . . . . . . . . . . . . . 5 59 3.3. The series instances . . . . . . . . . . . . . . . . . . 6 60 4. Redefined Relation Type Value . . . . . . . . . . . . . . . . 6 61 5. New Property Parameters . . . . . . . . . . . . . . . . . . . 9 62 5.1. Split . . . . . . . . . . . . . . . . . . . . . . . . . . 9 63 5.2. Lookahead count . . . . . . . . . . . . . . . . . . . . . 10 64 5.3. Lookahead period . . . . . . . . . . . . . . . . . . . . 10 65 6. New Properties . . . . . . . . . . . . . . . . . . . . . . . 11 66 6.1. Generating Series members . . . . . . . . . . . . . . . . 11 67 6.2. Series UID . . . . . . . . . . . . . . . . . . . . . . . 12 68 6.3. Series-exception-date . . . . . . . . . . . . . . . . . . 13 69 6.4. Series-date . . . . . . . . . . . . . . . . . . . . . . . 14 70 6.5. Series-id . . . . . . . . . . . . . . . . . . . . . . . . 16 71 6.6. Last series id . . . . . . . . . . . . . . . . . . . . . 17 72 6.7. Series Rule . . . . . . . . . . . . . . . . . . . . . . . 19 73 6.8. SITEM-STATUS Property . . . . . . . . . . . . . . . . . . 21 74 7. Redefined RELATED-TO Property . . . . . . . . . . . . . . . . 21 75 7.1. RELATED-TO . . . . . . . . . . . . . . . . . . . . . . . 21 76 8. Backwards compatibility . . . . . . . . . . . . . . . . . . . 23 77 9. CalDAV extensions . . . . . . . . . . . . . . . . . . . . . . 24 78 10. Security Considerations . . . . . . . . . . . . . . . . . . . 24 79 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24 80 11.1. iCalendar Property Registrations . . . . . . . . . . . . 24 81 11.2. iCalendar Property Parameter Registrations . . . . . . . 25 82 11.3. iCalendar RELTYPE Value Registrations . . . . . . . . . 25 83 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 25 84 13. Normative References . . . . . . . . . . . . . . . . . . . . 26 85 Appendix A. Points for discussion . . . . . . . . . . . . . . . 26 86 Appendix B. Change log . . . . . . . . . . . . . . . . . . . . . 27 87 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 27 89 1. Introduction 91 Since iCalendar was first defined there has been only one standard 92 way to express a repeating set of events - the recurrence. This 93 defined a master event, a set of rules for computing the instances 94 and a way of overriding certain instances. 96 This approach works well enough in certain situations but has many 97 problems which need to be addressed. 99 This specification introduces a new approach to repeating patterns of 100 entities which avoids some of the problems. 102 2. Overrides and iCalendar recurrences 104 The recurrence rules specify how instances are to be computed. These 105 rules provide a set of keys - the RECURRENCE-IDs - and an instance 106 can be created with the calculated start date/time and a copy of the 107 duration (or calculated end date/time). 109 The specification allows for overrides. These are handled by 110 supplying a complete replacement for the instance with a RECURRENCE- 111 ID property matching that of the instance being overridden. This may 112 change any of the properties (except the UID) - including start, end 113 or duration. 115 If a long lived recurrence is heavily overridden it becomes very 116 cumbersome. The master plus overrides is considered a single 117 resource in most circumstances (however iTip allows the delivery of a 118 single instance in certain situations). 120 Simple meetings can become heavily modifed recurrences through adding 121 the weeks agenda to the description, changing of attendees etc. 123 There are approaches being considered to mitigate some of these 124 issues which mostly involve only storing differences. Depending on 125 the actual changes this may be more or less succesful. However 126 recurrences are still awkward to deal with. 128 2.1. Changing the master start or the recurrence rules 130 This can lead to some very difficult problems to resolve. In the 131 case of a heavily modified meeting it may be difficult to impossible 132 to determine which override applies to the newly modified event. 134 For example, a weekly book-reading is moved from Monday to Friday. 135 There are weeks of scheduled events in the future. Do we move them 136 all forward to the next instance or skip one and move them back? If 137 it becomes bi-weekly rather than weekly do we drop every other or 138 just space them out more? 140 To be sure - some of these problems are not totally resolved by a 141 series approach but they become more tractable. An approach on how 142 to mitigate these problems is defined later on in this specification. 144 2.2. Splitting recurrences 146 The [RFC5545] THISANDFUTURE range is poorly supported. Splitting is 147 what a number of implementations use to avoid changing overrrides in 148 the past. 150 The recurring event is split into 2, one being the truncated original 151 the other being a new recurring event starting at the time of the 152 THISANDFUTURE override. 154 There is left the problem of relating the two, this can be 155 accomplished by use of the RELATED-TO property but that is not 156 standardized. 158 3. Series 160 A series is a, generally regularly, repeating sets of events or tasks 161 each instance of which is usually, but not always, different in some 162 respect. Examples may be a library running an after-school reading 163 program which usually, takes place at the same time each week but 164 always differs in the book or author being studied. 166 In recurrences an instances is a calculated 'virtual' object, unless 167 overridden. It has the same UID as the master and a RECURRENCE-ID 168 which is always one of the calculated set. 170 In a series, a specified number of instances are created ahead of 171 time each with their own unique UID. They are all related to the 172 master using a SERIES-MASTER relation type defined in this 173 specification. Each instance acts as an individual component as far 174 as retrieval and searching is concerned. 176 Each instance and master is identified as a member of the full series 177 by the SERIES-UID property. The value of this property is the same 178 in all members of the series even when splits have occurred. 180 As instances are created a LAST-SERIES-ID property is added or 181 updated in the master to indicate which instance was last created. 182 When there are SXDATE properties this property value may represent an 183 instance which cannot be created. It merely represents the latest 184 calculated date. 186 This property allows generated instances to be deleted without the 187 addition of SXDATE properties to the master. The SXDATE only 188 indicates future instances which MUST NOT be created. 190 As time goes on more instances are created either by the server or by 191 a client when it inspects the current state of the series. The 192 number of instances may be based on time or a count. 194 For example, an organization may allow rooms to be booked only 4 195 weeks ahead. Thus a series may be set up which has that 4 week set 196 of events in the future. Each will have the room as an attendee 197 ensuring that at least the room is booked at the regular time. 199 This does not prevent a client or server from creating dummy events 200 out into the future as a guide for people managing their calendars. 201 The application or server merely has to ensure that those dummy 202 events are marked as such and are read-only. 204 To facilitate this there is a new SITEM-STATUS property which may be 205 used to mark such an instance. 207 3.1. Modifying series patterns and splitting 209 If it becomes necessary to modify the series rules or the master 210 start then the series is always split at the point of the 211 modification. 213 When a series is split the previous master is modifed to truncate the 214 current series at the last generated instance and a parameter 215 SPLIT=YES is added to the series rule to indicate that this master is 216 now split. 218 The split may result in a number of instances related to the old 219 series but overlapping the new. It is up to the implementation to 220 decide what should be done with these but this usually requires a 221 degree of interaction with a human (or very intelligent robot). The 222 application may offer to copy them into the corresponding new 223 instances - if these can be easily determined, offer to delete all of 224 them or let the user manually copy information and delete. 226 The new series master is related to the old master by the new series 227 master having a RELATED-TO property with RELTYPE=SERIES-MASTER 228 pointing at the previous master. In that way a backwards chain of 229 series masters may be created 231 3.2. The series master 233 A series master is identified in much the same way as a recurrence 234 master. It will contain an SRULE and 0 or more SDATE properties or 1 235 or more SDATE properties. Additionally it may contain 0 or more 236 SXDATE properties to exclude instances. 238 As noted above, if the series was split it may contain a RELATED-TO 239 property with RELTYPE=SERIES-MASTER and a value of the previous 240 series master. 242 The master will also contain a LAST-SERIES-ID if any instances have 243 been calculated and perhaps generated. 245 It is important to note that the series master is NOT a member of the 246 series. This makes it easier for services to filter out series 247 masters. 249 3.3. The series instances 251 A series instance is identified by having a SERIES-ID property which 252 is calculated in the same manner as a RECURRENCE-ID. It MUST also 253 contain a RELATED-TO property with RELTYPE=SERIES-MASTER and a value 254 being the UID of the series master. 256 As noted above, if the series was split it may contain a RELATED-TO 257 property with RELTYPE=SERIES-MASTER and a value being the UID of the 258 previous series master. 260 4. Redefined Relation Type Value 262 Relationship parameter type values are defined in section 3.2.15. of 263 [RFC5545]. This specification augments that parameter to include the 264 new relationship values SERIES-MASTER 266 Format Definition: 268 This property parameter is respecified as follows: 270 reltypeparam = "RELTYPE" "=" 271 ("PARENT" ; Parent relationship - Default 272 / "CHILD" ; Child relationship 273 / "SIBLING" ; Sibling relationship 274 / "DEPENDS-ON" ; refers to previous task 275 / "REFID" ; Relationship based on REFID 276 / "STRUCTURED-CATEGORY" 277 ; Relationship based on STRUCTURED-CATEGORY 278 / "FINISHTOSTART" ; Temporal relationship 279 / "FINISHTOFINISH" ; Temporal relationship 280 / "STARTTOFINISH" ; Temporal relationship 281 / "STARTTOSTART" ; Temporal relationship 282 / "SERIES-MASTER" ; link to the master component 283 / iana-token ; Some other IANA-registered 284 ; iCalendar relationship type 285 / x-name) ; A non-standard, experimental 286 ; relationship type 288 Description: This parameter can be specified on a property that 289 references another related calendar component. The parameter may 290 specify the hierarchical relationship type of the calendar 291 component referenced by the property when the value is PARENT, 292 CHILD or SIBLING. If this parameter is not specified on an 293 allowable property, the default relationship type is PARENT. 294 Applications MUST treat x-name and iana-token values they don't 295 recognize the same way as they would the PARENT value. 297 This parameter defines the temporal relationship when the value is 298 one of the project management standard relationships 299 FINISHTOSTART, FINISHTOFINISH, STARTTOFINISH or STARTTOSTART. 300 This property will be present in the predecessor entity and will 301 refer to the successor entity. The GAP parameter specifies the 302 lead or lag time between the predecessor and the successor. In 303 the description of each temporal relationship below we refer to 304 Task-A which contains and controls the relationship and Task-B the 305 target of the relationship. 307 RELTYPE=PARENT: See [RFC5545] section 3.2.15. 309 RELTYPE=CHILD: See [RFC5545] section 3.2.15. 311 RELTYPE=SIBLING: See [RFC5545] section 3.2.15. 313 RELTYPE=DEPENDS-ON: Indicates that the current calendar component 314 depends on the referenced calendar component in some manner. For 315 example a task may be blocked waiting on the other, referenced, 316 task. 318 RELTYPE=REFID: Establishes a reference from the current component to 319 components with a REFID property which matches the value given in 320 the associated RELATED-TO property. 322 RELTYPE=SERIES-MASTER: Indicates that the current calendar component 323 is bsed on the referenced calendar component. The value is a UID. 325 RELTYPE=STRUCTURED-CATEGORY: Establishes a reference from the 326 current component to components with a STRUCTURED-CATEGORY 327 property which matches the value given in the associated RELATED- 328 TO property. 330 RELTYPE=FINISHTOSTART: Task-B cannot start until Task-A finishes. 331 For example, when sanding is complete, painting can begin. 333 ============ 334 | Task-A |--+ 335 ============ | 336 | 337 V 338 ============ 339 | Task-B | 340 ============ 342 Figure 1: Finish to start relationship 344 RELTYPE=FINISHTOFINISH: Task-B cannot finish before Task-A is 345 finished, that is the end of Task-A defines the end of Task-B. 346 For example, we start the potatoes, then the meat then the peas 347 but they should all be cooked at the same time. 349 ============ 350 | Task-A |--+ 351 ============ | 352 | 353 ============ | 354 | Task-B |<-+ 355 ============ 357 Figure 2: Finish to finish relationship 359 RELTYPE=STARTTOFINISH: The start of Task-A (which occurs after Task- 360 B) controls the finish of Task-B. For example, ticket sales 361 (Task-B) end when the game starts (Task-A). 363 ============ 364 +--| Task-A | 365 | ============ 366 | 367 ============ | 368 | Task-B |<-+ 369 ============ 371 Figure 3: Start to finish relationship 373 RELTYPE=STARTTOSTART: The start of Task-A triggers the start of 374 Task-B, that is Task-B can start anytime after Task-A starts. 376 ============ 377 +--| Task-A | 378 | ============ 379 | 380 | ============ 381 +->| Task-B | 382 ============ 384 Figure 4: Start to start relationship 386 5. New Property Parameters 388 5.1. Split 390 Parameter name: SPLIT 392 Purpose: To indicate a series has been split. 394 Format Definition: 396 This parameter is defined by the following notation: 398 splitparam = "SPLIT" "=" 399 ("YES" ; The series is split 400 / "NO" ; The series is not split (default) 401 / x-name ; Experimental reference type 402 / iana-token) ; Other IANA registered type 404 Description: This parameter MAY be specified on the SRULE property 405 to indicate that the series has been split with SPLIT=YES. Once 406 split is is probably innapropriate to modify the series further. 408 5.2. Lookahead count 410 Parameter name: LOOKAHEAD-COUNT 412 Purpose: To specify the number of series instances that should be 413 generated in advance. 415 Format Definition: 417 This parameter is defined by the following notation: 419 lookahead-countparam = "LOOKAHEAD-COUNT" "=" 1*DIGIT 421 Description: This parameter MAY be specified on the SRULE property 422 to indicate how many series instances should be generated in 423 advance. 425 An implementation is free to apply its own limts but MUST NOT 426 generate more than those defined by this parameter and/or the 427 LOOKAHEAD-PERIOD parameter. 429 If both the LOOKAHEAD-PERIOD and LOOKAHEAD-COUNT arameters are 430 supplied the result should be limited by both. 432 For example, if the LOOKAHEAD-PERIOD parameter would cause 8 433 instances to be generated but LOOKAHEAD-COUNT specifies 4 then 434 only 4 instances will be generated. 436 5.3. Lookahead period 438 Parameter name: LOOKAHEAD-PERIOD 440 Purpose: To specify a maximum period for which series instances 441 should be generated in advance. 443 Format Definition: 445 This parameter is defined by the following notation: 447 lookahead-periodparam = "LOOKAHEAD-PERIOD" "=" 448 DQUOTE dur-value DQUOTE 450 Description: This parameter MAY be specified on the SRULE property 451 to indicate how far in advance series instances should be 452 generated. 454 An implementation is free to apply its own limts but MUST NOT 455 generate more than those defined by this parameter and/or the 456 LOOKAHEAD-COUNT parameter. 458 If both the LOOKAHEAD-PERIOD and LOOKAHEAD-COUNT arameters are 459 supplied the result should be limited by both. 461 For example, if the LOOKAHEAD-PERIOD parameter would cause 8 462 instances to be generated but LOOKAHEAD-COUNT specifies 4 then 463 only 4 instances will be generated. 465 The value is a quoted duration. 467 6. New Properties 469 The SERIES-ID, LAST-SERIES-ID, SDATE and SXDATE properties are 470 identical in form and in the parameters they take. 472 All must conform in form to the DTSTART property of the master 473 component. Only the SDATE may specify a time which is not part of 474 the calculated series. 476 The SRULE property value is identical in form to the RRULE property 477 defined in [RFC5545]. The LOOKAHEAD-COUNT and LOOKAHEAD-PERIOD 478 parameters indicate how many instances should be generated in 479 advance. 481 6.1. Generating Series members 483 An agent, either the server or a client, will periodically extend the 484 set of instances. The number of such generated instances is limited 485 by: 487 Elements of the rule: The UNTIL or COUNT parts of the rule define 488 when the series terminates. Thus a COUNT=100 specifies a maximum 489 of 100 series members. 491 Lookahead count: This specifies how many series memerbs can exist 492 from the current date/time. Thus a LOOKAHEAD-COUNT=4 means a 493 maximum of 4 generated instances. 495 Lookahead period: This specifies how far into the future series 496 members can be generated. Thus a LOOKAHEAD-PERIOD="PT2M" means a 497 maximum period of 2 months. 499 System limits: This client or server SHOULD also apply limits to 500 prevent a series from generating an overlarge set of members. 502 The starting point for the calculation is the DTSTART of the master 503 component or the LAST-SERIES-ID if it exists in the master. In both 504 cases the instance represented by that date is NOT generated as part 505 of the intance set and the actual instance may have been excluded by 506 an SXDATE property but the starting date is still valid. 508 The starting date/time property defines the first instance in the 509 next batch of series members. Note that the starting property value 510 MUST match the pattern of the series rule, if specified. For 511 example, if the rule specifies every Wednesday the starting date MUST 512 be a Wednesday. 514 The end date/time of the set will be provided by the UNTIL part of 515 the rule, the LOOKAHEAD-PERIOD or by a system maxima. 517 A set of date/time values can be generated within those contraints. 518 As each date/time value is generated it can be ignored if it is one 519 of the SXDATE values. 521 Generation of values can terminate when the size of the result 522 exceeds that given by the COUNT rule element, the LOOKAHEAD-COUNT 523 value or any systm limit. 525 Any SDATE values that fall within the current range and are not in 526 the set of SXDATE values can be added and the result truncated again 527 to match the size limits. 529 Finally, any date/time values that have already been generated and 530 are present as SERIES-ID values should be removed from the set. What 531 remains is the new set of members to extend the current series. 533 The last of those values becomes the new value for the LAST-SERIES-ID 534 property in the series master. 536 As noted above the "SXDATE" property can be used to exclude the value 537 specified in the master. This leads to a complication as the master 538 needs to be preserved as a container for the values which define the 539 series. This is flagged by adding a DELETED-MASTER element to the 540 SERIES-STATUS property. 542 6.2. Series UID 544 Property name: SERIES-UID 545 Purpose: This property defines the persistent, globally unique 546 identifier for the full series. 548 Value Type: TEXT 550 Property Parameters: IANA and non-standard property parameters can 551 be specified on this property. 553 Conformance: This property MUST be specified in any "VEVENT", 554 "VTODO", and "VJOURNAL" calendar components acting as a series 555 master or series instance. 557 Description: The SERIES-UID MUST be globally unique. This value 558 SHOULD be generated by following the recommendations in section 559 5.3 of [RFC7986]. 561 Format Definition: 563 This property is defined by the following notation: 565 seruid = "SERIES-UID" seruidparam ":" text CRLF 567 seruidparam = *(";" other-param) 569 Example: 571 The following is an example of this property: 573 SERIES-UID:123e4567-e89b-12d3-a456-426655440000 575 6.3. Series-exception-date 577 Property name: SXDATE 579 Purpose: This property defines the list of DATE-TIME exceptions for 580 series of events, to-dos or journal entries. 582 Value Type: The default value type for this property is DATE-TIME. 583 The value type can be set to DATE. 585 Property Parameters: IANA, non-standard, value data type, and time 586 zone identifier property parameters can be specified on this 587 property. 589 Conformance: This property can be specified in "VEVENT", "VTODO", 590 and "VJOURNAL" calendar components acting as the series master. 592 Description: The exception dates, if specified, are used when 593 computing the instances of the series. They specify date/time 594 values which are to be removed from the set of possible series 595 instances. 597 Format Definition: 599 This property is defined by the following notation: 601 sxdate = "SXDATE" sxdtparam ":" sxdtval *("," sxdtval) CRLF 603 sxdtparam = *( 604 ; 605 ; The following are OPTIONAL, 606 ; but MUST NOT occur more than once. 607 ; 608 (";" "VALUE" "=" ("DATE-TIME" / "DATE")) / 609 ; 610 (";" tzidparam) / 611 ; 612 ; The following is OPTIONAL, 613 ; and MAY occur more than once. 614 ; 615 (";" other-param) 616 ; 617 ) 619 sxdtval = date-time / date 620 ;Value MUST match value type 622 Example: 624 The following is an example of this property: 626 SXDATE:19960402T010000Z,19960403T010000Z,19960404T010000Z 628 6.4. Series-date 630 Property name: SDATE 632 Purpose: This property defines the list of DATE-TIME values for 633 series of events, to-dos or journal entries. 635 Value Type: The default value type for this property is DATE-TIME. 636 The value type can be set to DATE. 638 Property Parameters: IANA, non-standard, value data type, and time 639 zone identifier property parameters can be specified on this 640 property. 642 Conformance: This property can be specified in "VEVENT", "VTODO", 643 and "VJOURNAL" calendar components acting as the series master. 645 Description: This property can appear along with the "SRULE" 646 property to define a extra series occurrences. When they both 647 appear in a series master component, the instances are defined by 648 the union of occurrences defined by both the "SDATE" and "SRULE". 650 Purpose: 652 This property is defined by the following notation: 654 sdate = "SDATE" sdtparam ":" sdtval *("," sdtval) CRLF 656 sdtparam = *( 657 ; 658 ; The following are OPTIONAL, 659 ; but MUST NOT occur more than once. 660 ; 661 (";" "VALUE" "=" ("DATE-TIME" / "DATE" / "PERIOD")) / 662 (";" tzidparam) / 663 ; 664 ; The following is OPTIONAL, 665 ; and MAY occur more than once. 666 ; 667 (";" other-param) 668 ; 669 ) 671 sdtval = date-time / date 672 ;Value MUST match value type 674 Example: 676 The following are examples of this property: 678 SDATE:19970714T123000Z 679 SDATE;TZID=America/New_York:19970714T083000 681 SDATE;VALUE=PERIOD:19960403T020000Z/19960403T040000Z, 682 19960404T010000Z/PT3H 684 SDATE;VALUE=DATE:19970101,19970120,19970217,19970421 685 19970526,19970704,19970901,19971014,19971128,19971129,19971225 687 6.5. Series-id 689 Property name: SERIES-ID 691 Purpose: This property is used in conjunction with the "UID" and 692 "SEQUENCE" properties to identify a specific instance of a 693 "VEVENT", "VTODO", or "VJOURNAL" calendar component in a series. 694 The property value is the original value of the "DTSTART" property 695 of the series instance before any changes occur. 697 Value type: The default value type is DATE-TIME. The value type can 698 be set to a DATE value type. This property MUST have the same 699 value type as the "DTSTART" property contained within the series 700 component. Furthermore, this property MUST be specified as a date 701 with local time if and only if the "DTSTART" property contained 702 within the series component is specified as a date with local 703 time. 705 Property Parameters: IANA, non-standard, value data type and time 706 zone identifier parameters can be specified on this property. 708 Conformance: This property can be specified zero or more times in 709 any iCalendar component. 711 Description: The SERIES-ID is the originally calculated value of the 712 DTSTART property based on the master identified by the RELATED-TO 713 property with a RELTYPE=SERIES-MASTER parameter. 715 The full series of components can only be retrieved by searching 716 for all components with a matching RELATED-TO property. 718 If the value of the "DTSTART" property is a DATE type value, then 719 the value MUST be the calendar date for the series instance. 721 The DATE-TIME value is set to the time when the original series 722 instance would occur; meaning that if the intent is to change a 723 Friday meeting to Thursday, the DATE-TIME is still set to the 724 original Friday meeting. 726 The "SERIES-ID" property is used in conjunction with the "UID" and 727 "SEQUENCE" properties to identify a particular instance of an 728 event, to-do, or journal in the series. For a given pair of "UID" 729 and "SEQUENCE" property values, the "SERIES-ID" value for a series 730 instance is fixed. 732 Format Definition: 734 This property is defined by the following notation: 736 serid = "SERIES-ID" sidparam ":" sidval CRLF 738 sidparam = *( 739 ; 740 ; The following are OPTIONAL, 741 ; but MUST NOT occur more than once. 742 ; 743 (";" "VALUE" "=" ("DATE-TIME" / "DATE")) / 744 (";" tzidparam) / 745 ; 746 ; The following is OPTIONAL, 747 ; and MAY occur more than once. 748 ; 749 (";" other-param) 750 ; 751 ) 753 sidval = date-time / date 754 ;Value MUST match value type 756 Example: 758 The following are examples of this property: 760 SERIES-ID;VALUE=DATE:19960401 762 SERIES-ID;TZID=America/New_York:20170120T120000 764 6.6. Last series id 766 Property name: LAST-SERIES-ID 768 Purpose: To specify the last calculated instance of the series. 769 When new instances are created they MUST have a SERIES-ID after 770 the value of this property. 772 In all respects this property is identical to SERIES-ID and is in 773 fact a copy of the SERIES-ID which would be present in the last 774 created instance (assuming it is not suppressed by an SXDATE). 776 Value type: DATE or DATE_TIME (the default). This has the same 777 requirements as SERIES-ID. 779 Property Parameters: IANA, non-standard, value data type and time 780 zone identifier parameters can be specified on this property. 782 Conformance: This property MAY be specified in any iCalendar 783 component. 785 Description: This property allows a client or server to delete the 786 trailing instances in a series without having them recreated by 787 some other agent. 789 Format Definition: 791 This property is defined by the following notation: 793 last-series-i = "LAST-SERIES-ID" lastseriesidparam / 794 ( 795 ";" "VALUE" "=" "TEXT" 796 ":" text 797 ) 798 ( 799 ";" "VALUE" "=" "REFERENCE" 800 ":" text 801 ) 802 ( 803 ";" "VALUE" "=" "URI" 804 ":" uri 805 ) 806 CRLF 808 lastseriesidparam = *( 810 ; the following is MANDATORY 811 ; and MAY occur more than once 813 (";" relparam) / 815 ; the following are MANDATORY 816 ; but MUST NOT occur more than once 818 (";" fmttypeparam) / 819 (";" labelparam) / 820 ; labelparam is defined in ... 822 ; the following is OPTIONAL 823 ; and MAY occur more than once 825 (";" xparam) 827 ) 829 Example: 831 The following is an example of this property. It points to a server 832 acting as the source for the calendar object. 834 LINK;REL=SOURCE;LABEL=The Egg:http://example.com/events 836 6.7. Series Rule 838 Property name: SRULE 840 Purpose: This property defines a rule or repeating pattern for a 841 series of events, to-dos or journal entries. 843 Value Type: RECUR 845 Property Parameters: IANA, non-standard, look-ahead count or date 846 property parameters can be specified on this property. 848 Conformance: This property can be specified in any "VEVENT", 849 "VTODO", and "VJOURNAL" calendar component. 851 [RFC5545] states that the RRULE component SHOULD only appear once. 852 This is unduly limiting for those applications that require more 853 than one rule to specify the series. In fact, some complex rules 854 are better expressed as multiple rules. Recipients of iCalendar 855 data containing SRULE MUST support the occurrence of multiple 856 SRULEs. 858 Clients and servers MAY choose to reduce the number of SRULE 859 properties to 1. In reality many - if not most - clients are 860 unable to handle the full set of SRULE or RRULE features. 862 Description: The series rule, if specified, is used in computing the 863 instances to be generated for the series. These are generated by 864 considering the master "DTSTART" property along with the "SRULE", 865 "SDATE", and "SXDATE" properties contained within the series 866 master. The "DTSTART" property defines the first instance in the 867 recurrence set which is represented by that master event. 869 Unlike the RRULE the "DTSTART" property MUST be synchronized with 870 the series rule, if specified. For example, if the DTSTART 871 specifies a date on Wednesday but the SRULE specifies every 872 Tuesday then a server or client MUST reject the component. 874 The final series is represented by gathering all of the start 875 DATE-TIME values generated by any of the specified "SRULE" and 876 "SDATE" properties, and then excluding any start DATE-TIME values 877 specified by "SXDATE" properties. This implies that start DATE- 878 TIME values specified by "SXDATE" properties take precedence over 879 those specified by inclusion properties (i.e., "SDATE" and 880 "SRULE"). Where duplicate instances are generated by the "SRULE" 881 and "SDATE" properties, only one instance is considered. 882 Duplicate instances are ignored. 884 The "DTSTART" property specified within the master iCalendar 885 object defines the first instance of the recurrence. In most 886 cases, a "DTSTART" property of DATE-TIME value type used with a 887 series rule, should be specified as a date with local time and 888 time zone reference to make sure all the recurrence instances 889 start at the same local time regardless of time zone changes. 891 If the duration of the series component is specified with the 892 "DTEND" or "DUE" property, then the same exact duration will apply 893 to all the members of the generated series. Else, if the duration 894 of the series master component is specified with the "DURATION" 895 property, then the same nominal duration will apply to all the 896 members of the generated series and the exact duration of each 897 instance will depend on its specific start time. For example, 898 series instances of a nominal duration of one day will have an 899 exact duration of more or less than 24 hours on a day where a time 900 zone shift occurs. The duration of a specific instance may be 901 modified in an exception component or simply by using an "SDATE" 902 property of PERIOD value type. 904 Format Definition: 906 This property is defined by the following notation: 908 srule = "SRULE" srulparam ":" recur CRLF 910 sruleparam = *( 911 ; the following are OPTIONAL 912 ; but MUST NOT occur more than once 914 (";" lookahead-countparam) / 915 (";" lookahead-periodparam) / 917 ; the following is OPTIONAL 918 ; and MAY occur more than once 920 (";" xparam) 922 ) 924 Examples: Refer to [RFC5545] for example of the use of RRULE which 925 has identical format. 927 6.8. SITEM-STATUS Property 929 Property name: SITEM-STATUS 931 Purpose: This property is used to define the status of a series 932 item. 934 Conformance: This property MAY be specified in any iCalendar series 935 item. 937 Description: An item may be generated to provide an indication to a 938 user or client of when an event may occur - even if that event is 939 outside of the generated period. 941 When this property is absent the series item is treated as a 942 concrete item which may be updated subject to the constraints of 943 the server/storage for the item. 945 Format Definition: 947 This property is defined by the following notation: 949 sitem-status = "SITEM-STATUS" sisparam ":" SISvalue CRLF 951 sisparam = *(";" other-param) 953 sisvalue = "DUMMY" ; This item is generated as an indication of where 954 ; an item might appear when it is generated 955 / iana-token 956 / x-name 958 Example: 960 The following is an example of this property. 962 SITEM-STATUS:DUMMY 964 7. Redefined RELATED-TO Property 966 7.1. RELATED-TO 968 Property name: RELATED-TO 970 Purpose: This property is used to represent a relationship or 971 reference between one calendar component and others. The 972 definition here extends the definition in Section 3.8.4.5. of 973 [RFC5545] by including a section on RELTYPE=SERIES-MASTER. 975 Value type: URI, UID or TEXT 977 Property Parameters: Relationship type, IANA and non-standard 978 property parameters can be specified on this property. 980 Conformance: This property MAY be specified in any iCalendar 981 component. 983 Description: By default or when VALUE=UID is specified, the property 984 value consists of the persistent, globally unique identifier of 985 another calendar component. This value would be represented in a 986 calendar component by the "UID" property. 988 By default, the property value points to another calendar 989 component that has a PARENT relationship to the referencing 990 object. The "RELTYPE" property parameter is used to either 991 explicitly state the default PARENT relationship type to the 992 referenced calendar component or to override the default PARENT 993 relationship type and specify either a CHILD or SIBLING 994 relationship or a temporal relationship. 996 The PARENT relationship indicates that the calendar component is a 997 subordinate of the referenced calendar component. The CHILD 998 relationship indicates that the calendar component is a superior 999 of the referenced calendar component. The SIBLING relationship 1000 indicates that the calendar component is a peer of the referenced 1001 calendar component. 1003 The FINISHTOSTART, FINISHTOFINISH, STARTTOFINISH or STARTTOSTART 1004 relationships define temporal relationships as specified in the 1005 reltype parameter definition. 1007 The SERIES-MASTER relationship when included in a series instance 1008 refers to the master of that series. When included in a series 1009 master it refers to a previous master in a chain of spilt series. 1011 Changes to a calendar component referenced by this property can 1012 have an implicit impact on the related calendar component. For 1013 example, if a group event changes its start or end date or time, 1014 then the related, dependent events will need to have their start 1015 and end dates changed in a corresponding way. Similarly, if a 1016 PARENT calendar component is cancelled or deleted, then there is 1017 an implied impact to the related CHILD calendar components. This 1018 property is intended only to provide information on the 1019 relationship of calendar components. It is up to the target 1020 calendar system to maintain any property implications of this 1021 relationship. 1023 Format Definition: 1025 This property is defined by the following notation: 1027 related = "RELATED-TO" relparam ( ":" text ) / 1028 ( 1029 ";" "VALUE" "=" "UID" 1030 ":" uid 1031 ) 1032 ( 1033 ";" "VALUE" "=" "URI" 1034 ":" uri 1035 ) 1036 CRLF 1038 relparam = *( 1039 ; 1040 ; The following are OPTIONAL, 1041 ; but MUST NOT occur more than once. 1042 ; 1043 (";" reltypeparam) / 1044 (";" gapparam) / 1045 ; 1046 ; The following is OPTIONAL, 1047 ; and MAY occur more than once. 1048 ; 1049 (";" other-param) 1050 ; 1051 ) 1053 Example: 1055 The following are examples of this property. 1057 RELATED-TO;RELTYPE=SERIES-MASTER:19960401-080045-4000F192713 1059 8. Backwards compatibility 1061 Any clients following the approach specified in [RFC5545] are 1062 expected to ignore any properties, parameters or components they 1063 don't recognize. 1065 For such clients the series appears to be an unconnected set of 1066 components. They all have their own unique UIDS. If the client 1067 updates an instance this should be identical in effect to an update 1068 carried out by a client aware of the new properties. 1070 Updates MUST preserve the SERIES-ID, LAST-SERIES-ID, SRULE, SDATE and 1071 SXDATE properties. A client which does not do so is in violation of 1072 [RFC5545]. 1074 There are two possible problem areas: first we must prevent series 1075 unaware clients from updating the masters and secondly we must 1076 prevent attempts to update dummy instances. 1078 Both case are handled by the definition of a new header field : 1079 "ICAL-SERIES". The presence of this header field in requests from a 1080 client indicates that it is aware of this specification. In the 1081 absence of the header servers MUST NOT send master template items. 1083 In the case of an absent header servers MUST refuse to accept updates 1084 to dummy items - e.g. with an HTTP forbidden status in CalDAV. 1086 9. CalDAV extensions 1088 This specification may extend Caldav by adding reports to return all 1089 members of a series given the series master UID. This could be 1090 handled by the current query mechanism but it is likely to be 1091 sufficiently frequently used that a special query is appropriate. 1093 It is also likely we will want a CalDAV operation to split a series 1094 and generate the additional members of the series as a single atomic 1095 operation. 1097 10. Security Considerations 1099 Clients and servers should take care to limit the number of generated 1100 instances to a reasonable value. This can be a relatively small 1101 value. 1103 11. IANA Considerations 1105 11.1. iCalendar Property Registrations 1107 The following iCalendar property names have been added to the 1108 iCalendar Properties Registry defined in Section 8.3.2 of [RFC5545] 1109 +----------------+---------+-------------+ 1110 | Property | Status | Reference | 1111 +----------------+---------+-------------+ 1112 | LAST-SERIES-ID | Current | Section 6.6 | 1113 | SERIES-ID | Current | Section 6.5 | 1114 | SERIES-UID | Current | Section 6.2 | 1115 | SDATE | Current | Section 6.4 | 1116 | SRULE | Current | Section 6.7 | 1117 | SXDATE | Current | Section 6.3 | 1118 +----------------+---------+-------------+ 1120 11.2. iCalendar Property Parameter Registrations 1122 The following iCalendar property parameter names have been added to 1123 the iCalendar Parameters Registry defined in Section 8.3.3 of 1124 [RFC5545] 1126 +------------------+---------+-------------+ 1127 | Parameter | Status | Reference | 1128 +------------------+---------+-------------+ 1129 | LOOKAHEAD-COUNT | Current | Section 5.2 | 1130 | LOOKAHEAD-PERIOD | Current | Section 5.3 | 1131 | SPLIT | Current | Section 5.1 | 1132 +------------------+---------+-------------+ 1134 11.3. iCalendar RELTYPE Value Registrations 1136 The following iCalendar "RELTYPE" values have been added to the 1137 iCalendar Relationship Types Registry defined in Section 8.3.8 of 1138 [RFC5545] 1140 +-------------------+---------+-----------+ 1141 | Relationship Type | Status | Reference | 1142 +-------------------+---------+-----------+ 1143 | SERIES-ID | Current | Section 4 | 1144 +-------------------+---------+-----------+ 1146 12. Acknowledgements 1148 The author would like to thank the members of the Calendaring and 1149 Scheduling Consortium technical committees and the following 1150 individuals for contributing their ideas, support and comments: 1152 The author would also like to thank the Calendaring and Scheduling 1153 Consortium for advice with this specification. 1155 13. Normative References 1157 [I-D.daboo-caldav-attachments] 1158 Daboo, C. and A. Quillaud, "CalDAV Managed Attachments", 1159 draft-daboo-caldav-attachments-03 (work in progress), 1160 February 2014. 1162 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1163 Requirement Levels", BCP 14, RFC 2119, 1164 DOI 10.17487/RFC2119, March 1997, 1165 . 1167 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1168 Resource Identifier (URI): Generic Syntax", STD 66, 1169 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1170 . 1172 [RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and 1173 Scheduling Core Object Specification (iCalendar)", 1174 RFC 5545, DOI 10.17487/RFC5545, September 2009, 1175 . 1177 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 1178 DOI 10.17487/RFC5988, October 2010, 1179 . 1181 [RFC7986] Daboo, C., "New Properties for iCalendar", RFC 7986, 1182 DOI 10.17487/RFC7986, October 2016, 1183 . 1185 [W3C.REC-xml-20060816] 1186 Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and 1187 F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fourth 1188 Edition)", World Wide Web Consortium Recommendation REC- 1189 xml-20060816, August 2006, 1190 . 1192 [W3C.WD-xptr-xpointer-20021219] 1193 DeRose, S., Daniel, R., and E. Maler, "XPointer xpointer() 1194 Scheme", World Wide Web Consortium WD WD-xptr-xpointer- 1195 20021219, December 2002, 1196 . 1198 Appendix A. Points for discussion 1200 Splitting and linking: The spec currently only allows for backward 1201 linking to previous masters. There is a parameter added to the 1202 rule SPLIT=YES to indicate that the series was split 1203 It makes sense to have a forward link to the new(er) series. 1204 However, a client/server may not know what the UID is until after 1205 data is stored. The new chain can be determined via a query so 1206 perhaps we can leave it up to the protocols to figure out that 1207 mechanism. 1209 CalDAV queries: if there were a better more generalised query 1210 language such an extensions might be unnecessary. Should we 1211 define a query language specifically for calendaring? 1213 Appendix B. Change log 1215 2018-01-01 MD Better descriptions - LAST-SESSION-ID. 1217 2017-09-30 MD Minor updates: better backward compatibility. 1219 2017-02-12 MD Initial version 1221 Author's Address 1223 Michael Douglass 1224 Spherical Cow Group 1225 226 3rd Street 1226 Troy, NY 12180 1227 USA 1229 Email: mdouglass@sphericalcowgroup.com 1230 URI: http://sphericalcowgroup.com