idnits 2.17.1 draft-ietf-calext-jscalendar-30.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (September 6, 2020) is 1318 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) == Missing Reference: 'Alert' is mentioned on line 2963, but not defined == Missing Reference: 'Boolean' is mentioned on line 3215, but not defined == Missing Reference: 'Link' is mentioned on line 3107, but not defined == Missing Reference: 'PatchObject' is mentioned on line 3186, but not defined == Missing Reference: 'Location' is mentioned on line 3121, but not defined == Missing Reference: 'Participant' is mentioned on line 3155, but not defined == Missing Reference: 'Relation' is mentioned on line 3199, but not defined == Missing Reference: 'String' is mentioned on line 3242, but not defined == Missing Reference: 'TimeZone' is mentioned on line 3273, but not defined == Missing Reference: 'VirtualLocation' is mentioned on line 3310, but not defined -- Possible downref: Non-RFC (?) normative reference: ref. 'CLDR' -- Possible downref: Non-RFC (?) normative reference: ref. 'COLORS' -- Possible downref: Non-RFC (?) normative reference: ref. 'TZDB' Summary: 0 errors (**), 0 flaws (~~), 11 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Calendaring extensions N. Jenkins 3 Internet-Draft R. Stepanek 4 Intended status: Standards Track Fastmail 5 Expires: March 10, 2021 September 6, 2020 7 JSCalendar: A JSON representation of calendar data 8 draft-ietf-calext-jscalendar-30 10 Abstract 12 This specification defines a data model and JSON representation of 13 calendar data that can be used for storage and data exchange in a 14 calendaring and scheduling environment. It aims to be an alternative 15 and, over time, successor to the widely deployed iCalendar data 16 format, and to be unambiguous, extendable, and simple to process. In 17 contrast to the jCal format, which is also JSON-based, JSCalendar is 18 not a direct mapping from iCalendar, but defines the data model 19 independently and expands semantics where appropriate. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at https://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on March 10, 2021. 38 Copyright Notice 40 Copyright (c) 2020 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (https://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 56 1.1. Motivation and Relation to iCalendar and jCal . . . . . . 5 57 1.2. Notational Conventions . . . . . . . . . . . . . . . . . 6 58 1.3. Type Signatures . . . . . . . . . . . . . . . . . . . . . 6 59 1.4. Data Types . . . . . . . . . . . . . . . . . . . . . . . 7 60 1.4.1. Int . . . . . . . . . . . . . . . . . . . . . . . . . 7 61 1.4.2. UnsignedInt . . . . . . . . . . . . . . . . . . . . . 7 62 1.4.3. UTCDateTime . . . . . . . . . . . . . . . . . . . . . 7 63 1.4.4. LocalDateTime . . . . . . . . . . . . . . . . . . . . 7 64 1.4.5. Duration . . . . . . . . . . . . . . . . . . . . . . 8 65 1.4.6. SignedDuration . . . . . . . . . . . . . . . . . . . 9 66 1.4.7. Id . . . . . . . . . . . . . . . . . . . . . . . . . 10 67 1.4.8. PatchObject . . . . . . . . . . . . . . . . . . . . . 10 68 1.4.9. Time Zones . . . . . . . . . . . . . . . . . . . . . 11 69 1.4.10. Relation . . . . . . . . . . . . . . . . . . . . . . 11 70 2. JSCalendar Objects . . . . . . . . . . . . . . . . . . . . . 12 71 2.1. JSEvent . . . . . . . . . . . . . . . . . . . . . . . . . 12 72 2.2. JSTask . . . . . . . . . . . . . . . . . . . . . . . . . 12 73 2.3. JSGroup . . . . . . . . . . . . . . . . . . . . . . . . . 12 74 3. Structure of JSCalendar Objects . . . . . . . . . . . . . . . 13 75 3.1. Object Type . . . . . . . . . . . . . . . . . . . . . . . 13 76 3.2. Normalization and Equivalence . . . . . . . . . . . . . . 13 77 3.3. Vendor-specific Property Extensions, Values and Types . . 13 78 4. Common JSCalendar Properties . . . . . . . . . . . . . . . . 14 79 4.1. Metadata Properties . . . . . . . . . . . . . . . . . . . 14 80 4.1.1. @type . . . . . . . . . . . . . . . . . . . . . . . . 14 81 4.1.2. uid . . . . . . . . . . . . . . . . . . . . . . . . . 14 82 4.1.3. relatedTo . . . . . . . . . . . . . . . . . . . . . . 15 83 4.1.4. prodId . . . . . . . . . . . . . . . . . . . . . . . 15 84 4.1.5. created . . . . . . . . . . . . . . . . . . . . . . . 15 85 4.1.6. updated . . . . . . . . . . . . . . . . . . . . . . . 16 86 4.1.7. sequence . . . . . . . . . . . . . . . . . . . . . . 16 87 4.1.8. method . . . . . . . . . . . . . . . . . . . . . . . 16 88 4.2. What and Where Properties . . . . . . . . . . . . . . . . 16 89 4.2.1. title . . . . . . . . . . . . . . . . . . . . . . . . 16 90 4.2.2. description . . . . . . . . . . . . . . . . . . . . . 16 91 4.2.3. descriptionContentType . . . . . . . . . . . . . . . 16 92 4.2.4. showWithoutTime . . . . . . . . . . . . . . . . . . . 17 93 4.2.5. locations . . . . . . . . . . . . . . . . . . . . . . 17 94 4.2.6. virtualLocations . . . . . . . . . . . . . . . . . . 18 95 4.2.7. links . . . . . . . . . . . . . . . . . . . . . . . . 19 96 4.2.8. locale . . . . . . . . . . . . . . . . . . . . . . . 21 97 4.2.9. keywords . . . . . . . . . . . . . . . . . . . . . . 21 98 4.2.10. categories . . . . . . . . . . . . . . . . . . . . . 21 99 4.2.11. color . . . . . . . . . . . . . . . . . . . . . . . . 21 100 4.3. Recurrence Properties . . . . . . . . . . . . . . . . . . 22 101 4.3.1. recurrenceId . . . . . . . . . . . . . . . . . . . . 22 102 4.3.2. recurrenceRules . . . . . . . . . . . . . . . . . . . 22 103 4.3.3. excludedRecurrenceRules . . . . . . . . . . . . . . . 31 104 4.3.4. recurrenceOverrides . . . . . . . . . . . . . . . . . 31 105 4.3.5. excluded . . . . . . . . . . . . . . . . . . . . . . 32 106 4.4. Sharing and Scheduling Properties . . . . . . . . . . . . 32 107 4.4.1. priority . . . . . . . . . . . . . . . . . . . . . . 32 108 4.4.2. freeBusyStatus . . . . . . . . . . . . . . . . . . . 33 109 4.4.3. privacy . . . . . . . . . . . . . . . . . . . . . . . 33 110 4.4.4. replyTo . . . . . . . . . . . . . . . . . . . . . . . 34 111 4.4.5. participants . . . . . . . . . . . . . . . . . . . . 35 112 4.5. Alerts Properties . . . . . . . . . . . . . . . . . . . . 40 113 4.5.1. useDefaultAlerts . . . . . . . . . . . . . . . . . . 40 114 4.5.2. alerts . . . . . . . . . . . . . . . . . . . . . . . 40 115 4.6. Multilingual Properties . . . . . . . . . . . . . . . . . 43 116 4.6.1. localizations . . . . . . . . . . . . . . . . . . . . 43 117 4.7. Time Zone Properties . . . . . . . . . . . . . . . . . . 43 118 4.7.1. timeZone . . . . . . . . . . . . . . . . . . . . . . 43 119 4.7.2. timeZones . . . . . . . . . . . . . . . . . . . . . . 44 120 5. Type-specific JSCalendar Properties . . . . . . . . . . . . . 46 121 5.1. JSEvent Properties . . . . . . . . . . . . . . . . . . . 46 122 5.1.1. start . . . . . . . . . . . . . . . . . . . . . . . . 46 123 5.1.2. duration . . . . . . . . . . . . . . . . . . . . . . 46 124 5.1.3. status . . . . . . . . . . . . . . . . . . . . . . . 46 125 5.2. JSTask Properties . . . . . . . . . . . . . . . . . . . . 47 126 5.2.1. due . . . . . . . . . . . . . . . . . . . . . . . . . 47 127 5.2.2. start . . . . . . . . . . . . . . . . . . . . . . . . 47 128 5.2.3. estimatedDuration . . . . . . . . . . . . . . . . . . 47 129 5.2.4. percentComplete . . . . . . . . . . . . . . . . . . . 47 130 5.2.5. progress . . . . . . . . . . . . . . . . . . . . . . 47 131 5.2.6. progressUpdated . . . . . . . . . . . . . . . . . . . 48 132 5.3. JSGroup Properties . . . . . . . . . . . . . . . . . . . 48 133 5.3.1. entries . . . . . . . . . . . . . . . . . . . . . . . 49 134 5.3.2. source . . . . . . . . . . . . . . . . . . . . . . . 49 135 6. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 49 136 6.1. Simple event . . . . . . . . . . . . . . . . . . . . . . 50 137 6.2. Simple task . . . . . . . . . . . . . . . . . . . . . . . 50 138 6.3. Simple group . . . . . . . . . . . . . . . . . . . . . . 50 139 6.4. All-day event . . . . . . . . . . . . . . . . . . . . . . 51 140 6.5. Task with a due date . . . . . . . . . . . . . . . . . . 51 141 6.6. Event with end time zone . . . . . . . . . . . . . . . . 52 142 6.7. Floating-time event (with recurrence) . . . . . . . . . . 52 143 6.8. Event with multiple locations and localization . . . . . 53 144 6.9. Recurring event with overrides . . . . . . . . . . . . . 54 145 6.10. Recurring event with participants . . . . . . . . . . . . 55 146 7. Security Considerations . . . . . . . . . . . . . . . . . . . 57 147 7.1. Expanding Recurrences . . . . . . . . . . . . . . . . . . 57 148 7.2. JSON Parsing . . . . . . . . . . . . . . . . . . . . . . 57 149 7.3. URI Values . . . . . . . . . . . . . . . . . . . . . . . 58 150 7.4. Spam . . . . . . . . . . . . . . . . . . . . . . . . . . 58 151 7.5. Duplication . . . . . . . . . . . . . . . . . . . . . . . 59 152 7.6. Time Zones . . . . . . . . . . . . . . . . . . . . . . . 59 153 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 59 154 8.1. Media Type Registration . . . . . . . . . . . . . . . . . 59 155 8.2. Creation of "JSCalendar Properties" Registry . . . . . . 60 156 8.2.1. Preliminary Community Review . . . . . . . . . . . . 61 157 8.2.2. Submit Request to IANA . . . . . . . . . . . . . . . 61 158 8.2.3. Designated Expert Review . . . . . . . . . . . . . . 61 159 8.2.4. Change Procedures . . . . . . . . . . . . . . . . . . 62 160 8.2.5. JSCalendar Properties Registry Template . . . . . . . 62 161 8.2.6. Initial Contents for the JSCalendar Properties 162 Registry . . . . . . . . . . . . . . . . . . . . . . 63 163 8.3. Creation of "JSCalendar Types" Registry . . . . . . . . . 71 164 8.3.1. JSCalendar Types Registry Template . . . . . . . . . 71 165 8.3.2. Initial Contents for the JSCalendar Types Registry . 71 166 8.4. Creation of "JSCalendar Enum Values" Registry . . . . . . 73 167 8.4.1. JSCalendar Enum Property Template . . . . . . . . . . 73 168 8.4.2. JSCalendar Enum Value Template . . . . . . . . . . . 73 169 8.4.3. Initial Contents for the JSCalendar Enum Registry . . 73 170 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 79 171 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 79 172 10.1. Normative References . . . . . . . . . . . . . . . . . . 79 173 10.2. Informative References . . . . . . . . . . . . . . . . . 81 174 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 82 176 1. Introduction 178 This document defines a data model for calendar event and task 179 objects, or groups of such objects, in electronic calendar 180 applications and systems. The format aims to be unambiguous, 181 extendable and simple to process. 183 The key design considerations for this data model are as follows: 185 o The attributes of the calendar entry represented must be described 186 as simple key-value pairs. Simple events are simple to represent; 187 complex events can be modelled accurately. 189 o Wherever possible, there should be only one way to express the 190 desired semantics, reducing complexity. 192 o The data model should avoid ambiguities, which often lead to 193 interoperability issues between implementations. 195 o The data model should be compatible with the iCalendar data format 196 [RFC5545] [RFC7986] and extensions, but the specification should 197 add new attributes where the iCalendar format currently lacks 198 expressivity, and drop seldom-used, obsolete, or redundant 199 properties. This means translation with no loss of semantics 200 should be easy with most common iCalendar files. 202 o Extensions, such as new properties and components, should not 203 require updates to this document. 205 The representation of this data model is defined in the I-JSON format 206 [RFC7493], which is a strict subset of the JavaScript Object Notation 207 (JSON) Data Interchange Format [RFC8259]. Using JSON is mostly a 208 pragmatic choice: its widespread use makes JSCalendar easier to 209 adopt, and the ready availability of production-ready JSON 210 implementations eliminates a whole category of parser-related 211 interoperability issues, which iCalendar has often suffered from. 213 1.1. Motivation and Relation to iCalendar and jCal 215 The iCalendar data format [RFC5545], a widely deployed interchange 216 format for calendaring and scheduling data, has served calendaring 217 vendors for a long while, but contains some ambiguities and pitfalls 218 that can not be overcome without backward-incompatible changes. 220 Sources of implementation errors include the following: 222 o iCalendar defines various formats for local times, UTC time, and 223 dates. 225 o iCalendar requires custom time zone definitions within a single 226 calendar component. 228 o iCalendar's definition of recurrence rules is ambiguous and has 229 resulted in differing understandings even between experienced 230 calendar developers. 232 o The iCalendar format itself causes interoperability issues due to 233 misuse of CRLF-terminated strings, line continuations, and subtle 234 differences among iCalendar parsers. 236 In recent years, many new products and services have appeared that 237 wish to use a JSON representation of calendar data within their APIs. 238 The JSON format for iCalendar data, jCal [RFC7265], is a direct 239 mapping between iCalendar and JSON. In its effort to represent full 240 iCalendar semantics, it inherits all the same pitfalls and uses a 241 complicated JSON structure. 243 As a consequence, since the standardization of jCal, the majority of 244 implementations and service providers either kept using iCalendar, or 245 came up with their own proprietary JSON representations, which are 246 incompatible with each other and often suffer from common pitfalls, 247 such as storing event start times in UTC (which become incorrect if 248 the timezone's rules change in the future). JSCalendar meets the 249 demand for JSON-formatted calendar data that is free of such known 250 problems and provides a standard representation as an alternative to 251 the proprietary formats. 253 1.2. Notational Conventions 255 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 256 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 257 "OPTIONAL" in this document are to be interpreted as described in BCP 258 14 [RFC2119] [RFC8174] when, and only when, they appear in all 259 capitals, as shown here. 261 The underlying format used for this specification is JSON. 262 Consequently, the terms "object" and "array" as well as the four 263 primitive types (strings, numbers, booleans, and null) are to be 264 interpreted as described in Section 1 of [RFC8259]. 266 Some examples in this document contain "partial" JSON documents used 267 for illustrative purposes. In these examples, three periods "..." 268 are used to indicate a portion of the document that has been removed 269 for compactness. 271 1.3. Type Signatures 273 Type signatures are given for all JSON values in this document. The 274 following conventions are used: 276 o "*" - The type is undefined (the value could be any type, although 277 permitted values may be constrained by the context of this value). 279 o "String" - The JSON string type. 281 o "Number" - The JSON number type. 283 o "Boolean" - The JSON boolean type. 285 o "A[B]" - A JSON object where the keys are all of type "A", and the 286 values are all of type "B". 288 o "A[]" - An array of values of type "A". 290 o "A|B" - The value is either of type "A" or of type "B". 292 Other types may also be given, with their representations defined 293 elsewhere in this document. 295 1.4. Data Types 297 In addition to the standard JSON data types, the following data types 298 are used in this specification: 300 1.4.1. Int 302 Where "Int" is given as a data type, it means an integer in the range 303 -2^53+1 <= value <= 2^53-1, the safe range for integers stored in a 304 floating-point double, represented as a JSON "Number". 306 1.4.2. UnsignedInt 308 Where "UnsignedInt" is given as a data type, it means an integer in 309 the range 0 <= value <= 2^53-1, represented as a JSON "Number". 311 1.4.3. UTCDateTime 313 This is a string in [RFC3339] "date-time" format, with the further 314 restrictions that any letters MUST be in uppercase, the time 315 component MUST be included and the time offset MUST be the character 316 "Z". Fractional second values MUST NOT be included unless non-zero 317 and MUST NOT have trailing zeros, to ensure there is only a single 318 representation for each date-time. 320 For example "2010-10-10T10:10:10.003Z" is OK, but 321 "2010-10-10T10:10:10.000Z" is invalid and is correctly encoded as 322 "2010-10-10T10:10:10Z". 324 1.4.4. LocalDateTime 326 This is a date-time string with no time zone/offset information. It 327 is otherwise in the same format as UTCDateTime, including fractional 328 seconds. For example "2006-01-02T15:04:05" and 329 "2006-01-02T15:04:05.003" are both valid. The time zone to associate 330 the LocalDateTime with comes from an associated property, or if no 331 time zone is associated it defines "floating time". Floating date- 332 times are not tied to any specific time zone. Instead, they occur in 333 each time zone at the given wall-clock time (as opposed to the same 334 instant point in time). 336 A time zone may have a period of discontinuity, for example a change 337 from standard time to daylight-savings time. When converting local 338 date-times that fall in the discontinuity to UTC, the offset before 339 the transition is used. 341 For example, in the America/Los_Angeles time zone, the date-time 342 2020-11-01T01:30:00 occurs twice: before the DST transition with a 343 UTC offset of -07:00, and again after the transition with an offset 344 of -08:00. When converting to UTC, we therefore use the offset 345 before the transition (-07:00) and so it becomes 346 2020-11-01T08:30:00Z. 348 Similarly, in the Australia/Melbourne time zone, the date-time 349 2020-10-04T02:30:00 does not exist: the clocks are moved forward one 350 hour for DST on that day at 02:00. However, such a value may appear 351 during calculations (see duration semantics below), or due to a 352 change in time zone rules (so it was valid when the event was first 353 created). Again, it is interpreted as though the offset before the 354 transition is in effect (+10:00), therefore when converted to UTC we 355 get 2020-10-03T16:30:00Z. 357 1.4.5. Duration 359 Where Duration is given as a type, it means a length of time 360 represented by a subset of ISO8601 duration format, as specified by 361 the following ABNF [RFC5234]: 363 dur-secfrac = "." 1*DIGIT 364 dur-second = 1*DIGIT [dur-secfrac] "S" 365 dur-minute = 1*DIGIT "M" [dur-second] 366 dur-hour = 1*DIGIT "H" [dur-minute] 367 dur-time = "T" (dur-hour / dur-minute / dur-second) 368 dur-day = 1*DIGIT "D" 369 dur-week = 1*DIGIT "W" 370 dur-cal = (dur-week [dur-day] / dur-day) 372 duration = "P" (dur-cal [dur-time] / dur-cal / dur-time) 374 In addition, the duration MUST NOT include fractional second values 375 unless the fraction is non-zero. 377 A duration specifies an abstract number of weeks, days, hours, 378 minutes, and/or seconds. A duration specified using weeks or days 379 does not always correspond to an exact multiple of 24 hours. The 380 number of hours/minutes/seconds may vary if it overlaps a period of 381 discontinuity in the event's time zone, for example a change from 382 standard time to daylight-savings time. Leap seconds MUST NOT be 383 considered when adding or subtracting a duration to/from a 384 LocalDateTime. 386 To add a duration to a LocalDateTime: 388 1. Add any week or day components of the duration to the date. 390 2. If a time zone applies to the LocalDateTime, convert it to a 391 UTCDateTime following the semantics in Section 1.4.4. 393 3. Add any hour, minute or second components of the duration (in 394 absolute time). 396 4. Convert the resulting UTCDateTime back to a LocalDateTime in the 397 time zone that applies. 399 To subtract a duration from a LocalDateTime, the steps apply in 400 reverse: 402 1. If a time zone applies to the LocalDateTime, convert it to UTC 403 following the semantics in Section 1.4.4. 405 2. Subtract any hour, minute or second components of the duration 406 (in absolute time). 408 3. Convert the resulting UTCDateTime back to LocalDateTime in the 409 time zone that applies. 411 4. Subtract any week or day components of the duration from the 412 date. 414 5. If the resulting time does not exist on the date due to a 415 discontinuity in the time zone, use the semantics in 416 Section 1.4.4 to convert to UTC and back to get a valid 417 LocalDateTime. 419 These semantics match the iCalendar DURATION value type ([RFC5545], 420 Section 3.3.6). 422 1.4.6. SignedDuration 424 A SignedDuration represents a length of time that may be positive or 425 negative and is typically used to express the offset of a point in 426 time relative to an associated time. It is represented as a 427 Duration, optionally preceded by a sign character. It is specified 428 by the following ABNF: 430 signed-duration = ["+" / "-"] duration 432 A negative sign indicates a point in time at or before the associated 433 time, a positive or no sign a time at or after the associated time. 435 1.4.7. Id 437 Where "Id" is given as a data type, it means a "String" of at least 1 438 and a maximum of 255 octets in size, and it MUST only contain 439 characters from the "URL and Filename Safe" base64url alphabet, as 440 defined in Section 5 of [RFC4648], excluding the pad character ("="). 441 This means the allowed characters are the ASCII alphanumeric 442 characters ("A-Za-z0-9"), hyphen ("-"), and underscore ("_"). 444 Unless otherwise specified, Ids are arbitrary and only have meaning 445 within the object where they are being used. Ids need not be unique 446 among different objects. For example, two JSEvent objects might use 447 the same ids in their respective "links" properties. Or within the 448 same JSEvent object the same Id could appear in the "participants" 449 and "alerts" properties. These situations do not imply any semantic 450 connections among the objects. 452 Nevertheless, a UUID is typically a good choice. 454 1.4.8. PatchObject 456 A PatchObject is of type "String[*]", and represents an unordered set 457 of patches on a JSON object. Each key is a path represented in a 458 subset of JSON pointer format [RFC6901]. The paths have an implicit 459 leading "/", so each key is prefixed with "/" before applying the 460 JSON pointer evaluation algorithm. 462 A patch within a PatchObject is only valid if all of the following 463 conditions apply: 465 1. The pointer MUST NOT insert/delete from an array; the array MUST 466 be replaced in its entirety instead. 468 2. When evaluating a path, all parts prior to the last (i.e., the 469 value after the final slash) MUST exist. 471 3. There MUST NOT be two patches in the PatchObject where the 472 pointer of one is a prefix of the pointer of the other, e.g., 473 "alerts/foo/offset" and "alerts". 475 4. The value for the patch MUST be valid for the property being set 476 (of the correct type and obeying any other applicable 477 restrictions), or if null the property MUST be optional. 479 The value associated with each pointer is either: 481 o null: Remove the property at the given path from the patched 482 object. If the property is not present in the object, this a no- 483 op. 485 o Anything else: Set the value for the property to this value (this 486 may be a replacement or addition to the object being patched). 488 A PatchObject does not define its own "@type" property. A "@type" 489 property in a patch MUST be handled as any other patched property 490 value. 492 Implementations MUST reject in its entirety a PatchObject if any of 493 its patches is invalid. Implementations MUST NOT apply partial 494 patches. 496 1.4.9. Time Zones 498 By default, time zones in JSCalendar are identified by their names in 499 the IANA Time Zone Database [TZDB], and the zone rules of the 500 respective zone records apply. 502 Implementations MAY embed the definitions of custom time zones in the 503 "timeZones" property (see Section 4.7.2). 505 1.4.10. Relation 507 A Relation object defines the relation to other objects, using a 508 possibly empty set of relation types. The object that defines this 509 relation is the linking object, while the other object is the linked 510 object. The Relation object has the following properties: 512 o @type: "String" (mandatory) 514 Specifies the type of this object. This MUST be "Relation". 516 o relation: "String[Boolean]" (optional, default: empty Object) 518 Describes how the linked object is related to the linking object. 519 The relation is defined as a set of relation types. If empty, the 520 relationship between the two objects is unspecified. 522 Keys in the set MUST be one of the following values, or specified 523 in the property definition where the Relation object is used, or a 524 value registered in the IANA JSCalendar Enum Registry, or a 525 vendor-specific value: 527 * "first": The linked object is the first in a series the linking 528 object is part of. 530 * "next": The linked object is the next in a series the linking 531 object is part of. 533 * "child": The linked object is a subpart of the linking object. 535 * "parent": The linking object is a subpart of the linked object. 537 The value for each key in the set MUST be true. 539 2. JSCalendar Objects 541 This section describes the calendar object types specified by 542 JSCalendar. 544 2.1. JSEvent 546 Media type: "application/jscalendar+json;type=jsevent" 548 A JSEvent represents a scheduled amount of time on a calendar, 549 typically a meeting, appointment, reminder or anniversary. It is 550 required to start at a certain point in time and typically has a non- 551 zero duration. Multiple participants may partake in the event at 552 multiple locations. 554 The @type (Section 4.1.1) property value MUST be "jsevent". 556 2.2. JSTask 558 Media type: "application/jscalendar+json;type=jstask" 560 A JSTask represents an action-item, assignment, to-do or work item. 561 It may start and be due at certain points in time, may take some 562 estimated time to complete, and may recur, none of which is required. 564 The @type (Section 4.1.1) property value MUST be "jstask". 566 2.3. JSGroup 568 Media type: "application/jscalendar+json;type=jsgroup" 570 A JSGroup is a collection of JSEvent (Section 2.1) and/or JSTask 571 (Section 2.2) objects. Typically, objects are grouped by topic 572 (e.g., by keywords) or calendar membership. 574 The @type (Section 4.1.1) property value MUST be "jsgroup". 576 3. Structure of JSCalendar Objects 578 A JSCalendar object is a JSON object, which MUST be valid I-JSON (a 579 stricter subset of JSON), as specified in [RFC8259]. Property names 580 and values are case-sensitive. 582 The object has a collection of properties, as specified in the 583 following sections. Properties are specified as being either 584 mandatory or optional. Optional properties may have a default value, 585 if explicitly specified in the property definition. 587 3.1. Object Type 589 JSCalendar objects MUST name their type in the "@type" property, if 590 not explicitly specified otherwise for the respective object type. A 591 notable exception to this rule is the PatchObject (Section 1.4.8). 593 3.2. Normalization and Equivalence 595 JSCalendar aims to provide unambiguous definitions for value types 596 and properties, but does not define a general normalization or 597 equivalence method for JSCalendar objects and types. This is because 598 the notion of equivalence might range from byte-level equivalence to 599 semantic equivalence, depending on the respective use case. 601 Normalization of JSCalendar objects is hindered because of the 602 following reasons: 604 o Custom JSCalendar properties may contain arbitrary JSON values, 605 including arrays. However, equivalence of arrays might or might 606 not depend on the order of elements, depending on the respective 607 property definition. 609 o Several JSCalendar property values are defined as URIs and media 610 types, but normalization of these types is inherently protocol- 611 and scheme-specific, depending on the use-case of the equivalence 612 definition (see Section 6 of [RFC3986]). 614 Considering this, the definition of equivalence and normalization is 615 left to client and server implementations and to be negotiated by a 616 calendar exchange protocol or defined elsewhere. 618 3.3. Vendor-specific Property Extensions, Values and Types 620 Vendors MAY add additional properties to the calendar object to 621 support their custom features. To avoid conflict, the names of these 622 properties MUST be prefixed by a domain name controlled by the vendor 623 followed by a colon, e.g., "example.com:customprop". If the value is 624 a new JSCalendar object, it either MUST include a "@type" property or 625 it MUST explicitly be specified to not require a type designator. 626 The type name MUST be prefixed with a domain name controlled by the 627 vendor. 629 Some JSCalendar properties allow vendor-specific value extensions. 630 Such vendor-specific values MUST be prefixed by a domain name 631 controlled by the vendor followed by a colon, e.g., 632 "example.com:customrel". 634 Vendors are strongly encouraged to register any new property values 635 or extensions that are useful to other systems as well, rather than 636 use a vendor-specific prefix. 638 4. Common JSCalendar Properties 640 This section describes the properties that are common to the various 641 JSCalendar object types. Specific JSCalendar object types may only 642 support a subset of these properties. The object type definitions in 643 Section 5 describe the set of supported properties per type. 645 4.1. Metadata Properties 647 4.1.1. @type 649 Type: "String" (mandatory). 651 Specifies the type which this object represents. This MUST be one of 652 the following values: 654 o "jsevent": a JSCalendar event (Section 2.1). 656 o "jstask": a JSCalendar task (Section 2.2). 658 o "jsgroup": a JSCalendar group (Section 2.3). 660 4.1.2. uid 662 Type: "String" (mandatory). 664 A globally unique identifier, used to associate the object as the 665 same across different systems, calendars and views. The value of 666 this property MUST be unique across all JSCalendar objects, even if 667 they are of different type. [RFC4122] describes a range of 668 established algorithms to generate universally unique identifiers 669 (UUID). UUID version 4, described in Section 4.4 of [RFC4122], is 670 RECOMMENDED. 672 For compatibility with [RFC5545] UIDs, implementations MUST be able 673 to receive and persist values of at least 255 octets for this 674 property, but they MUST NOT truncate values in the middle of a UTF-8 675 multi-octet sequence. 677 4.1.3. relatedTo 679 Type: "String[Relation]" (optional). 681 Relates the object to other JSCalendar objects. This is represented 682 as a map of the UIDs of the related objects to information about the 683 relation. 685 If an object is split to make a "this and future" change to a 686 recurrence, the original object MUST be truncated to end at the 687 previous occurrence before this split, and a new object created to 688 represent all the occurrences after the split. A "next" relation 689 MUST be set on the original object's relatedTo property for the UID 690 of the new object. A "first" relation for the UID of the first 691 object in the series MUST be set on the new object. Clients can then 692 follow these UIDs to get the complete set of objects if the user 693 wishes to modify them all at once. 695 4.1.4. prodId 697 Type: "String" (optional). 699 The identifier for the product that last updated the JSCalendar 700 object. This should be set whenever the data in the object is 701 modified (i.e., whenever the "updated" property is set). 703 The vendor of the implementation SHOULD ensure that this is a 704 globally unique identifier, using some technique such as an FPI 705 value, as defined in [ISO.9070.1991]. It MUST only use characters of 706 an iCalendar TEXT data value (see Section 3.3.11 of [RFC5545]). 708 This property SHOULD NOT be used to alter the interpretation of a 709 JSCalendar object beyond the semantics specified in this document. 710 For example, it is not to be used to further the understanding of 711 non-standard properties, a practice that is knows to cause long-term 712 interoperability problems. 714 4.1.5. created 716 Type: "UTCDateTime" (optional). 718 The date and time this object was initially created. 720 4.1.6. updated 722 Type: "UTCDateTime" (mandatory). 724 The date and time the data in this object was last modified (or its 725 creation date/time if not modified since). 727 4.1.7. sequence 729 Type: "UnsignedInt" (optional, default: 0). 731 Initially zero, this MUST be incremented by one every time a change 732 is made to the object, except if the change only modifies the 733 "participants" property (see Section 4.4.5). 735 This is used as part of iTIP [RFC5546] to know which version of the 736 object a scheduling message relates to. 738 4.1.8. method 740 Type: "String" (optional). 742 The iTIP [RFC5546] method, in lowercase. This MUST only be present 743 if the JSCalendar object represents an iTIP scheduling message. 745 4.2. What and Where Properties 747 4.2.1. title 749 Type: "String" (optional, default: empty String). 751 A short summary of the object. 753 4.2.2. description 755 Type: "String" (optional, default: empty String). 757 A longer-form text description of the object. The content is 758 formatted according to the "descriptionContentType" property. 760 4.2.3. descriptionContentType 762 Type: "String" (optional, default: "text/plain"). 764 Describes the media type [RFC6838] of the contents of the 765 "description" property. Media types MUST be sub-types of type 766 "text", and SHOULD be "text/plain" or "text/html" [MIME]. They MAY 767 include parameters and the "charset" parameter value MUST be "utf-8", 768 if specified. Descriptions of type "text/html" MAY contain "cid" 769 URLs [RFC2392] to reference links in the calendar object by use of 770 the "cid" property of the Link object. 772 4.2.4. showWithoutTime 774 Type: "Boolean" (optional, default: false). 776 Indicates that the time is not important to display to the user when 777 rendering this calendar object. An example of this is an event that 778 conceptually occurs all day or across multiple days, such as "New 779 Year's Day" or "Italy Vacation". While the time component is 780 important for free-busy calculations and checking for scheduling 781 clashes, calendars may choose to omit displaying it and/or display 782 the object separately to other objects to enhance the user's view of 783 their schedule. 785 Such events are also commonly known as "all-day" events. 787 4.2.5. locations 789 Type: "Id[Location]" (optional). 791 A map of location ids to Location objects, representing locations 792 associated with the object. 794 A Location object has the following properties. It MUST have at 795 least one property other than the "relativeTo" property. 797 o @type: "String" (mandatory) 799 Specifies the type of this object. This MUST be "Location". 801 o name: "String" (optional) 803 The human-readable name of the location. 805 o description: "String" (optional) 807 Human-readable, plain-text instructions for accessing this 808 location. This may be an address, set of directions, door access 809 code, etc. 811 o locationTypes: "String[Boolean]" (optional) 813 A set of one or more location types that describe this location. 814 All types MUST be from the Location Types Registry [LOCATIONTYPES] 815 as defined in [RFC4589]. The set is represented as a map, with 816 the keys being the location types. The value for each key in the 817 map MUST be true. 819 o relativeTo: "String" (optional) 821 Specifies the relation between this location and the time of the 822 JSCalendar object. This is primarily to allow events representing 823 travel to specify the location of departure (at the start of the 824 event) and location of arrival (at the end); this is particularly 825 important if these locations are in different time zones, as a 826 client may wish to highlight this information for the user. 828 This MUST be one of the following values, a value registered in 829 the IANA JSCalendar Enum Registry, or a vendor-specific value. 830 Any value the client or server doesn't understand should be 831 treated the same as if this property is omitted. 833 * "start": The event/task described by this JSCalendar object 834 occurs at this location at the time the event/task starts. 836 * "end": The event/task described by this JSCalendar object 837 occurs at this location at the time the event/task ends. 839 o timeZone: "String" (optional) 841 A time zone for this location. See also Section 1.4.9. 843 o coordinates: "String" (optional) 845 A "geo:" URI [RFC5870] for the location. 847 o linkIds: "Id[Boolean]" (optional) 849 A set of link ids for links to alternative representations of this 850 location. Each key in the set MUST be the id of a Link object 851 defined in the "links" property of this calendar object. The 852 value for each key in the set MUST be true. If there are no 853 links, this MUST be omitted (rather than specified as an empty 854 set). 856 For example, an alternative representation could be in vCard 857 format. 859 4.2.6. virtualLocations 861 Type: "Id[VirtualLocation]" (optional). 863 A map of ids to VirtualLocation objects, representing virtual 864 locations, such as video conferences or chat rooms, associated with 865 the object. 867 A VirtualLocation object has the following properties. 869 o @type: "String" (mandatory) 871 Specifies the type of this object. This MUST be 872 "VirtualLocation". 874 o name: "String" (optional, default: empty String) 876 The human-readable name of the virtual location. 878 o description: "String" (optional) 880 Human-readable plain-text instructions for accessing this 881 location. This may be an address, set of directions, door access 882 code, etc. 884 o uri: "String" (mandatory) 886 A URI that represents how to connect to this virtual location. 888 This may be a telephone number (represented using the "tel:" 889 scheme, e.g., "tel:+1-555-555-555") for a teleconference, a web 890 address for online chat, or any custom URI. 892 4.2.7. links 894 Type: "Id[Link]" (optional). 896 A map of link ids to Link objects, representing external resources 897 associated with the object. 899 A Link object has the following properties: 901 o @type: "String" (mandatory) 903 Specifies the type of this object. This MUST be "Link". 905 o href: "String" (mandatory) 907 A URI from which the resource may be fetched. 909 This MAY be a "data:" URL [RFC2397], but it is recommended that 910 the file be hosted on a server to avoid embedding arbitrarily 911 large data in JSCalendar object instances. 913 o cid: "String" (optional) 915 This MUST be a valid "content-id" value according to the 916 definition of Section 2 in [RFC2392]. The value MUST be unique 917 within this Link object but has no meaning beyond that. It MAY be 918 different from the link id for this Link object. 920 o contentType: "String" (optional) 922 The media type [RFC6838] of the resource, if known. 924 o size: "UnsignedInt" (optional) 926 The size, in octets, of the resource when fully decoded (i.e., the 927 number of octets in the file the user would download), if known. 928 Note that this is an informational estimate, and implementations 929 must be prepared to handle the actual size being quite different 930 when the resource is fetched. 932 o rel: "String" (optional) 934 Identifies the relation of the linked resource to the object. If 935 set, the value MUST be a relation type from the IANA registry 936 [LINKRELS], as established in [RFC8288]. 938 Links with a rel of "enclosure" MUST be considered by the client 939 as attachments for download. 941 Links with a rel of "describedby" MUST be considered by the client 942 to be an alternative representation of the description. 944 Links with a rel of "icon" MUST be considered by the client to be 945 an image that it may use when presenting the calendar data to a 946 user. The "display" property may be set to indicate the purpose 947 of this image. 949 o display: "String" (optional) 951 Describes the intended purpose of a link to an image. If set, the 952 "rel" property MUST be set to "icon". The value MUST be one of 953 the following values, a value registered in the IANA JSCalendar 954 Enum Registry, or a vendor-specific value: 956 * "badge": an image meant to be displayed alongside the title of 957 the object. 959 * "graphic": a full image replacement for the object itself. 961 * "fullsize": an image that is used to enhance the object. 963 * "thumbnail": a smaller variant of "fullsize" to be used when 964 space for the image is constrained. 966 o title: "String" (optional) 968 A human-readable plain-text description of the resource. 970 4.2.8. locale 972 Type: "String" (optional). 974 The language tag as defined in [RFC5646] that best describes the 975 locale used for the text in the calendar object, if known. 977 4.2.9. keywords 979 Type: "String[Boolean]" (optional). 981 A set of keywords or tags that relate to the object. The set is 982 represented as a map, with the keys being the keywords. The value 983 for each key in the map MUST be true. 985 4.2.10. categories 987 Type: "String[Boolean]" (optional). 989 A set of categories that relate to the calendar object. The set is 990 represented as a map, with the keys being the categories specified as 991 URIs. The value for each key in the map MUST be true. 993 In contrast to keywords, categories typically are structured. For 994 example, a vendor owning the domain "example.com" might define the 995 categories "http://example.com/categories/sports/american-football" 996 and "http://example.com/categories/music/r-b". 998 4.2.11. color 1000 Type: "String" (optional). 1002 A color clients MAY use when displaying this calendar object. The 1003 value is a color name taken from the set of names defined in 1004 Section 4.3 of CSS Color Module Level 3 [COLORS], or an RGB value in 1005 hexadecimal notation, as defined in Section 4.2.1 of CSS Color Module 1006 Level 3. 1008 4.3. Recurrence Properties 1010 Some events and tasks occur at regular or irregular intervals. 1011 Rather than having to copy the data for every occurrence there can be 1012 a master event with rules to generate recurrences, and/or overrides 1013 that add extra dates or exceptions to the rules. 1015 The recurrence set is the compelete set of instances for an object. 1016 It is generated by considering the following properties in order, all 1017 of which are optional: 1019 1. The recurrenceRules property (Section 4.3.2) generates a set of 1020 extra date-times on which the object occurs. 1022 2. The excludedRecurrenceRules property (Section 4.3.3) generates a 1023 set of date-times that are to be removed from the previously 1024 generated set of date-times on which the object occurs. 1026 3. The recurrenceOverrides property (Section 4.3.4) defines date- 1027 times which are added or excluded to form the final set. (This 1028 property may also contain changes to the object to apply to 1029 particular instances.) 1031 4.3.1. recurrenceId 1033 Type: "LocalDateTime" (optional). 1035 If present, this JSCalendar object represents one occurrence of a 1036 recurring JSCalendar object. If present the "recurrenceRules" and 1037 "recurrenceOverrides" properties MUST NOT be present. 1039 The value is a date-time either produced by the "recurrenceRules" of 1040 the master event, or added as a key to the "recurrenceOverrides" 1041 property of the master event. 1043 4.3.2. recurrenceRules 1045 Type: "RecurrenceRule[]" (optional). 1047 Defines a set of recurrence rules (repeating patterns) for recurring 1048 calendar objects. 1050 A JSEvent recurs by applying the recurrence rules to the "start" 1051 date-time. 1053 A JSTask recurs by applying the recurrence rules to the "start" date- 1054 time, if defined, otherwise it recurs by the "due" date-time, if 1055 defined. If the task defines neither a "start" nor "due" date-time, 1056 it MUST NOT define a "recurrenceRules" property. 1058 If multiple recurrence rules are given, each rule is to be applied 1059 and then the union of the results used, ignoring any duplicates. 1061 A RecurrenceRule object is a JSON object mapping of a RECUR value 1062 type in iCalendar [RFC5545] [RFC7529] and has the same semantics. It 1063 has the following properties: 1065 o @type: "String" (mandatory) 1067 Specifies the type of this object. This MUST be "RecurrenceRule". 1069 o frequency: "String" (mandatory) 1071 The time span covered by each iteration of this recurrence rule 1072 (see Section 4.3.2.1 for full semantics). This MUST be one of the 1073 following values: 1075 * "yearly" 1077 * "monthly" 1079 * "weekly" 1081 * "daily" 1083 * "hourly" 1085 * "minutely" 1087 * "secondly" 1089 This is the FREQ part from iCalendar, converted to lowercase. 1091 o interval: "UnsignedInt" (optional, default: 1) 1093 The interval of iteration periods at which the recurrence repeats. 1094 If included, it MUST be an integer >= 1. 1096 This is the INTERVAL part from iCalendar. 1098 o rscale: "String" (optional, default: "gregorian") 1099 The calendar system in which this recurrence rule operates, in 1100 lowercase. This MUST be either a CLDR-registered calendar system 1101 name [CLDR], or a vendor-specific value. 1103 This is the RSCALE part from iCalendar RSCALE [RFC7529], converted 1104 to lowercase. 1106 o skip: "String" (optional, default: "omit") 1108 The behaviour to use when the expansion of the recurrence produces 1109 invalid dates. This property only has an effect if the frequency 1110 is "yearly" or "monthly". It MUST be one of the following values: 1112 * "omit" 1114 * "backward" 1116 * "forward" 1118 This is the SKIP part from iCalendar RSCALE [RFC7529], converted 1119 to lowercase. 1121 o firstDayOfWeek: "String" (optional, default: "mo") 1123 The day on which the week is considered to start, represented as a 1124 lowercase abbreviated two-letter English day of the week. If 1125 included, it MUST be one of the following values: 1127 * "mo" 1129 * "tu" 1131 * "we" 1133 * "th" 1135 * "fr" 1137 * "sa" 1139 * "su" 1141 This is the WKST part from iCalendar. 1143 o byDay: "NDay[]" (optional) 1145 Days of the week on which to repeat. An "NDay" object has the 1146 following properties: 1148 * @type: "String" (mandatory) 1150 Specifies the type of this object. This MUST be "NDay". 1152 * day: "String" (mandatory) 1154 A day of the week on which to repeat; the allowed values are 1155 the same as for the "firstDayOfWeek" RecurrenceRule property. 1157 This is the day-of-the-week of the BYDAY part in iCalendar, 1158 converted to lowercase. 1160 * nthOfPeriod: "Int" (optional) 1162 If present, rather than representing every occurrence of the 1163 weekday defined in the "day" property, it represents only a 1164 specific instance within the recurrence period. The value can 1165 be positive or negative, but MUST NOT be zero. A negative 1166 integer means nth-last of period. 1168 This is the ordinal part of the BYDAY value in iCalendar (e.g., 1169 1 or -3). 1171 o byMonthDay: "Int[]" (optional) 1173 Days of the month on which to repeat. Valid values are between 1 1174 and the maximum number of days any month may have in the calendar 1175 given by the "rscale" property, and the negative values of these 1176 numbers. For example, in the Gregorian calendar valid values are 1177 1 to 31 and -31 to -1. Negative values offset from the end of the 1178 month. The array MUST have at least one entry if included. 1180 This is the BYMONTHDAY part in iCalendar. 1182 o byMonth: "String[]" (optional) 1184 The months in which to repeat. Each entry is a string 1185 representation of a number, starting from "1" for the first month 1186 in the calendar (e.g., "1" means January with the Gregorian 1187 calendar), with an optional "L" suffix (see [RFC7529]) for leap 1188 months (this MUST be uppercase, e.g., "3L"). The array MUST have 1189 at least one entry if included. 1191 This is the BYMONTH part from iCalendar. 1193 o byYearDay: "Int[]" (optional) 1194 The days of the year on which to repeat. Valid values are between 1195 1 and the maximum number of days any year may have in the calendar 1196 given by the "rscale" property, and the negative values of these 1197 numbers. For example, in the Gregorian calendar valid values are 1198 1 to 366 and -366 to -1. Negative values offset from the end of 1199 the year. The array MUST have at least one entry if included. 1201 This is the BYYEARDAY part from iCalendar. 1203 o byWeekNo: "Int[]" (optional) 1205 Weeks of the year in which to repeat. Valid values are between 1 1206 and the maximum number of weeks any year may have in the calendar 1207 given by the "rscale" property, and the negative values of these 1208 numbers. For example, in the Gregorian calendar valid values are 1209 1 to 53 and -53 to -1. The array MUST have at least one entry if 1210 included. 1212 This is the BYWEEKNO part from iCalendar. 1214 o byHour: "UnsignedInt[]" (optional) 1216 The hours of the day in which to repeat. Valid values are 0 to 1217 23. The array MUST have at least one entry if included. This is 1218 the BYHOUR part from iCalendar. 1220 o byMinute: "UnsignedInt[]" (optional) 1222 The minutes of the hour in which to repeat. Valid values are 0 to 1223 59. The array MUST have at least one entry if included. 1225 This is the BYMINUTE part from iCalendar. 1227 o bySecond: "UnsignedInt[]" (optional) 1229 The seconds of the minute in which to repeat. Valid values are 0 1230 to 60. The array MUST have at least one entry if included. 1232 This is the BYSECOND part from iCalendar. 1234 o bySetPosition: "Int[]" (optional) 1236 The occurrences within the recurrence interval to include in the 1237 final results. Negative values offset from the end of the list of 1238 occurrences. The array MUST have at least one entry if included. 1239 This is the BYSETPOS part from iCalendar. 1241 o count: "UnsignedInt" (optional) 1242 The number of occurrences at which to range-bound the recurrence. 1243 This MUST NOT be included if an "until" property is specified. 1245 This is the COUNT part from iCalendar. 1247 o until: "LocalDateTime" (optional) 1249 The date-time at which to finish recurring. The last occurrence 1250 is on or before this date-time. This MUST NOT be included if a 1251 "count" property is specified. Note: if not specified otherwise 1252 for a specific JSCalendar object, this date is to be interpreted 1253 in the time zone specified in the JSCalendar object's "timeZone" 1254 property. 1256 This is the UNTIL part from iCalendar. 1258 4.3.2.1. Interpreting recurrence rules 1260 A recurrence rule specifies a set of date-times for recurring 1261 calendar objects. A recurrence rule has the following semantics. 1262 Note, wherever "year", "month" or "day of month" is used, this is 1263 within the calendar system given by the "rscale" property, which 1264 defaults to "gregorian" if omitted. 1266 1. A set of candidates is generated. This is every second within a 1267 period defined by the frequency property value: 1269 * "yearly": every second from midnight on the 1st day of a year 1270 (inclusive) to midnight the 1st day of the following year 1271 (exclusive). 1273 If skip is not "omit", the calendar system has leap months and 1274 there is a byMonth property, generate candidates for the leap 1275 months even if they don't occur in this year. 1277 If skip is not "omit" and there is a byMonthDay property, 1278 presume each month has the maximum number of days any month 1279 may have in this calendar system when generating candidates, 1280 even if it's more than this month actually has. 1282 * "monthly": every second from midnight on the 1st day of a 1283 month (inclusive) to midnight on the 1st of the following 1284 month (exclusive). 1286 If skip is not "omit" and there is a byMonthDay property, 1287 presume the month has the maximum number of days any month may 1288 have in this calendar system when generating candidates, even 1289 if it's more than this month actually has. 1291 * "weekly": every second from midnight (inclusive) on the first 1292 day of the week (as defined by the firstDayOfWeek property, or 1293 Monday if omitted), to midnight 7 days later (exclusive). 1295 * "daily": every second from midnight at the start of the day 1296 (inclusive) to midnight at the end of the day (exclusive). 1298 * "hourly": every second from the beginning of the hour 1299 (inclusive) to the beginning of the next hour (exclusive). 1301 * "minutely": every second from the beginning of the minute 1302 (inclusive) to the beginning of the next minute (exclusive). 1304 * "secondly": the second itself, only. 1306 2. Each date-time candidate is compared against all of the byX 1307 properties of the rule except bySetPosition. If any property in 1308 the rule does not match the date-time, it is eliminated. Each 1309 byX property is an array; the date-time matches the property if 1310 it matches any of the values in the array. The properties have 1311 the following semantics: 1313 * byMonth: the date-time is in the given month. 1315 * byWeekNo: the date-time is in the nth week of the year. 1316 Negative numbers mean the nth last week of the year. This 1317 corresponds to weeks according to week numbering as defined in 1318 ISO.8601.2004, with a week defined as a seven day period, 1319 starting on the firstDayOfWeek property value or Monday if 1320 omitted. Week number one of the calendar year is the first 1321 week that contains at least four days in that calendar year. 1323 If the date-time is not valid (this may happen when generating 1324 candidates with a skip property in effect), it is always 1325 eliminated by this property. 1327 * byYearDay: the date-time is on the nth day of year. Negative 1328 numbers mean the nth last day of the year. 1330 If the date-time is not valid (this may happen when generating 1331 candidates with a skip property in effect), it is always 1332 eliminated by this property. 1334 * byMonthDay: the date-time is on the given day of the month. 1335 Negative numbers mean the nth last day of the month. 1337 * byDay: the date-time is on the given day of the week. If the 1338 day is prefixed by a number, it is the nth occurrence of that 1339 day of the week within the month (if frequency is monthly) or 1340 year (if frequency is yearly). Negative numbers means nth 1341 last occurrence within that period. 1343 * byHour: the date-time has the given hour value. 1345 * byMinute: the date-time has the given minute value. 1347 * bySecond: the date-time has the given second value. 1349 If a skip property is defined and is not "omit", there may be 1350 candidates that do not correspond to valid dates (e.g., 31st 1351 February in the Gregorian calendar). In this case, the 1352 properties MUST be considered in the order above and: 1354 1. After applying the byMonth filter, if the candidate's month 1355 is invalid for the given year, increment it (if skip is 1356 "forward") or decrement it (if skip is "backward") until a 1357 valid month is found, incrementing/decrementing the year as 1358 well if passing through the beginning/end of the year. This 1359 only applies to calendar systems with leap months. 1361 2. After applying the byMonthDay filter, if the day of the month 1362 is invalid for the given month and year, change the date to 1363 the first day of the next month (if skip is "forward") or the 1364 last day of the current month (if skip is "backward"). 1366 3. If any valid date produced after applying the skip is already 1367 a candidate, eliminate the duplicate. (For example after 1368 adjusting, 30th February and 31st February would both become 1369 the same "real" date, so one is eliminated as a duplicate.) 1371 3. If a bySetPosition property is included, this is now applied to 1372 the ordered list of remaining dates. This property specifies the 1373 indexes of date-times to keep; all others should be eliminated. 1374 Negative numbers are indexes from the end of the list, with -1 1375 being the last item. 1377 4. Any date-times before the start date of the event are eliminated 1378 (see below for why this might be needed). 1380 5. If a skip property is included and is not "omit", eliminate any 1381 date-times that have already been produced by previous iterations 1382 of the algorithm. (This is not possible if skip is "omit".) 1384 6. If further dates are required (we have not reached the until 1385 date, or count limit) skip the next (interval - 1) sets of 1386 candidates, then continue from step 1. 1388 When determining the set of occurrence dates for an event or task, 1389 the following extra rules must be applied: 1391 1. The initial date-time to which the rule is applied (the "start" 1392 date-time for events; the "start" or "due" date-time for tasks) 1393 is always the first occurrence in the expansion (and is counted 1394 if the recurrence is limited by a "count" property), even if it 1395 would normally not match the rule. 1397 2. The first set of candidates to consider is that which would 1398 contain the initial date-time. This means the first set may 1399 include candidates before the initial date-time; such candidates 1400 are eliminated from the results in step (4) as outlined before. 1402 3. The following properties MUST be implicitly added to the rule 1403 under the given conditions: 1405 * If frequency is not "secondly" and no bySecond property: Add a 1406 bySecond property with the sole value being the seconds value 1407 of the initial date-time. 1409 * If frequency is not "secondly" or "minutely", and no byMinute 1410 property: Add a byMinute property with the sole value being 1411 the minutes value of the initial date-time. 1413 * If frequency is not "secondly", "minutely" or "hourly" and no 1414 byHour property: Add a byHour property with the sole value 1415 being the hours value of the initial date-time. 1417 * If frequency is "weekly" and no byDay property: Add a byDay 1418 property with the sole value being the day-of-the-week of the 1419 initial date-time. 1421 * If frequency is "monthly" and no byDay property and no 1422 byMonthDay property: Add a byMonthDay property with the sole 1423 value being the day-of-the-month of the initial date-time. 1425 * If frequency is "yearly" and no byYearDay property: 1427 + If there are no byMonth or byWeekNo properties, and either 1428 there is a byMonthDay property or there is no byDay 1429 property: Add a byMonth property with the sole value being 1430 the month of the initial date-time. 1432 + If there is no byMonthDay, byWeekNo or byDay properties: 1433 Add a byMonthDay property with the sole value being the 1434 day-of-the-month of the initial date-time. 1436 + If there is a byWeekNo property and no byMonthDay or byDay 1437 properties: Add a byDay property with the sole value being 1438 the day-of-the-week of the initial date-time. 1440 4.3.3. excludedRecurrenceRules 1442 Type: "RecurrenceRule[]" (optional). 1444 Defines a set of recurrence rules (repeating patterns) for date-times 1445 on which the object will not occur. The rules are interpreted the 1446 same as for the "recurrenceRules" property (see Section 4.3.2), with 1447 the exception that the initial date-time to which the rule is applied 1448 (the "start" date-time for events; the "start" or "due" date-time for 1449 tasks) is only considered part of the expansion if it matches the 1450 rule. The resulting set of date-times are then removed from those 1451 generated by the recurrenceRules property, as described in 1452 Section 4.3. 1454 4.3.4. recurrenceOverrides 1456 Type: "LocalDateTime[PatchObject]" (optional). 1458 A map of the recurrence ids (the date-time produced by the recurrence 1459 rule) to an object of patches to apply to the generated occurrence 1460 object. 1462 If the recurrence id does not match a date-time from the recurrence 1463 rule (or no rule is specified), it is to be treated as an additional 1464 occurrence (like an RDATE from iCalendar). The patch object may 1465 often be empty in this case. 1467 If the patch object defines the "excluded" property value to be true, 1468 then the recurring calendar object does not occur at the recurrence 1469 id date-time (like an EXDATE from iCalendar). Such a patch object 1470 MUST NOT patch any other property. 1472 By default, an occurrence inherits all properties from the main 1473 object except the start (or due) date-time, which is shifted to match 1474 the recurrence id LocalDateTime. However, individual properties of 1475 the occurrence can be modified by a patch, or multiple patches. It 1476 is valid to patch the "start" property value, and this patch takes 1477 precedence over the value generated from the recurrence id. Both the 1478 recurrence id as well as the patched "start" date-time may occur 1479 before the original JSCalendar object's "start" or "due" date. 1481 A pointer in the PatchObject MUST be ignored if it starts with one of 1482 the following prefixes: 1484 o @type 1486 o method 1488 o privacy 1490 o prodId 1492 o recurrenceId 1494 o recurrenceOverrides 1496 o recurrenceRules 1498 o relatedTo 1500 o replyTo 1502 o uid 1504 4.3.5. excluded 1506 Type: "Boolean" (optional, default: false). 1508 Defines if this object is an overridden, excluded instance of a 1509 recurring JSCalendar object (see Section 4.3.4). If this property 1510 value is true, this calendar object instance MUST be removed from the 1511 occurrence expansion. The absence of this property or its default 1512 value false indicates that this instance MUST be included in the 1513 occurrence expansion. 1515 4.4. Sharing and Scheduling Properties 1517 4.4.1. priority 1519 Type: "Int" (optional, default: 0). 1521 Specifies a priority for the calendar object. This may be used as 1522 part of scheduling systems to help resolve conflicts for a time 1523 period. 1525 The priority is specified as an integer in the range 0 to 9. A value 1526 of 0 specifies an undefined priority, for which the treatment will 1527 vary by situation. A value of 1 is the highest priority. A value of 1528 2 is the second highest priority. Subsequent numbers specify a 1529 decreasing ordinal priority. A value of 9 is the lowest priority. 1530 Other integer values are reserved for future use. 1532 4.4.2. freeBusyStatus 1534 Type: "String" (optional, default: "busy"). 1536 Specifies how this calendar object should be treated when calculating 1537 free-busy state. This MUST be one of the following values, a value 1538 registered in the IANA JSCalendar Enum Registry, or a vendor-specific 1539 value: 1541 o "free": The object should be ignored when calculating whether the 1542 user is busy. 1544 o "busy": The object should be included when calculating whether the 1545 user is busy. 1547 4.4.3. privacy 1549 Type: "String" (optional, default: "public"). 1551 Calendar objects are normally collected together and may be shared 1552 with other users. The privacy property allows the object owner to 1553 indicate that it should not be shared, or should only have the time 1554 information shared but the details withheld. Enforcement of the 1555 restrictions indicated by this property are up to the API via which 1556 this object is accessed. 1558 This property MUST NOT affect the information sent to scheduled 1559 participants; it is only interpreted when the object is shared as 1560 part of a shared calendar. 1562 The value MUST be one of the following values, a value registered in 1563 the IANA JSCalendar Enum Registry, or a vendor-specific value. Any 1564 value the client or server doesn't understand should be preserved but 1565 treated as equivalent to "private". 1567 o "public": The full details of the object are visible to those whom 1568 the object's calendar is shared with. 1570 o "private": The details of the object are hidden; only the basic 1571 time and metadata is shared. The following properties MAY be 1572 shared, any other properties MUST NOT be shared: 1574 * @type 1576 * created 1578 * due 1579 * duration 1581 * estimatedDuration 1583 * freeBusyStatus 1585 * privacy 1587 * recurrenceOverrides. Only patches which apply to another 1588 permissible property are allowed to be shared. 1590 * sequence 1592 * showWithoutTime 1594 * start 1596 * timeZone 1598 * timeZones 1600 * uid 1602 * updated 1604 o "secret": The object is hidden completely (as though it did not 1605 exist) when the calendar this object is in is shared. 1607 4.4.4. replyTo 1609 Type: "String[String]" (optional). 1611 Represents methods by which participants may submit their RSVP 1612 response to the organizer of the calendar object. The keys in the 1613 property value are the available methods and MUST only contain ASCII 1614 alphanumeric characters (A-Za-z0-9). The value is a URI for the 1615 method specified in the key. Future methods may be defined in future 1616 specifications and registered with IANA; a calendar client MUST 1617 ignore any method it does not understand, but MUST preserve the 1618 method key and URI. This property MUST be omitted if no method is 1619 defined (rather than being specified as an empty object). 1621 The following methods are defined: 1623 o "imip": The organizer accepts an iMIP [RFC6047] response at this 1624 email address. The value MUST be a "mailto:" URI. 1626 o "web": Opening this URI in a web browser will provide the user 1627 with a page where they can submit a reply to the organizer. 1629 o "other": The organizer is identified by this URI but the method 1630 for submitting the response is undefined. 1632 4.4.5. participants 1634 Type: "Id[Participant]" (optional). 1636 A map of participant ids to participants, describing their 1637 participation in the calendar object. 1639 If this property is set and any participant has a sendTo property, 1640 then the "replyTo" property of this calendar object MUST define at 1641 least one reply method. 1643 A Participant object has the following properties: 1645 o @type: "String" (mandatory) 1647 Specifies the type of this object. This MUST be "Participant". 1649 o name: "String" (optional) 1651 The display name of the participant (e.g., "Joe Bloggs"). 1653 o email: "String" (optional) 1655 The email address for the participant. 1657 o description: "String" (optional). 1659 A plain text description of this participant. For example, this 1660 may include more information about their role in the event or how 1661 best to contact them. 1663 o sendTo: "String[String]" (optional) 1665 Represents methods by which the participant may receive the 1666 invitation and updates to the calendar object. 1668 The keys in the property value are the available methods and MUST 1669 only contain ASCII alphanumeric characters (A-Za-z0-9). The value 1670 is a URI for the method specified in the key. Future methods may 1671 be defined in future specifications and registered with IANA; a 1672 calendar client MUST ignore any method it does not understand, but 1673 MUST preserve the method key and URI. This property MUST be 1674 omitted if no method is defined (rather than being specified as an 1675 empty object). 1677 The following methods are defined: 1679 * "imip": The participant accepts an iMIP [RFC6047] request at 1680 this email address. The value MUST be a "mailto:" URI. It MAY 1681 be different from the value of the participant's "email" 1682 property. 1684 * "other": The participant is identified by this URI but the 1685 method for submitting the invitation is undefined. 1687 o kind: "String" (optional) 1689 What kind of entity this participant is, if known. 1691 This MUST be one of the following values, a value registered in 1692 the IANA JSCalendar Enum Registry, or a vendor-specific value. 1693 Any value the client or server doesn't understand should be 1694 treated the same as if this property is omitted. 1696 * "individual": a single person 1698 * "group": a collection of people invited as a whole 1700 * "location": a physical location that needs to be scheduled, 1701 e.g., a conference room 1703 * "resource": a non-human resource other than a location, such as 1704 a projector 1706 o roles: "String[Boolean]" (mandatory) 1708 A set of roles that this participant fulfills. 1710 At least one role MUST be specified for the participant. The keys 1711 in the set MUST be one of the following values, a value registered 1712 in the IANA JSCalendar Enum Registry, or a vendor-specific value: 1714 * "owner": The participant is an owner of the object. This 1715 signifies they have permission to make changes to it that 1716 affect the other participants. Non-owner participants may only 1717 change properties that just affect themself (for example 1718 setting their own alerts or changing their rsvp status). 1720 * "attendee": The participant is expected to be present at the 1721 event. 1723 * "optional": The participant's involvement with the event is 1724 optional. This is expected to be primarily combined with the 1725 "attendee" role. 1727 * "informational": The participant is copied for informational 1728 reasons, and is not expected to attend. 1730 * "chair": The participant is in charge of the event/task when it 1731 occurs. 1733 * "contact": The participant is someone that may be contacted for 1734 information about the event. 1736 The value for each key in the set MUST be true. It is expected 1737 that no more than one of the roles "attendee" and "informational" 1738 be present; if more than one are given, "attendee" takes 1739 precedence over "informational". Roles that are unknown to the 1740 implementation MUST be preserved. 1742 o locationId: "String" (optional) 1744 The location at which this participant is expected to be 1745 attending. 1747 If the value does not correspond to any location id in the 1748 "locations" property of the JSCalendar object, this MUST be 1749 treated the same as if the participant's locationId were omitted. 1751 o language: "String" (optional) 1753 The language tag as defined in [RFC5646] that best describes the 1754 participant's preferred language, if known. 1756 o participationStatus: "String" (optional, default: "needs-action") 1758 The participation status, if any, of this participant. 1760 The value MUST be one of the following values, a value registered 1761 in the IANA JSCalendar Enum Registry, or a vendor-specific value: 1763 * "needs-action": No status yet set by the participant. 1765 * "accepted": The invited participant will participate. 1767 * "declined": The invited participant will not participate. 1769 * "tentative": The invited participant may participate. 1771 * "delegated": The invited participant has delegated their 1772 attendance to another participant, as specified in the 1773 delegatedTo property. 1775 o participationComment: "String" (optional) 1777 A note from the participant to explain their participation status. 1779 o expectReply: "Boolean" (optional, default: false) 1781 If true, the organizer is expecting the participant to notify them 1782 of their participation status. 1784 o scheduleAgent: "String" (optional, default: "server") 1786 Who is responsible for sending scheduling messages with this 1787 calendar object to the participant. 1789 The value MUST be one of the following values, a value registered 1790 in the IANA JSCalendar Enum Registry, or a vendor-specific value: 1792 * "server": The calendar server will send the scheduling 1793 messages. 1795 * "client": The calendar client will send the scheduling 1796 messages. 1798 * "none": No scheduling messages are to be sent to this 1799 participant. 1801 o scheduleForceSend: "Boolean" (optional, default: false) 1803 A client may set the property on a participant to true to request 1804 that the server send a scheduling message to the participant when 1805 it would not normally do so (e.g. if no significant change is made 1806 the object or the scheduleAgent is set to client). The property 1807 MUST NOT be stored in the JSCalendar object on the server or 1808 appear in a scheduling message. 1810 o scheduleSequence: "UnsignedInt" (optional, default: 0) 1812 The sequence number of the last response from the participant. If 1813 defined, this MUST be a non-negative integer. 1815 This can be used to determine whether the participant has sent a 1816 new RSVP following significant changes to the calendar object, and 1817 to determine if future responses are responding to a current or 1818 older view of the data. 1820 o scheduleStatus: "String[]" (optional) 1822 A list of status codes, as defined in Section 3.8.8.3 of 1823 [RFC5545], returned from the processing of the most recent 1824 scheduling message sent to this participant. 1826 Servers MUST only add or change this property when they send a 1827 scheduling message to the participant. Clients SHOULD NOT change 1828 or remove this property if it was provided by the server. Clients 1829 MAY add, change, or remove the property for participants where the 1830 client is handling the scheduling. 1832 This property MUST NOT be included in scheduling messages. 1834 o scheduleUpdated: "UTCDateTime" (optional) 1836 The timestamp for the most recent response from this participant. 1838 This is the "updated" property of the last response when using 1839 iTIP. It can be compared to the "updated" property in future 1840 responses to detect and discard older responses delivered out of 1841 order. 1843 o invitedBy: "String" (optional) 1845 The participant id of the participant who invited this one, if 1846 known. 1848 o delegatedTo: "String[Boolean]" (optional) 1850 A set of participant ids that this participant has delegated their 1851 participation to. Each key in the set MUST be the id of a 1852 participant. The value for each key in the set MUST be true. If 1853 there are no delegates, this MUST be omitted (rather than 1854 specified as an empty set). 1856 o delegatedFrom: "String[Boolean]" (optional) 1858 A set of participant ids that this participant is acting as a 1859 delegate for. Each key in the set MUST be the id of a 1860 participant. The value for each key in the set MUST be true. If 1861 there are no delegators, this MUST be omitted (rather than 1862 specified as an empty set). 1864 o memberOf: "String[Boolean]" (optional) 1866 A set of group participants that were invited to this calendar 1867 object, which caused this participant to be invited due to their 1868 membership in the group(s). Each key in the set MUST be the id of 1869 a participant. The value for each key in the set MUST be true. 1870 If there are no groups, this MUST be omitted (rather than 1871 specified as an empty set). 1873 o linkIds: "String[Boolean]" (optional) 1875 A set of links to more information about this participant, for 1876 example in vCard format. The keys in the set MUST be the id of a 1877 Link object in the calendar object's "links" property. The value 1878 for each key in the set MUST be true. If there are no links, this 1879 MUST be omitted (rather than specified as an empty set). 1881 o progress: "String" (optional; only allowed for participants of a 1882 JSTask). Represents the progress of the participant for this 1883 task. It MUST NOT be set if the "participationStatus" of this 1884 participant is any value other than "accepted". See Section 5.2.5 1885 for allowed values and semantics. 1887 o progressUpdated: "UTCDateTime" (optional; only allowed for 1888 participants of a JSTask). Specifies the date-time the progress 1889 property was last set on this participant. See Section 5.2.6 for 1890 allowed values and semantics. 1892 o percentComplete: "UnsignedInt" (optional; only allowed for 1893 participants of a JSTask). Represents the percent completion of 1894 the participant for this task. The property value MUST be a 1895 positive integer between 0 and 100. 1897 4.5. Alerts Properties 1899 4.5.1. useDefaultAlerts 1901 Type: "Boolean" (optional, default: false). 1903 If true, use the user's default alerts and ignore the value of the 1904 "alerts" property. Fetching user defaults is dependent on the API 1905 from which this JSCalendar object is being fetched, and is not 1906 defined in this specification. If an implementation cannot determine 1907 the user's default alerts, or none are set, it MUST process the 1908 alerts property as if "useDefaultAlerts" is set to false. 1910 4.5.2. alerts 1912 Type: "Id[Alert]" (optional). 1914 A map of alert ids to Alert objects, representing alerts/reminders to 1915 display or send to the user for this calendar object. 1917 An Alert Object has the following properties: 1919 o @type: "String" (mandatory) 1921 Specifies the type of this object. This MUST be "Alert". 1923 o trigger: "OffsetTrigger|AbsoluteTrigger|UnknownTrigger" 1924 (mandatory) 1926 Defines when to trigger the alert. New types may be defined in 1927 future documents. 1929 An "OffsetTrigger" object has the following properties: 1931 * @type: "String" (mandatory) 1933 Specifies the type of this object. This MUST be 1934 "OffsetTrigger". 1936 * offset: "SignedDuration" (mandatory). 1938 Defines the offset at which to trigger the alert relative to 1939 the time property defined in the "relativeTo" property of the 1940 alert. Negative durations signify alerts before the time 1941 property, positive durations signify alerts after. 1943 * relativeTo: "String" (optional, default: "start") 1945 Specifies the time property that the alert offset is relative 1946 to. The value MUST be one of: 1948 + "start": triggers the alert relative to the start of the 1949 calendar object 1951 + "end": triggers the alert relative to the end/due time of 1952 the calendar object 1954 An "AbsoluteTrigger" object has the following properties: 1956 * @type: "String" (mandatory) 1958 Specifies the type of this object. This MUST be 1959 "AbsoluteTrigger". 1961 * when: "UTCDateTime" (mandatory). 1963 Defines a specific UTC date-time when the alert is triggered. 1965 An "UnknownTrigger" object is an object that contains a "@type" 1966 property whose value is not recognized (i.e., not "OffsetTrigger" 1967 or "AbsoluteTrigger"), plus zero or more other properties. This 1968 is for compatibility with client extensions and future 1969 specifications. Implementations SHOULD NOT trigger for trigger 1970 types they do not understand, but MUST preserve them. 1972 o acknowledged: "UTCDateTime" (optional) 1974 This records when an alert was last acknowledged. This is set 1975 when the user has dismissed the alert; other clients that sync 1976 this property SHOULD automatically dismiss or suppress duplicate 1977 alerts (alerts with the same alert id that triggered on or before 1978 this date-time). 1980 For a recurring calendar object, the "acknowledged" property of 1981 the parent object MUST be updated, unless the alert is already 1982 overridden in the "recurrenceOverrides" property. 1984 Certain kinds of alert action may not provide feedback as to when 1985 the user sees them, for example email based alerts. For those 1986 kinds of alerts, this property SHOULD be set immediately when the 1987 alert is triggered and the action successfully carried out. 1989 o relatedTo: "String[Relation]" (optional) 1991 Relates this alert to other alerts in the same JSCalendar object. 1992 If the user wishes to snooze an alert, the application SHOULD 1993 create an alert to trigger after snoozing. All snooze alerts 1994 SHOULD set a relation to the identifier of the original alert. 1995 The Relation object SHOULD set the "parent" relation type. 1997 o action: "String" (optional, default: "display") 1999 Describes how to alert the user. 2001 The value MUST be at most one of the following values, a value 2002 registered in the IANA JSCalendar Enum Registry, or a vendor- 2003 specific value: 2005 * "display": The alert should be displayed as appropriate for the 2006 current device and user context. 2008 * "email": The alert should trigger an email sent out to the 2009 user, notifying about the alert. This action is typically only 2010 appropriate for server implementations. 2012 4.6. Multilingual Properties 2014 4.6.1. localizations 2016 Type: "String[PatchObject]" (optional). 2018 A map of language tags [RFC5646] to patch objects, which localize the 2019 calendar object into the locale of the respective language tag. 2021 See the description of PatchObject (Section 1.4.8) for the structure 2022 of the PatchObject. The patches are applied to the top-level 2023 calendar object. In addition, the "locale" property of the patched 2024 object is set to the language tag. All pointers for patches MUST end 2025 with one of the following suffixes; any patch that does not follow 2026 this MUST be ignored unless otherwise specified in a future RFC: 2028 o title 2030 o description 2032 o name 2034 A patch MUST NOT have the prefix "recurrenceOverrides"; any 2035 localization of the override MUST be a patch to the localizations 2036 property inside the override instead. For example, a patch to 2037 "locations/abcd1234/title" is permissible, but a patch to "uid" or 2038 "recurrenceOverrides/2018-01-05T14:00:00/title" is not. 2040 Note that this specification does not define how to maintain validity 2041 of localized content. For example, a client application changing a 2042 JSCalendar object's title property might also need to update any 2043 localizations of this property. Client implementations SHOULD 2044 provide the means to manage localizations, but how to achieve this is 2045 specific to the application's workflow and requirements. 2047 4.7. Time Zone Properties 2049 4.7.1. timeZone 2051 Type: "String|null" (optional, default: null). 2053 Identifies the time zone the object is scheduled in, or null for 2054 floating time. This is either a name from the IANA Time Zone 2055 Database [TZDB] or the id of a custom time zone from the "timeZones" 2056 property (see Section 1.4.9). If omitted, this MUST be presumed to 2057 be null (i.e., floating time). 2059 4.7.2. timeZones 2061 Type: "String[TimeZone]" (optional). 2063 Maps identifiers of custom time zones to their time zone definitions. 2064 The following restrictions apply for each key in the map: 2066 o It MUST start with the "/" character (ASCII decimal 47; also see 2067 Sections 3.2.19 of [RFC5545] and 3.6. of [RFC7808] for discussion 2068 of the forward slash character in time zone identifiers). 2070 o It MUST be a valid "paramtext" value as specified in Section 3.1. 2071 of [RFC5545]. 2073 o At least one other property in the same JSCalendar object MUST 2074 reference a time zone using this identifier (i.e., orphaned time 2075 zones are not allowed). 2077 An identifier need only be unique to this JSCalendar object. A 2078 JSCalendar object may be part in a hierarchy of other JSCalendar 2079 objects (say, a JSEvent is an entry in a JSGroup). In this case, the 2080 set of time zones is the sum of the time zone definitions of this 2081 object and its parent objects. If multiple time zones with the same 2082 identifier exist, then the definition closest to the calendar object 2083 in relation to its parents MUST be used. (In context of JSEvent, a 2084 time zone definition in its timeZones property has precedence over a 2085 definition of the same id in the JSGroup). Time zone definitions in 2086 any children of the calendar object MUST be ignored. 2088 A TimeZone object maps a VTIMEZONE component from iCalendar [RFC5545] 2089 and the semantics are as defined there. A valid time zone MUST 2090 define at least one transition rule in the "standard" or "daylight" 2091 property. Its properties are: 2093 o @type: "String" (mandatory) 2095 Specifies the type of this object. This MUST be "TimeZone". 2097 o tzId: "String" (mandatory). 2099 The TZID property from iCalendar. 2101 o updated: "UTCDateTime" (optional) 2103 The LAST-MODIFIED property from iCalendar. 2105 o url: "String" (optional) 2106 The TZURL property from iCalendar. 2108 o validUntil: "UTCDateTime" (optional) 2110 The TZUNTIL property from iCalendar specified in [RFC7808]. 2112 o aliases: "String[Boolean]" (optional) 2114 Maps the TZID-ALIAS-OF properties from iCalendar specified in 2115 [RFC7808] to a JSON set of aliases. The set is represented as an 2116 object, with the keys being the aliases. The value for each key 2117 in the set MUST be true. 2119 o standard: "TimeZoneRule[]" (optional) 2121 The STANDARD sub-components from iCalendar. The order MUST be 2122 preserved during conversion. 2124 o daylight: "TimeZoneRule[]" (optional). 2126 The DAYLIGHT sub-components from iCalendar. The order MUST be 2127 preserved during conversion. 2129 A TimeZoneRule object maps a STANDARD or DAYLIGHT sub-component from 2130 iCalendar, with the restriction that at most one recurrence rule is 2131 allowed per rule. It has the following properties: 2133 o @type: "String" (mandatory) 2135 Specifies the type of this object. This MUST be "TimeZoneRule". 2137 o start: "LocalDateTime" (mandatory) 2139 The DTSTART property from iCalendar. 2141 o offsetTo: "String" (mandatory) 2143 The TZOFFSETTO property from iCalendar. 2145 o offsetFrom: "String" (mandatory) 2147 The TZOFFSETFROM property from iCalendar. 2149 o recurrenceRules: "RecurrenceRule[]" (optional) 2151 The RRULE property mapped as specified in Section 4.3.2. During 2152 recurrence rule evaluation, the "until" property value MUST be 2153 interpreted as a local time in the UTC time zone. 2155 o recurrenceOverrides: "LocalDateTime[PatchObject]" (optional) 2157 Maps the RDATE properties from iCalendar. The set is represented 2158 as an object, with the keys being the recurrence dates. The patch 2159 object MUST be empty. 2161 o names: "String[Boolean]" (optional) 2163 Maps the TZNAME properties from iCalendar to a JSON set. The set 2164 is represented as an object, with the keys being the names. The 2165 value for each key in the set MUST be true. 2167 o comments: "String[]" (optional). Maps the COMMENT properties from 2168 iCalendar. The order MUST be preserved during conversion. 2170 5. Type-specific JSCalendar Properties 2172 5.1. JSEvent Properties 2174 In addition to the common JSCalendar object properties (Section 4) a 2175 JSEvent has the following properties: 2177 5.1.1. start 2179 Type: "LocalDateTime" (mandatory). 2181 The date/time the event starts in the event's time zone (as specified 2182 in the "timeZone" property, see Section 4.7.1). 2184 5.1.2. duration 2186 Type: "Duration" (optional, default: "PT0S"). 2188 The zero or positive duration of the event in the event's start time 2189 zone. 2191 A JSEvent MAY involve start and end locations that are in different 2192 time zones (e.g., a trans-continental flight). This can be expressed 2193 using the "relativeTo" and "timeZone" properties of the JSEvent's 2194 Location objects (see Section 4.2.5). 2196 5.1.3. status 2198 Type: "String" (optional, default: "confirmed"). 2200 The scheduling status (Section 4.4) of a JSEvent. If set, it MUST be 2201 one of the following values, a value registered in the IANA 2202 JSCalendar Enum Registry, or a vendor-specific value: 2204 o "confirmed": Indicates the event is definitely happening. 2206 o "cancelled": Indicates the event has been cancelled. 2208 o "tentative": Indicates the event may happen. 2210 5.2. JSTask Properties 2212 In addition to the common JSCalendar object properties (Section 4) a 2213 JSTask has the following properties: 2215 5.2.1. due 2217 Type: "LocalDateTime" (optional). 2219 The date/time the task is due in the task's time zone. 2221 5.2.2. start 2223 Type: "LocalDateTime" (optional). 2225 The date/time the task should start in the task's time zone. 2227 5.2.3. estimatedDuration 2229 Type: "Duration" (optional). 2231 Specifies the estimated positive duration of time the task takes to 2232 complete. 2234 5.2.4. percentComplete 2236 Type: "UnsignedInt" (optional). 2238 Represents the percent completion of the task overall. The property 2239 value MUST be a positive integer between 0 and 100. 2241 5.2.5. progress 2243 Type: "String" (optional). 2245 Defines the progress of this task. If omitted, the default progress 2246 (Section 4.4) of a JSTask is defined as follows (in order of 2247 evaluation): 2249 o "completed": if the "progress" property value of all participants 2250 is "completed". 2252 o "failed": if at least one "progress" property value of a 2253 participant is "failed". 2255 o "in-process": if at least one "progress" property value of a 2256 participant is "in-process". 2258 o "needs-action": If none of the other criteria match. 2260 If set, it MUST be one of the following values, a value registered in 2261 the IANA JSCalendar Enum Registry, or a vendor-specific value: 2263 o "needs-action": Indicates the task needs action. 2265 o "in-process": Indicates the task is in process. 2267 o "completed": Indicates the task is completed. 2269 o "failed": Indicates the task failed. 2271 o "cancelled": Indicates the task was cancelled. 2273 5.2.6. progressUpdated 2275 Type: "UTCDateTime" (optional). 2277 Specifies the date/time the "progress" property of either the task 2278 overall (Section 5.2.5) or a specific participant (Section 4.4.5) was 2279 last updated. 2281 If the task is recurring and has future instances, a client may want 2282 to keep track of the last progress update timestamp of a specific 2283 task recurrence, but leave other instances unchanged. One way to 2284 achieve this is by overriding the progressUpdated property in the 2285 task "recurrenceOverrides" property. However, this could produce a 2286 long list of timestamps for regularly recurring tasks. An 2287 alternative approach is to split the JSTask into a current, single 2288 instance of JSTask with this instance progress update time and a 2289 future recurring instance. See also Section 4.1.3 on splitting. 2291 5.3. JSGroup Properties 2293 JSGroup supports the following common JSCalendar properties 2294 (Section 4): 2296 o @type 2298 o categories 2299 o color 2301 o created 2303 o description 2305 o descriptionContentType 2307 o keywords 2309 o links 2311 o locale 2313 o prodId 2315 o timeZones 2317 o title 2319 o updated 2321 o uid 2323 In addition, the following JSGroup-specific properties are supported: 2325 5.3.1. entries 2327 Type: "(JSTask|JSEvent)[]" (mandatory). 2329 A collection of group members. Implementations MUST ignore entries 2330 of unknown type. 2332 5.3.2. source 2334 Type: "String" (optional). 2336 The source from which updated versions of this group may be retrieved 2337 from. The value MUST be a URI. 2339 6. Examples 2341 The following examples illustrate several aspects of the JSCalendar 2342 data model and format. The examples may omit mandatory or additional 2343 properties, which is indicated by a placeholder property with key 2344 "...". While most of the examples use calendar event objects, they 2345 are also illustrative for tasks. 2347 6.1. Simple event 2349 This example illustrates a simple one-time event. It specifies a 2350 one-time event that begins on January 15, 2018 at 1pm New York local 2351 time and ends after 1 hour. 2353 { 2354 "@type": "jsevent", 2355 "uid": "2a358cee-6489-4f14-a57f-c104db4dc2f1", 2356 "updated": "2018-01-15T18:00:00Z", 2357 "title": "Some event", 2358 "start": "2018-01-15T13:00:00", 2359 "timeZone": "America/New_York", 2360 "duration": "PT1H" 2361 } 2363 6.2. Simple task 2365 This example illustrates a simple task for a plain to-do item. 2367 { 2368 "@type": "jstask", 2369 "uid": "2a358cee-6489-4f14-a57f-c104db4dc2f2", 2370 "updated": "2018-01-15T18:00:00Z", 2371 "title": "Do something" 2372 } 2374 6.3. Simple group 2376 This example illustrates a simple calendar object group that contains 2377 an event and a task. 2379 { 2380 "@type": "jsgroup", 2381 "uid": "2a358cee-6489-4f14-a57f-c104db4dc343", 2382 "updated": "2018-01-15T18:00:00Z", 2383 "name": "A simple group", 2384 "entries": [{ 2385 "@type": "jsevent", 2386 "uid": "2a358cee-6489-4f14-a57f-c104db4dc2f1", 2387 "updated": "2018-01-15T18:00:00Z", 2388 "title": "Some event", 2389 "start": "2018-01-15T13:00:00", 2390 "timeZone": "America/New_York", 2391 "duration": "PT1H" 2392 }, 2393 "2a358cee-6489-4f14-a57f-c104db4dc2f2": { 2394 "@type": "jstask", 2395 "uid": "2a358cee-6489-4f14-a57f-c104db4dc2f2", 2396 "updated": "2018-01-15T18:00:00Z", 2397 "title": "Do something" 2398 }] 2399 } 2401 6.4. All-day event 2403 This example illustrates an event for an international holiday. It 2404 specifies an all-day event on April 1 that occurs every year since 2405 the year 1900. 2407 { 2408 "...": "", 2409 "title": "April Fool's Day", 2410 "showWithoutTime": true, 2411 "start": "1900-04-01T00:00:00", 2412 "duration": "P1D", 2413 "recurrenceRules": [{ 2414 "@type": "RecurrenceRule", 2415 "frequency": "yearly" 2416 }] 2417 } 2419 6.5. Task with a due date 2421 This example illustrates a task with a due date. It is a reminder to 2422 buy groceries before 6pm Vienna local time on January 19, 2018. The 2423 calendar user expects to need 1 hour for shopping. 2425 { 2426 "...": "", 2427 "title": "Buy groceries", 2428 "due": "2018-01-19T18:00:00", 2429 "timeZone": "Europe/Vienna", 2430 "estimatedDuration": "PT1H" 2431 } 2433 6.6. Event with end time zone 2435 This example illustrates the use of end time zones by use of an 2436 international flight. The flight starts on April 1, 2018 at 9am in 2437 Berlin local time. The duration of the flight is scheduled at 10 2438 hours 30 minutes. The time at the flight's destination is in the 2439 same time zone as Tokyo. Calendar clients could use the end time 2440 zone to display the arrival time in Tokyo local time and highlight 2441 the time zone difference of the flight. The location names can serve 2442 as input for navigation systems. 2444 { 2445 "...": "", 2446 "title": "Flight XY51 to Tokyo", 2447 "start": "2018-04-01T09:00:00", 2448 "timeZone": "Europe/Berlin", 2449 "duration": "PT10H30M", 2450 "locations": { 2451 "2a358cee-6489-4f14-a57f-c104db4dc2f1": { 2452 "@type": "Location", 2453 "rel": "start", 2454 "name": "Frankfurt Airport (FRA)" 2455 }, 2456 "c2c7ac67-dc13-411e-a7d4-0780fb61fb08": { 2457 "@type": "Location", 2458 "rel": "end", 2459 "name": "Narita International Airport (NRT)", 2460 "timeZone": "Asia/Tokyo" 2461 } 2462 } 2463 } 2465 6.7. Floating-time event (with recurrence) 2467 This example illustrates the use of floating time. Since January 1, 2468 2018, a calendar user blocks 30 minutes every day to practice Yoga at 2469 7am local time, in whatever time zone the user is located on that 2470 date. 2472 { 2473 "...": "", 2474 "title": "Yoga", 2475 "start": "2018-01-01T07:00:00", 2476 "duration": "PT30M", 2477 "recurrenceRules": [{ 2478 "@type": "RecurrenceRule", 2479 "frequency": "daily" 2480 }] 2481 } 2483 6.8. Event with multiple locations and localization 2485 This example illustrates an event that happens at both a physical and 2486 a virtual location. Fans can see a live concert on premises or 2487 online. The event title and descriptions are localized. 2489 { 2490 "...": "", 2491 "title": "Live from Music Bowl: The Band", 2492 "description": "Go see the biggest music event ever!", 2493 "locale": "en", 2494 "start": "2018-07-04T17:00:00", 2495 "timeZone": "America/New_York", 2496 "duration": "PT3H", 2497 "locations": { 2498 "c0503d30-8c50-4372-87b5-7657e8e0fedd": { 2499 "@type": "Location", 2500 "name": "The Music Bowl", 2501 "description": "Music Bowl, Central Park, New York", 2502 "coordinates": "geo:40.7829,-73.9654" 2503 } 2504 }, 2505 "virtualLocations": { 2506 "6f3696c6-1e07-47d0-9ce1-f50014b0041a": { 2507 "@type": "VirtualLocation", 2508 "name": "Free live Stream from Music Bowl", 2509 "uri": "https://stream.example.com/the_band_2018" 2510 } 2511 }, 2512 "localizations": { 2513 "de": { 2514 "title": "Live von der Music Bowl: The Band!", 2515 "description": "Schau dir das groesste Musikereignis an!", 2516 "virtualLocations/6f3696c6-1e07-47d0-9ce1-f50014b0041a/name": 2517 "Gratis Live-Stream aus der Music Bowl" 2518 } 2519 } 2520 } 2522 6.9. Recurring event with overrides 2524 This example illustrates the use of recurrence overrides. A math 2525 course at a University is held for the first time on January 8, 2018 2526 at 9am London time and occurs every week until June 25, 2018. Each 2527 lecture lasts for one hour and 30 minutes and is located at the 2528 Mathematics department. This event has exceptional occurrences: at 2529 the last occurrence of the course is an exam, which lasts for 2 hours 2530 and starts at 10am. Also, the location of the exam differs from the 2531 usual location. On April 2 no course is held. On January 5 at 2pm 2532 is an optional introduction course, that occurs before the first 2533 regular lecture. 2535 { 2536 "...": "", 2537 "title": "Calculus I", 2538 "start": "2018-01-08T09:00:00", 2539 "timeZone": "Europe/London", 2540 "duration": "PT1H30M", 2541 "locations": { 2542 "2a358cee-6489-4f14-a57f-c104db4dc2f1": { 2543 "@type": "Location", 2544 "title": "Math lab room 1", 2545 "description": "Math Lab I, Department of Mathematics" 2546 } 2547 }, 2548 "recurrenceRules": [{ 2549 "@type": "RecurrenceRule", 2550 "frequency": "weekly", 2551 "until": "2018-06-25T09:00:00" 2552 }], 2553 "recurrenceOverrides": { 2554 "2018-01-05T14:00:00": { 2555 "title": "Introduction to Calculus I (optional)" 2556 }, 2557 "2018-04-02T09:00:00": { 2558 "excluded": "true" 2559 }, 2560 "2018-06-25T09:00:00": { 2561 "title": "Calculus I Exam", 2562 "start": "2018-06-25T10:00:00", 2563 "duration": "PT2H", 2564 "locations": { 2565 "2a358cee-6489-4f14-a57f-c104db4dc2f1": { 2566 "@type": "Location", 2567 "title": "Big Auditorium", 2568 "description": "Big Auditorium, Other Road" 2569 } 2570 } 2571 } 2572 } 2573 } 2575 6.10. Recurring event with participants 2577 This example illustrates scheduled events. A team meeting occurs 2578 every week since January 8, 2018 at 9am Johannesburg time. The event 2579 owner also chairs the event. Participants meet in a virtual meeting 2580 room. An attendee has accepted the invitation, but on March 8, 2018 2581 he is unavailable and declined participation for this occurrence. 2583 { 2584 "...": "", 2585 "title": "FooBar team meeting", 2586 "start": "2018-01-08T09:00:00", 2587 "timeZone": "Africa/Johannesburg", 2588 "duration": "PT1H", 2589 "virtualLocations": { 2590 "2a358cee-6489-4f14-a57f-c104db4dc2f1": { 2591 "@type": "VirtualLocation", 2592 "name": "ChatMe meeting room", 2593 "uri": "https://chatme.example.com?id=1234567" 2594 } 2595 }, 2596 "recurrenceRules": [{ 2597 "@type": "RecurrenceRule", 2598 "frequency": "weekly" 2599 }], 2600 "replyTo": { 2601 "imip": "mailto:6489-4f14-a57f-c1@schedule.example.com" 2602 }, 2603 "participants": { 2604 "dG9tQGZvb2Jhci5xlLmNvbQ": { 2605 "@type": "Participant", 2606 "name": "Tom Tool", 2607 "email": "tom@foobar.example.com", 2608 "sendTo": { 2609 "imip": "mailto:6489-4f14-a57f-c1@calendar.example.com" 2610 }, 2611 "participationStatus": "accepted", 2612 "roles": { 2613 "attendee": true 2614 } 2615 }, 2616 "em9lQGZvb2GFtcGxlLmNvbQ": { 2617 "@type": "Participant", 2618 "name": "Zoe Zelda", 2619 "email": "zoe@foobar.example.com", 2620 "sendTo": { 2621 "imip": "mailto:zoe@foobar.example.com" 2622 }, 2623 "participationStatus": "accepted", 2624 "roles": { 2625 "owner": true, 2626 "attendee": true, 2627 "chair": true 2628 } 2629 }, 2630 "...": "" 2632 }, 2633 "recurrenceOverrides": { 2634 "2018-03-08T09:00:00": { 2635 "participants/dG9tQGZvb2Jhci5xlLmNvbQ/participationStatus": 2636 "declined" 2637 } 2638 } 2639 } 2641 7. Security Considerations 2643 Calendaring and scheduling information is very privacy-sensitive. 2644 Its transmission must be done carefully to protect it from possible 2645 threats, such as eavesdropping, replay, message insertion, deletion, 2646 modification, and man-in-the-middle attacks. 2648 The data being stored and transmitted may be used in systems with 2649 real world consequences. For example, a home automation system may 2650 turn an alarm on and off. Or a coworking space may charge money to 2651 the organiser of an event that books one of their meeting rooms. 2652 Such systems must be careful to authenticate all data they receive to 2653 prevent them from being subverted. 2655 This document just defines the data format; such considerations are 2656 primarily the concern of the API or method of storage and 2657 transmission of such files. 2659 7.1. Expanding Recurrences 2661 A recurrence rule may produce infinite occurrences of an event. 2662 Implementations MUST handle expansions carefully to prevent 2663 accidental or deliberate resource exhaustion. 2665 Conversely, a recurrence rule may be specified that does not expand 2666 to anything. It is not always possible to tell this through static 2667 analysis of the rule, so implementations MUST be careful to avoid 2668 getting stuck in infinite loops, or otherwise exhausting resources 2669 while searching for the next occurrence. 2671 7.2. JSON Parsing 2673 The Security Considerations of [RFC8259] apply to the use of JSON as 2674 the data interchange format. 2676 As for any serialization format, parsers need to thoroughly check the 2677 syntax of the supplied data. JSON uses opening and closing tags for 2678 several types and structures, and it is possible that the end of the 2679 supplied data will be reached when scanning for a matching closing 2680 tag; this is an error condition, and implementations need to stop 2681 scanning at the end of the supplied data. 2683 JSON also uses a string encoding with some escape sequences to encode 2684 special characters within a string. Care is needed when processing 2685 these escape sequences to ensure that they are fully formed before 2686 the special processing is triggered, with special care taken when the 2687 escape sequences appear adjacent to other (non-escaped) special 2688 characters or adjacent to the end of data (as in the previous 2689 paragraph). 2691 If parsing JSON into a non-textual structured data format, 2692 implementations may need to allocate storage to hold JSON string 2693 elements. Since JSON does not use explicit string lengths, the risk 2694 of denial of service due to resource exhaustion is small, but 2695 implementations may still wish to place limits on the size of 2696 allocations they are willing to make in any given context, to avoid 2697 untrusted data causing excessive memory allocation. 2699 7.3. URI Values 2701 Several JSCalendar properties contain URIs as values, and processing 2702 these properties requires extra care. Section 7 of [RFC3986] 2703 discusses security risks related to URIs. 2705 A maliciously constructed JSCalendar object may contain a very large 2706 number of URIs. In the case of published calendars with a large 2707 number of subscribers, such objects could be widely distributed. 2708 Implementations should be careful to limit the automatic fetching of 2709 linked resources to reduce the risk of this being an amplification 2710 vector for a denial-of-service attack. 2712 7.4. Spam 2714 Calendar systems may receive JSCalendar files from untrusted sources, 2715 in particular as attachments to emails. This can be a vector for an 2716 attacker to inject spam into a user's calendar. This may confuse, 2717 annoy, and mislead users, or overwhelm their calendar with bogus 2718 events, preventing them from seeing legitimate ones. 2720 Heuristic, statistical or machine-learning-based filters can be 2721 effective in filtering out spam. Authentication mechanisms such as 2722 DKIM [RFC6376] can help establish the source of messages and 2723 associate the data with existing relationships (such as an address 2724 book contact). Misclassifications are always possible however, and 2725 providing a feedback mechanism for users to quickly correct this is 2726 advised. 2728 7.5. Duplication 2730 It is important for calendar systems to maintain the UID of an event 2731 when updating it to avoid unexpected duplication of events. When the 2732 UID changes, consumers of the data may not remove the previous 2733 version of the event if it has a different UID. This can lead to a 2734 confusing situation for the user, with many variations of the event 2735 and no indication of which one is correct. Care must be taken by 2736 consumers of the data to remove old events where possible to avoid an 2737 accidental denial-of-service attack due to the volume of data. 2739 7.6. Time Zones 2741 Events recur in a particular time zone. When this differs from the 2742 user's current time zone, it may unexpectedly cause an occurrence to 2743 shift in time for that user due to a daylight savings change in the 2744 event's time zone. A maliciously crafted event could attempt to 2745 confuse users with such an event to ensure a meeting is missed. 2747 8. IANA Considerations 2749 8.1. Media Type Registration 2751 This document defines a media type for use with JSCalendar data 2752 formatted in JSON. 2754 Type name: application 2756 Subtype name: jscalendar+json 2758 Required parameters: type 2760 The "type" parameter conveys the type of the JSCalendar data in 2761 the body part, with the value being one of "jsevent", "jstask", or 2762 "jsgroup". The parameter MUST NOT occur more than once. It MUST 2763 match the value of the "@type" property of the JSON-formatted 2764 JSCalendar object in the body. 2766 Optional parameters: none 2768 Encoding considerations: Same as encoding considerations of 2769 application/json as specified in RFC8529, Section 11 [RFC8259]. 2771 Security considerations: See Section 7 of this document. 2773 Interoperability considerations: This media type provides an 2774 alternative to iCalendar, jCal and proprietary JSON-based 2775 calendaring data formats. 2777 Published specification: This specification. 2779 Applications that use this media type: Applications that currently 2780 make use of the text/calendar and application/calendar+json media 2781 types can use this as an alternative. Similarly, applications 2782 that use the application/json media type to transfer calendaring 2783 data can use this to further specify the content. 2785 Fragment identifier considerations: N/A 2787 Additional information: 2789 Magic number(s): N/A 2791 File extensions(s): N/A 2793 Macintosh file type code(s): N/A 2795 Person & email address to contact for further information: 2796 calsify@ietf.org 2798 Intended usage: COMMON 2800 Restrictions on usage: N/A 2802 Author: See the "Author's Address" section of this document. 2804 Change controller: IETF 2806 8.2. Creation of "JSCalendar Properties" Registry 2808 The IANA will create the "JSCalendar Properties" registry to allow 2809 interoperability of extensions to JSCalendar objects. 2811 This registry follows the Expert Review process ([RFC8126], 2812 Section 4.5). If the "intended use" field is "common", sufficient 2813 documentation is required to enable interoperability. Preliminary 2814 community review for this registry is optional but strongly 2815 encouraged. 2817 A registration can have an intended use of "common", "reserved", or 2818 "obsolete". The IANA will list common-use registrations prominently 2819 and separately from those with other intended use values. 2821 A "reserved" registration reserves a property name without assigning 2822 semantics to avoid name collisions with future extensions or protocol 2823 use. 2825 An "obsolete" registration denotes a property that is no longer 2826 expected to be added by up-to-date systems. A new property has 2827 probably been defined covering the obsolete property's semantics. 2829 The JSCalendar property registration procedure is not a formal 2830 standards process but rather an administrative procedure intended to 2831 allow community comment and sanity checking without excessive time 2832 delay. It is designed to encourage vendors to document and register 2833 new properties they add for use cases not covered by the original 2834 standard, leading to increased interoperability. 2836 8.2.1. Preliminary Community Review 2838 Notice of a potential new registration SHOULD be sent to the Calext 2839 mailing list for review. This mailing list is 2840 appropriate to solicit community feedback on a proposed new property. 2842 Properties registrations must be marked with their intended use: 2843 "common", "reserved" or "obsolete". 2845 The intent of the public posting to this list is to solicit comments 2846 and feedback on the choice of the property name, the unambiguity of 2847 the specification document, and a review of any interoperability or 2848 security considerations. The submitter may submit a revised 2849 registration proposal or abandon the registration completely at any 2850 time. 2852 8.2.2. Submit Request to IANA 2854 Registration requests can be sent to . 2856 8.2.3. Designated Expert Review 2858 The primary concern of the designated expert (DE) is preventing name 2859 collisions and encouraging the submitter to document security and 2860 privacy considerations. For a common-use registration, the DE is 2861 expected to confirm that suitable documentation, as described in 2862 Section 4.6 of [RFC8126], is available to ensure interoperability. 2863 That documentation will usually be in an RFC, but simple definitions 2864 are likely to use a web/wiki page, and if a sentence or two is deemed 2865 sufficient it could be described in the registry itself. The DE 2866 should also verify that the property name does not conflict with work 2867 that is active or already published within the IETF. A published 2868 specification is not required for reserved or obsolete registrations. 2870 The DE will either approve or deny the registration request and 2871 publish a notice of the decision to the Calext WG mailing list or its 2872 successor, as well as inform IANA. A denial notice must be justified 2873 by an explanation, and, in the cases where it is possible, concrete 2874 suggestions on how the request can be modified so as to become 2875 acceptable should be provided. 2877 8.2.4. Change Procedures 2879 Once a JSCalendar property has been published by the IANA, the change 2880 controller may request a change to its definition. The same 2881 procedure that would be appropriate for the original registration 2882 request is used to process a change request. 2884 JSCalendar property registrations may not be deleted; properties that 2885 are no longer believed appropriate for use can be declared obsolete 2886 by a change to their "intended use" field; such properties will be 2887 clearly marked in the lists published by the IANA. 2889 Significant changes to a JSCalendar property's definition should be 2890 requested only when there are serious omissions or errors in the 2891 published specification, as such changes may cause interoperability 2892 issues. When review is required, a change request may be denied if 2893 it renders entities that were valid under the previous definition 2894 invalid under the new definition. 2896 The owner of a JSCalendar property may pass responsibility to another 2897 person or agency by informing the IANA; this can be done without 2898 discussion or review. 2900 8.2.5. JSCalendar Properties Registry Template 2902 o Property Name: The name of the property. The property name MUST 2903 NOT already be registered for any of the object types listed in 2904 the "Property Context" field of this registration. Other object 2905 types MAY already have registered a different property with the 2906 same name. 2908 o Property Type: The type of this property, using type signatures as 2909 specified in Section 1.3. The property type MUST be registed in 2910 the Type Registry. 2912 o Property Context: A comma-separated list of JSCalendar object 2913 types this property is allowed on. 2915 o Reference or Description: A brief description or RFC number and 2916 section reference where the property is specified (omitted for 2917 "reserved" property names). 2919 o Intended Use: Common, reserved, or obsolete. 2921 o Change Controller: ("IETF" for IETF-stream RFCs). 2923 8.2.6. Initial Contents for the JSCalendar Properties Registry 2925 The following table lists the initial entries of the JSCalendar 2926 Properties registry. All properties are for common-use. All RFC 2927 section references are for this document. The change controller for 2928 all these properties is "IETF". 2930 +---------------+----------------------------+------------+---------+ 2931 | Property Name | Property Type | Property | Referen | 2932 | | | Context | ce or D | 2933 | | | | escript | 2934 | | | | ion | 2935 +---------------+----------------------------+------------+---------+ 2936 | @type | String | JSEvent, | Section | 2937 | | | JSTask, | 4.1.1, | 2938 | | | JSGroup, A | Section | 2939 | | | bsoluteTri | 4.5.2, | 2940 | | | gger, | Section | 2941 | | | Alert, | 4.2.7, | 2942 | | | Link, | Section | 2943 | | | Location, | 4.2.5, | 2944 | | | NDay, Offs | Section | 2945 | | | etTrigger, | 4.4.5, | 2946 | | | Participan | Section | 2947 | | | t, Recurre | 4.3.2, | 2948 | | | nceRule, | Section | 2949 | | | Relation, | 4.1.3, | 2950 | | | TimeZone, | Section | 2951 | | | TimeZoneRu | 4.7.2, | 2952 | | | le, Virtua | Section | 2953 | | | lLocation | 4.7.2, | 2954 | | | | Section | 2955 | | | | 4.2.6 | 2956 | | | | | 2957 | acknowledged | UTCDateTime | Alert | Section | 2958 | | | | 4.5.2 | 2959 | | | | | 2960 | action | String | Alert | Section | 2961 | | | | 4.5.2 | 2962 | | | | | 2963 | alerts | Id[Alert] | JSEvent, | Section | 2964 | | | JSTask | 4.5.2 | 2965 | | | | | 2966 | aliases | String[Boolean] | TimeZone | Section | 2967 | | | | 4.7.2 | 2968 | | | | | 2969 | byDay | NDay[] | Recurrence | Section | 2970 | | | Rule | 4.3.2 | 2971 | | | | | 2972 | byHour | UnsignedInt[] | Recurrence | Section | 2973 | | | Rule | 4.3.2 | 2974 | | | | | 2975 | byMinute | UnsignedInt[] | Recurrence | Section | 2976 | | | Rule | 4.3.2 | 2977 | | | | | 2978 | byMonth | String[] | Recurrence | Section | 2979 | | | Rule | 4.3.2 | 2980 | | | | | 2981 | byMonthDay | Int[] | Recurrence | Section | 2982 | | | Rule | 4.3.2 | 2983 | | | | | 2984 | bySecond | UnsignedInt[] | Recurrence | Section | 2985 | | | Rule | 4.3.2 | 2986 | | | | | 2987 | bySetPosition | Int[] | Recurrence | Section | 2988 | | | Rule | 4.3.2 | 2989 | | | | | 2990 | byWeekNo | Int[] | Recurrence | Section | 2991 | | | Rule | 4.3.2 | 2992 | | | | | 2993 | byYearDay | Int[] | Recurrence | Section | 2994 | | | Rule | 4.3.2 | 2995 | | | | | 2996 | categories | String[Boolean] | JSEvent, | Section | 2997 | | | JSTask, | 4.2.10 | 2998 | | | JSGroup | | 2999 | | | | | 3000 | cid | String | Link | Section | 3001 | | | | 4.2.7 | 3002 | | | | | 3003 | color | String | JSEvent, | Section | 3004 | | | JSTask, | 4.2.11 | 3005 | | | JSGroup | | 3006 | | | | | 3007 | comments | String[] | TimeZoneRu | Section | 3008 | | | le | 4.7.2 | 3009 | | | | | 3010 | contentType | String | Link | Section | 3011 | | | | 4.2.7 | 3012 | | | | | 3013 | coordinates | String | Location | Section | 3014 | | | | 4.2.5 | 3015 | | | | | 3016 | count | UnsignedInt | Recurrence | Section | 3017 | | | Rule | 4.3.2 | 3018 | | | | | 3019 | created | UTCDateTime | JSEvent, | Section | 3020 | | | JSTask, | 4.1.5 | 3021 | | | JSGroup | | 3022 | | | | | 3023 | day | String | NDay | Section | 3024 | | | | 4.3.2 | 3025 | | | | | 3026 | daylight | TimeZoneRule | TimeZone | Section | 3027 | | | | 4.7.2 | 3028 | | | | | 3029 | delegatedFrom | String[Boolean] | Participan | Section | 3030 | | | t | 4.4.5 | 3031 | | | | | 3032 | delegatedTo | String[Boolean] | Participan | Section | 3033 | | | t | 4.4.5 | 3034 | | | | | 3035 | description | String | JSEvent, | Section | 3036 | | | JSTask, | 4.2.2, | 3037 | | | Location, | Section | 3038 | | | Participan | 4.2.5, | 3039 | | | t, Virtual | Section | 3040 | | | Location | 4.4.5, | 3041 | | | | Section | 3042 | | | | 4.2.6 | 3043 | | | | | 3044 | descriptionCo | String | JSEvent, | Section | 3045 | ntentType | | JSTask | 4.2.3 | 3046 | | | | | 3047 | display | String | Link | Section | 3048 | | | | 4.2.7 | 3049 | | | | | 3050 | due | LocalDateTime | JSTask | Section | 3051 | | | | 5.2.1 | 3052 | | | | | 3053 | duration | Duration | JSEvent | Section | 3054 | | | | 5.1.2 | 3055 | | | | | 3056 | email | String | Participan | Section | 3057 | | | t | 4.4.5 | 3058 | | | | | 3059 | entries | (JSTask|JSEvent)[] | JSGroup | Section | 3060 | | | | 5.3.1 | 3061 | | | | | 3062 | estimatedDura | Duration | JSTask | Section | 3063 | tion | | | 5.2.3 | 3064 | | | | | 3065 | excluded | Boolean | JSEvent, | Section | 3066 | | | JSTask | 4.3.5 | 3067 | | | | | 3068 | excludedRecur | RecurrenceRule[] | JSEvent, | Section | 3069 | renceRules | | JSTask | 4.3.3 | 3070 | | | | | 3071 | expectReply | Boolean | Participan | Section | 3072 | | | t | 4.4.5 | 3073 | | | | | 3074 | firstDayOfWee | String | Recurrence | Section | 3075 | k | | Rule | 4.3.2 | 3076 | | | | | 3077 | freeBusyStatu | String | JSEvent, | Section | 3078 | s | | JSTask | 4.4.2 | 3079 | | | | | 3080 | frequency | String | Recurrence | Section | 3081 | | | Rule | 4.3.2 | 3082 | | | | | 3083 | href | String | Link | Section | 3084 | | | | 4.2.7 | 3085 | | | | | 3086 | interval | UnsignedInt | Recurrence | Section | 3087 | | | Rule | 4.3.2 | 3088 | | | | | 3089 | invitedBy | String | Participan | Section | 3090 | | | t | 4.4.5 | 3091 | | | | | 3092 | keywords | String[Boolean] | JSEvent, | Section | 3093 | | | JSTask, | 4.2.9 | 3094 | | | JSGroup | | 3095 | | | | | 3096 | kind | String | Participan | Section | 3097 | | | t | 4.4.5 | 3098 | | | | | 3099 | language | String | Participan | Section | 3100 | | | t | 4.4.5 | 3101 | | | | | 3102 | linkIds | Id[Boolean] | Location, | Section | 3103 | | | Participan | 4.2.5, | 3104 | | | t | Section | 3105 | | | | 4.4.5 | 3106 | | | | | 3107 | links | Id[Link] | JSGroup, | Section | 3108 | | | JSEvent, | 4.2.7 | 3109 | | | JSTask | | 3110 | | | | | 3111 | locale | String | JSGroup, | Section | 3112 | | | JSEvent, | 4.2.7 | 3113 | | | JSTask | | 3114 | | | | | 3115 | localizations | String[PatchObject] | JSEvent, | Section | 3116 | | | JSTask | 4.6.1 | 3117 | | | | | 3118 | locationId | String | Participan | Section | 3119 | | | t | 4.4.5 | 3120 | | | | | 3121 | locations | Id[Location] | JSEvent, | Section | 3122 | | | JSTask | 4.2.5 | 3123 | | | | | 3124 | locationTypes | String[Boolean] | Location | Section | 3125 | | | | 4.2.5 | 3126 | | | | | 3127 | memberOf | String[Boolean] | Participan | Section | 3128 | | | t | 4.4.5 | 3129 | | | | | 3130 | method | String | JSEvent, | Section | 3131 | | | JSTask | 4.1.8 | 3132 | | | | | 3133 | name | String | Location, | Section | 3134 | | | VirtualLoc | 4.2.5, | 3135 | | | ation, Par | Section | 3136 | | | ticipant | 4.2.6, | 3137 | | | | Section | 3138 | | | | 4.4.5 | 3139 | | | | | 3140 | names | String[Boolean] | TimeZoneRu | Section | 3141 | | | le | 4.7.2 | 3142 | | | | | 3143 | nthOfPeriod | Int | NDay | Section | 3144 | | | | 4.3.2 | 3145 | | | | | 3146 | offset | SignedDuration | OffsetTrig | Section | 3147 | | | ger | 4.5.2 | 3148 | | | | | 3149 | offsetFrom | UTCDateTime | TimeZoneRu | Section | 3150 | | | le | 4.7.2 | 3151 | | | | | 3152 | offsetTo | UTCDateTime | TimeZoneRu | Section | 3153 | | | le | 4.7.2 | 3154 | | | | | 3155 | participants | Id[Participant] | JSEvent, | Section | 3156 | | | JSTask | 4.4.5 | 3157 | | | | | 3158 | participation | String | Participan | Section | 3159 | Comment | | t | 4.4.5 | 3160 | | | | | 3161 | participation | String | Participan | Section | 3162 | Status | | t | 4.4.5 | 3163 | | | | | 3164 | percentComple | UnsignedInt | JSTask, Pa | Section | 3165 | te | | rticipant | 5.2.4 | 3166 | | | | | 3167 | priority | Int | JSEvent, | Section | 3168 | | | JSTask | 4.4.1 | 3169 | | | | | 3170 | privacy | String | JSEvent, | Section | 3171 | | | JSTask | 4.4.3 | 3172 | | | | | 3173 | prodId | String | JSEvent, | Section | 3174 | | | JSTask, | 4.1.4 | 3175 | | | JSGroup | | 3176 | | | | | 3177 | progress | String | JSTask, Pa | Section | 3178 | | | rticipant | 5.2.5 | 3179 | | | | | 3180 | progressUpdat | UTCDateTime | JSTask, Pa | Section | 3181 | ed | | rticipant | 5.2.6 | 3182 | | | | | 3183 | recurrenceId | LocalDateTime | JSEvent, | Section | 3184 | | | JSTask | 4.3.1 | 3185 | | | | | 3186 | recurrenceOve | LocalDateTime[PatchObject] | JSEvent, | Section | 3187 | rrides | | JSTask, Ti | 4.3.4, | 3188 | | | meZoneRule | Section | 3189 | | | | 4.7.2 | 3190 | | | | | 3191 | recurrenceRul | RecurrenceRule[] | JSEvent, | Section | 3192 | es | | JSTask, Ti | 4.3.2, | 3193 | | | meZoneRule | Section | 3194 | | | | 4.7.2 | 3195 | | | | | 3196 | rel | String | Link | Section | 3197 | | | | 4.2.7 | 3198 | | | | | 3199 | relatedTo | String[Relation] | JSEvent, | Section | 3200 | | | JSTask, | 4.1.3, | 3201 | | | Alert | Section | 3202 | | | | 4.5.2 | 3203 | | | | | 3204 | relation | String[Boolean] | Relation | Section | 3205 | | | | 1.4.10 | 3206 | | | | | 3207 | relativeTo | String | OffsetTrig | Section | 3208 | | | ger, | 4.5.2, | 3209 | | | Location | Section | 3210 | | | | 4.2.5 | 3211 | | | | | 3212 | replyTo | String[String] | JSEvent, | Section | 3213 | | | JSTask | 4.4.4 | 3214 | | | | | 3215 | roles | String[Boolean] | Participan | Section | 3216 | | | t | 4.4.5 | 3217 | | | | | 3218 | rscale | String | Recurrence | Section | 3219 | | | Rule | 4.3.2 | 3220 | | | | | 3221 | standard | TimeZoneRule | TimeZone | Section | 3222 | | | | 4.7.2 | 3223 | | | | | 3224 | start | LocalDateTime | TimeZoneRu | Section | 3225 | | | le | 4.7.2 | 3226 | | | | | 3227 | scheduleAgent | String | Participan | Section | 3228 | | | t | 4.4.5 | 3229 | | | | | 3230 | scheduleForce | Boolean | Participan | Section | 3231 | Send | | t | 4.4.5 | 3232 | | | | | 3233 | scheduleSeque | UnsignedInt | Participan | Section | 3234 | nce | | t | 4.4.5 | 3235 | | | | | 3236 | scheduleStatu | String[] | Participan | Section | 3237 | s | | t | 4.4.5 | 3238 | | | | | 3239 | scheduleUpdat | UTCDateTime | Participan | Section | 3240 | ed | | t | 4.4.5 | 3241 | | | | | 3242 | sendTo | String[String] | Participan | Section | 3243 | | | t | 4.4.5 | 3244 | | | | | 3245 | sequence | UnsignedInt | JSEvent, | Section | 3246 | | | JSTask | 4.1.7 | 3247 | | | | | 3248 | showWithoutTi | Boolean | JSEvent, | Section | 3249 | me | | JSTask | 4.2.4 | 3250 | | | | | 3251 | size | UnsignedInt | Link | Section | 3252 | | | | 4.2.7 | 3253 | | | | | 3254 | skip | String | Recurrence | Section | 3255 | | | Rule | 4.3.2 | 3256 | | | | | 3257 | source | String | JSGroup | Section | 3258 | | | | 5.3.2 | 3259 | | | | | 3260 | start | LocalDateTime | JSEvent, | Section | 3261 | | | JSTask | 5.1.1, | 3262 | | | | Section | 3263 | | | | 5.2.2 | 3264 | | | | | 3265 | status | String | JSEvent | Section | 3266 | | | | 5.1.3 | 3267 | | | | | 3268 | timeZone | String|null | JSEvent, | Section | 3269 | | | JSTask, | 4.7.1, | 3270 | | | Location | Section | 3271 | | | | 4.2.5 | 3272 | | | | | 3273 | timeZones | String[TimeZone] | JSEvent, | Section | 3274 | | | JSTask | 4.7.2 | 3275 | | | | | 3276 | title | String | JSEvent, | Section | 3277 | | | JSTask, | 4.2.1 | 3278 | | | JSGroup, | | 3279 | | | Link | | 3280 | | | | | 3281 | trigger | OffsetTrigger|AbsoluteTrig | Alert | Section | 3282 | | ger|UnknownTrigger | | 4.5.2 | 3283 | | | | | 3284 | tzId | String | TimeZone | Section | 3285 | | | | 4.7.2 | 3286 | | | | | 3287 | uid | String | JSEvent, | Section | 3288 | | | JSTask, | 4.1.2 | 3289 | | | JSGroup | | 3290 | | | | | 3291 | until | LocalDateTime | Recurrence | Section | 3292 | | | Rule | 4.3.2 | 3293 | | | | | 3294 | updated | UTCDateTime | JSEvent, | Section | 3295 | | | JSTask, | 4.1.6 | 3296 | | | JSGroup | | 3297 | | | | | 3298 | uri | String | VirtualLoc | Section | 3299 | | | ation | 4.2.6 | 3300 | | | | | 3301 | url | String | TimeZone | Section | 3302 | | | | 4.7.2 | 3303 | | | | | 3304 | useDefaultAle | Boolean | JSEvent, | Section | 3305 | rts | | JSTask | 4.5.1 | 3306 | | | | | 3307 | validUntil | UTCDateTime | TimeZone | Section | 3308 | | | | 4.7.2 | 3309 | | | | | 3310 | virtualLocati | Id[VirtualLocation] | JSEvent, | Section | 3311 | ons | | JSTask | 4.2.6 | 3312 | | | | | 3313 | when | UTCDateTime | AbsoluteTr | Section | 3314 | | | igger | 4.5.2 | 3315 +---------------+----------------------------+------------+---------+ 3317 Table 1 3319 8.3. Creation of "JSCalendar Types" Registry 3321 The IANA will create the "JSCalendar Types" registry to avoid name 3322 collisions and provide a complete reference for all data types used 3323 for JSCalendar property values. The registration process is the same 3324 as for the JSCalendar Properties registry, as defined in Section 8.2. 3326 8.3.1. JSCalendar Types Registry Template 3328 o Type Name: The name of the type. 3330 o Reference or Description: A brief description or RFC number and 3331 section reference where the Type is specified (may be omitted for 3332 "reserved" type names). 3334 o Intended Use: Common, reserved, or obsolete. 3336 o Change Controller: ("IETF" for IETF-stream RFCs). 3338 8.3.2. Initial Contents for the JSCalendar Types Registry 3340 The following table lists the initial entries of the JSCalendar Types 3341 registry. All properties are for common-use. All RFC section 3342 references are for this document. The change controller for all 3343 these properties is "IETF". 3345 +-----------------+--------------------------+ 3346 | Type Name | Reference or Description | 3347 +-----------------+--------------------------+ 3348 | Alert | Section 4.5.2 | 3349 | | | 3350 | Boolean | Section 1.3 | 3351 | | | 3352 | Duration | Section 1.4.5 | 3353 | | | 3354 | Id | Section 1.4.7 | 3355 | | | 3356 | Int | Section 1.4.1 | 3357 | | | 3358 | LocalDateTime | Section 1.4.4 | 3359 | | | 3360 | Link | Section 4.2.7 | 3361 | | | 3362 | Location | Section 4.2.5 | 3363 | | | 3364 | NDay | Section 4.3.2 | 3365 | | | 3366 | Number | Section 1.3 | 3367 | | | 3368 | Participant | Section 4.4.5 | 3369 | | | 3370 | PatchObject | Section 1.4.8 | 3371 | | | 3372 | RecurrenceRule | Section 4.3.2 | 3373 | | | 3374 | Relation | Section 1.4.10 | 3375 | | | 3376 | SignedDuration | Section 1.4.6 | 3377 | | | 3378 | String | Section 1.3 | 3379 | | | 3380 | TimeZone | Section 4.7.2 | 3381 | | | 3382 | TimeZoneRule | Section 4.7.2 | 3383 | | | 3384 | UnsignedInt | Section 1.4.2 | 3385 | | | 3386 | UTCDateTime | Section 1.4.3 | 3387 | | | 3388 | VirtualLocation | Section 4.2.6 | 3389 +-----------------+--------------------------+ 3391 Table 2 3393 8.4. Creation of "JSCalendar Enum Values" Registry 3395 The IANA will create the "JSCalendar Enum Values" registry to allow 3396 interoperable extension of semantics for properties with enumerable 3397 values. Each such property will have a subregistry of allowed 3398 values. The registration process for a new enum value or adding a 3399 new enumerable property is the same as for the JSCalendar Properties 3400 registry, as defined in Section 8.2. 3402 8.4.1. JSCalendar Enum Property Template 3404 This template is for adding a subregistry for a new enumerable 3405 property to the JSCalendar Enum registry. 3407 o Registry Name: This MUST be of the form "Enum Values for 3408 {property-name} (Context: {context})" where: 3410 {property-name} is the name(s) of the property or properties where 3411 these values may be used. This MUST be registered in the 3412 JSCalendar Properties registry. 3414 {context} is the list of allowed object types where the property 3415 or properties may appear, as registered in the JSCalendar 3416 Properties registry. This disambiguates where there may be two 3417 distinct properties with the same name in different contexts. 3419 o Change Controller: ("IETF" for properties defined in IETF-stream 3420 RFCs). 3422 o Initial Contents: The initial list of defined values for this 3423 enum, using the template defined in Section 8.4.2. 3425 8.4.2. JSCalendar Enum Value Template 3427 This template is for adding a new enum value to a subregistry in the 3428 JSCalendar Enum registry. 3430 o Enum Value: The verbatim value of the enum. 3432 o Reference or Description: A brief description or RFC number and 3433 section reference for the semantics of this value. 3435 8.4.3. Initial Contents for the JSCalendar Enum Registry 3437 For each subregistry created in this section, all RFC section 3438 references are for this document and the change controller is IETF. 3440 ------------------------------------------------------------ 3441 Enum Values for action (Context: Alert) 3443 +------------+--------------------------+ 3444 | Enum Value | Reference or Description | 3445 +------------+--------------------------+ 3446 | display | Section 4.5.2 | 3447 | | | 3448 | email | Section 4.5.2 | 3449 +------------+--------------------------+ 3451 Table 3 3453 ------------------------------------------------------------ 3455 Enum Values for display (Context: Link) 3457 +------------+--------------------------+ 3458 | Enum Value | Reference or Description | 3459 +------------+--------------------------+ 3460 | badge | Section 4.2.7 | 3461 | | | 3462 | graphic | Section 4.2.7 | 3463 | | | 3464 | fullsize | Section 4.2.7 | 3465 | | | 3466 | thumbnail | Section 4.2.7 | 3467 +------------+--------------------------+ 3469 Table 4 3471 ------------------------------------------------------------ 3473 Enum Values for freeBusyStatus (Context: JSEvent, JSTask) 3475 +------------+--------------------------+ 3476 | Enum Value | Reference or Description | 3477 +------------+--------------------------+ 3478 | free | Section 4.4.2 | 3479 | | | 3480 | busy | Section 4.4.2 | 3481 +------------+--------------------------+ 3483 Table 5 3485 ------------------------------------------------------------ 3487 Enum Values for kind (Context: Participant) 3488 +------------+--------------------------+ 3489 | Enum Value | Reference or Description | 3490 +------------+--------------------------+ 3491 | individual | Section 4.4.5 | 3492 | | | 3493 | group | Section 4.4.5 | 3494 | | | 3495 | resource | Section 4.4.5 | 3496 | | | 3497 | location | Section 4.4.5 | 3498 +------------+--------------------------+ 3500 Table 6 3502 ------------------------------------------------------------ 3504 Enum Values for participationStatus (Context: Participant) 3506 +--------------+--------------------------+ 3507 | Enum Value | Reference or Description | 3508 +--------------+--------------------------+ 3509 | needs-action | Section 4.4.5 | 3510 | | | 3511 | accepted | Section 4.4.5 | 3512 | | | 3513 | declined | Section 4.4.5 | 3514 | | | 3515 | tenative | Section 4.4.5 | 3516 | | | 3517 | delegated | Section 4.4.5 | 3518 +--------------+--------------------------+ 3520 Table 7 3522 ------------------------------------------------------------ 3524 Enum Values for privacy (Context: JSEvent, JSTask) 3525 +------------+--------------------------+ 3526 | Enum Value | Reference or Description | 3527 +------------+--------------------------+ 3528 | public | Section 4.4.3 | 3529 | | | 3530 | private | Section 4.4.3 | 3531 | | | 3532 | secret | Section 4.4.3 | 3533 +------------+--------------------------+ 3535 Table 8 3537 ------------------------------------------------------------ 3539 Enum Values for progress (Context: JSTask, Participant) 3541 +--------------+--------------------------+ 3542 | Enum Value | Reference or Description | 3543 +--------------+--------------------------+ 3544 | needs-action | Section 5.2.5 | 3545 | | | 3546 | in-process | Section 5.2.5 | 3547 | | | 3548 | completed | Section 5.2.5 | 3549 | | | 3550 | failed | Section 5.2.5 | 3551 | | | 3552 | cancelled | Section 5.2.5 | 3553 +--------------+--------------------------+ 3555 Table 9 3557 ------------------------------------------------------------ 3559 Enum Values for relation (Context: Relation) 3560 +------------+--------------------------+ 3561 | Enum Value | Reference or Description | 3562 +------------+--------------------------+ 3563 | first | Section 1.4.10 | 3564 | | | 3565 | next | Section 1.4.10 | 3566 | | | 3567 | child | Section 1.4.10 | 3568 | | | 3569 | parent | Section 1.4.10 | 3570 +------------+--------------------------+ 3572 Table 10 3574 ------------------------------------------------------------ 3576 Enum Values for relativeTo (Context: OffsetTrigger, Location) 3578 +------------+--------------------------+ 3579 | Enum Value | Reference or Description | 3580 +------------+--------------------------+ 3581 | start | Section 4.5.2 | 3582 | | | 3583 | end | Section 4.5.2 | 3584 +------------+--------------------------+ 3586 Table 11 3588 ------------------------------------------------------------ 3590 Enum Values for roles (Context: Participant) 3591 +---------------+--------------------------+ 3592 | Enum Value | Reference or Description | 3593 +---------------+--------------------------+ 3594 | owner | Section 4.4.5 | 3595 | | | 3596 | attendee | Section 4.4.5 | 3597 | | | 3598 | optional | Section 4.4.5 | 3599 | | | 3600 | informational | Section 4.4.5 | 3601 | | | 3602 | chair | Section 4.4.5 | 3603 | | | 3604 | contact | Section 4.4.5 | 3605 +---------------+--------------------------+ 3607 Table 12 3609 ------------------------------------------------------------ 3611 Enum Values for scheduleAgent (Context: Participant) 3613 +------------+--------------------------+ 3614 | Enum Value | Reference or Description | 3615 +------------+--------------------------+ 3616 | server | Section 4.4.5 | 3617 | | | 3618 | client | Section 4.4.5 | 3619 | | | 3620 | none | Section 4.4.5 | 3621 +------------+--------------------------+ 3623 Table 13 3625 ------------------------------------------------------------ 3627 Enum Values for status (Context: JSEvent) 3628 +------------+--------------------------+ 3629 | Enum Value | Reference or Description | 3630 +------------+--------------------------+ 3631 | confirmed | Section 5.1.3 | 3632 | | | 3633 | cancelled | Section 5.1.3 | 3634 | | | 3635 | tentative | Section 5.1.3 | 3636 +------------+--------------------------+ 3638 Table 14 3640 9. Acknowledgments 3642 The authors would like to thank the members of CalConnect for their 3643 valuable contributions. This specification originated from the work 3644 of the API technical committee of CalConnect, the Calendaring and 3645 Scheduling Consortium. 3647 10. References 3649 10.1. Normative References 3651 [CLDR] "Unicode Common Locale Data Repository", 3652 . 3654 [COLORS] "CSS Color Module", . 3656 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3657 Requirement Levels", BCP 14, RFC 2119, 3658 DOI 10.17487/RFC2119, March 1997, 3659 . 3661 [RFC2392] Levinson, E., "Content-ID and Message-ID Uniform Resource 3662 Locators", RFC 2392, DOI 10.17487/RFC2392, August 1998, 3663 . 3665 [RFC2397] Masinter, L., "The "data" URL scheme", RFC 2397, 3666 DOI 10.17487/RFC2397, August 1998, 3667 . 3669 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 3670 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 3671 . 3673 [RFC4589] Schulzrinne, H. and H. Tschofenig, "Location Types 3674 Registry", RFC 4589, DOI 10.17487/RFC4589, July 2006, 3675 . 3677 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 3678 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 3679 . 3681 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 3682 Specifications: ABNF", STD 68, RFC 5234, 3683 DOI 10.17487/RFC5234, January 2008, 3684 . 3686 [RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and 3687 Scheduling Core Object Specification (iCalendar)", 3688 RFC 5545, DOI 10.17487/RFC5545, September 2009, 3689 . 3691 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 3692 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 3693 September 2009, . 3695 [RFC5870] Mayrhofer, A. and C. Spanring, "A Uniform Resource 3696 Identifier for Geographic Locations ('geo' URI)", 3697 RFC 5870, DOI 10.17487/RFC5870, June 2010, 3698 . 3700 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 3701 Specifications and Registration Procedures", BCP 13, 3702 RFC 6838, DOI 10.17487/RFC6838, January 2013, 3703 . 3705 [RFC6901] Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., 3706 "JavaScript Object Notation (JSON) Pointer", RFC 6901, 3707 DOI 10.17487/RFC6901, April 2013, 3708 . 3710 [RFC7493] Bray, T., Ed., "The I-JSON Message Format", RFC 7493, 3711 DOI 10.17487/RFC7493, March 2015, 3712 . 3714 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 3715 Writing an IANA Considerations Section in RFCs", BCP 26, 3716 RFC 8126, DOI 10.17487/RFC8126, June 2017, 3717 . 3719 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 3720 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 3721 May 2017, . 3723 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 3724 Interchange Format", STD 90, RFC 8259, 3725 DOI 10.17487/RFC8259, December 2017, 3726 . 3728 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 3729 DOI 10.17487/RFC8288, October 2017, 3730 . 3732 [TZDB] "IANA Time Zone Database", 3733 . 3735 10.2. Informative References 3737 [LINKRELS] 3738 "IANA Link Relation Types", 3739 . 3742 [LOCATIONTYPES] 3743 "IANA Location Types Registry", 3744 . 3747 [MIME] "IANA Media Types", . 3750 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3751 Resource Identifier (URI): Generic Syntax", STD 66, 3752 RFC 3986, DOI 10.17487/RFC3986, January 2005, 3753 . 3755 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 3756 Unique IDentifier (UUID) URN Namespace", RFC 4122, 3757 DOI 10.17487/RFC4122, July 2005, 3758 . 3760 [RFC5546] Daboo, C., Ed., "iCalendar Transport-Independent 3761 Interoperability Protocol (iTIP)", RFC 5546, 3762 DOI 10.17487/RFC5546, December 2009, 3763 . 3765 [RFC6047] Melnikov, A., Ed., "iCalendar Message-Based 3766 Interoperability Protocol (iMIP)", RFC 6047, 3767 DOI 10.17487/RFC6047, December 2010, 3768 . 3770 [RFC6376] Crocker, D., Ed., Hansen, T., Ed., and M. Kucherawy, Ed., 3771 "DomainKeys Identified Mail (DKIM) Signatures", STD 76, 3772 RFC 6376, DOI 10.17487/RFC6376, September 2011, 3773 . 3775 [RFC7265] Kewisch, P., Daboo, C., and M. Douglass, "jCal: The JSON 3776 Format for iCalendar", RFC 7265, DOI 10.17487/RFC7265, May 3777 2014, . 3779 [RFC7529] Daboo, C. and G. Yakushev, "Non-Gregorian Recurrence Rules 3780 in the Internet Calendaring and Scheduling Core Object 3781 Specification (iCalendar)", RFC 7529, 3782 DOI 10.17487/RFC7529, May 2015, 3783 . 3785 [RFC7808] Douglass, M. and C. Daboo, "Time Zone Data Distribution 3786 Service", RFC 7808, DOI 10.17487/RFC7808, March 2016, 3787 . 3789 [RFC7986] Daboo, C., "New Properties for iCalendar", RFC 7986, 3790 DOI 10.17487/RFC7986, October 2016, 3791 . 3793 Authors' Addresses 3795 Neil Jenkins 3796 Fastmail 3797 PO Box 234 3798 Collins St West 3799 Melbourne VIC 8007 3800 Australia 3802 Email: neilj@fastmailteam.com 3803 URI: https://www.fastmail.com 3805 Robert Stepanek 3806 Fastmail 3807 PO Box 234 3808 Collins St West 3809 Melbourne VIC 8007 3810 Australia 3812 Email: rsto@fastmailteam.com 3813 URI: https://www.fastmail.com