idnits 2.17.1 draft-ietf-calext-icalendar-series-03.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: ---------------------------------------------------------------------------- == There is 1 instance of lines with non-ascii characters in the document. 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 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 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). -- The document date (12 April 2021) is 1103 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: 'RFC2119' is defined on line 1152, but no explicit reference was found in the text == Unused Reference: 'RFC2518' is defined on line 1157, but no explicit reference was found in the text == Unused Reference: 'RFC3986' is defined on line 1163, but no explicit reference was found in the text == Unused Reference: 'RFC4791' is defined on line 1168, but no explicit reference was found in the text == Unused Reference: 'RFC5546' is defined on line 1178, but no explicit reference was found in the text == Unused Reference: 'RFC6047' is defined on line 1183, but no explicit reference was found in the text == Unused Reference: 'RFC6638' is defined on line 1188, but no explicit reference was found in the text == Unused Reference: 'RFC8174' is defined on line 1196, but no explicit reference was found in the text == Unused Reference: 'RFC3552' is defined on line 1203, but no explicit reference was found in the text == Unused Reference: 'RFC4918' is defined on line 1208, but no explicit reference was found in the text == Unused Reference: 'RFC5378' is defined on line 1213, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2518 (Obsoleted by RFC 4918) Summary: 3 errors (**), 0 flaws (~~), 14 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 12 April 2021 4 Intended status: Standards Track 5 Expires: 14 October 2021 7 Support for Series in iCalendar 8 draft-ietf-calext-icalendar-series-03 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 14 October 2021. 34 Copyright Notice 36 Copyright (c) 2021 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. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 78 11.1. iCalendar Property Registrations . . . . . . . . . . . . 25 79 11.2. iCalendar Property Parameter Registrations . . . . . . . 25 80 11.3. iCalendar RELTYPE Value Registrations . . . . . . . . . 26 81 12. Normative References . . . . . . . . . . . . . . . . . . . . 26 82 13. Informative References . . . . . . . . . . . . . . . . . . . 27 83 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 27 85 1. Acknowledgements 87 The author would like to thank the members of the Calendaring and 88 Scheduling Consortium technical committees and the following 89 individuals for contributing their ideas, support and comments: 91 The author would also like to thank the Calendaring and Scheduling 92 Consortium for advice with this specification. 94 2. Introduction 96 Since iCalendar was first defined there has been only one way to 97 express a repeating set of events - the recurrence. This defined a 98 master event, a set of rules for computing the instances and a way of 99 overriding certain instances. 101 This approach works well enough in certain situations but has many 102 problems which need to be addressed. 104 This specification introduces a new approach to repeating patterns of 105 entities which avoids some of the problems. 107 3. Terms and definitions 109 4. Overrides and iCalendar recurrences 111 The recurrence rules specify how instances are to be computed. These 112 rules provide a set of keys - the RECURRENCE-ID - and an instance can 113 be created with the calculated start date/time and a copy of the 114 duration (or calculated end date/time). 116 The [RFC5545] specification allows for overrides. These are handled 117 by supplying a complete replacement for the instance with a 118 RECURRENCE- ID property matching that of the instance being 119 overridden. This may change any of the properties (except the UID) - 120 including start, end or duration. 122 If a long lived recurrence is heavily overridden it becomes very 123 cumbersome. The master plus overrides is considered a single 124 resource in most circumstances (iTip allows the delivery of a single 125 instance in certain situations). 127 Simple meetings can become heavily modified recurrences through 128 adding the weeks agenda to the description, changing of attendees 129 etc. 131 There are approaches being considered to mitigate some of these 132 issues which mostly involve only storing changes. This can help if 133 the changes are minor but heavily modified instances are still a 134 problem. 136 4.1. Changing the master start or the recurrence rules 138 This can lead to some very difficult problems to resolve. In the 139 case of a heavily modified meeting it may be difficult to impossible 140 to determine which override applies to the newly modified event. 142 For example, a weekly book-reading is moved from Monday to Friday. 143 There are weeks of scheduled events in the future. Do we move them 144 all forward to the next instance or skip one and move them back? If 145 it becomes bi-weekly rather than weekly do we drop every other or 146 just space them out more? 148 While these problems are not totally resolved by a series approach, 149 they become more tractable. 151 4.2. Splitting recurrences 153 The [RFC5545] THISANDFUTURE range is poorly supported. Splitting is 154 the approach a number of implementations use to avoid changing 155 overrides in the past. 157 The recurring event is split into 2, one being the truncated original 158 the other being a new recurring event starting at the time of the 159 THISANDFUTURE override. 161 There is left the problem of relating the two, this can be 162 accomplished by use of the RELATED-TO property but that is not 163 standardized. 165 5. Series 167 A series is a, generally regularly, repeating sets of events or tasks 168 each instance of which is usually, but not always, different in some 169 respect. Examples may be a library running an after-school reading 170 program which usually, takes place at the same time each week but 171 always differs in the book or author being studied. 173 In recurrences an instances is a calculated 'virtual' object, unless 174 overridden. It has the same UID as the master and a RECURRENCE-ID 175 which is always one of the calculated set. 177 In a series, a specified number of instances are created ahead of 178 time each with their own unique UID. They are all related to the 179 master using a SERIES-MASTER relation type defined in this 180 specification. Each instance acts as an individual component as far 181 as retrieval and searching is concerned. 183 Each instance and master is identified as a member of the full series 184 by the SERIES-UID property. The value of this property is the same 185 in all members of the series even when splits have occurred. 187 As instances are created a LAST-SERIES-ID property is added or 188 updated in the master to indicate which instance was last created. 189 When there are SXDATE properties this property value may represent an 190 instance which cannot be created. It merely represents the latest 191 calculated date. 193 This property allows generated instances to be deleted without the 194 addition of SXDATE properties to the master. The SXDATE only 195 indicates future instances which MUST NOT be created. 197 As time goes on more instances are created either by the server or by 198 a client when it inspects the current state of the series. The 199 number of instances may be based on time or a count. 201 For example, an organization may allow rooms to be booked only 4 202 weeks ahead. Thus a series may be set up which has that 4 week set 203 of events in the future. Each will have the room as an attendee 204 ensuring that at least the room is booked at the regular time. 206 5.1. Modifying series patterns and splitting 208 If it becomes necessary to modify the series rules or the master 209 start then the series is always split at the point of the 210 modification. 212 When a series is split the previous master is modifed to truncate the 213 current series at the last generated instance and a parameter 214 SPLIT=YES is added to the series rule to indicate that this master is 215 now split. 217 The split may result in a number of instances related to the old 218 series but overlapping the new. It is up to the implementation to 219 decide what should be done with these but this usually requires a 220 degree of interaction with a human (or very intelligent robot). The 221 application may offer to copy them into the corresponding new 222 instances - if these can be easily determined, offer to delete all of 223 them or let the user manually copy information and delete. 225 The new series master is related to the old master by the new series 226 master having a RELATED-TO property with RELTYPE=SERIES-MASTER 227 pointing at the previous master. In that way a backwards chain of 228 series masters may be created 230 5.2. The series master 232 A series master is identified in much the same way as a recurrence 233 master. It will contain an SRULE and 0 or more SDATE properties or 1 234 or more SDATE properties. Additionally it may contain 0 or more 235 SXDATE properties to exclude instances. 237 As noted above, if the series was split it may contain a RELATED-TO 238 property with RELTYPE=SERIES-MASTER and a value of the previous 239 series master. 241 The master will also contain a LAST-SERIES-ID if any instances have 242 been calculated and perhaps generated. 244 It is important to note that the series master is the first member of 245 the series. Thus the first instance always occurs AFTER the series 246 master. 248 5.3. The series instances 250 A series instance is identified by having a SERIES-ID property which 251 is calculated in the same manner as a RECURRENCE-ID. It MUST also 252 contain a RELATED-TO property with RELTYPE=SERIES-MASTER and a value 253 being the UID of the series master. 255 As noted above, if the series was split it may contain a RELATED-TO 256 property with RELTYPE=SERIES-MASTER and a value being the UID of the 257 previous series master. 259 6. Redefined Relation Type Value 261 Relationship parameter type values are defined in [RFC5545]. This 262 specification augments that parameter to include the new relationship 263 values SERIES-MASTER. 265 Format Definition 267 This property parameter is respecified as follows: 269 reltypeparam = "RELTYPE" "=" 270 ("PARENT" ; Parent relationship - Default 271 / "CHILD" ; Child relationship 272 / "SIBLING" ; Sibling relationship 273 / "DEPENDS-ON" ; refers to previous task 274 / "REFID" ; Relationship based on REFID 275 / "STRUCTURED-CATEGORY" 276 ; Relationship based on STRUCTURED-CATEGORY 277 / "FINISHTOSTART" ; Temporal relationship 278 / "FINISHTOFINISH" ; Temporal relationship 279 / "STARTTOFINISH" ; Temporal relationship 280 / "STARTTOSTART" ; Temporal relationship 281 / "SERIES-MASTER" ; link to the master component 282 / iana-token ; Some other IANA-registered 283 ; iCalendar relationship type 284 / x-name) ; A non-standard, experimental 285 ; relationship type 287 Figure 1 289 Description 291 This parameter can be specified on a property that references another 292 related calendar component. The parameter may specify the 293 hierarchical relationship type of the calendar component referenced 294 by the property when the value is PARENT, CHILD or SIBLING. If this 295 parameter is not specified on an allowable property, the default 296 relationship type is PARENT. Applications MUST treat x-name and 297 iana-token values they don't recognize the same way as they would the 298 PARENT value. 300 This parameter defines the temporal relationship when the value is 301 one of the project management standard relationships FINISHTOSTART, 302 FINISHTOFINISH, STARTTOFINISH or STARTTOSTART. This property will be 303 present in the predecessor entity and will refer to the successor 304 entity. The GAP parameter specifies the lead or lag time between the 305 predecessor and the successor. In the description of each temporal 306 relationship below we refer toTask-A which contains and controls the 307 relationship and Task-B the target of the relationship. 309 RELTYPE=PARENT See [RFC5545]. 311 RELTYPE=CHILD See [RFC5545]. 313 RELTYPE=SIBLING See [RFC5545]. 315 RELTYPE=DEPENDS-ON Indicates that the current calendar component 316 depends on the referenced calendar component in some manner. For 317 example a task may be blocked waiting on the other, referenced, 318 task. 320 RELTYPE=REFID Establishes a reference from the current component to 321 components with a REFID property which matches the value given in 322 the associated RELATED-TO property. 324 RELTYPE=SERIES-MASTER Indicates that the current calendar component 325 is based on the referenced calendar component. The value is a 326 UID. 328 RELTYPE=STRUCTURED-CATEGORY Establishes a reference from the current 329 component to components with a STRUCTURED-CATEGORY property which 330 matches the value given in the associated RELATED- TO property. 332 RELTYPE=FINISHTOSTART 334 Task-B cannot start until Task-A finishes. For example, when sanding 335 is complete, painting can begin. 337 ============ 338 | Task-A |--+ 339 ============ | 340 | 341 V 342 ============ 343 | Task-B | 344 ============ 346 Figure 2: Finish to start relationship 348 RELTYPE=FINISHTOFINISH 350 Task-B cannot finish before Task-A is finished, that is the end of 351 Task-A defines the end of Task-B. For example, we start the 352 potatoes, then the meat then the peas but they should all be cooked 353 at the same time. 355 ============ 356 | Task-A |--+ 357 ============ | 358 | 359 ============ | 360 | Task-B |<-+ 361 ============ 363 Figure 3: Finish to finish relationship 365 RELTYPE=STARTTOFINISH 367 The start of Task-A (which occurs after Task-B) controls the finish 368 of Task-B. For example, ticket sales (Task-B) end when the game 369 starts (Task-A). 371 ============ 372 +--| Task-A | 373 | ============ 374 | 375 ============ | 376 | Task-B |<-+ 377 ============ 379 Figure 4: Start to finish relationship 381 RELTYPE=STARTTOSTART 383 The start of Task-A triggers the start of Task-B, that is Task-B can 384 start anytime after Task-A starts. 386 ============ 387 +--| Task-A | 388 | ============ 389 | 390 | ============ 391 +->| Task-B | 392 ============ 394 Figure 5: Start to start relationship 396 7. New Property Parameters 398 7.1. Split 400 Parameter name SPLIT 402 Purpose To indicate a series has been split. 404 Format Definition 406 This parameter is defined by the following notation: 408 splitparam = "SPLIT" "=" 409 ("YES" ; The series is split 410 / "NO" ; The series is not split (default) 411 / x-name ; Experimental reference type 412 / iana-token) ; Other IANA registered type 413 Figure 6 415 Description This parameter MAY be specified on the SRULE property to 416 indicate that the series has been split with SPLIT=YES. Once 417 split is is probably inappropriate to modify the series further. 419 7.2. Lookahead count 421 Parameter name LOOKAHEAD-COUNT 423 Purpose To specify the number of series instances that should be 424 generated in advance. 426 Format Definition 428 This parameter is defined by the following notation: 430 lookahead-countparam = "LOOKAHEAD-COUNT" "=" 1*DIGIT 432 Figure 7 434 Description 436 This parameter MAY be specified on the SRULE property to indicate how 437 many series instances should be generated in advance. 439 An implementation is free to apply its own limts but MUST NOT 440 generate more than those defined by this parameter and/or the 441 LOOKAHEAD-PERIOD parameter. 443 If both the LOOKAHEAD-PERIOD and LOOKAHEAD-COUNT arameters are 444 supplied the result should be limited by both. 446 For example, if the LOOKAHEAD-PERIOD parameter would cause 8 447 instances to be generated but LOOKAHEAD-COUNT specifies 4 then only 4 448 instances will be generated. 450 7.3. Lookahead period 452 Parameter name LOOKAHEAD-PERIOD 454 Purpose To specify a maximum period for which series instances 455 should be generated in advance. 457 Format Definition 459 This parameter is defined by the following notation: 461 lookahead-periodparam = "LOOKAHEAD-PERIOD" "=" 462 DQUOTE dur-value DQUOTE 464 Figure 8 466 Description 468 This parameter MAY be specified on the SRULE property to indicate how 469 far in advance series instances should be generated. 471 An implementation is free to apply its own limts but MUST NOT 472 generate more than those defined by this parameter and/or the 473 LOOKAHEAD-COUNT parameter. 475 If both the LOOKAHEAD-PERIOD and LOOKAHEAD-COUNT arameters are 476 supplied the result should be limited by both. 478 For example, if the LOOKAHEAD-PERIOD parameter would cause 8 479 instances to be generated but LOOKAHEAD-COUNT specifies 4 then only 4 480 instances will be generated. 482 The value is a quoted duration. 484 8. New Properties 486 8.1. General 488 The SERIES-ID, LAST-SERIES-ID, SDATE and SXDATE properties are 489 identical in form and in the parameters they take. 491 All must conform in form to the DTSTART property of the master 492 component. Only the SDATE may specify a time which is not part of 493 the calculated series. 495 The SRULE property value is identical in form to the RRULE property 496 defined in [RFC5545]. The LOOKAHEAD-COUNT and LOOKAHEAD-PERIOD 497 parameters indicate how many instances should be generated in 498 advance. 500 8.2. Generating Series members 502 An agent, either the server or a client, will periodically extend the 503 set of instances. The number of such generated instances is limited 504 by: 506 Elements of the rule The UNTIL or COUNT parts of the rule define 507 when the series terminates. Thus a COUNT=100 specifies a maximum 508 of 100 series members. 510 Lookahead count This specifies how many series members can exist 511 from the current date/time. Thus a LOOKAHEAD-COUNT=4 means a 512 maximum of 4 generated instances. 514 Lookahead period This specifies how far into the future series 515 members can be generated. Thus a LOOKAHEAD-PERIOD="PT2M" means a 516 maximum period of 2 months. 518 System limits This client or server SHOULD also apply limits to 519 prevent a series from generating an overlarge set of members. 521 The starting point for the calculation is the DTSTART of the master 522 component or the LAST-SERIES-ID if it exists in the master. In both 523 cases the instance represented by that date is NOT generated as part 524 of the instance set and the actual instance may have been excluded by 525 an SXDATE property but the starting date is still valid. 527 The starting date/time property defines the first instance in the 528 next batch of series members. Note that the starting property value 529 MUST match the pattern of the series rule, if specified. For 530 example, if the rule specifies every Wednesday the starting date MUST 531 be a Wednesday. 533 The end date/time of the set will be provided by the UNTIL part of 534 the rule, the LOOKAHEAD-PERIOD or by a system maxima. 536 A set of date/time values can be generated within those contraints. 537 As each date/time value is generated it can be ignored if it is one 538 of the SXDATE values. 540 Generation of values can terminate when the size of the result 541 exceeds that given by the COUNT rule element, the LOOKAHEAD-COUNT 542 value or any system limit. 544 Any SDATE values that fall within the current range and are not in 545 the set of SXDATE values can be added and the result truncated again 546 to match the size limits. 548 Finally, any date/time values that have already been generated and 549 are present as SERIES-ID values should be removed from the set. What 550 remains is the new set of members to extend the current series. 552 The last of those values becomes the new value for the LAST-SERIES-ID 553 property in the series master. 555 As noted above the "SXDATE" property can be used to exclude the value 556 specified in the master. This leads to a complication as the master 557 needs to be preserved as a container for the values which define the 558 series. This is flagged by adding a DELETED-MASTER element to the 559 SERIES-STATUS property. 561 8.3. Series UID 563 Property name SERIES-UID 565 Purpose This property defines the persistent, globally unique 566 identifier for the full series. 568 Value Type TEXT 570 Property Parameters IANA and non-standard property parameters can be 571 specified on this property. 573 Conformance This property MUST be specified in any "VEVENT", 574 "VTODO", and "VJOURNAL" calendar components acting as a series 575 master or series instance. 577 Description The SERIES-UID MUST be globally unique. This value 578 SHOULD be generated by following the recommendations in [RFC7986]. 580 Format Definition 582 This property is defined by the following notation: 584 seruid = "SERIES-UID" seruidparam ":" text CRLF 586 seruidparam = *(";" other-param) 588 Figure 9 590 EXAMPLE 592 The following is an example of this property: 594 SERIES-UID:123e4567-e89b-12d3-a456-426655440000 596 Figure 10 598 8.4. Series-exception-date 600 Property name SXDATE 602 Purpose This property defines the list of DATE-TIME exceptions for 603 series of events, to-dos or journal entries. 605 Value Type The default value type for this property is DATE-TIME. 606 The value type can be set to DATE. 608 Property Parameters IANA, non-standard, value data type, and time 609 zone identifier property parameters can be specified on this 610 property. 612 Conformance This property can be specified in "VEVENT", "VTODO", and 613 "VJOURNAL" calendar components acting as the series master. 615 Description The exception dates, if specified, are used when 616 computing the instances of the series. They specify date/time 617 values which are to be removed from the set of possible series 618 instances. 620 Format Definition 622 This property is defined by the following notation: 624 sxdate = "SXDATE" sxdtparam ":" sxdtval *("," sxdtval) CRLF 626 sxdtparam = *( 627 ; 628 ; The following are OPTIONAL, 629 ; but MUST NOT occur more than once. 630 ; 631 (";" "VALUE" "=" ("DATE-TIME" / "DATE")) / 632 ; 633 (";" tzidparam) / 634 ; 635 ; The following is OPTIONAL, 636 ; and MAY occur more than once. 637 ; 638 (";" other-param) 639 ; 640 ) 642 sxdtval = date-time / date 643 ;Value MUST match value type 645 Figure 11 647 EXAMPLE 649 The following is an example of this property: 651 SXDATE:19960402T010000Z,19960403T010000Z,19960404T010000Z 653 Figure 12 655 8.5. Series-date 657 Property name SDATE 659 Purpose This property defines the list of DATE-TIME values for 660 series of events, to-dos or journal entries. 662 Value Type The default value type for this property is DATE-TIME. 663 The value type can be set to DATE. 665 Property Parameters IANA, non-standard, value data type, and time 666 zone identifier property parameters can be specified on this 667 property. 669 Conformance This property can be specified in "VEVENT", "VTODO", and 670 "VJOURNAL" calendar components acting as the series master. 672 Description This property can appear along with the "SRULE" property 673 to define a extra series occurrences. When they both appear in a 674 series master component, the instances are defined by the union of 675 occurrences defined by both the "SDATE" and "SRULE". 677 Format Definition 679 This property is defined by the following notation: 681 sdate = "SDATE" sdtparam ":" sdtval *("," sdtval) CRLF 683 sdtparam = *( 684 ; 685 ; The following are OPTIONAL, 686 ; but MUST NOT occur more than once. 687 ; 688 (";" "VALUE" "=" ("DATE-TIME" / "DATE" / "PERIOD")) / 689 (";" tzidparam) / 690 ; 691 ; The following is OPTIONAL, 692 ; and MAY occur more than once. 693 ; 694 (";" other-param) 695 ; 696 ) 698 sdtval = date-time / date 699 ;Value MUST match value type 701 Figure 13 703 EXAMPLE 705 The following are examples of this property: 707 SDATE:19970714T123000Z 708 SDATE;TZID=America/New_York:19970714T083000 710 SDATE;VALUE=PERIOD:19960403T020000Z/19960403T040000Z, 711 19960404T010000Z/PT3H 713 SDATE;VALUE=DATE:19970101,19970120,19970217,19970421 714 19970526,19970704,19970901,19971014,19971128,19971129,19971225 716 Figure 14 718 8.6. Series-id 720 Property name SERIES-ID 722 Purpose This property is used in conjunction with the "UID" and 723 "SEQUENCE" properties to identify a specific instance of a 724 "VEVENT", "VTODO", or "VJOURNAL" calendar component in a series. 725 The property value is the original value of the "DTSTART" property 726 of the series instance before any changes occur. 728 Value type The default value type is DATE-TIME. The value type can 729 be set to a DATE value type. This property MUST have the same 730 value type as the "DTSTART" property contained within the series 731 component. Furthermore, this property MUST be specified as a date 732 with local time if and only if the "DTSTART" property contained 733 within the series component is specified as a date with local 734 time. 736 Property Parameters IANA, non-standard, value data type and time 737 zone identifier parameters can be specified on this property. 739 Conformance This property can be specified zero or more times in any 740 iCalendar component. 742 Description 744 The SERIES-ID is the originally calculated value of the DTSTART 745 property based on the master identified by the RELATED-TO property 746 with a RELTYPE=SERIES-MASTER parameter. 748 The full series of components can only be retrieved by searching 749 for all components with a matching RELATED-TO property. 751 Figure 15 753 If the value of the "DTSTART" property is a DATE type value, then 754 the value MUST be the calendar date for the series instance. 756 Figure 16 758 The DATE-TIME value is set to the time when the original series 759 instance would occur; meaning that if the intent is to change a 760 Friday meeting to Thursday, the DATE-TIME is still set to the 761 original Friday meeting. 763 Figure 17 765 The "SERIES-ID" property is used in conjunction with the "UID" and 766 "SEQUENCE" properties to identify a particular instance of an 767 event, to-do, or journal in the series. For a given pair of "UID" 768 and "SEQUENCE" property values, the "SERIES-ID" value for a series 769 instance is fixed. 771 Figure 18 773 Format Definition 775 This property is defined by the following notation: 777 serid = "SERIES-ID" sidparam ":" sidval CRLF 779 sidparam = *( 780 ; 781 ; The following are OPTIONAL, 782 ; but MUST NOT occur more than once. 783 ; 784 (";" "VALUE" "=" ("DATE-TIME" / "DATE")) / 785 (";" tzidparam) / 786 ; 787 ; The following is OPTIONAL, 788 ; and MAY occur more than once. 789 ; 790 (";" other-param) 791 ; 792 ) 794 sidval = date-time / date 795 ;Value MUST match value type 797 Figure 19 799 EXAMPLE 801 The following are examples of this property: 803 SERIES-ID;VALUE=DATE:19960401 805 SERIES-ID;TZID=America/New_York:20170120T120000 807 Figure 20 809 8.7. Last series ID 811 Property name LAST-SERIES-ID 813 Purpose 815 To specify the last calculated instance of the series. When new 816 instances are created they MUST have a SERIES-ID after the value of 817 this property. 819 In all respects this property is identical to SERIES-ID and is in 820 fact a copy of the SERIES-ID which would be present in the last 821 created instance (assuming it is not suppressed by an SXDATE). 823 Value type DATE or DATE_TIME (the default). This has the same 824 requirements as SERIES-ID. 826 Property Parameters IANA, non-standard, value data type and time 827 zone identifier parameters can be specified on this property. 829 Conformance This property MAY be specified in any iCalendar 830 component. 832 Description When used in a component the value of this property 833 points to additional information related to the component. For 834 example, it may reference the originating web server. 836 Format Definition 838 This property is defined by the following notation: 840 last-series-i = "LAST-SERIES-ID" lastseriesidparam / 841 ( 842 ";" "VALUE" "=" "TEXT" 843 ":" text 844 ) 845 ( 846 ";" "VALUE" "=" "REFERENCE" 847 ":" text 848 ) 849 ( 850 ";" "VALUE" "=" "URI" 851 ":" uri 852 ) 853 CRLF 855 lastseriesidparam = *( 857 ; the following is MANDATORY 858 ; and MAY occur more than once 860 (";" relparam) / 862 ; the following are MANDATORY 863 ; but MUST NOT occur more than once 865 (";" fmttypeparam) / 866 (";" labelparam) / 867 ; labelparam is defined in ... 869 ; the following is OPTIONAL 870 ; and MAY occur more than once 872 (";" xparam) 874 ) 876 Figure 21 878 EXAMPLE 880 The following is an example of this property. It points to a server 881 acting as the source for the calendar object. 883 LINK;REL=SOURCE;LABEL=The Egg:http://example.com/events 885 Figure 22 887 8.8. Series Rule 889 Property name SRULE 891 Purpose This property defines a rule or repeating pattern for a 892 series of events, to-dos or journal entries. 894 Value Type RECUR 896 Property Parameters IANA, non-standard, look-ahead count or date 897 property parameters can be specified on this property. 899 Conformance This property can be specified in any "VEVENT", "VTODO", 900 and "VJOURNAL" calendar component, but it SHOULD NOT be specified 901 more than once. 903 Description 905 The series rule, if specified, is used in computing the instances to 906 be generated for the series. These are generated by considering the 907 master "DTSTART" property along with the "SRULE", "SDATE", and 908 "SXDATE" properties contained within the series master. The 909 "DTSTART" property defines the first instance in the recurrence set 910 which is represented by that master event. 912 Unlike the RRULE the "DTSTART" property MUST be synchronized with the 913 series rule, if specified. For example, if the DTSTARTS species a 914 date on Wednesday but the SRULE specifies every Tuesday then a server 915 or client MUSt reject the component. 917 The final series is represented by gathering all of the start DATE- 918 TIME values generated by any of the specified "SRULE" and "SDATE" 919 properties, and then excluding any start DATE-TIME values specified 920 by "SXDATE" properties. This implies that start DATE- TIME values 921 specified by "SXDATE" properties take precedence over those specified 922 by inclusion properties (i.e., "SDATE" and "SRULE"). Where duplicate 923 instances are generated by the "SRULE" and "SDATE" properties, only 924 one instance is considered. Duplicate instances are ignored. 926 The "DTSTART" property specified within the master iCalendar object 927 defines the first instance of the recurrence. In most cases, a 928 "DTSTART" property of DATE-TIME value type used with a series rule, 929 should be specified as a date with local time and time zone reference 930 to make sure all the recurrence instances start at the same local 931 time regardless of time zone changes. 933 If the duration of the series component is specified with the "DTEND" 934 or "DUE" property, then the same exact duration will apply to all the 935 members of the generated series. Else, if the duration of the series 936 master component is specified with the "DURATION" property, then the 937 same nominal duration will apply to all the members of the generated 938 series and the exact duration of each instance will depend on its 939 specific start time. For example, series instances of a nominal 940 duration of one day will have an exact duration of more or less than 941 24 hours on a day where a time zone shift occurs. The duration of a 942 specific instance may be modified in an exception component or simply 943 by using an "SDATE" property of PERIOD value type. 945 Format Definition 947 This property is defined by the following notation: 949 srule = "SRULE" srulparam ":" recur CRLF 951 sruleparam = *( 952 ; the following are OPTIONAL 953 ; but MUST NOT occur more than once 955 (";" lookahead-countparam) / 956 (";" lookahead-periodparam) / 958 ; the following is OPTIONAL 959 ; and MAY occur more than once 961 (";" xparam) 963 ) 965 Figure 23 967 EXAMPLE 969 TODO - Say they are pretty much the same as RRULE but extra params 971 9. Redefined RELATED-TO Property 973 9.1. RELATED-TO 975 Property name RELATED-TO 977 Purpose This property is used to represent a relationship or 978 reference between one calendar component and another. The 979 definition here extends the definition in [RFC5545] by including a 980 section on RELTYPE=SERIES-MASTER. 982 Value type URI, UID or TEXT 984 Conformance This property MAY be specified in any iCalendar 985 component. 987 Description By default or when VALUE=UID is specified, the property 988 value consists of the persistent, globally unique identifier of 989 another calendar component. This value would be represented in a 990 calendar component by the "UID" property. 992 By default, the property value points to another calendar 993 component that has a PARENT relationship to the referencing 994 object. The "RELTYPE" property parameter is used to either 995 explicitly state the default PARENT relationship type to the 996 referenced calendar component or to override the default PARENT 997 relationship type and specify either a CHILD or SIBLING 998 relationship or a temporal relationship. 1000 The PARENT relationship indicates that the calendar component is a 1001 subordinate of the referenced calendar component. The CHILD 1002 relationship indicates that the calendar component is a superior 1003 of the referenced calendar component. The SIBLING relationship 1004 indicates that the calendar component is a peer of the referenced 1005 calendar component. 1007 The FINISHTOSTART, FINISHTOFINISH, STARTTOFINISH or STARTTOSTART 1008 relationships define temporal relationships as specified in the 1009 reltype parameter definition. 1011 The SERIES-MASTER relationship when included in a series instance 1012 refers to the master of that series. When included in a series 1013 master it refers to a previous master in a chain of spilt series. 1015 Changes to a calendar component referenced by this property can 1016 have an implicit impact on the related calendar component. For 1017 example, if a group event changes its start or end date or time, 1018 then the related, dependent events will need to have their start 1019 and end dates changed in a corresponding way. Similarly, if a 1020 PARENT calendar component is cancelled or deleted, then there is 1021 an implied impact to the related CHILD calendar components. This 1022 property is intended only to provide information on the 1023 relationship of calendar components. It is up to the target 1024 calendar system to maintain any property implications of this 1025 relationship. 1027 Format Definition This property is defined by the following 1028 notation: 1030 related = "RELATED-TO" relparam ( ":" text ) / 1031 ( 1032 ";" "VALUE" "=" "UID" 1033 ":" uid 1034 ) 1035 ( 1036 ";" "VALUE" "=" "URI" 1037 ":" uri 1038 ) 1039 CRLF 1041 relparam = *( 1042 ; 1043 ; The following are OPTIONAL, 1044 ; but MUST NOT occur more than once. 1045 ; 1046 (";" reltypeparam) / 1047 (";" gapparam) / 1048 ; 1049 ; The following is OPTIONAL, 1050 ; and MAY occur more than once. 1051 ; 1052 (";" other-param) 1053 ; 1054 ) 1056 Figure 24 1058 EXAMPLE 1060 The following are examples of this property. 1062 RELATED-TO;RELTYPE=SERIES-MASTER:19960401-080045-4000F192713 1064 Figure 25 1066 10. Backwards compatibility 1068 Any clients following the approach specified in [RFC5545] are 1069 expected to ignore any properties or parameters they don't recognize. 1071 For such clients the series appears to be an unconnected set of 1072 components. They all have their own unique UIDS. If the client 1073 updates an instance this should be identical in effect to an update 1074 carried out by a client aware of the new properties. 1076 Updates MUST preserve the SERIES-ID, LAST-SERIES-ID, SRULE, SDATE and 1077 SXDATE properties. A client which does not do so is in violation of 1078 [RFC5545]. 1080 TODO - More text needed here... == 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 11. IANA Considerations 1097 11.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 11.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 11.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 12. Normative References 1152 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1153 Requirement Levels", RFC 2119, IETF RFC 2119, 1154 DOI 10.17487/RFC2119, March 1997, 1155 . 1157 [RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S., and D. 1158 Jensen, "HTTP Extensions for Distributed 1159 Authoring — WEBDAV", RFC 2518, IETF RFC 2518, 1160 DOI 10.17487/RFC2518, February 1999, 1161 . 1163 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1164 Resource Identifier (URI): Generic Syntax", RFC 3986, 1165 IETF RFC 3986, DOI 10.17487/RFC3986, January 2005, 1166 . 1168 [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, 1169 "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, 1170 IETF RFC 4791, DOI 10.17487/RFC4791, March 2007, 1171 . 1173 [RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and 1174 Scheduling Core Object Specification (iCalendar)", RFC 1175 5545, IETF RFC 5545, DOI 10.17487/RFC5545, September 2009, 1176 . 1178 [RFC5546] Daboo, C., Ed., "iCalendar Transport-Independent 1179 Interoperability Protocol (iTIP)", RFC 5546, IETF RFC 1180 5546, DOI 10.17487/RFC5546, December 2009, 1181 . 1183 [RFC6047] Melnikov, A., Ed., "iCalendar Message-Based 1184 Interoperability Protocol (iMIP)", RFC 6047, IETF RFC 1185 6047, DOI 10.17487/RFC6047, December 2010, 1186 . 1188 [RFC6638] Daboo, C. and B. Desruisseaux, "Scheduling Extensions to 1189 CalDAV", RFC 6638, IETF RFC 6638, DOI 10.17487/RFC6638, 1190 June 2012, . 1192 [RFC7986] Daboo, C., "New Properties for iCalendar", RFC 7986, 1193 IETF RFC 7986, DOI 10.17487/RFC7986, October 2016, 1194 . 1196 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1197 2119 Key Words", RFC 8174, IETF RFC 8174, 1198 DOI 10.17487/RFC8174, May 2017, 1199 . 1201 13. Informative References 1203 [RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC 1204 Text on Security Considerations", RFC 3552, IETF RFC 3552, 1205 DOI 10.17487/RFC3552, July 2003, 1206 . 1208 [RFC4918] Dusseault, L., Ed., "HTTP Extensions for Web Distributed 1209 Authoring and Versioning (WebDAV)", RFC 4918, IETF RFC 1210 4918, DOI 10.17487/RFC4918, June 2007, 1211 . 1213 [RFC5378] Bradner, S., Ed. and J. Contreras, Ed., "Rights 1214 Contributors Provide to the IETF Trust", RFC 5378, 1215 IETF RFC 5378, DOI 10.17487/RFC5378, November 2008, 1216 . 1218 Author's Address 1219 Michael Douglass 1221 Email: mikeadouglass@gmail.com