idnits 2.17.1 draft-ietf-calext-icalendar-series-02.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 : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** The abstract seems to contain references ([RFC5545]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 193: '...e instances which MUST NOT be created....' RFC 2119 keyword, line 249: '...nner as a RECURRENCE-ID. It MUST also...' RFC 2119 keyword, line 294: '...T. Applications MUST treat x-name and...' RFC 2119 keyword, line 413: '... This parameter MAY be specified on t...' RFC 2119 keyword, line 434: '... This parameter MAY be specified on t...' (45 more instances...) -- The abstract seems to indicate that this document updates RFC5545, but the header doesn't have an 'Updates:' line to match this. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (14 October 2020) is 1284 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) No issues found here. Summary: 3 errors (**), 0 flaws (~~), 1 warning (==), 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 14 October 2020 4 Intended status: Standards Track 5 Expires: 17 April 2021 7 Support for Series in iCalendar 8 draft-ietf-calext-icalendar-series-02 10 Abstract 12 This document updates [RFC5545] by defining a new repeating set of 13 events known as a series. This differs from recurrences in that each 14 instance is a separate entity with a parent relationship to a 15 specified template entity. 17 Status of This Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at https://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on 17 April 2021. 34 Copyright Notice 36 Copyright (c) 2020 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 41 license-info) in effect on the date of publication of this document. 42 Please review these documents carefully, as they describe your rights 43 and restrictions with respect to this document. Code Components 44 extracted from this document must include Simplified BSD License text 45 as described in Section 4.e of the Trust Legal Provisions and are 46 provided without warranty as described in the Simplified BSD License. 48 Table of Contents 50 1. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 2 51 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 52 3. Terms and definitions . . . . . . . . . . . . . . . . . . . . 3 53 4. Overrides and iCalendar recurrences . . . . . . . . . . . . . 3 54 4.1. Changing the master start or the recurrence rules . . . . 3 55 4.2. Splitting recurrences . . . . . . . . . . . . . . . . . . 4 56 5. Series . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 57 5.1. Modifying series patterns and splitting . . . . . . . . . 5 58 5.2. The series master . . . . . . . . . . . . . . . . . . . . 6 59 5.3. The series instances . . . . . . . . . . . . . . . . . . 6 60 6. Redefined Relation Type Value . . . . . . . . . . . . . . . . 6 61 7. New Property Parameters . . . . . . . . . . . . . . . . . . . 9 62 7.1. Split . . . . . . . . . . . . . . . . . . . . . . . . . . 9 63 7.2. Lookahead count . . . . . . . . . . . . . . . . . . . . . 10 64 7.3. Lookahead period . . . . . . . . . . . . . . . . . . . . 10 65 8. New Properties . . . . . . . . . . . . . . . . . . . . . . . 11 66 8.1. General . . . . . . . . . . . . . . . . . . . . . . . . . 11 67 8.2. Generating Series members . . . . . . . . . . . . . . . . 11 68 8.3. Series UID . . . . . . . . . . . . . . . . . . . . . . . 13 69 8.4. Series-exception-date . . . . . . . . . . . . . . . . . . 13 70 8.5. Series-date . . . . . . . . . . . . . . . . . . . . . . . 15 71 8.6. Series-id . . . . . . . . . . . . . . . . . . . . . . . . 16 72 8.7. Last series ID . . . . . . . . . . . . . . . . . . . . . 18 73 8.8. Series Rule . . . . . . . . . . . . . . . . . . . . . . . 21 74 9. Redefined RELATED-TO Property . . . . . . . . . . . . . . . . 22 75 9.1. RELATED-TO . . . . . . . . . . . . . . . . . . . . . . . 22 76 10. Backwards compatibility . . . . . . . . . . . . . . . . . . . 24 77 11. CalDAV extensions . . . . . . . . . . . . . . . . . . . . . . 25 78 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 79 12.1. iCalendar Property Registrations . . . . . . . . . . . . 25 80 12.2. iCalendar Property Parameter Registrations . . . . . . . 26 81 12.3. iCalendar RELTYPE Value Registrations . . . . . . . . . 26 82 13. Normative references . . . . . . . . . . . . . . . . . . . . 26 83 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 26 85 1. Acknowledgements 87 The authors would like to thank the members of the Calendaring and 88 Scheduling Consortium (CalConnect) for contributing their ideas and 89 support. 91 2. Introduction 93 Since iCalendar was first defined there has been only one way to 94 express a repeating set of events - the recurrence. This defined a 95 master event, a set of rules for computing the instances and a way of 96 overriding certain instances. 98 This approach works well enough in certain situations but has many 99 problems which need to be addressed. 101 This specification introduces a new approach to repeating patterns of 102 entities which avoids some of the problems. 104 3. Terms and definitions 106 No terms and definitions are listed in this document. 108 4. Overrides and iCalendar recurrences 110 The recurrence rules specify how instances are to be computed. These 111 rules provide a set of keys - the RECURRENCE-ID - and an instance can 112 be created with the calculated start date/time and a copy of the 113 duration (or calculated end date/time). 115 The specification allows for overrides. These are handled by 116 supplying a complete replacement for the instance with a RECURRENCE- 117 ID property matching that of the instance being overridden. This may 118 change any of the properties (except the UID) - including start, end 119 or duration. 121 If a long lived recurrence is heavily overridden it becomes very 122 cumbersome. The master plus overrides is considered a single 123 resource in most circumstances (iTip allows the delivery of a single 124 instance in certain situations). 126 Simple meetings can become heavily modified recurrences through 127 adding the weeks agenda to the description, changing of attendees 128 etc. 130 There are approaches being considered to mitigate some of these 131 issues which mostly involve only storing changes but recurrences are 132 still awkward to deal with. 134 4.1. Changing the master start or the recurrence rules 136 This can lead to some very difficult problems to resolve. In the 137 case of a heavily modified meeting it may be difficult to impossible 138 to determine which override applies to the newly modified event. 140 For example, a weekly book-reading is moved from Monday to Friday. 141 There are weeks of scheduled events in the future. Do we move them 142 all forward to the next instance or skip one and move them back? If 143 it becomes bi-weekly rather than weekly do we drop every other or 144 just space them out more? 146 To be sure - some of these problems are not totally resolved by a 147 series approach but they become more tractable. 149 4.2. Splitting recurrences 151 The [RFC5545] THISANDFUTURE range is poorly supported. Splitting is 152 what a number of implementations use to avoid changing overrides in 153 the past. 155 The recurring event is split into 2, one being the truncated original 156 the other being a new recurring event starting at the time of the 157 THISANDFUTURE override. 159 There is left the problem of relating the two, this can be 160 accomplished by use of the RELATED-TO property but that is not 161 standardized. 163 5. Series 165 A series is a, generally regularly, repeating sets of events or tasks 166 each instance of which is usually, but not always, different in some 167 respect. Examples may be a library running an after-school reading 168 program which usually, takes place at the same time each week but 169 always differs in the book or author being studied. 171 In recurrences an instances is a calculated 'virtual' object, unless 172 overridden. It has the same UID as the master and a RECURRENCE-ID 173 which is always one of the calculated set. 175 In a series, a specified number of instances are created ahead of 176 time each with their own unique UID. They are all related to the 177 master using a SERIES-MASTER relation type defined in this 178 specification. Each instance acts as an individual component as far 179 as retrieval and searching is concerned. 181 Each instance and master is identified as a member of the full series 182 by the SERIES-UID property. The value of this property is the same 183 in all members of the series even when splits have occurred. 185 As instances are created a LAST-SERIES-ID property is added or 186 updated in the master to indicate which instance was last created. 187 When there are SXDATE properties this property value may represent an 188 instance which cannot be created. It merely represents the latest 189 calculated date. 191 This property allows generated instances to be deleted without the 192 addition of SXDATE properties to the master. The SXDATE only 193 indicates future instances which MUST NOT be created. 195 As time goes on more instances are created either by the server or by 196 a client when it inspects the current state of the series. The 197 number of instances may be based on time or a count. 199 For example, an organization may allow rooms to be booked only 4 200 weeks ahead. Thus a series may be set up which has that 4 week set 201 of events in the future. Each will have the room as an attendee 202 ensuring that at least the room is booked at the regular time. 204 5.1. Modifying series patterns and splitting 206 If it becomes necessary to modify the series rules or the master 207 start then the series is always split at the point of the 208 modification. 210 When a series is split the previous master is modifed to truncate the 211 current series at the last generated instance and a parameter 212 SPLIT=YES is added to the series rule to indicate that this master is 213 now split. 215 The split may result in a number of instances related to the old 216 series but overlapping the new. It is up to the implementation to 217 decide what should be done with these but this usually requires a 218 degree of interaction with a human (or very intelligent robot). The 219 application may offer to copy them into the corresponding new 220 instances - if these can be easily determined, offer to delete all of 221 them or let the user manually copy information and delete. 223 The new series master is related to the old master by the new series 224 master having a RELATED-TO property with RELTYPE=SERIES-MASTER 225 pointing at the previous master. In that way a backwards chain of 226 series masters may be created 228 5.2. The series master 230 A series master is identified in much the same way as a recurrence 231 master. It will contain an SRULE and 0 or more SDATE properties or 1 232 or more SDATE properties. Additionally it may contain 0 or more 233 SXDATE properties to exclude instances. 235 As noted above, if the series was split it may contain a RELATED-TO 236 property with RELTYPE=SERIES-MASTER and a value of the previous 237 series master. 239 The master will also contain a LAST-SERIES-ID if any instances have 240 been calculated and perhaps generated. 242 It is important to note that the series master is the first member of 243 the series. Thus the first instance always occurs AFTER the series 244 master. 246 5.3. The series instances 248 A series instance is identified by having a SERIES-ID property which 249 is calculated in the same manner as a RECURRENCE-ID. It MUST also 250 contain a RELATED-TO property with RELTYPE=SERIES-MASTER and a value 251 being the UID of the series master. 253 As noted above, if the series was split it may contain a RELATED-TO 254 property with RELTYPE=SERIES-MASTER and a value being the UID of the 255 previous series master. 257 6. Redefined Relation Type Value 259 Relationship parameter type values are defined in [RFC5545]. This 260 specification augments that parameter to include the new relationship 261 values SERIES-MASTER. 263 Format Definition 265 This property parameter is respecified as follows: 267 reltypeparam = "RELTYPE" "=" 268 ("PARENT" ; Parent relationship - Default 269 / "CHILD" ; Child relationship 270 / "SIBLING" ; Sibling relationship 271 / "DEPENDS-ON" ; refers to previous task 272 / "REFID" ; Relationship based on REFID 273 / "STRUCTURED-CATEGORY" 274 ; Relationship based on STRUCTURED-CATEGORY 275 / "FINISHTOSTART" ; Temporal relationship 276 / "FINISHTOFINISH" ; Temporal relationship 277 / "STARTTOFINISH" ; Temporal relationship 278 / "STARTTOSTART" ; Temporal relationship 279 / "SERIES-MASTER" ; link to the master component 280 / iana-token ; Some other IANA-registered 281 ; iCalendar relationship type 282 / x-name) ; A non-standard, experimental 283 ; relationship type 285 Figure 1 287 Description 289 This parameter can be specified on a property that references another 290 related calendar component. The parameter may specify the 291 hierarchical relationship type of the calendar component referenced 292 by the property when the value is PARENT, CHILD or SIBLING. If this 293 parameter is not specified on an allowable property, the default 294 relationship type is PARENT. Applications MUST treat x-name and 295 iana-token values they don't recognize the same way as they would the 296 PARENT value. 298 This parameter defines the temporal relationship when the value is 299 one of the project management standard relationships FINISHTOSTART, 300 FINISHTOFINISH, STARTTOFINISH or STARTTOSTART. This property will be 301 present in the predecessor entity and will refer to the successor 302 entity. The GAP parameter specifies the lead or lag time between the 303 predecessor and the successor. In the description of each temporal 304 relationship below we refer toTask-A which contains and controls the 305 relationship and Task-B the target of the relationship. 307 RELTYPE=PARENT See [RFC5545]. 309 RELTYPE=CHILD See [RFC5545]. 311 RELTYPE=SIBLING See [RFC5545]. 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 based on the referenced calendar component. The value is a 324 UID. 326 RELTYPE=STRUCTURED-CATEGORY Establishes a reference from the current 327 component to components with a STRUCTURED-CATEGORY property which 328 matches the value given in the associated RELATED- TO property. 330 RELTYPE=FINISHTOSTART 332 Task-B cannot start until Task-A finishes. For example, when sanding 333 is complete, painting can begin. 335 ============ 336 | Task-A |--+ 337 ============ | 338 | 339 V 340 ============ 341 | Task-B | 342 ============ 344 Figure 2: Finish to start relationship 346 RELTYPE=FINISHTOFINISH 348 Task-B cannot finish before Task-A is finished, that is the end of 349 Task-A defines the end of Task-B. For example, we start the 350 potatoes, then the meat then the peas but they should all be cooked 351 at the same time. 353 ============ 354 | Task-A |--+ 355 ============ | 356 | 357 ============ | 358 | Task-B |<-+ 359 ============ 361 Figure 3: Finish to finish relationship 363 RELTYPE=STARTTOFINISH 365 The start of Task-A (which occurs after Task-B) controls the finish 366 of Task-B. For example, ticket sales (Task-B) end when the game 367 starts (Task-A). 369 ============ 370 +--| Task-A | 371 | ============ 372 | 373 ============ | 374 | Task-B |<-+ 375 ============ 377 Figure 4: Start to finish relationship 379 RELTYPE=STARTTOSTART 381 The start of Task-A triggers the start of Task-B, that is Task-B can 382 start anytime after Task-A starts. 384 ============ 385 +--| Task-A | 386 | ============ 387 | 388 | ============ 389 +->| Task-B | 390 ============ 392 Figure 5: Start to start relationship 394 7. New Property Parameters 396 7.1. Split 398 Parameter name SPLIT 400 Purpose To indicate a series has been split. 402 Format Definition 404 This parameter is defined by the following notation: 406 splitparam = "SPLIT" "=" 407 ("YES" ; The series is split 408 / "NO" ; The series is not split (default) 409 / x-name ; Experimental reference type 410 / iana-token) ; Other IANA registered type 411 Figure 6 413 Description This parameter MAY be specified on the SRULE property to 414 indicate that the series has been split with SPLIT=YES. Once 415 split is is probably inappropriate to modify the series further. 417 7.2. Lookahead count 419 Parameter name LOOKAHEAD-COUNT 421 Purpose To specify the number of series instances that should be 422 generated in advance. 424 Format Definition 426 This parameter is defined by the following notation: 428 lookahead-countparam = "LOOKAHEAD-COUNT" "=" 1*DIGIT 430 Figure 7 432 Description 434 This parameter MAY be specified on the SRULE property to indicate how 435 many series instances should be generated in advance. 437 An implementation is free to apply its own limts but MUST NOT 438 generate more than those defined by this parameter and/or the 439 LOOKAHEAD-PERIOD parameter. 441 If both the LOOKAHEAD-PERIOD and LOOKAHEAD-COUNT arameters are 442 supplied the result should be limited by both. 444 For example, if the LOOKAHEAD-PERIOD parameter would cause 8 445 instances to be generated but LOOKAHEAD-COUNT specifies 4 then only 4 446 instances will be generated. 448 7.3. Lookahead period 450 Parameter name LOOKAHEAD-PERIOD 452 Purpose To specify a maximum period for which series instances 453 should be generated in advance. 455 Format Definition 457 This parameter is defined by the following notation: 459 lookahead-periodparam = "LOOKAHEAD-PERIOD" "=" 460 DQUOTE dur-value DQUOTE 462 Figure 8 464 Description 466 This parameter MAY be specified on the SRULE property to indicate how 467 far in advance series instances should be generated. 469 An implementation is free to apply its own limts but MUST NOT 470 generate more than those defined by this parameter and/or the 471 LOOKAHEAD-COUNT parameter. 473 If both the LOOKAHEAD-PERIOD and LOOKAHEAD-COUNT arameters are 474 supplied the result should be limited by both. 476 For example, if the LOOKAHEAD-PERIOD parameter would cause 8 477 instances to be generated but LOOKAHEAD-COUNT specifies 4 then only 4 478 instances will be generated. 480 The value is a quoted duration. 482 8. New Properties 484 8.1. General 486 The SERIES-ID, LAST-SERIES-ID, SDATE and SXDATE properties are 487 identical in form and in the parameters they take. 489 All must conform in form to the DTSTART property of the master 490 component. Only the SDATE may specify a time which is not part of 491 the calculated series. 493 The SRULE property value is identical in form to the RRULE property 494 defined in [RFC5545]. The LOOKAHEAD-COUNT and LOOKAHEAD-PERIOD 495 parameters indicate how many instances should be generated in 496 advance. 498 8.2. Generating Series members 500 An agent, either the server or a client, will periodically extend the 501 set of instances. The number of such generated instances is limited 502 by: 504 Elements of the rule The UNTIL or COUNT parts of the rule define 505 when the series terminates. Thus a COUNT=100 specifies a maximum 506 of 100 series members. 508 Lookahead count This specifies how many series members can exist 509 from the current date/time. Thus a LOOKAHEAD-COUNT=4 means a 510 maximum of 4 generated instances. 512 Lookahead period This specifies how far into the future series 513 members can be generated. Thus a LOOKAHEAD-PERIOD="PT2M" means a 514 maximum period of 2 months. 516 System limits This client or server SHOULD also apply limits to 517 prevent a series from generating an overlarge set of members. 519 The starting point for the calculation is the DTSTART of the master 520 component or the LAST-SERIES-ID if it exists in the master. In both 521 cases the instance represented by that date is NOT generated as part 522 of the instance set and the actual instance may have been excluded by 523 an SXDATE property but the starting date is still valid. 525 The starting date/time property defines the first instance in the 526 next batch of series members. Note that the starting property value 527 MUST match the pattern of the series rule, if specified. For 528 example, if the rule specifies every Wednesday the starting date MUST 529 be a Wednesday. 531 The end date/time of the set will be provided by the UNTIL part of 532 the rule, the LOOKAHEAD-PERIOD or by a system maxima. 534 A set of date/time values can be generated within those contraints. 535 As each date/time value is generated it can be ignored if it is one 536 of the SXDATE values. 538 Generation of values can terminate when the size of the result 539 exceeds that given by the COUNT rule element, the LOOKAHEAD-COUNT 540 value or any system limit. 542 Any SDATE values that fall within the current range and are not in 543 the set of SXDATE values can be added and the result truncated again 544 to match the size limits. 546 Finally, any date/time values that have already been generated and 547 are present as SERIES-ID values should be removed from the set. What 548 remains is the new set of members to extend the current series. 550 The last of those values becomes the new value for the LAST-SERIES-ID 551 property in the series master. 553 As noted above the "SXDATE" property can be used to exclude the value 554 specified in the master. This leads to a complication as the master 555 needs to be preserved as a container for the values which define the 556 series. This is flagged by adding a DELETED-MASTER element to the 557 SERIES-STATUS property. 559 8.3. Series UID 561 Property name SERIES-UID 563 Purpose This property defines the persistent, globally unique 564 identifier for the full series. 566 Value Type TEXT 568 Property Parameters IANA and non-standard property parameters can be 569 specified on this property. 571 Conformance This property MUST be specified in any "VEVENT", 572 "VTODO", and "VJOURNAL" calendar components acting as a series 573 master or series instance. 575 Description The SERIES-UID MUST be globally unique. This value 576 SHOULD be generated by following the recommendations in [RFC7986]. 578 Format Definition 580 This property is defined by the following notation: 582 seruid = "SERIES-UID" seruidparam ":" text CRLF 584 seruidparam = *(";" other-param) 586 Figure 9 588 EXAMPLE 590 The following is an example of this property: 592 SERIES-UID:123e4567-e89b-12d3-a456-426655440000 594 Figure 10 596 8.4. Series-exception-date 598 Property name SXDATE 600 Purpose This property defines the list of DATE-TIME exceptions for 601 series of events, to-dos or journal entries. 603 Value Type The default value type for this property is DATE-TIME. 604 The value type can be set to DATE. 606 Property Parameters IANA, non-standard, value data type, and time 607 zone identifier property parameters can be specified on this 608 property. 610 Conformance This property can be specified in "VEVENT", "VTODO", and 611 "VJOURNAL" calendar components acting as the series master. 613 Description The exception dates, if specified, are used when 614 computing the instances of the series. They specify date/time 615 values which are to be removed from the set of possible series 616 instances. 618 Format Definition 620 This property is defined by the following notation: 622 sxdate = "SXDATE" sxdtparam ":" sxdtval *("," sxdtval) CRLF 624 sxdtparam = *( 625 ; 626 ; The following are OPTIONAL, 627 ; but MUST NOT occur more than once. 628 ; 629 (";" "VALUE" "=" ("DATE-TIME" / "DATE")) / 630 ; 631 (";" tzidparam) / 632 ; 633 ; The following is OPTIONAL, 634 ; and MAY occur more than once. 635 ; 636 (";" other-param) 637 ; 638 ) 640 sxdtval = date-time / date 641 ;Value MUST match value type 643 Figure 11 645 EXAMPLE 647 The following is an example of this property: 649 SXDATE:19960402T010000Z,19960403T010000Z,19960404T010000Z 651 Figure 12 653 8.5. Series-date 655 Property name SDATE 657 Purpose This property defines the list of DATE-TIME values for 658 series of events, to-dos or journal entries. 660 Value Type The default value type for this property is DATE-TIME. 661 The value type can be set to DATE. 663 Property Parameters IANA, non-standard, value data type, and time 664 zone identifier property parameters can be specified on this 665 property. 667 Conformance This property can be specified in "VEVENT", "VTODO", and 668 "VJOURNAL" calendar components acting as the series master. 670 Description This property can appear along with the "SRULE" property 671 to define a extra series occurrences. When they both appear in a 672 series master component, the instances are defined by the union of 673 occurrences defined by both the "SDATE" and "SRULE". 675 Format Definition 677 This property is defined by the following notation: 679 sdate = "SDATE" sdtparam ":" sdtval *("," sdtval) CRLF 681 sdtparam = *( 682 ; 683 ; The following are OPTIONAL, 684 ; but MUST NOT occur more than once. 685 ; 686 (";" "VALUE" "=" ("DATE-TIME" / "DATE" / "PERIOD")) / 687 (";" tzidparam) / 688 ; 689 ; The following is OPTIONAL, 690 ; and MAY occur more than once. 691 ; 692 (";" other-param) 693 ; 694 ) 696 sdtval = date-time / date 697 ;Value MUST match value type 699 Figure 13 701 EXAMPLE 703 The following are examples of this property: 705 SDATE:19970714T123000Z 706 SDATE;TZID=America/New_York:19970714T083000 708 SDATE;VALUE=PERIOD:19960403T020000Z/19960403T040000Z, 709 19960404T010000Z/PT3H 711 SDATE;VALUE=DATE:19970101,19970120,19970217,19970421 712 19970526,19970704,19970901,19971014,19971128,19971129,19971225 714 Figure 14 716 8.6. Series-id 718 Property name SERIES-ID 720 Purpose This property is used in conjunction with the "UID" and 721 "SEQUENCE" properties to identify a specific instance of a 722 "VEVENT", "VTODO", or "VJOURNAL" calendar component in a series. 723 The property value is the original value of the "DTSTART" property 724 of the series instance before any changes occur. 726 Value type The default value type is DATE-TIME. The value type can 727 be set to a DATE value type. This property MUST have the same 728 value type as the "DTSTART" property contained within the series 729 component. Furthermore, this property MUST be specified as a date 730 with local time if and only if the "DTSTART" property contained 731 within the series component is specified as a date with local 732 time. 734 Property Parameters IANA, non-standard, value data type and time 735 zone identifier parameters can be specified on this property. 737 Conformance This property can be specified zero or more times in any 738 iCalendar component. 740 Description 742 The SERIES-ID is the originally calculated value of the DTSTART 743 property based on the master identified by the RELATED-TO property 744 with a RELTYPE=SERIES-MASTER parameter. 746 The full series of components can only be retrieved by searching 747 for all components with a matching RELATED-TO property. 749 Figure 15 751 If the value of the "DTSTART" property is a DATE type value, then 752 the value MUST be the calendar date for the series instance. 754 Figure 16 756 The DATE-TIME value is set to the time when the original series 757 instance would occur; meaning that if the intent is to change a 758 Friday meeting to Thursday, the DATE-TIME is still set to the 759 original Friday meeting. 761 Figure 17 763 The "SERIES-ID" property is used in conjunction with the "UID" and 764 "SEQUENCE" properties to identify a particular instance of an 765 event, to-do, or journal in the series. For a given pair of "UID" 766 and "SEQUENCE" property values, the "SERIES-ID" value for a series 767 instance is fixed. 769 Figure 18 771 Format Definition 773 This property is defined by the following notation: 775 serid = "SERIES-ID" sidparam ":" sidval CRLF 777 sidparam = *( 778 ; 779 ; The following are OPTIONAL, 780 ; but MUST NOT occur more than once. 781 ; 782 (";" "VALUE" "=" ("DATE-TIME" / "DATE")) / 783 (";" tzidparam) / 784 ; 785 ; The following is OPTIONAL, 786 ; and MAY occur more than once. 787 ; 788 (";" other-param) 789 ; 790 ) 792 sidval = date-time / date 793 ;Value MUST match value type 795 Figure 19 797 EXAMPLE 799 The following are examples of this property: 801 SERIES-ID;VALUE=DATE:19960401 803 SERIES-ID;TZID=America/New_York:20170120T120000 805 Figure 20 807 8.7. Last series ID 809 Property name LAST-SERIES-ID 811 Purpose 813 To specify the last calculated instance of the series. When new 814 instances are created they MUST have a SERIES-ID after the value of 815 this property. 817 In all respects this property is identical to SERIES-ID and is in 818 fact a copy of the SERIES-ID which would be present in the last 819 created instance (assuming it is not suppressed by an SXDATE). 821 Value type DATE or DATE_TIME (the default). This has the same 822 requirements as SERIES-ID. 824 Property Parameters IANA, non-standard, value data type and time 825 zone identifier parameters can be specified on this property. 827 Conformance This property MAY be specified in any iCalendar 828 component. 830 Description When used in a component the value of this property 831 points to additional information related to the component. For 832 example, it may reference the originating web server. 834 Format Definition 836 This property is defined by the following notation: 838 last-series-i = "LAST-SERIES-ID" lastseriesidparam / 839 ( 840 ";" "VALUE" "=" "TEXT" 841 ":" text 842 ) 843 ( 844 ";" "VALUE" "=" "REFERENCE" 845 ":" text 846 ) 847 ( 848 ";" "VALUE" "=" "URI" 849 ":" uri 850 ) 851 CRLF 853 lastseriesidparam = *( 855 ; the following is MANDATORY 856 ; and MAY occur more than once 858 (";" relparam) / 860 ; the following are MANDATORY 861 ; but MUST NOT occur more than once 863 (";" fmttypeparam) / 864 (";" labelparam) / 865 ; labelparam is defined in ... 867 ; the following is OPTIONAL 868 ; and MAY occur more than once 870 (";" xparam) 872 ) 874 Figure 21 876 EXAMPLE 878 The following is an example of this property. It points to a server 879 acting as the source for the calendar object. 881 LINK;REL=SOURCE;LABEL=The Egg:http://example.com/events 883 Figure 22 885 8.8. Series Rule 887 Property name RRULE 889 Purpose This property defines a rule or repeating pattern for a 890 series of events, to-dos or journal entries. 892 Value Type RECUR 894 Property Parameters IANA, non-standard, look-ahead count or date 895 property parameters can be specified on this property. 897 Conformance This property can be specified in any "VEVENT", "VTODO", 898 and "VJOURNAL" calendar component, but it SHOULD NOT be specified 899 more than once. 901 Description 903 The series rule, if specified, is used in computing the instances to 904 be generated for the series. These are generated by considering the 905 master "DTSTART" property along with the "SRULE", "SDATE", and 906 "SXDATE" properties contained within the series master. The 907 "DTSTART" property defines the first instance in the recurrence set 908 which is represented by that master event. 910 Unlike the RRULE the "DTSTART" property MUST be synchronized with the 911 series rule, if specified. For example, if the DTSTARTS species a 912 date on Wednesday but the SRULE specifies every Tuesday then a server 913 or client MUSt reject the component. 915 The final series is represented by gathering all of the start DATE- 916 TIME values generated by any of the specified "SRULE" and "SDATE" 917 properties, and then excluding any start DATE-TIME values specified 918 by "SXDATE" properties. This implies that start DATE- TIME values 919 specified by "SXDATE" properties take precedence over those specified 920 by inclusion properties (i.e., "SDATE" and "SRULE"). Where duplicate 921 instances are generated by the "SRULE" and "SDATE" properties, only 922 one instance is considered. Duplicate instances are ignored. 924 The "DTSTART" property specified within the master iCalendar object 925 defines the first instance of the recurrence. In most cases, a 926 "DTSTART" property of DATE-TIME value type used with a series rule, 927 should be specified as a date with local time and time zone reference 928 to make sure all the recurrence instances start at the same local 929 time regardless of time zone changes. 931 If the duration of the series component is specified with the "DTEND" 932 or "DUE" property, then the same exact duration will apply to all the 933 members of the generated series. Else, if the duration of the series 934 master component is specified with the "DURATION" property, then the 935 same nominal duration will apply to all the members of the generated 936 series and the exact duration of each instance will depend on its 937 specific start time. For example, series instances of a nominal 938 duration of one day will have an exact duration of more or less than 939 24 hours on a day where a time zone shift occurs. The duration of a 940 specific instance may be modified in an exception component or simply 941 by using an "SDATE" property of PERIOD value type. 943 Format Definition 945 This property is defined by the following notation: 947 srule = "SRULE" srulparam ":" recur CRLF 949 sruleparam = *( 950 ; the following are OPTIONAL 951 ; but MUST NOT occur more than once 953 (";" lookahead-countparam) / 954 (";" lookahead-periodparam) / 956 ; the following is OPTIONAL 957 ; and MAY occur more than once 959 (";" xparam) 961 ) 963 Figure 23 965 EXAMPLE 967 TODO - Say they are pretty much the same as RRULE but extra params 969 9. Redefined RELATED-TO Property 971 9.1. RELATED-TO 973 Property name RELATED-TO 975 Purpose This property is used to represent a relationship or 976 reference between one calendar component and another. The 977 definition here extends the definition in [RFC5545] by including a 978 section on RELTYPE=SERIES-MASTER. 980 Value type URI, UID or TEXT 982 Conformance This property MAY be specified in any iCalendar 983 component. 985 Description By default or when VALUE=UID is specified, the property 986 value consists of the persistent, globally unique identifier of 987 another calendar component. This value would be represented in a 988 calendar component by the "UID" property. 990 By default, the property value points to another calendar 991 component that has a PARENT relationship to the referencing 992 object. The "RELTYPE" property parameter is used to either 993 explicitly state the default PARENT relationship type to the 994 referenced calendar component or to override the default PARENT 995 relationship type and specify either a CHILD or SIBLING 996 relationship or a temporal relationship. 998 The PARENT relationship indicates that the calendar component is a 999 subordinate of the referenced calendar component. The CHILD 1000 relationship indicates that the calendar component is a superior 1001 of the referenced calendar component. The SIBLING relationship 1002 indicates that the calendar component is a peer of the referenced 1003 calendar component. 1005 The FINISHTOSTART, FINISHTOFINISH, STARTTOFINISH or STARTTOSTART 1006 relationships define temporal relationships as specified in the 1007 reltype parameter definition. 1009 The SERIES-MASTER relationship when included in a series instance 1010 refers to the master of that series. When included in a series 1011 master it refers to a previous master in a chain of spilt series. 1013 Changes to a calendar component referenced by this property can 1014 have an implicit impact on the related calendar component. For 1015 example, if a group event changes its start or end date or time, 1016 then the related, dependent events will need to have their start 1017 and end dates changed in a corresponding way. Similarly, if a 1018 PARENT calendar component is cancelled or deleted, then there is 1019 an implied impact to the related CHILD calendar components. This 1020 property is intended only to provide information on the 1021 relationship of calendar components. It is up to the target 1022 calendar system to maintain any property implications of this 1023 relationship. 1025 Format Definition This property is defined by the following 1026 notation: 1028 related = "RELATED-TO" relparam ( ":" text ) / 1029 ( 1030 ";" "VALUE" "=" "UID" 1031 ":" uid 1032 ) 1033 ( 1034 ";" "VALUE" "=" "URI" 1035 ":" uri 1036 ) 1037 CRLF 1039 relparam = *( 1040 ; 1041 ; The following are OPTIONAL, 1042 ; but MUST NOT occur more than once. 1043 ; 1044 (";" reltypeparam) / 1045 (";" gapparam) / 1046 ; 1047 ; The following is OPTIONAL, 1048 ; and MAY occur more than once. 1049 ; 1050 (";" other-param) 1051 ; 1052 ) 1054 Figure 24 1056 EXAMPLE 1058 The following are examples of this property. 1060 RELATED-TO;RELTYPE=SERIES-MASTER:19960401-080045-4000F192713 1062 Figure 25 1064 10. Backwards compatibility 1066 Any clients following the approach specified in [RFC5545] are 1067 expected to ignore any properties or parameters they don't recognize. 1069 For such clients the series appears to be an unconnected set of 1070 components. They all have their own unique UIDS. If the client 1071 updates an instance this should be identical in effect to an update 1072 carried out by a client aware of the new properties. 1074 Updates MUST preserve the SERIES-ID, LAST-SERIES-ID, SRULE, SDATE and 1075 SXDATE properties. A client which does not do so is in violation of 1076 [RFC5545]. 1078 TODO - More text needed here... 1080 11. CalDAV extensions 1082 This specification may extend Caldav by adding reports to return all 1083 members of a series given the series master UID. This could be 1084 handled by the current query mechanism but it is likely to be 1085 sufficiently frequently used that a special query is appropriate. 1087 It is also likely we will want a CalDAV operation to split a series 1088 and generate the additional members of the series as a single atomic 1089 operation. == Security Considerations 1091 Clients and servers should take care to limit the number of generated 1092 instances to a reasonable value. This can be a relatively small 1093 value. 1095 12. IANA Considerations 1097 12.1. iCalendar Property Registrations 1099 The following iCalendar property names have been added to the 1100 iCalendar Properties Registry defined in [RFC5545]. 1102 +================+=========+=============+ 1103 | Property | Status | Reference | 1104 +================+=========+=============+ 1105 | LAST-SERIES-ID | Current | Section 8.7 | 1106 +----------------+---------+-------------+ 1107 | SERIES-ID | Current | Section 8.6 | 1108 +----------------+---------+-------------+ 1109 | SERIES-UID | Current | Section 8.3 | 1110 +----------------+---------+-------------+ 1111 | SDATE | Current | Section 8.5 | 1112 +----------------+---------+-------------+ 1113 | SRULE | Current | Section 8.8 | 1114 +----------------+---------+-------------+ 1115 | SXDATE | Current | Section 8.4 | 1116 +----------------+---------+-------------+ 1118 Table 1 1120 12.2. iCalendar Property Parameter Registrations 1122 The following iCalendar property parameter names have been added to 1123 the iCalendar Parameters Registry defined in [RFC5545]. 1125 +==================+=========+=============+ 1126 | Parameter | Status | Reference | 1127 +==================+=========+=============+ 1128 | LOOKAHEAD-COUNT | Current | Section 7.2 | 1129 +------------------+---------+-------------+ 1130 | LOOKAHEAD-PERIOD | Current | Section 7.3 | 1131 +------------------+---------+-------------+ 1132 | SPLIT | Current | Section 7.1 | 1133 +------------------+---------+-------------+ 1135 Table 2 1137 12.3. iCalendar RELTYPE Value Registrations 1139 The following iCalendar "RELTYPE" values have been added to the 1140 iCalendar Relationship Types Registry defined in [RFC5545]. 1142 +===================+=========+===========+ 1143 | Relationship Type | Status | Reference | 1144 +===================+=========+===========+ 1145 | SERIES-ID | Current | Section 5 | 1146 +-------------------+---------+-----------+ 1148 Table 3 1150 13. Normative references 1152 [RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and 1153 Scheduling Core Object Specification (iCalendar)", IETF 1154 RFC 5545, IETF RFC 5545, DOI 10.17487/RFC5545, September 1155 2009, . 1157 [RFC7986] Daboo, C., "New Properties for iCalendar", IETF RFC 7986, 1158 IETF RFC 7986, DOI 10.17487/RFC7986, October 2016, 1159 . 1161 Author's Address 1163 Michael Douglass 1165 Email: mikeadouglass@gmail.com