idnits 2.17.1 draft-ietf-calext-jscalendar-28.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 (July 27, 2020) is 1367 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 2888, but not defined == Missing Reference: 'Boolean' is mentioned on line 3112, but not defined == Missing Reference: 'Link' is mentioned on line 3020, but not defined == Missing Reference: 'PatchObject' is mentioned on line 3087, but not defined == Missing Reference: 'Location' is mentioned on line 3034, but not defined == Missing Reference: 'Participant' is mentioned on line 3056, but not defined == Missing Reference: 'Relation' is mentioned on line 3096, but not defined == Missing Reference: 'String' is mentioned on line 3133, but not defined == Missing Reference: 'TimeZone' is mentioned on line 3164, but not defined == Missing Reference: 'VirtualLocation' is mentioned on line 3192, 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: January 28, 2021 July 27, 2020 7 JSCalendar: A JSON representation of calendar data 8 draft-ietf-calext-jscalendar-28 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 January 28, 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 . . . . . . . . . . . . . . . . . . . 8 66 1.4.7. Id . . . . . . . . . . . . . . . . . . . . . . . . . 8 67 1.4.8. PatchObject . . . . . . . . . . . . . . . . . . . . . 9 68 1.4.9. Time Zones . . . . . . . . . . . . . . . . . . . . . 9 69 1.4.10. Relation . . . . . . . . . . . . . . . . . . . . . . 10 70 2. JSCalendar Objects . . . . . . . . . . . . . . . . . . . . . 10 71 2.1. JSEvent . . . . . . . . . . . . . . . . . . . . . . . . . 10 72 2.2. JSTask . . . . . . . . . . . . . . . . . . . . . . . . . 11 73 2.3. JSGroup . . . . . . . . . . . . . . . . . . . . . . . . . 11 74 3. Structure of JSCalendar Objects . . . . . . . . . . . . . . . 11 75 3.1. Normalization and Equivalence . . . . . . . . . . . . . . 11 76 3.2. Vendor-specific Property Extensions and Values . . . . . 12 77 4. Common JSCalendar Properties . . . . . . . . . . . . . . . . 12 78 4.1. Metadata Properties . . . . . . . . . . . . . . . . . . . 12 79 4.1.1. @type . . . . . . . . . . . . . . . . . . . . . . . . 12 80 4.1.2. uid . . . . . . . . . . . . . . . . . . . . . . . . . 13 81 4.1.3. relatedTo . . . . . . . . . . . . . . . . . . . . . . 13 82 4.1.4. prodId . . . . . . . . . . . . . . . . . . . . . . . 13 83 4.1.5. created . . . . . . . . . . . . . . . . . . . . . . . 14 84 4.1.6. updated . . . . . . . . . . . . . . . . . . . . . . . 14 85 4.1.7. sequence . . . . . . . . . . . . . . . . . . . . . . 14 86 4.1.8. method . . . . . . . . . . . . . . . . . . . . . . . 14 87 4.2. What and Where Properties . . . . . . . . . . . . . . . . 14 88 4.2.1. title . . . . . . . . . . . . . . . . . . . . . . . . 14 89 4.2.2. description . . . . . . . . . . . . . . . . . . . . . 15 90 4.2.3. descriptionContentType . . . . . . . . . . . . . . . 15 91 4.2.4. showWithoutTime . . . . . . . . . . . . . . . . . . . 15 92 4.2.5. locations . . . . . . . . . . . . . . . . . . . . . . 15 93 4.2.6. virtualLocations . . . . . . . . . . . . . . . . . . 17 94 4.2.7. links . . . . . . . . . . . . . . . . . . . . . . . . 17 95 4.2.8. locale . . . . . . . . . . . . . . . . . . . . . . . 19 96 4.2.9. keywords . . . . . . . . . . . . . . . . . . . . . . 19 97 4.2.10. categories . . . . . . . . . . . . . . . . . . . . . 19 98 4.2.11. color . . . . . . . . . . . . . . . . . . . . . . . . 20 99 4.3. Recurrence Properties . . . . . . . . . . . . . . . . . . 20 100 4.3.1. recurrenceId . . . . . . . . . . . . . . . . . . . . 20 101 4.3.2. recurrenceRules . . . . . . . . . . . . . . . . . . . 21 102 4.3.3. excludedRecurrenceRules . . . . . . . . . . . . . . . 29 103 4.3.4. recurrenceOverrides . . . . . . . . . . . . . . . . . 29 104 4.3.5. excluded . . . . . . . . . . . . . . . . . . . . . . 30 105 4.4. Sharing and Scheduling Properties . . . . . . . . . . . . 30 106 4.4.1. priority . . . . . . . . . . . . . . . . . . . . . . 31 107 4.4.2. freeBusyStatus . . . . . . . . . . . . . . . . . . . 31 108 4.4.3. privacy . . . . . . . . . . . . . . . . . . . . . . . 31 109 4.4.4. replyTo . . . . . . . . . . . . . . . . . . . . . . . 33 110 4.4.5. participants . . . . . . . . . . . . . . . . . . . . 33 111 4.5. Alerts Properties . . . . . . . . . . . . . . . . . . . . 39 112 4.5.1. useDefaultAlerts . . . . . . . . . . . . . . . . . . 39 113 4.5.2. alerts . . . . . . . . . . . . . . . . . . . . . . . 39 114 4.6. Multilingual Properties . . . . . . . . . . . . . . . . . 41 115 4.6.1. localizations . . . . . . . . . . . . . . . . . . . . 41 116 4.7. Time Zone Properties . . . . . . . . . . . . . . . . . . 42 117 4.7.1. timeZone . . . . . . . . . . . . . . . . . . . . . . 42 118 4.7.2. timeZones . . . . . . . . . . . . . . . . . . . . . . 42 119 5. Type-specific JSCalendar Properties . . . . . . . . . . . . . 45 120 5.1. JSEvent Properties . . . . . . . . . . . . . . . . . . . 45 121 5.1.1. start . . . . . . . . . . . . . . . . . . . . . . . . 45 122 5.1.2. duration . . . . . . . . . . . . . . . . . . . . . . 45 123 5.1.3. status . . . . . . . . . . . . . . . . . . . . . . . 45 124 5.2. JSTask Properties . . . . . . . . . . . . . . . . . . . . 46 125 5.2.1. due . . . . . . . . . . . . . . . . . . . . . . . . . 46 126 5.2.2. start . . . . . . . . . . . . . . . . . . . . . . . . 46 127 5.2.3. estimatedDuration . . . . . . . . . . . . . . . . . . 46 128 5.2.4. percentComplete . . . . . . . . . . . . . . . . . . . 46 129 5.2.5. progress . . . . . . . . . . . . . . . . . . . . . . 46 130 5.2.6. progressUpdated . . . . . . . . . . . . . . . . . . . 47 131 5.3. JSGroup Properties . . . . . . . . . . . . . . . . . . . 47 132 5.3.1. entries . . . . . . . . . . . . . . . . . . . . . . . 48 133 5.3.2. source . . . . . . . . . . . . . . . . . . . . . . . 48 134 6. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 48 135 6.1. Simple event . . . . . . . . . . . . . . . . . . . . . . 49 136 6.2. Simple task . . . . . . . . . . . . . . . . . . . . . . . 49 137 6.3. Simple group . . . . . . . . . . . . . . . . . . . . . . 49 138 6.4. All-day event . . . . . . . . . . . . . . . . . . . . . . 50 139 6.5. Task with a due date . . . . . . . . . . . . . . . . . . 50 140 6.6. Event with end time-zone . . . . . . . . . . . . . . . . 51 141 6.7. Floating-time event (with recurrence) . . . . . . . . . . 51 142 6.8. Event with multiple locations and localization . . . . . 52 143 6.9. Recurring event with overrides . . . . . . . . . . . . . 53 144 6.10. Recurring event with participants . . . . . . . . . . . . 54 146 7. Security Considerations . . . . . . . . . . . . . . . . . . . 56 147 7.1. Expanding Recurrences . . . . . . . . . . . . . . . . . . 56 148 7.2. JSON Parsing . . . . . . . . . . . . . . . . . . . . . . 56 149 7.3. URI Values . . . . . . . . . . . . . . . . . . . . . . . 57 150 7.4. Spam . . . . . . . . . . . . . . . . . . . . . . . . . . 57 151 7.5. Duplication . . . . . . . . . . . . . . . . . . . . . . . 58 152 7.6. Time Zones . . . . . . . . . . . . . . . . . . . . . . . 58 153 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 58 154 8.1. Media Type Registration . . . . . . . . . . . . . . . . . 58 155 8.2. Creation of "JSCalendar Properties" Registry . . . . . . 59 156 8.2.1. Preliminary Community Review . . . . . . . . . . . . 60 157 8.2.2. Submit Request to IANA . . . . . . . . . . . . . . . 60 158 8.2.3. Designated Expert Review . . . . . . . . . . . . . . 60 159 8.2.4. Change Procedures . . . . . . . . . . . . . . . . . . 61 160 8.2.5. JSCalendar Properties Registry Template . . . . . . . 61 161 8.2.6. Initial Contents for the JSCalendar Properties 162 Registry . . . . . . . . . . . . . . . . . . . . . . 62 163 8.3. Creation of "JSCalendar Types" Registry . . . . . . . . . 69 164 8.3.1. JSCalendar Types Registry Template . . . . . . . . . 69 165 8.3.2. Initial Contents for the JSCalendar Types Registry . 69 166 8.4. Creation of "JSCalendar Enum Values" Registry . . . . . . 71 167 8.4.1. JSCalendar Enum Property Template . . . . . . . . . . 71 168 8.4.2. JSCalendar Enum Value Template . . . . . . . . . . . 71 169 8.4.3. Initial Contents for the JSCalendar Enum Registry . . 71 170 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 77 171 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 77 172 10.1. Normative References . . . . . . . . . . . . . . . . . . 77 173 10.2. Informative References . . . . . . . . . . . . . . . . . 79 174 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 80 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 1.4.5. Duration 338 Where Duration is given as a type, it means a length of time 339 represented by a subset of ISO8601 duration format, as specified by 340 the following ABNF [RFC5234]: 342 dur-secfrac = "." 1*DIGIT 343 dur-second = 1*DIGIT [dur-secfrac] "S" 344 dur-minute = 1*DIGIT "M" [dur-second] 345 dur-hour = 1*DIGIT "H" [dur-minute] 346 dur-time = "T" (dur-hour / dur-minute / dur-second) 347 dur-day = 1*DIGIT "D" 348 dur-week = 1*DIGIT "W" 350 duration = "P" (dur-day [dur-time] / dur-time / dur-week) 352 In addition, the duration MUST NOT include fractional second values 353 unless the fraction is non-zero. 355 1.4.6. SignedDuration 357 A SignedDuration represents a length of time that may be positive or 358 negative and is typically used to express the offset of a point in 359 time relative to an associated time. It is represented as a 360 Duration, optionally preceded by a sign character. It is specified 361 by the following ABNF: 363 signed-duration = ["+" / "-"] duration 365 A negative sign indicates a point in time at or before the associated 366 time, a positive or no sign a time at or after the associated time. 368 1.4.7. Id 370 Where "Id" is given as a data type, it means a "String" of at least 1 371 and a maximum of 255 octets in size, and it MUST only contain 372 characters from the "URL and Filename Safe" base64url alphabet, as 373 defined in Section 5 of [RFC4648], excluding the pad character ("="). 374 This means the allowed characters are the ASCII alphanumeric 375 characters ("A-Za-z0-9"), hyphen ("-"), and underscore ("_"). 377 Unless otherwise specified, Ids are arbitrary and only have meaning 378 within the object where they are being used. Ids need not be unique 379 among different objects. For example, two JSEvent objects might use 380 the same ids in their respective "links" properties. Or within the 381 same JSEvent object the same Id could appear in the "participants" 382 and "alerts" properties. These situations do not imply any semantic 383 connections among the objects. 385 Nevertheless, a UUID is typically a good choice. 387 1.4.8. PatchObject 389 A PatchObject is of type "String[*]", and represents an unordered set 390 of patches on a JSON object. Each key is a path represented in a 391 subset of JSON pointer format [RFC6901]. The paths have an implicit 392 leading "/", so each key is prefixed with "/" before applying the 393 JSON pointer evaluation algorithm. 395 A patch within a PatchObject is only valid if all of the following 396 conditions apply: 398 1. The pointer MUST NOT insert/delete from an array; the array MUST 399 be replaced in its entirety instead. 401 2. When evaluating a path, all parts prior to the last (i.e., the 402 value after the final slash) MUST exist. 404 3. There MUST NOT be two patches in the PatchObject where the 405 pointer of one is a prefix of the pointer of the other, e.g., 406 "alerts/foo/offset" and "alerts". 408 4. The value for the patch MUST be valid for the property being set 409 (of the correct type and obeying any other applicable 410 restrictions), or if null the property MUST be optional. 412 The value associated with each pointer is either: 414 o null: Remove the property at the given path from the patched 415 object. If the property is not present in the object, this a no- 416 op. 418 o Anything else: Set the value for the property to this value (this 419 may be a replacement or addition to the object being patched). 421 Implementations MUST reject in its entirety a PatchObject if any of 422 its patches is invalid. Implementations MUST NOT apply partial 423 patches. 425 1.4.9. Time Zones 427 By default, time zones in JSCalendar are identified by their names in 428 the IANA Time Zone Database [TZDB], and the zone rules of the 429 respective zone records apply. 431 Implementations MAY embed the definitions of custom time zones in the 432 "timeZones" property (see Section 4.7.2). 434 1.4.10. Relation 436 A Relation object defines the relation to other objects, using a 437 possibly empty set of relation types. The object that defines this 438 relation is the linking object, while the other object is the linked 439 object. The Relation object has the following properties: 441 o @type: "String" (mandatory) 443 Specifies the type of this object. This MUST be "Relation". 445 o relation: "String[Boolean]" (optional, default: empty Object) 447 Describes how the linked object is related to the linking object. 448 The relation is defined as a set of relation types. If empty, the 449 relationship between the two objects is unspecified. 451 Keys in the set MUST be one of the following values, or specified 452 in the property definition where the Relation object is used, or a 453 value registered in the IANA JSCalendar Enum Registry, or a 454 vendor-specific value: 456 * "first": The linked object is the first in a series the linking 457 object is part of. 459 * "next": The linked object is the next in a series the linking 460 object is part of. 462 * "child": The linked object is a subpart of the linking object. 464 * "parent": The linking object is a subpart of the linked object. 466 The value for each key in the set MUST be true. 468 2. JSCalendar Objects 470 This section describes the calendar object types specified by 471 JSCalendar. 473 2.1. JSEvent 475 Media type: "application/jscalendar+json;type=jsevent" 477 A JSEvent represents a scheduled amount of time on a calendar, 478 typically a meeting, appointment, reminder or anniversary. It is 479 required to start at a certain point in time and typically has a non- 480 zero duration. Multiple participants may partake in the event at 481 multiple locations. 483 The @type (Section 4.1.1) property value MUST be "jsevent". 485 2.2. JSTask 487 Media type: "application/jscalendar+json;type=jstask" 489 A JSTask represents an action-item, assignment, to-do or work item. 490 It may start and be due at certain points in time, may take some 491 estimated time to complete, and may recur, none of which is required. 493 The @type (Section 4.1.1) property value MUST be "jstask". 495 2.3. JSGroup 497 Media type: "application/jscalendar+json;type=jsgroup" 499 A JSGroup is a collection of JSEvent (Section 2.1) and/or JSTask 500 (Section 2.2) objects. Typically, objects are grouped by topic 501 (e.g., by keywords) or calendar membership. 503 The @type (Section 4.1.1) property value MUST be "jsgroup". 505 3. Structure of JSCalendar Objects 507 A JSCalendar object is a JSON object, which MUST be valid I-JSON (a 508 stricter subset of JSON), as specified in [RFC8259]. Property names 509 and values are case-sensitive. 511 The object has a collection of properties, as specified in the 512 following sections. Properties are specified as being either 513 mandatory or optional. Optional properties may have a default value, 514 if explicitly specified in the property definition. 516 3.1. Normalization and Equivalence 518 JSCalendar aims to provide unambiguous definitions for value types 519 and properties, but does not define a general normalization or 520 equivalence method for JSCalendar objects and types. This is because 521 the notion of equivalence might range from byte-level equivalence to 522 semantic equivalence, depending on the respective use case. 524 Normalization of JSCalendar objects is hindered because of the 525 following reasons: 527 o Custom JSCalendar properties may contain arbitrary JSON values, 528 including arrays. However, equivalence of arrays might or might 529 not depend on the order of elements, depending on the respective 530 property definition. 532 o Several JSCalendar property values are defined as URIs and media 533 types, but normalization of these types is inherently protocol- 534 and scheme-specific, depending on the use-case of the equivalence 535 definition (see Section 6 of [RFC3986]). 537 Considering this, the definition of equivalence and normalization is 538 left to client and server implementations and to be negotiated by a 539 calendar exchange protocol or defined elsewhere. 541 3.2. Vendor-specific Property Extensions and Values 543 Vendors MAY add additional properties to the calendar object to 544 support their custom features. The names of these properties MUST be 545 prefixed with a domain name controlled by the vendor to avoid 546 conflict, e.g., "example.com/customprop". 548 Some JSCalendar properties allow vendor-specific value extensions. 549 Such vendor-specific values MUST be prefixed with a domain name 550 controlled by the vendor, e.g., "example.com/customrel". 552 Vendors are strongly encouraged to register any new property values 553 or extensions that are useful to other systems as well, rather than 554 use a vendor-specific prefix. 556 4. Common JSCalendar Properties 558 This section describes the properties that are common to the various 559 JSCalendar object types. Specific JSCalendar object types may only 560 support a subset of these properties. The object type definitions in 561 Section 5 describe the set of supported properties per type. 563 4.1. Metadata Properties 565 4.1.1. @type 567 Type: "String" (mandatory). 569 Specifies the type which this object represents. This MUST be one of 570 the following values: 572 o "jsevent": a JSCalendar event (Section 2.1). 574 o "jstask": a JSCalendar task (Section 2.2). 576 o "jsgroup": a JSCalendar group (Section 2.3). 578 4.1.2. uid 580 Type: "String" (mandatory). 582 A globally unique identifier, used to associate the object as the 583 same across different systems, calendars and views. The value of 584 this property MUST be unique across all JSCalendar objects, even if 585 they are of different type. [RFC4122] describes a range of 586 established algorithms to generate universally unique identifiers 587 (UUID). UUID version 4, described in Section 4.4 of [RFC4122], is 588 RECOMMENDED. 590 For compatibility with [RFC5545] UIDs, implementations MUST be able 591 to receive and persist values of at least 255 octets for this 592 property, but they MUST NOT truncate values in the middle of a UTF-8 593 multi-octet sequence. 595 4.1.3. relatedTo 597 Type: "String[Relation]" (optional). 599 Relates the object to other JSCalendar objects. This is represented 600 as a map of the UIDs of the related objects to information about the 601 relation. 603 If an object is split to make a "this and future" change to a 604 recurrence, the original object MUST be truncated to end at the 605 previous occurrence before this split, and a new object created to 606 represent all the occurrences after the split. A "next" relation 607 MUST be set on the original object's relatedTo property for the UID 608 of the new object. A "first" relation for the UID of the first 609 object in the series MUST be set on the new object. Clients can then 610 follow these UIDs to get the complete set of objects if the user 611 wishes to modify them all at once. 613 4.1.4. prodId 615 Type: "String" (optional). 617 The identifier for the product that last updated the JSCalendar 618 object. This should be set whenever the data in the object is 619 modified (i.e., whenever the "updated" property is set). 621 The vendor of the implementation SHOULD ensure that this is a 622 globally unique identifier, using some technique such as an FPI 623 value, as defined in [ISO.9070.1991]. It MUST only use characters of 624 an iCalendar TEXT data value (see Section 3.3.11 of [RFC5545]). 626 This property SHOULD NOT be used to alter the interpretation of a 627 JSCalendar object beyond the semantics specified in this document. 628 For example, it is not to be used to further the understanding of 629 non-standard properties, a practice that is knows to cause long-term 630 interoperability problems. 632 4.1.5. created 634 Type: "UTCDateTime" (optional). 636 The date and time this object was initially created. 638 4.1.6. updated 640 Type: "UTCDateTime" (mandatory). 642 The date and time the data in this object was last modified (or its 643 creation date/time if not modified since). 645 4.1.7. sequence 647 Type: "UnsignedInt" (optional, default: 0). 649 Initially zero, this MUST be incremented by one every time a change 650 is made to the object, except if the change only modifies the 651 "participants" property (see Section 4.4.5). 653 This is used as part of iTIP [RFC5546] to know which version of the 654 object a scheduling message relates to. 656 4.1.8. method 658 Type: "String" (optional). 660 The iTIP [RFC5546] method, in lowercase. This MUST only be present 661 if the JSCalendar object represents an iTIP scheduling message. 663 4.2. What and Where Properties 665 4.2.1. title 667 Type: "String" (optional, default: empty String). 669 A short summary of the object. 671 4.2.2. description 673 Type: "String" (optional, default: empty String). 675 A longer-form text description of the object. The content is 676 formatted according to the "descriptionContentType" property. 678 4.2.3. descriptionContentType 680 Type: "String" (optional, default: "text/plain"). 682 Describes the media type [RFC6838] of the contents of the 683 "description" property. Media types MUST be sub-types of type 684 "text", and SHOULD be "text/plain" or "text/html" [MIME]. They MAY 685 include parameters and the "charset" parameter value MUST be "utf-8", 686 if specified. Descriptions of type "text/html" MAY contain "cid" 687 URLs [RFC2392] to reference links in the calendar object by use of 688 the "cid" property of the Link object. 690 4.2.4. showWithoutTime 692 Type: "Boolean" (optional, default: false). 694 Indicates that the time is not important to display to the user when 695 rendering this calendar object. An example of this is an event that 696 conceptually occurs all day or across multiple days, such as "New 697 Year's Day" or "Italy Vacation". While the time component is 698 important for free-busy calculations and checking for scheduling 699 clashes, calendars may choose to omit displaying it and/or display 700 the object separately to other objects to enhance the user's view of 701 their schedule. 703 Such events are also commonly known as "all-day" events. 705 4.2.5. locations 707 Type: "Id[Location]" (optional). 709 A map of location ids to Location objects, representing locations 710 associated with the object. 712 A Location object has the following properties. It MUST have at 713 least one property other than the "relativeTo" property. 715 o @type: "String" (mandatory) 717 Specifies the type of this object. This MUST be "Location". 719 o name: "String" (optional) 721 The human-readable name of the location. 723 o description: "String" (optional) 725 Human-readable, plain-text instructions for accessing this 726 location. This may be an address, set of directions, door access 727 code, etc. 729 o locationTypes: "String[Boolean]" (optional) 731 A set of one or more location types that describe this location. 732 All types MUST be from the Location Types Registry [LOCATIONTYPES] 733 as defined in [RFC4589]. The set is represented as a map, with 734 the keys being the location types. The value for each key in the 735 map MUST be true. 737 o relativeTo: "String" (optional) 739 Specifies the relation between this location and the time of the 740 JSCalendar object. This is primarily to allow events representing 741 travel to specify the location of departure (at the start of the 742 event) and location of arrival (at the end); this is particularly 743 important if these locations are in different time zones, as a 744 client may wish to highlight this information for the user. 746 This MUST be one of the following values, a value registered in 747 the IANA JSCalendar Enum Registry, or a vendor-specific value. 748 Any value the client or server doesn't understand should be 749 treated the same as if this property is omitted. 751 * "start": The event/task described by this JSCalendar object 752 occurs at this location at the time the event/task starts. 754 * "end": The event/task described by this JSCalendar object 755 occurs at this location at the time the event/task ends. 757 o timeZone: "String" (optional) 759 A time zone for this location. See also Section 1.4.9. 761 o coordinates: "String" (optional) 763 A "geo:" URI [RFC5870] for the location. 765 o linkIds: "Id[Boolean]" (optional) 766 A set of link ids for links to alternative representations of this 767 location. Each key in the set MUST be the id of a Link object 768 defined in the "links" property of this calendar object. The 769 value for each key in the set MUST be true. If there are no 770 links, this MUST be omitted (rather than specified as an empty 771 set). 773 For example, an alternative representation could be in vCard 774 format. 776 4.2.6. virtualLocations 778 Type: "Id[VirtualLocation]" (optional). 780 A map of ids to VirtualLocation objects, representing virtual 781 locations, such as video conferences or chat rooms, associated with 782 the object. 784 A VirtualLocation object has the following properties. 786 o @type: "String" (mandatory) 788 Specifies the type of this object. This MUST be 789 "VirtualLocation". 791 o name: "String" (optional, default: empty String) 793 The human-readable name of the virtual location. 795 o description: "String" (optional) 797 Human-readable plain-text instructions for accessing this 798 location. This may be an address, set of directions, door access 799 code, etc. 801 o uri: "String" (mandatory) 803 A URI that represents how to connect to this virtual location. 805 This may be a telephone number (represented using the "tel:" 806 scheme, e.g., "tel:+1-555-555-555") for a teleconference, a web 807 address for online chat, or any custom URI. 809 4.2.7. links 811 Type: "Id[Link]" (optional). 813 A map of link ids to Link objects, representing external resources 814 associated with the object. 816 A Link object has the following properties: 818 o @type: "String" (mandatory) 820 Specifies the type of this object. This MUST be "Link". 822 o href: "String" (mandatory) 824 A URI from which the resource may be fetched. 826 This MAY be a "data:" URL [RFC2397], but it is recommended that 827 the file be hosted on a server to avoid embedding arbitrarily 828 large data in JSCalendar object instances. 830 o cid: "String" (optional) 832 This MUST be a valid "content-id" value according to the 833 definition of Section 2 in [RFC2392]. The value MUST be unique 834 within this Link object but has no meaning beyond that. It MAY be 835 different from the link id for this Link object. 837 o contentType: "String" (optional) 839 The media type [RFC6838] of the resource, if known. 841 o size: "UnsignedInt" (optional) 843 The size, in octets, of the resource when fully decoded (i.e., the 844 number of octets in the file the user would download), if known. 845 Note that this is an informational estimate, and implementations 846 must be prepared to handle the actual size being quite different 847 when the resource is fetched. 849 o rel: "String" (optional) 851 Identifies the relation of the linked resource to the object. If 852 set, the value MUST be a relation type from the IANA registry 853 [LINKRELS], as established in [RFC8288]. 855 Links with a rel of "enclosure" MUST be considered by the client 856 as attachments for download. 858 Links with a rel of "describedby" MUST be considered by the client 859 to be an alternative representation of the description. 861 Links with a rel of "icon" MUST be considered by the client to be 862 an image that it may use when presenting the calendar data to a 863 user. The "display" property may be set to indicate the purpose 864 of this image. 866 o display: "String" (optional) 868 Describes the intended purpose of a link to an image. If set, the 869 "rel" property MUST be set to "icon". The value MUST be one of 870 the following values, a value registered in the IANA JSCalendar 871 Enum Registry, or a vendor-specific value: 873 * "badge": an image meant to be displayed alongside the title of 874 the object. 876 * "graphic": a full image replacement for the object itself. 878 * "fullsize": an image that is used to enhance the object. 880 * "thumbnail": a smaller variant of "fullsize" to be used when 881 space for the image is constrained. 883 o title: "String" (optional) 885 A human-readable plain-text description of the resource. 887 4.2.8. locale 889 Type: "String" (optional). 891 The language tag as defined in [RFC5646] that best describes the 892 locale used for the text in the calendar object, if known. 894 4.2.9. keywords 896 Type: "String[Boolean]" (optional). 898 A set of keywords or tags that relate to the object. The set is 899 represented as a map, with the keys being the keywords. The value 900 for each key in the map MUST be true. 902 4.2.10. categories 904 Type: "String[Boolean]" (optional). 906 A set of categories that relate to the calendar object. The set is 907 represented as a map, with the keys being the categories specified as 908 URIs. The value for each key in the map MUST be true. 910 In contrast to keywords, categories typically are structured. For 911 example, a vendor owning the domain "example.com" might define the 912 categories "http://example.com/categories/sports/american-football" 913 and "http://example.com/categories/music/r-b". 915 4.2.11. color 917 Type: "String" (optional). 919 A color clients MAY use when displaying this calendar object. The 920 value is a color name taken from the set of names defined in 921 Section 4.3 of CSS Color Module Level 3 [COLORS], or an RGB value in 922 hexadecimal notation, as defined in Section 4.2.1 of CSS Color Module 923 Level 3. 925 4.3. Recurrence Properties 927 Some events and tasks occur at regular or irregular intervals. 928 Rather than having to copy the data for every occurrence there can be 929 a master event with rules to generate recurrences, and/or overrides 930 that add extra dates or exceptions to the rules. 932 The recurrence set is the compelete set of instances for an object. 933 It is generated by considering the following properties in order, all 934 of which are optional: 936 1. The recurrenceRules property (Section 4.3.2) generates a set of 937 extra date-times on which the object occurs. 939 2. The excludedRecurrenceRules property (Section 4.3.3) generates a 940 set of date-times that are to be removed from the previously 941 generated set of date-times on which the object occurs. 943 3. The recurrenceOverrides property (Section 4.3.4) defines date- 944 times which are added or excluded to form the final set. (This 945 property may also contain changes to the object to apply to 946 particular instances.) 948 4.3.1. recurrenceId 950 Type: "LocalDateTime" (optional). 952 If present, this JSCalendar object represents one occurrence of a 953 recurring JSCalendar object. If present the "recurrenceRules" and 954 "recurrenceOverrides" properties MUST NOT be present. 956 The value is a date-time either produced by the "recurrenceRules" of 957 the master event, or added as a key to the "recurrenceOverrides" 958 property of the master event. 960 4.3.2. recurrenceRules 962 Type: "RecurrenceRule[]" (optional). 964 Defines a set of recurrence rules (repeating patterns) for recurring 965 calendar objects. 967 A JSEvent recurs by applying the recurrence rules to the "start" 968 date-time. 970 A JSTask recurs by applying the recurrence rules to the "start" date- 971 time, if defined, otherwise it recurs by the "due" date-time, if 972 defined. If the task defines neither a "start" nor "due" date-time, 973 it MUST NOT define a "recurrenceRules" property. 975 If multiple recurrence rules are given, each rule is to be applied 976 and then the union of the results used, ignoring any duplicates. 978 A RecurrenceRule object is a JSON object mapping of a RECUR value 979 type in iCalendar [RFC5545] [RFC7529] and has the same semantics. It 980 has the following properties: 982 o @type: "String" (mandatory) 984 Specifies the type of this object. This MUST be "RecurrenceRule". 986 o frequency: "String" (mandatory) 988 The time span covered by each iteration of this recurrence rule 989 (see Section 4.3.2.1 for full semantics). This MUST be one of the 990 following values: 992 * "yearly" 994 * "monthly" 996 * "weekly" 998 * "daily" 1000 * "hourly" 1002 * "minutely" 1003 * "secondly" 1005 This is the FREQ part from iCalendar, converted to lowercase. 1007 o interval: "UnsignedInt" (optional, default: 1) 1009 The interval of iteration periods at which the recurrence repeats. 1010 If included, it MUST be an integer >= 1. 1012 This is the INTERVAL part from iCalendar. 1014 o rscale: "String" (optional, default: "gregorian") 1016 The calendar system in which this recurrence rule operates, in 1017 lowercase. This MUST be either a CLDR-registered calendar system 1018 name [CLDR], or a vendor-specific value. 1020 This is the RSCALE part from iCalendar RSCALE [RFC7529], converted 1021 to lowercase. 1023 o skip: "String" (optional, default: "omit") 1025 The behaviour to use when the expansion of the recurrence produces 1026 invalid dates. This property only has an effect if the frequency 1027 is "yearly" or "monthly". It MUST be one of the following values: 1029 * "omit" 1031 * "backward" 1033 * "forward" 1035 This is the SKIP part from iCalendar RSCALE [RFC7529], converted 1036 to lowercase. 1038 o firstDayOfWeek: "String" (optional, default: "mo") 1040 The day on which the week is considered to start, represented as a 1041 lowercase abbreviated two-letter English day of the week. If 1042 included, it MUST be one of the following values: 1044 * "mo" 1046 * "tu" 1048 * "we" 1050 * "th" 1051 * "fr" 1053 * "sa" 1055 * "su" 1057 This is the WKST part from iCalendar. 1059 o byDay: "NDay[]" (optional) 1061 Days of the week on which to repeat. An "NDay" object has the 1062 following properties: 1064 * day: "String" (mandatory) 1066 A day of the week on which to repeat; the allowed values are 1067 the same as for the "firstDayOfWeek" RecurrenceRule property. 1069 This is the day-of-the-week of the BYDAY part in iCalendar, 1070 converted to lowercase. 1072 * nthOfPeriod: "Int" (optional) 1074 If present, rather than representing every occurrence of the 1075 weekday defined in the "day" property, it represents only a 1076 specific instance within the recurrence period. The value can 1077 be positive or negative, but MUST NOT be zero. A negative 1078 integer means nth-last of period. 1080 This is the ordinal part of the BYDAY value in iCalendar (e.g., 1081 1 or -3). 1083 o byMonthDay: "Int[]" (optional) 1085 Days of the month on which to repeat. Valid values are between 1 1086 and the maximum number of days any month may have in the calendar 1087 given by the "rscale" property, and the negative values of these 1088 numbers. For example, in the Gregorian calendar valid values are 1089 1 to 31 and -31 to -1. Negative values offset from the end of the 1090 month. The array MUST have at least one entry if included. 1092 This is the BYMONTHDAY part in iCalendar. 1094 o byMonth: "String[]" (optional) 1096 The months in which to repeat. Each entry is a string 1097 representation of a number, starting from "1" for the first month 1098 in the calendar (e.g., "1" means January with the Gregorian 1099 calendar), with an optional "L" suffix (see [RFC7529]) for leap 1100 months (this MUST be uppercase, e.g., "3L"). The array MUST have 1101 at least one entry if included. 1103 This is the BYMONTH part from iCalendar. 1105 o byYearDay: "Int[]" (optional) 1107 The days of the year on which to repeat. Valid values are between 1108 1 and the maximum number of days any year may have in the calendar 1109 given by the "rscale" property, and the negative values of these 1110 numbers. For example, in the Gregorian calendar valid values are 1111 1 to 366 and -366 to -1. Negative values offset from the end of 1112 the year. The array MUST have at least one entry if included. 1114 This is the BYYEARDAY part from iCalendar. 1116 o byWeekNo: "Int[]" (optional) 1118 Weeks of the year in which to repeat. Valid values are between 1 1119 and the maximum number of weeks any year may have in the calendar 1120 given by the "rscale" property, and the negative values of these 1121 numbers. For example, in the Gregorian calendar valid values are 1122 1 to 53 and -53 to -1. The array MUST have at least one entry if 1123 included. 1125 This is the BYWEEKNO part from iCalendar. 1127 o byHour: "UnsignedInt[]" (optional) 1129 The hours of the day in which to repeat. Valid values are 0 to 1130 23. The array MUST have at least one entry if included. This is 1131 the BYHOUR part from iCalendar. 1133 o byMinute: "UnsignedInt[]" (optional) 1135 The minutes of the hour in which to repeat. Valid values are 0 to 1136 59. The array MUST have at least one entry if included. 1138 This is the BYMINUTE part from iCalendar. 1140 o bySecond: "UnsignedInt[]" (optional) 1142 The seconds of the minute in which to repeat. Valid values are 0 1143 to 60. The array MUST have at least one entry if included. 1145 This is the BYSECOND part from iCalendar. 1147 o bySetPosition: "Int[]" (optional) 1149 The occurrences within the recurrence interval to include in the 1150 final results. Negative values offset from the end of the list of 1151 occurrences. The array MUST have at least one entry if included. 1152 This is the BYSETPOS part from iCalendar. 1154 o count: "UnsignedInt" (optional) 1156 The number of occurrences at which to range-bound the recurrence. 1157 This MUST NOT be included if an "until" property is specified. 1159 This is the COUNT part from iCalendar. 1161 o until: "LocalDateTime" (optional) 1163 The date-time at which to finish recurring. The last occurrence 1164 is on or before this date-time. This MUST NOT be included if a 1165 "count" property is specified. Note: if not specified otherwise 1166 for a specific JSCalendar object, this date is to be interpreted 1167 in the time zone specified in the JSCalendar object's "timeZone" 1168 property. 1170 This is the UNTIL part from iCalendar. 1172 4.3.2.1. Interpreting recurrence rules 1174 A recurrence rule specifies a set of date-times for recurring 1175 calendar objects. A recurrence rule has the following semantics. 1176 Note, wherever "year", "month" or "day of month" is used, this is 1177 within the calendar system given by the "rscale" property, which 1178 defaults to "gregorian" if omitted. 1180 1. A set of candidates is generated. This is every second within a 1181 period defined by the frequency property value: 1183 * "yearly": every second from midnight on the 1st day of a year 1184 (inclusive) to midnight the 1st day of the following year 1185 (exclusive). 1187 If skip is not "omit", the calendar system has leap months and 1188 there is a byMonth property, generate candidates for the leap 1189 months even if they don't occur in this year. 1191 If skip is not "omit" and there is a byMonthDay property, 1192 presume each month has the maximum number of days any month 1193 may have in this calendar system when generating candidates, 1194 even if it's more than this month actually has. 1196 * "monthly": every second from midnight on the 1st day of a 1197 month (inclusive) to midnight on the 1st of the following 1198 month (exclusive). 1200 If skip is not "omit" and there is a byMonthDay property, 1201 presume the month has the maximum number of days any month may 1202 have in this calendar system when generating candidates, even 1203 if it's more than this month actually has. 1205 * "weekly": every second from midnight (inclusive) on the first 1206 day of the week (as defined by the firstDayOfWeek property, or 1207 Monday if omitted), to midnight 7 days later (exclusive). 1209 * "daily": every second from midnight at the start of the day 1210 (inclusive) to midnight at the end of the day (exclusive). 1212 * "hourly": every second from the beginning of the hour 1213 (inclusive) to the beginning of the next hour (exclusive). 1215 * "minutely": every second from the beginning of the minute 1216 (inclusive) to the beginning of the next minute (exclusive). 1218 * "secondly": the second itself, only. 1220 2. Each date-time candidate is compared against all of the byX 1221 properties of the rule except bySetPosition. If any property in 1222 the rule does not match the date-time, it is eliminated. Each 1223 byX property is an array; the date-time matches the property if 1224 it matches any of the values in the array. The properties have 1225 the following semantics: 1227 * byMonth: the date-time is in the given month. 1229 * byWeekNo: the date-time is in the nth week of the year. 1230 Negative numbers mean the nth last week of the year. This 1231 corresponds to weeks according to week numbering as defined in 1232 ISO.8601.2004, with a week defined as a seven day period, 1233 starting on the firstDayOfWeek property value or Monday if 1234 omitted. Week number one of the calendar year is the first 1235 week that contains at least four days in that calendar year. 1237 If the date-time is not valid (this may happen when generating 1238 candidates with a skip property in effect), it is always 1239 eliminated by this property. 1241 * byYearDay: the date-time is on the nth day of year. Negative 1242 numbers mean the nth last day of the year. 1244 If the date-time is not valid (this may happen when generating 1245 candidates with a skip property in effect), it is always 1246 eliminated by this property. 1248 * byMonthDay: the date-time is on the given day of the month. 1249 Negative numbers mean the nth last day of the month. 1251 * byDay: the date-time is on the given day of the week. If the 1252 day is prefixed by a number, it is the nth occurrence of that 1253 day of the week within the month (if frequency is monthly) or 1254 year (if frequency is yearly). Negative numbers means nth 1255 last occurrence within that period. 1257 * byHour: the date-time has the given hour value. 1259 * byMinute: the date-time has the given minute value. 1261 * bySecond: the date-time has the given second value. 1263 If a skip property is defined and is not "omit", there may be 1264 candidates that do not correspond to valid dates (e.g., 31st 1265 February in the Gregorian calendar). In this case, the 1266 properties MUST be considered in the order above and: 1268 1. After applying the byMonth filter, if the candidate's month 1269 is invalid for the given year, increment it (if skip is 1270 "forward") or decrement it (if skip is "backward") until a 1271 valid month is found, incrementing/decrementing the year as 1272 well if passing through the beginning/end of the year. This 1273 only applies to calendar systems with leap months. 1275 2. After applying the byMonthDay filter, if the day of the month 1276 is invalid for the given month and year, change the date to 1277 the first day of the next month (if skip is "forward") or the 1278 last day of the current month (if skip is "backward"). 1280 3. If any valid date produced after applying the skip is already 1281 a candidate, eliminate the duplicate. (For example after 1282 adjusting, 30th February and 31st February would both become 1283 the same "real" date, so one is eliminated as a duplicate.) 1285 3. If a bySetPosition property is included, this is now applied to 1286 the ordered list of remaining dates. This property specifies the 1287 indexes of date-times to keep; all others should be eliminated. 1288 Negative numbers are indexes from the end of the list, with -1 1289 being the last item. 1291 4. Any date-times before the start date of the event are eliminated 1292 (see below for why this might be needed). 1294 5. If a skip property is included and is not "omit", eliminate any 1295 date-times that have already been produced by previous iterations 1296 of the algorithm. (This is not possible if skip is "omit".) 1298 6. If further dates are required (we have not reached the until 1299 date, or count limit) skip the next (interval - 1) sets of 1300 candidates, then continue from step 1. 1302 When determining the set of occurrence dates for an event or task, 1303 the following extra rules must be applied: 1305 1. The initial date-time to which the rule is applied (the "start" 1306 date-time for events; the "start" or "due" date-time for tasks) 1307 is always the first occurrence in the expansion (and is counted 1308 if the recurrence is limited by a "count" property), even if it 1309 would normally not match the rule. 1311 2. The first set of candidates to consider is that which would 1312 contain the initial date-time. This means the first set may 1313 include candidates before the initial date-time; such candidates 1314 are eliminated from the results in step (4) as outlined before. 1316 3. The following properties MUST be implicitly added to the rule 1317 under the given conditions: 1319 * If frequency is not "secondly" and no bySecond property: Add a 1320 bySecond property with the sole value being the seconds value 1321 of the initial date-time. 1323 * If frequency is not "secondly" or "minutely", and no byMinute 1324 property: Add a byMinute property with the sole value being 1325 the minutes value of the initial date-time. 1327 * If frequency is not "secondly", "minutely" or "hourly" and no 1328 byHour property: Add a byHour property with the sole value 1329 being the hours value of the initial date-time. 1331 * If frequency is "weekly" and no byDay property: Add a byDay 1332 property with the sole value being the day-of-the-week of the 1333 initial date-time. 1335 * If frequency is "monthly" and no byDay property and no 1336 byMonthDay property: Add a byMonthDay property with the sole 1337 value being the day-of-the-month of the initial date-time. 1339 * If frequency is "yearly" and no byYearDay property: 1341 + If there are no byMonth or byWeekNo properties, and either 1342 there is a byMonthDay property or there is no byDay 1343 property: Add a byMonth property with the sole value being 1344 the month of the initial date-time. 1346 + If there is no byMonthDay, byWeekNo or byDay properties: 1347 Add a byMonthDay property with the sole value being the 1348 day-of-the-month of the initial date-time. 1350 + If there is a byWeekNo property and no byMonthDay or byDay 1351 properties: Add a byDay property with the sole value being 1352 the day-of-the-week of the initial date-time. 1354 4.3.3. excludedRecurrenceRules 1356 Type: "RecurrenceRule[]" (optional). 1358 Defines a set of recurrence rules (repeating patterns) for date-times 1359 on which the object will not occur. The rules are interpreted the 1360 same as for the "recurrenceRules" property (see Section 4.3.2), with 1361 the exception that the initial date-time to which the rule is applied 1362 (the "start" date-time for events; the "start" or "due" date-time for 1363 tasks) is only considered part of the expansion if it matches the 1364 rule. The resulting set of date-times are then removed from those 1365 generated by the recurrenceRules property, as described in 1366 Section 4.3. 1368 4.3.4. recurrenceOverrides 1370 Type: "LocalDateTime[PatchObject]" (optional). 1372 A map of the recurrence ids (the date-time produced by the recurrence 1373 rule) to an object of patches to apply to the generated occurrence 1374 object. 1376 If the recurrence id does not match a date-time from the recurrence 1377 rule (or no rule is specified), it is to be treated as an additional 1378 occurrence (like an RDATE from iCalendar). The patch object may 1379 often be empty in this case. 1381 If the patch object defines the "excluded" property value to be true, 1382 then the recurring calendar object does not occur at the recurrence 1383 id date-time (like an EXDATE from iCalendar). Such a patch object 1384 MUST NOT patch any other property. 1386 By default, an occurrence inherits all properties from the main 1387 object except the start (or due) date-time, which is shifted to match 1388 the recurrence id LocalDateTime. However, individual properties of 1389 the occurrence can be modified by a patch, or multiple patches. It 1390 is valid to patch the "start" property value, and this patch takes 1391 precedence over the value generated from the recurrence id. Both the 1392 recurrence id as well as the patched "start" date-time may occur 1393 before the original JSCalendar object's "start" or "due" date. 1395 A pointer in the PatchObject MUST be ignored if it starts with one of 1396 the following prefixes: 1398 o @type 1400 o method 1402 o privacy 1404 o prodId 1406 o recurrenceId 1408 o recurrenceOverrides 1410 o recurrenceRules 1412 o relatedTo 1414 o replyTo 1416 o uid 1418 4.3.5. excluded 1420 Type: "Boolean" (optional, default: false). 1422 Defines if this object is an overridden, excluded instance of a 1423 recurring JSCalendar object (see Section 4.3.4). If this property 1424 value is true, this calendar object instance MUST be removed from the 1425 occurrence expansion. The absence of this property or its default 1426 value false indicates that this instance MUST be included in the 1427 occurrence expansion. 1429 4.4. Sharing and Scheduling Properties 1430 4.4.1. priority 1432 Type: "Int" (optional, default: 0). 1434 Specifies a priority for the calendar object. This may be used as 1435 part of scheduling systems to help resolve conflicts for a time 1436 period. 1438 The priority is specified as an integer in the range 0 to 9. A value 1439 of 0 specifies an undefined priority, for which the treatment will 1440 vary by situation. A value of 1 is the highest priority. A value of 1441 2 is the second highest priority. Subsequent numbers specify a 1442 decreasing ordinal priority. A value of 9 is the lowest priority. 1443 Other integer values are reserved for future use. 1445 4.4.2. freeBusyStatus 1447 Type: "String" (optional, default: "busy"). 1449 Specifies how this calendar object should be treated when calculating 1450 free-busy state. This MUST be one of the following values, a value 1451 registered in the IANA JSCalendar Enum Registry, or a vendor-specific 1452 value: 1454 o "free": The object should be ignored when calculating whether the 1455 user is busy. 1457 o "busy": The object should be included when calculating whether the 1458 user is busy. 1460 4.4.3. privacy 1462 Type: "String" (optional, default: "public"). 1464 Calendar objects are normally collected together and may be shared 1465 with other users. The privacy property allows the object owner to 1466 indicate that it should not be shared, or should only have the time 1467 information shared but the details withheld. Enforcement of the 1468 restrictions indicated by this property are up to the API via which 1469 this object is accessed. 1471 This property MUST NOT affect the information sent to scheduled 1472 participants; it is only interpreted when the object is shared as 1473 part of a shared calendar. 1475 The value MUST be one of the following values, a value registered in 1476 the IANA JSCalendar Enum Registry, or a vendor-specific value. Any 1477 value the client or server doesn't understand should be preserved but 1478 treated as equivalent to "private". 1480 o "public": The full details of the object are visible to those whom 1481 the object's calendar is shared with. 1483 o "private": The details of the object are hidden; only the basic 1484 time and metadata is shared. The following properties MAY be 1485 shared, any other properties MUST NOT be shared: 1487 * @type 1489 * created 1491 * due 1493 * duration 1495 * estimatedDuration 1497 * freeBusyStatus 1499 * privacy 1501 * recurrenceOverrides. Only patches which apply to another 1502 permissible property are allowed to be shared. 1504 * sequence 1506 * showWithoutTime 1508 * start 1510 * timeZone 1512 * timeZones 1514 * uid 1516 * updated 1518 o "secret": The object is hidden completely (as though it did not 1519 exist) when the calendar this object is in is shared. 1521 4.4.4. replyTo 1523 Type: "String[String]" (optional). 1525 Represents methods by which participants may submit their RSVP 1526 response to the organizer of the calendar object. The keys in the 1527 property value are the available methods and MUST only contain ASCII 1528 alphanumeric characters (A-Za-z0-9). The value is a URI for the 1529 method specified in the key. Future methods may be defined in future 1530 specifications and registered with IANA; a calendar client MUST 1531 ignore any method it does not understand, but MUST preserve the 1532 method key and URI. This property MUST be omitted if no method is 1533 defined (rather than being specified as an empty object). 1535 The following methods are defined: 1537 o "imip": The organizer accepts an iMIP [RFC6047] response at this 1538 email address. The value MUST be a "mailto:" URI. 1540 o "web": Opening this URI in a web browser will provide the user 1541 with a page where they can submit a reply to the organizer. 1543 o "other": The organizer is identified by this URI but the method 1544 for submitting the response is undefined. 1546 4.4.5. participants 1548 Type: "Id[Participant]" (optional). 1550 A map of participant ids to participants, describing their 1551 participation in the calendar object. 1553 If this property is set and any participant has a sendTo property, 1554 then the "replyTo" property of this calendar object MUST define at 1555 least one reply method. 1557 A Participant object has the following properties: 1559 o @type: "String" (mandatory) 1561 Specifies the type of this object. This MUST be "Participant". 1563 o name: "String" (optional) 1565 The display name of the participant (e.g., "Joe Bloggs"). 1567 o email: "String" (optional) 1568 The email address for the participant. 1570 o description: "String" (optional). 1572 A plain text description of this participant. For example, this 1573 may include more information about their role in the event or how 1574 best to contact them. 1576 o sendTo: "String[String]" (optional) 1578 Represents methods by which the participant may receive the 1579 invitation and updates to the calendar object. 1581 The keys in the property value are the available methods and MUST 1582 only contain ASCII alphanumeric characters (A-Za-z0-9). The value 1583 is a URI for the method specified in the key. Future methods may 1584 be defined in future specifications and registered with IANA; a 1585 calendar client MUST ignore any method it does not understand, but 1586 MUST preserve the method key and URI. This property MUST be 1587 omitted if no method is defined (rather than being specified as an 1588 empty object). 1590 The following methods are defined: 1592 * "imip": The participant accepts an iMIP [RFC6047] request at 1593 this email address. The value MUST be a "mailto:" URI. It MAY 1594 be different from the value of the participant's "email" 1595 property. 1597 * "other": The participant is identified by this URI but the 1598 method for submitting the invitation is undefined. 1600 o kind: "String" (optional) 1602 What kind of entity this participant is, if known. 1604 This MUST be one of the following values, a value registered in 1605 the IANA JSCalendar Enum Registry, or a vendor-specific value. 1606 Any value the client or server doesn't understand should be 1607 treated the same as if this property is omitted. 1609 * "individual": a single person 1611 * "group": a collection of people invited as a whole 1613 * "location": a physical location that needs to be scheduled, 1614 e.g., a conference room 1616 * "resource": a non-human resource other than a location, such as 1617 a projector 1619 o roles: "String[Boolean]" (mandatory) 1621 A set of roles that this participant fulfills. 1623 At least one role MUST be specified for the participant. The keys 1624 in the set MUST be one of the following values, a value registered 1625 in the IANA JSCalendar Enum Registry, or a vendor-specific value: 1627 * "owner": The participant is an owner of the object. This 1628 signifies they have permission to make changes to it that 1629 affect the other participants. Non-owner participants may only 1630 change properties that just affect themself (for example 1631 setting their own alerts or changing their rsvp status). 1633 * "attendee": The participant is expected to be present at the 1634 event. 1636 * "optional": The participant's involvement with the event is 1637 optional. This is expected to be primarily combined with the 1638 "attendee" role. 1640 * "informational": The participant is copied for informational 1641 reasons, and is not expected to attend. 1643 * "chair": The participant is in charge of the event/task when it 1644 occurs. 1646 * "contact": The participant is someone that may be contacted for 1647 information about the event. 1649 The value for each key in the set MUST be true. It is expected 1650 that no more than one of the roles "attendee" and "informational" 1651 be present; if more than one are given, "attendee" takes 1652 precedence over "informational". Roles that are unknown to the 1653 implementation MUST be preserved. 1655 o locationId: "String" (optional) 1657 The location at which this participant is expected to be 1658 attending. 1660 If the value does not correspond to any location id in the 1661 "locations" property of the JSCalendar object, this MUST be 1662 treated the same as if the participant's locationId were omitted. 1664 o language: "String" (optional) 1666 The language tag as defined in [RFC5646] that best describes the 1667 participant's preferred language, if known. 1669 o participationStatus: "String" (optional, default: "needs-action") 1671 The participation status, if any, of this participant. 1673 The value MUST be one of the following values, a value registered 1674 in the IANA JSCalendar Enum Registry, or a vendor-specific value: 1676 * "needs-action": No status yet set by the participant. 1678 * "accepted": The invited participant will participate. 1680 * "declined": The invited participant will not participate. 1682 * "tentative": The invited participant may participate. 1684 * "delegated": The invited participant has delegated their 1685 attendance to another participant, as specified in the 1686 delegatedTo property. 1688 o participationComment: "String" (optional) 1690 A note from the participant to explain their participation status. 1692 o expectReply: "Boolean" (optional, default: false) 1694 If true, the organizer is expecting the participant to notify them 1695 of their participation status. 1697 o scheduleAgent: "String" (optional, default: "server") 1699 Who is responsible for sending scheduling messages with this 1700 calendar object to the participant. 1702 The value MUST be one of the following values, a value registered 1703 in the IANA JSCalendar Enum Registry, or a vendor-specific value: 1705 * "server": The calendar server will send the scheduling 1706 messages. 1708 * "client": The calendar client will send the scheduling 1709 messages. 1711 * "none": No scheduling messages are to be sent to this 1712 participant. 1714 o scheduleForceSend: "Boolean" (optional, default: false) 1716 A client may set the property on a participant to true to request 1717 that the server send a scheduling message to the participant when 1718 it would not normally do so (e.g. if no significant change is made 1719 the object or the scheduleAgent is set to client). The property 1720 MUST NOT be stored in the JSCalendar object on the server or 1721 appear in a scheduling message. 1723 o scheduleSequence: "UnsignedInt" (optional, default: 0) 1725 The sequence number of the last response from the participant. If 1726 defined, this MUST be a non-negative integer. 1728 This can be used to determine whether the participant has sent a 1729 new RSVP following significant changes to the calendar object, and 1730 to determine if future responses are responding to a current or 1731 older view of the data. 1733 o scheduleStatus: "String[]" (optional) 1735 A list of status codes, as defined in Section 3.8.8.3 of 1736 [RFC5545], returned from the processing of the most recent 1737 scheduling message sent to this participant. 1739 Servers MUST only add or change this property when they send a 1740 scheduling message to the participant. Clients SHOULD NOT change 1741 or remove this property if it was provided by the server. Clients 1742 MAY add, change, or remove the property for participants where the 1743 client is handling the scheduling. 1745 This property MUST NOT be included in scheduling messages. 1747 o scheduleUpdated: "UTCDateTime" (optional) 1749 The timestamp for the most recent response from this participant. 1751 This is the "updated" property of the last response when using 1752 iTIP. It can be compared to the "updated" property in future 1753 responses to detect and discard older responses delivered out of 1754 order. 1756 o invitedBy: "String" (optional) 1757 The participant id of the participant who invited this one, if 1758 known. 1760 o delegatedTo: "String[Boolean]" (optional) 1762 A set of participant ids that this participant has delegated their 1763 participation to. Each key in the set MUST be the id of a 1764 participant. The value for each key in the set MUST be true. If 1765 there are no delegates, this MUST be omitted (rather than 1766 specified as an empty set). 1768 o delegatedFrom: "String[Boolean]" (optional) 1770 A set of participant ids that this participant is acting as a 1771 delegate for. Each key in the set MUST be the id of a 1772 participant. The value for each key in the set MUST be true. If 1773 there are no delegators, this MUST be omitted (rather than 1774 specified as an empty set). 1776 o memberOf: "String[Boolean]" (optional) 1778 A set of group participants that were invited to this calendar 1779 object, which caused this participant to be invited due to their 1780 membership in the group(s). Each key in the set MUST be the id of 1781 a participant. The value for each key in the set MUST be true. 1782 If there are no groups, this MUST be omitted (rather than 1783 specified as an empty set). 1785 o linkIds: "String[Boolean]" (optional) 1787 A set of links to more information about this participant, for 1788 example in vCard format. The keys in the set MUST be the id of a 1789 Link object in the calendar object's "links" property. The value 1790 for each key in the set MUST be true. If there are no links, this 1791 MUST be omitted (rather than specified as an empty set). 1793 o progress: "String" (optional; only allowed for participants of a 1794 JSTask). Represents the progress of the participant for this 1795 task. It MUST NOT be set if the "participationStatus" of this 1796 participant is any value other than "accepted". See Section 5.2.5 1797 for allowed values and semantics. 1799 o progressUpdated: "UTCDateTime" (optional; only allowed for 1800 participants of a JSTask). Specifies the date-time the progress 1801 property was last set on this participant. See Section 5.2.6 for 1802 allowed values and semantics. 1804 o percentComplete: "UnsignedInt" (optional; only allowed for 1805 participants of a JSTask). Represents the percent completion of 1806 the participant for this task. The property value MUST be a 1807 positive integer between 0 and 100. 1809 4.5. Alerts Properties 1811 4.5.1. useDefaultAlerts 1813 Type: "Boolean" (optional, default: false). 1815 If true, use the user's default alerts and ignore the value of the 1816 "alerts" property. Fetching user defaults is dependent on the API 1817 from which this JSCalendar object is being fetched, and is not 1818 defined in this specification. If an implementation cannot determine 1819 the user's default alerts, or none are set, it MUST process the 1820 alerts property as if "useDefaultAlerts" is set to false. 1822 4.5.2. alerts 1824 Type: "Id[Alert]" (optional). 1826 A map of alert ids to Alert objects, representing alerts/reminders to 1827 display or send to the user for this calendar object. 1829 An Alert Object has the following properties: 1831 o @type: "String" (mandatory) 1833 Specifies the type of this object. This MUST be "Alert". 1835 o trigger: "OffsetTrigger|AbsoluteTrigger|UnknownTrigger" 1836 (mandatory) 1838 Defines when to trigger the alert. New types may be defined in 1839 future documents. 1841 An "OffsetTrigger" object has the following properties: 1843 * @type: "String" (mandatory) 1845 Specifies the type of this object. This MUST be 1846 "OffsetTrigger". 1848 * offset: "SignedDuration" (mandatory). 1850 Defines the offset at which to trigger the alert relative to 1851 the time property defined in the "relativeTo" property of the 1852 alert. Negative durations signify alerts before the time 1853 property, positive durations signify alerts after. If the 1854 calendar object does not define a time zone, the user's default 1855 time zone SHOULD be used when determining the offset, if known. 1856 Otherwise, the time zone to use is implementation specific. 1858 * relativeTo: "String" (optional, default: "start") 1860 Specifies the time property that the alert offset is relative 1861 to. The value MUST be one of: 1863 + "start": triggers the alert relative to the start of the 1864 calendar object 1866 + "end": triggers the alert relative to the end/due time of 1867 the calendar object 1869 An "AbsoluteTrigger" object has the following properties: 1871 * @type: "String" (mandatory) 1873 Specifies the type of this object. This MUST be 1874 "AbsoluteTrigger". 1876 * when: "UTCDateTime" (mandatory). 1878 Defines a specific UTC date-time when the alert is triggered. 1880 An "UnknownTrigger" object is an object that contains a "@type" 1881 property whose value is not recognized (i.e., not "OffsetTrigger" 1882 or "AbsoluteTrigger"), plus zero or more other properties. This 1883 is for compatibility with client extensions and future 1884 specifications. Implementations SHOULD NOT trigger for trigger 1885 types they do not understand, but MUST preserve them. 1887 o acknowledged: "UTCDateTime" (optional) 1889 This records when an alert was last acknowledged. This is set 1890 when the user has dismissed the alert; other clients that sync 1891 this property SHOULD automatically dismiss or suppress duplicate 1892 alerts (alerts with the same alert id that triggered on or before 1893 this date-time). 1895 For a recurring calendar object, the "acknowledged" property of 1896 the parent object MUST be updated, unless the alert is already 1897 overridden in the "recurrenceOverrides" property. 1899 Certain kinds of alert action may not provide feedback as to when 1900 the user sees them, for example email based alerts. For those 1901 kinds of alerts, this property SHOULD be set immediately when the 1902 alert is triggered and the action successfully carried out. 1904 o relatedTo: "String[Relation]" (optional) 1906 Relates this alert to other alerts in the same JSCalendar object. 1907 If the user wishes to snooze an alert, the application SHOULD 1908 create an alert to trigger after snoozing. All snooze alerts 1909 SHOULD set a relation to the identifier of the original alert. 1910 The Relation object SHOULD set the "parent" relation type. 1912 o action: "String" (optional, default: "display") 1914 Describes how to alert the user. 1916 The value MUST be at most one of the following values, a value 1917 registered in the IANA JSCalendar Enum Registry, or a vendor- 1918 specific value: 1920 * "display": The alert should be displayed as appropriate for the 1921 current device and user context. 1923 * "email": The alert should trigger an email sent out to the 1924 user, notifying about the alert. This action is typically only 1925 appropriate for server implementations. 1927 4.6. Multilingual Properties 1929 4.6.1. localizations 1931 Type: "String[PatchObject]" (optional). 1933 A map of language tags [RFC5646] to patch objects, which localize the 1934 calendar object into the locale of the respective language tag. 1936 See the description of PatchObject (Section 1.4.8) for the structure 1937 of the PatchObject. The patches are applied to the top-level 1938 calendar object. In addition, the "locale" property of the patched 1939 object is set to the language tag. All pointers for patches MUST end 1940 with one of the following suffixes; any patch that does not follow 1941 this MUST be ignored unless otherwise specified in a future RFC: 1943 o title 1945 o description 1946 o name 1948 A patch MUST NOT have the prefix "recurrenceOverrides"; any 1949 localization of the override MUST be a patch to the localizations 1950 property inside the override instead. For example, a patch to 1951 "locations/abcd1234/title" is permissible, but a patch to "uid" or 1952 "recurrenceOverrides/2018-01-05T14:00:00/title" is not. 1954 Note that this specification does not define how to maintain validity 1955 of localized content. For example, a client application changing a 1956 JSCalendar object's title property might also need to update any 1957 localizations of this property. Client implementations SHOULD 1958 provide the means to manage localizations, but how to achieve this is 1959 specific to the application's workflow and requirements. 1961 4.7. Time Zone Properties 1963 4.7.1. timeZone 1965 Type: "String|null" (optional, default: null). 1967 Identifies the time zone the object is scheduled in, or null for 1968 floating time. This is either a name from the IANA Time Zone 1969 Database [TZDB] or the id of a custom time zone from the "timeZones" 1970 property (see Section 1.4.9). If omitted, this MUST be presumed to 1971 be null (i.e., floating time). 1973 4.7.2. timeZones 1975 Type: "String[TimeZone]" (optional). 1977 Maps identifiers of custom time zones to their time zone definitions. 1978 The following restrictions apply for each key in the map: 1980 o It MUST start with the "/" character (ASCII decimal 47; also see 1981 Sections 3.2.19 of [RFC5545] and 3.6. of [RFC7808] for discussion 1982 of the forward slash character in time zone identifiers). 1984 o It MUST be a valid "paramtext" value as specified in Section 3.1. 1985 of [RFC5545]. 1987 o At least one other property in the same JSCalendar object MUST 1988 reference a time zone using this identifier (i.e., orphaned time 1989 zones are not allowed). 1991 An identifier need only be unique to this JSCalendar object. A 1992 JSCalendar object may be part in a hierarchy of other JSCalendar 1993 objects (say, a JSEvent is an entry in a JSGroup). In this case, the 1994 set of time zones is the sum of the time zone definitions of this 1995 object and its parent objects. If multiple time zones with the same 1996 identifier exist, then the definition closest to the calendar object 1997 in relation to its parents MUST be used. (In context of JSEvent, a 1998 time zone definition in its timeZones property has precedence over a 1999 definition of the same id in the JSGroup). Time zone definitions in 2000 any children of the calendar object MUST be ignored. 2002 A TimeZone object maps a VTIMEZONE component from iCalendar [RFC5545] 2003 and the semantics are as defined there. A valid time zone MUST 2004 define at least one transition rule in the "standard" or "daylight" 2005 property. Its properties are: 2007 o @type: "String" (mandatory) 2009 Specifies the type of this object. This MUST be "TimeZone". 2011 o tzId: "String" (mandatory). 2013 The TZID property from iCalendar. 2015 o lastModified: "UTCDateTime" (optional) 2017 The LAST-MODIFIED property from iCalendar. 2019 o url: "String" (optional) 2021 The TZURL property from iCalendar. 2023 o validUntil: "UTCDateTime" (optional) 2025 The TZUNTIL property from iCalendar specified in [RFC7808]. 2027 o aliases: "String[Boolean]" (optional) 2029 Maps the TZID-ALIAS-OF properties from iCalendar specified in 2030 [RFC7808] to a JSON set of aliases. The set is represented as an 2031 object, with the keys being the aliases. The value for each key 2032 in the set MUST be true. 2034 o standard: "TimeZoneRule[]" (optional) 2036 The STANDARD sub-components from iCalendar. The order MUST be 2037 preserved during conversion. 2039 o daylight: "TimeZoneRule[]" (optional). 2041 The DAYLIGHT sub-components from iCalendar. The order MUST be 2042 preserved during conversion. 2044 A TimeZoneRule object maps a STANDARD or DAYLIGHT sub-component from 2045 iCalendar, with the restriction that at most one recurrence rule is 2046 allowed per rule. It has the following properties: 2048 o @type: "String" (mandatory) 2050 Specifies the type of this object. This MUST be "TimeZoneRule". 2052 o start: "LocalDateTime" (mandatory) 2054 The DTSTART property from iCalendar. 2056 o offsetTo: "String" (mandatory) 2058 The TZOFFSETTO property from iCalendar. 2060 o offsetFrom: "String" (mandatory) 2062 The TZOFFSETFROM property from iCalendar. 2064 o recurrenceRule: "RecurrenceRule" (optional) 2066 The RRULE property mapped as specified in Section 4.3.2. During 2067 recurrence rule evaluation, the "until" property value MUST be 2068 interpreted as a local time in the UTC time zone. 2070 o recurrenceDates: "LocalDateTime[Boolean]" (optional) 2072 Maps the RDATE properties from iCalendar to a JSON set. The set 2073 is represented as an object, with the keys being the recurrence 2074 dates. The value for each key in the set MUST be true. 2076 o names: "String[Boolean]" (optional) 2078 Maps the TZNAME properties from iCalendar to a JSON set. The set 2079 is represented as an object, with the keys being the names. The 2080 value for each key in the set MUST be true. 2082 o comments: "String[]" (optional). Maps the COMMENT properties from 2083 iCalendar. The order MUST be preserved during conversion. 2085 5. Type-specific JSCalendar Properties 2087 5.1. JSEvent Properties 2089 In addition to the common JSCalendar object properties (Section 4) a 2090 JSEvent has the following properties: 2092 5.1.1. start 2094 Type: "LocalDateTime" (mandatory). 2096 The date/time the event starts in the event's time zone (as specified 2097 in the "timeZone" property, see Section 4.7.1). 2099 5.1.2. duration 2101 Type: "Duration" (optional, default: "PT0S"). 2103 The zero or positive duration of the event in the event's start time 2104 zone. 2106 Note that a duration specified using weeks or days does not always 2107 correspond to an exact multiple of 24 hours. The number of 2108 hours/minutes/seconds may vary if it overlaps a period of 2109 discontinuity in the event's time zone, for example a change from 2110 standard time to daylight-savings time. Leap seconds MUST NOT be 2111 considered when computing an exact duration. When computing an exact 2112 duration, the greatest order time components MUST be added first, 2113 that is, the number of days MUST be added first, followed by the 2114 number of hours, number of minutes, and number of seconds. 2115 Fractional seconds MUST be added last. These semantics match the 2116 iCalendar DURATION value type ([RFC5545], Section 3.3.6). 2118 A JSEvent MAY involve start and end locations that are in different 2119 time zones (e.g., a trans-continental flight). This can be expressed 2120 using the "relativeTo" and "timeZone" properties of the JSEvent's 2121 Location objects (see Section 4.2.5). 2123 5.1.3. status 2125 Type: "String" (optional, default: "confirmed"). 2127 The scheduling status (Section 4.4) of a JSEvent. If set, it MUST be 2128 one of the following values, a value registered in the IANA 2129 JSCalendar Enum Registry, or a vendor-specific value: 2131 o "confirmed": Indicates the event is definitely happening. 2133 o "cancelled": Indicates the event has been cancelled. 2135 o "tentative": Indicates the event may happen. 2137 5.2. JSTask Properties 2139 In addition to the common JSCalendar object properties (Section 4) a 2140 JSTask has the following properties: 2142 5.2.1. due 2144 Type: "LocalDateTime" (optional). 2146 The date/time the task is due in the task's time zone. 2148 5.2.2. start 2150 Type: "LocalDateTime" (optional). 2152 The date/time the task should start in the task's time zone. 2154 5.2.3. estimatedDuration 2156 Type: "Duration" (optional). 2158 Specifies the estimated positive duration of time the task takes to 2159 complete. 2161 5.2.4. percentComplete 2163 Type: "UnsignedInt" (optional). 2165 Represents the percent completion of the task overall. The property 2166 value MUST be a positive integer between 0 and 100. 2168 5.2.5. progress 2170 Type: "String" (optional). 2172 Defines the progress of this task. If omitted, the default progress 2173 (Section 4.4) of a JSTask is defined as follows (in order of 2174 evaluation): 2176 o "completed": if the "progress" property value of all participants 2177 is "completed". 2179 o "failed": if at least one "progress" property value of a 2180 participant is "failed". 2182 o "in-process": if at least one "progress" property value of a 2183 participant is "in-process". 2185 o "needs-action": If none of the other criteria match. 2187 If set, it MUST be one of the following values, a value registered in 2188 the IANA JSCalendar Enum Registry, or a vendor-specific value: 2190 o "needs-action": Indicates the task needs action. 2192 o "in-process": Indicates the task is in process. 2194 o "completed": Indicates the task is completed. 2196 o "failed": Indicates the task failed. 2198 o "cancelled": Indicates the task was cancelled. 2200 5.2.6. progressUpdated 2202 Type: "UTCDateTime" (optional). 2204 Specifies the date/time the "progress" property of either the task 2205 overall (Section 5.2.5) or a specific participant (Section 4.4.5) was 2206 last updated. 2208 If the task is recurring and has future instances, a client may want 2209 to keep track of the last progress update timestamp of a specific 2210 task recurrence, but leave other instances unchanged. One way to 2211 achieve this is by overriding the progressUpdated property in the 2212 task "recurrenceOverrides" property. However, this could produce a 2213 long list of timestamps for regularly recurring tasks. An 2214 alternative approach is to split the JSTask into a current, single 2215 instance of JSTask with this instance progress update time and a 2216 future recurring instance. See also Section 4.1.3 on splitting. 2218 5.3. JSGroup Properties 2220 JSGroup supports the following common JSCalendar properties 2221 (Section 4): 2223 o @type 2225 o categories 2227 o color 2229 o created 2230 o description 2232 o descriptionContentType 2234 o keywords 2236 o links 2238 o locale 2240 o prodId 2242 o timeZones 2244 o title 2246 o updated 2248 o uid 2250 In addition, the following JSGroup-specific properties are supported: 2252 5.3.1. entries 2254 Type: "(JSTask|JSEvent)[]" (mandatory). 2256 A collection of group members. Implementations MUST ignore entries 2257 of unknown type. 2259 5.3.2. source 2261 Type: "String" (optional). 2263 The source from which updated versions of this group may be retrieved 2264 from. The value MUST be a URI. 2266 6. Examples 2268 The following examples illustrate several aspects of the JSCalendar 2269 data model and format. The examples may omit mandatory or additional 2270 properties, which is indicated by a placeholder property with key 2271 "...". While most of the examples use calendar event objects, they 2272 are also illustrative for tasks. 2274 6.1. Simple event 2276 This example illustrates a simple one-time event. It specifies a 2277 one-time event that begins on January 15, 2018 at 1pm New York local 2278 time and ends after 1 hour. 2280 { 2281 "@type": "jsevent", 2282 "uid": "2a358cee-6489-4f14-a57f-c104db4dc2f1", 2283 "updated": "2018-01-15T18:00:00Z", 2284 "title": "Some event", 2285 "start": "2018-01-15T13:00:00", 2286 "timeZone": "America/New_York", 2287 "duration": "PT1H" 2288 } 2290 6.2. Simple task 2292 This example illustrates a simple task for a plain to-do item. 2294 { 2295 "@type": "jstask", 2296 "uid": "2a358cee-6489-4f14-a57f-c104db4dc2f2", 2297 "updated": "2018-01-15T18:00:00Z", 2298 "title": "Do something" 2299 } 2301 6.3. Simple group 2303 This example illustrates a simple calendar object group that contains 2304 an event and a task. 2306 { 2307 "@type": "jsgroup", 2308 "uid": "2a358cee-6489-4f14-a57f-c104db4dc343", 2309 "updated": "2018-01-15T18:00:00Z", 2310 "name": "A simple group", 2311 "entries": [{ 2312 "@type": "jsevent", 2313 "uid": "2a358cee-6489-4f14-a57f-c104db4dc2f1", 2314 "updated": "2018-01-15T18:00:00Z", 2315 "title": "Some event", 2316 "start": "2018-01-15T13:00:00", 2317 "timeZone": "America/New_York", 2318 "duration": "PT1H" 2319 }, 2320 "2a358cee-6489-4f14-a57f-c104db4dc2f2": { 2321 "@type": "jstask", 2322 "uid": "2a358cee-6489-4f14-a57f-c104db4dc2f2", 2323 "updated": "2018-01-15T18:00:00Z", 2324 "title": "Do something" 2325 }] 2326 } 2328 6.4. All-day event 2330 This example illustrates an event for an international holiday. It 2331 specifies an all-day event on April 1 that occurs every year since 2332 the year 1900. 2334 { 2335 "...": "", 2336 "title": "April Fool's Day", 2337 "showWithoutTime": true, 2338 "start": "1900-04-01T00:00:00", 2339 "duration": "P1D", 2340 "recurrenceRules": [{ 2341 "@type": "RecurrenceRule", 2342 "frequency": "yearly" 2343 }] 2344 } 2346 6.5. Task with a due date 2348 This example illustrates a task with a due date. It is a reminder to 2349 buy groceries before 6pm Vienna local time on January 19, 2018. The 2350 calendar user expects to need 1 hour for shopping. 2352 { 2353 "...": "", 2354 "title": "Buy groceries", 2355 "due": "2018-01-19T18:00:00", 2356 "timeZone": "Europe/Vienna", 2357 "estimatedDuration": "PT1H" 2358 } 2360 6.6. Event with end time-zone 2362 This example illustrates the use of end time-zones by use of an 2363 international flight. The flight starts on April 1, 2018 at 9am in 2364 Berlin local time. The duration of the flight is scheduled at 10 2365 hours 30 minutes. The time at the flights destination is in the same 2366 time-zone as Tokyo. Calendar clients could use the end time-zone to 2367 display the arrival time in Tokyo local time and highlight the time- 2368 zone difference of the flight. The location names can serve as input 2369 for navigation systems. 2371 { 2372 "...": "", 2373 "title": "Flight XY51 to Tokyo", 2374 "start": "2018-04-01T09:00:00", 2375 "timeZone": "Europe/Berlin", 2376 "duration": "PT10H30M", 2377 "locations": { 2378 "2a358cee-6489-4f14-a57f-c104db4dc2f1": { 2379 "@type": "Location", 2380 "rel": "start", 2381 "name": "Frankfurt Airport (FRA)" 2382 }, 2383 "c2c7ac67-dc13-411e-a7d4-0780fb61fb08": { 2384 "@type": "Location", 2385 "rel": "end", 2386 "name": "Narita International Airport (NRT)", 2387 "timeZone": "Asia/Tokyo" 2388 } 2389 } 2390 } 2392 6.7. Floating-time event (with recurrence) 2394 This example illustrates the use of floating-time. Since January 1, 2395 2018, a calendar user blocks 30 minutes every day to practice Yoga at 2396 7am local time, in whatever time-zone the user is located on that 2397 date. 2399 { 2400 "...": "", 2401 "title": "Yoga", 2402 "start": "2018-01-01T07:00:00", 2403 "duration": "PT30M", 2404 "recurrenceRules": [{ 2405 "@type": "RecurrenceRule", 2406 "frequency": "daily" 2407 }] 2408 } 2410 6.8. Event with multiple locations and localization 2412 This example illustrates an event that happens at both a physical and 2413 a virtual location. Fans can see a live concert on premises or 2414 online. The event title and descriptions are localized. 2416 { 2417 "...": "", 2418 "title": "Live from Music Bowl: The Band", 2419 "description": "Go see the biggest music event ever!", 2420 "locale": "en", 2421 "start": "2018-07-04T17:00:00", 2422 "timeZone": "America/New_York", 2423 "duration": "PT3H", 2424 "locations": { 2425 "c0503d30-8c50-4372-87b5-7657e8e0fedd": { 2426 "@type": "Location", 2427 "name": "The Music Bowl", 2428 "description": "Music Bowl, Central Park, New York", 2429 "coordinates": "geo:40.7829,-73.9654" 2430 } 2431 }, 2432 "virtualLocations": { 2433 "6f3696c6-1e07-47d0-9ce1-f50014b0041a": { 2434 "@type": "VirtualLocation", 2435 "name": "Free live Stream from Music Bowl", 2436 "uri": "https://stream.example.com/the_band_2018" 2437 } 2438 }, 2439 "localizations": { 2440 "de": { 2441 "title": "Live von der Music Bowl: The Band!", 2442 "description": "Schau dir das groesste Musikereignis an!", 2443 "virtualLocations/6f3696c6-1e07-47d0-9ce1-f50014b0041a/name": 2444 "Gratis Live-Stream aus der Music Bowl" 2445 } 2446 } 2447 } 2449 6.9. Recurring event with overrides 2451 This example illustrates the use of recurrence overrides. A math 2452 course at a University is held for the first time on January 8, 2018 2453 at 9am London time and occurs every week until June 25, 2018. Each 2454 lecture lasts for one hour and 30 minutes and is located at the 2455 Mathematics department. This event has exceptional occurrences: at 2456 the last occurrence of the course is an exam, which lasts for 2 hours 2457 and starts at 10am. Also, the location of the exam differs from the 2458 usual location. On April 2 no course is held. On January 5 at 2pm 2459 is an optional introduction course, that occurs before the first 2460 regular lecture. 2462 { 2463 "...": "", 2464 "title": "Calculus I", 2465 "start": "2018-01-08T09:00:00", 2466 "timeZone": "Europe/London", 2467 "duration": "PT1H30M", 2468 "locations": { 2469 "2a358cee-6489-4f14-a57f-c104db4dc2f1": { 2470 "@type": "Location", 2471 "title": "Math lab room 1", 2472 "description": "Math Lab I, Department of Mathematics" 2473 } 2474 }, 2475 "recurrenceRules": [{ 2476 "@type": "RecurrenceRule", 2477 "frequency": "weekly", 2478 "until": "2018-06-25T09:00:00" 2479 }], 2480 "recurrenceOverrides": { 2481 "2018-01-05T14:00:00": { 2482 "title": "Introduction to Calculus I (optional)" 2483 }, 2484 "2018-04-02T09:00:00": { 2485 "excluded": "true" 2486 }, 2487 "2018-06-25T09:00:00": { 2488 "title": "Calculus I Exam", 2489 "start": "2018-06-25T10:00:00", 2490 "duration": "PT2H", 2491 "locations": { 2492 "2a358cee-6489-4f14-a57f-c104db4dc2f1": { 2493 "@type": "Location", 2494 "title": "Big Auditorium", 2495 "description": "Big Auditorium, Other Road" 2496 } 2497 } 2498 } 2499 } 2500 } 2502 6.10. Recurring event with participants 2504 This example illustrates scheduled events. A team meeting occurs 2505 every week since January 8, 2018 at 9am Johannesburg time. The event 2506 owner also chairs the event. Participants meet in a virtual meeting 2507 room. An attendee has accepted the invitation, but on March 8, 2018 2508 he is unavailable and declined participation for this occurrence. 2510 { 2511 "...": "", 2512 "title": "FooBar team meeting", 2513 "start": "2018-01-08T09:00:00", 2514 "timeZone": "Africa/Johannesburg", 2515 "duration": "PT1H", 2516 "virtualLocations": { 2517 "2a358cee-6489-4f14-a57f-c104db4dc2f1": { 2518 "@type": "VirtualLocation", 2519 "name": "ChatMe meeting room", 2520 "uri": "https://chatme.example.com?id=1234567" 2521 } 2522 }, 2523 "recurrenceRules": [{ 2524 "@type": "RecurrenceRule", 2525 "frequency": "weekly" 2526 }], 2527 "replyTo": { 2528 "imip": "mailto:6489-4f14-a57f-c1@schedule.example.com" 2529 }, 2530 "participants": { 2531 "dG9tQGZvb2Jhci5xlLmNvbQ": { 2532 "@type": "Participant", 2533 "name": "Tom Tool", 2534 "email": "tom@foobar.example.com", 2535 "sendTo": { 2536 "imip": "mailto:6489-4f14-a57f-c1@calendar.example.com" 2537 }, 2538 "participationStatus": "accepted", 2539 "roles": { 2540 "attendee": true 2541 } 2542 }, 2543 "em9lQGZvb2GFtcGxlLmNvbQ": { 2544 "@type": "Participant", 2545 "name": "Zoe Zelda", 2546 "email": "zoe@foobar.example.com", 2547 "sendTo": { 2548 "imip": "mailto:zoe@foobar.example.com" 2549 }, 2550 "participationStatus": "accepted", 2551 "roles": { 2552 "owner": true, 2553 "attendee": true, 2554 "chair": true 2555 } 2556 }, 2557 "...": "" 2559 }, 2560 "recurrenceOverrides": { 2561 "2018-03-08T09:00:00": { 2562 "participants/dG9tQGZvb2Jhci5xlLmNvbQ/participationStatus": 2563 "declined" 2564 } 2565 } 2566 } 2568 7. Security Considerations 2570 Calendaring and scheduling information is very privacy-sensitive. 2571 Its transmission must be done carefully to protect it from possible 2572 threats, such as eavesdropping, replay, message insertion, deletion, 2573 modification, and man-in-the-middle attacks. 2575 The data being stored and transmitted may be used in systems with 2576 real world consequences. For example, a home automation system may 2577 turn an alarm on and off. Or a coworking space may charge money to 2578 the organiser of an event that books one of their meeting rooms. 2579 Such systems must be careful to authenticate all data they receive to 2580 prevent them from being subverted. 2582 This document just defines the data format; such considerations are 2583 primarily the concern of the API or method of storage and 2584 transmission of such files. 2586 7.1. Expanding Recurrences 2588 A recurrence rule may produce infinite occurrences of an event. 2589 Implementations MUST handle expansions carefully to prevent 2590 accidental or deliberate resource exhaustion. 2592 Conversely, a recurrence rule may be specified that does not expand 2593 to anything. It is not always possible to tell this through static 2594 analysis of the rule, so implementations MUST be careful to avoid 2595 getting stuck in infinite loops, or otherwise exhausting resources 2596 while searching for the next occurrence. 2598 7.2. JSON Parsing 2600 The Security Considerations of [RFC8259] apply to the use of JSON as 2601 the data interchange format. 2603 As for any serialization format, parsers need to thoroughly check the 2604 syntax of the supplied data. JSON uses opening and closing tags for 2605 several types and structures, and it is possible that the end of the 2606 supplied data will be reached when scanning for a matching closing 2607 tag; this is an error condition, and implementations need to stop 2608 scanning at the end of the supplied data. 2610 JSON also uses a string encoding with some escape sequences to encode 2611 special characters within a string. Care is needed when processing 2612 these escape sequences to ensure that they are fully formed before 2613 the special processing is triggered, with special care taken when the 2614 escape sequences appear adjacent to other (non-escaped) special 2615 characters or adjacent to the end of data (as in the previous 2616 paragraph). 2618 If parsing JSON into a non-textual structured data format, 2619 implementations may need to allocate storage to hold JSON string 2620 elements. Since JSON does not use explicit string lengths, the risk 2621 of denial of service due to resource exhaustion is small, but 2622 implementations may still wish to place limits on the size of 2623 allocations they are willing to make in any given context, to avoid 2624 untrusted data causing excessive memory allocation. 2626 7.3. URI Values 2628 Several JSCalendar properties contain URIs as values, and processing 2629 these properties requires extra care. Section 7 of [RFC3986] 2630 discusses security risks related to URIs. 2632 A maliciously constructed JSCalendar object may contain a very large 2633 number of URIs. In the case of published calendars with a large 2634 number of subscribers, such objects could be widely distributed. 2635 Implementations should be careful to limit the automatic fetching of 2636 linked resources to reduce the risk of this being an amplification 2637 vector for a denial-of-service attack. 2639 7.4. Spam 2641 Calendar systems may receive JSCalendar files from untrusted sources, 2642 in particular as attachments to emails. This can be a vector for an 2643 attacker to inject spam into a user's calendar. This may confuse, 2644 annoy, and mislead users, or overwhelm their calendar with bogus 2645 events, preventing them from seeing legitimate ones. 2647 Heuristic, statistical or machine-learning-based filters can be 2648 effective in filtering out spam. Authentication mechanisms such as 2649 DKIM [RFC6376] can help establish the source of messages and 2650 associate the data with existing relationships (such as an address 2651 book contact). Misclassifications are always possible however, and 2652 providing a feedback mechanism for users to quickly correct this is 2653 advised. 2655 7.5. Duplication 2657 It is important for calendar systems to maintain the UID of an event 2658 when updating it to avoid unexpected duplication of events. When the 2659 UID changes, consumers of the data may not remove the previous 2660 version of the event if it has a different UID. This can lead to a 2661 confusing situation for the user, with many variations of the event 2662 and no indication of which one is correct. Care must be taken by 2663 consumers of the data to remove old events where possible to avoid an 2664 accidental denial-of-service attack due to the volume of data. 2666 7.6. Time Zones 2668 Events recur in a particular time zone. When this differs from the 2669 user's current time zone, it may unexpectedly cause an occurrence to 2670 shift in time for that user due to a daylight savings change in the 2671 event's time zone. A maliciously crafted event could attempt to 2672 confuse users with such an event to ensure a meeting is missed. 2674 8. IANA Considerations 2676 8.1. Media Type Registration 2678 This document defines a media type for use with JSCalendar data 2679 formatted in JSON. 2681 Type name: application 2683 Subtype name: jscalendar+json 2685 Required parameters: type 2687 The "type" parameter conveys the type of the JSCalendar data in 2688 the body part, with the value being one of "jsevent", "jstask", or 2689 "jsgroup". The parameter MUST NOT occur more than once. It MUST 2690 match the value of the "@type" property of the JSON-formatted 2691 JSCalendar object in the body. 2693 Optional parameters: none 2695 Encoding considerations: Same as encoding considerations of 2696 application/json as specified in RFC8529, Section 11 [RFC8259]. 2698 Security considerations: See Section 7 of this document. 2700 Interoperability considerations: This media type provides an 2701 alternative to iCalendar, jCal and proprietary JSON-based 2702 calendaring data formats. 2704 Published specification: This specification. 2706 Applications that use this media type: Applications that currently 2707 make use of the text/calendar and application/calendar+json media 2708 types can use this as an alternative. Similarly, applications 2709 that use the application/json media type to transfer calendaring 2710 data can use this to further specify the content. 2712 Fragment identifier considerations: N/A 2714 Additional information: 2716 Magic number(s): N/A 2718 File extensions(s): N/A 2720 Macintosh file type code(s): N/A 2722 Person & email address to contact for further information: 2723 calsify@ietf.org 2725 Intended usage: COMMON 2727 Restrictions on usage: N/A 2729 Author: See the "Author's Address" section of this document. 2731 Change controller: IETF 2733 8.2. Creation of "JSCalendar Properties" Registry 2735 The IANA will create the "JSCalendar Properties" registry to allow 2736 interoperability of extensions to JSCalendar objects. 2738 This registry follows the Expert Review process ([RFC8126], 2739 Section 4.5). If the "intended use" field is "common", sufficient 2740 documentation is required to enable interoperability. Preliminary 2741 community review for this registry is optional but strongly 2742 encouraged. 2744 A registration can have an intended use of "common", "reserved", or 2745 "obsolete". The IANA will list common-use registrations prominently 2746 and separately from those with other intended use values. 2748 A "reserved" registration reserves a property name without assigning 2749 semantics to avoid name collisions with future extensions or protocol 2750 use. 2752 An "obsolete" registration denotes a property that is no longer 2753 expected to be added by up-to-date systems. A new property has 2754 probably been defined covering the obsolete property's semantics. 2756 The JSCalendar property registration procedure is not a formal 2757 standards process but rather an administrative procedure intended to 2758 allow community comment and sanity checking without excessive time 2759 delay. It is designed to encourage vendors to document and register 2760 new properties they add for use cases not covered by the original 2761 standard, leading to increased interoperability. 2763 8.2.1. Preliminary Community Review 2765 Notice of a potential new registration SHOULD be sent to the Calext 2766 mailing list for review. This mailing list is 2767 appropriate to solicit community feedback on a proposed new property. 2769 Properties registrations must be marked with their intended use: 2770 "common", "reserved" or "obsolete". 2772 The intent of the public posting to this list is to solicit comments 2773 and feedback on the choice of the property name, the unambiguity of 2774 the specification document, and a review of any interoperability or 2775 security considerations. The submitter may submit a revised 2776 registration proposal or abandon the registration completely at any 2777 time. 2779 8.2.2. Submit Request to IANA 2781 Registration requests can be sent to . 2783 8.2.3. Designated Expert Review 2785 The primary concern of the designated expert (DE) is preventing name 2786 collisions and encouraging the submitter to document security and 2787 privacy considerations. For a common-use registration, the DE is 2788 expected to confirm that suitable documentation, as described in 2789 Section 4.6 of [RFC8126], is available to ensure interoperability. 2790 That documentation will usually be in an RFC, but simple definitions 2791 are likely to use a web/wiki page, and if a sentence or two is deemed 2792 sufficient it could be described in the registry itself. The DE 2793 should also verify that the property name does not conflict with work 2794 that is active or already published within the IETF. A published 2795 specification is not required for reserved or obsolete registrations. 2797 The DE will either approve or deny the registration request and 2798 publish a notice of the decision to the Calext WG mailing list or its 2799 successor, as well as inform IANA. A denial notice must be justified 2800 by an explanation, and, in the cases where it is possible, concrete 2801 suggestions on how the request can be modified so as to become 2802 acceptable should be provided. 2804 8.2.4. Change Procedures 2806 Once a JSCalendar property has been published by the IANA, the change 2807 controller may request a change to its definition. The same 2808 procedure that would be appropriate for the original registration 2809 request is used to process a change request. 2811 JSCalendar property registrations may not be deleted; properties that 2812 are no longer believed appropriate for use can be declared obsolete 2813 by a change to their "intended use" field; such properties will be 2814 clearly marked in the lists published by the IANA. 2816 Significant changes to a JSCalendar property's definition should be 2817 requested only when there are serious omissions or errors in the 2818 published specification, as such changes may cause interoperability 2819 issues. When review is required, a change request may be denied if 2820 it renders entities that were valid under the previous definition 2821 invalid under the new definition. 2823 The owner of a JSCalendar property may pass responsibility to another 2824 person or agency by informing the IANA; this can be done without 2825 discussion or review. 2827 8.2.5. JSCalendar Properties Registry Template 2829 o Property Name: The name of the property. The property name MUST 2830 NOT already be registered for any of the object types listed in 2831 the "Property Context" field of this registration. Other object 2832 types MAY already have registered a different property with the 2833 same name. 2835 o Property Type: The type of this property, using type signatures as 2836 specified in Section 1.3. The property type MUST be registed in 2837 the Type Registry. 2839 o Property Context: A comma-separated list of JSCalendar object 2840 types this property is allowed on. 2842 o Reference or Description: A brief description or RFC number and 2843 section reference where the property is specified (omitted for 2844 "reserved" property names). 2846 o Intended Use: Common, reserved, or obsolete. 2848 o Change Controller: ("IETF" for IETF-stream RFCs). 2850 8.2.6. Initial Contents for the JSCalendar Properties Registry 2852 The following table lists the initial entries of the JSCalendar 2853 Properties registry. All properties are for common-use. All RFC 2854 section references are for this document. The change controller for 2855 all these properties is "IETF". 2857 +---------------+----------------------------+------------+---------+ 2858 | Property Name | Property Type | Property | Referen | 2859 | | | Context | ce or D | 2860 | | | | escript | 2861 | | | | ion | 2862 +---------------+----------------------------+------------+---------+ 2863 | @type | String | JSEvent, | Section | 2864 | | | JSTask, | 4.1.1, | 2865 | | | JSGroup, A | Section | 2866 | | | bsoluteTri | 4.5.2, | 2867 | | | gger, | Section | 2868 | | | Alert, | 4.2.7, | 2869 | | | Link, | Section | 2870 | | | Location, | 4.2.5, | 2871 | | | OffsetTrig | Section | 2872 | | | ger, Parti | 4.4.5, | 2873 | | | cipant, Re | Section | 2874 | | | currenceRu | 4.3.2, | 2875 | | | le, | Section | 2876 | | | Relation, | 4.1.3, | 2877 | | | TimeZone, | Section | 2878 | | | VirtualLoc | 4.7.2, | 2879 | | | ation | Section | 2880 | | | | 4.2.6 | 2881 | | | | | 2882 | acknowledged | UTCDateTime | Alert | Section | 2883 | | | | 4.5.2 | 2884 | | | | | 2885 | action | String | Alert | Section | 2886 | | | | 4.5.2 | 2887 | | | | | 2888 | alerts | Id[Alert] | JSEvent, | Section | 2889 | | | JSTask | 4.5.2 | 2890 | | | | | 2891 | byDay | NDay[] | Recurrence | Section | 2892 | | | Rule | 4.3.2 | 2893 | | | | | 2894 | byHour | UnsignedInt[] | Recurrence | Section | 2895 | | | Rule | 4.3.2 | 2896 | | | | | 2897 | byMinute | UnsignedInt[] | Recurrence | Section | 2898 | | | Rule | 4.3.2 | 2899 | | | | | 2900 | byMonth | String[] | Recurrence | Section | 2901 | | | Rule | 4.3.2 | 2902 | | | | | 2903 | byMonthDay | Int[] | Recurrence | Section | 2904 | | | Rule | 4.3.2 | 2905 | | | | | 2906 | bySecond | UnsignedInt[] | Recurrence | Section | 2907 | | | Rule | 4.3.2 | 2908 | | | | | 2909 | bySetPosition | Int[] | Recurrence | Section | 2910 | | | Rule | 4.3.2 | 2911 | | | | | 2912 | byWeekNo | Int[] | Recurrence | Section | 2913 | | | Rule | 4.3.2 | 2914 | | | | | 2915 | byYearDay | Int[] | Recurrence | Section | 2916 | | | Rule | 4.3.2 | 2917 | | | | | 2918 | categories | String[Boolean] | JSEvent, | Section | 2919 | | | JSTask, | 4.2.10 | 2920 | | | JSGroup | | 2921 | | | | | 2922 | cid | String | Link | Section | 2923 | | | | 4.2.7 | 2924 | | | | | 2925 | color | String | JSEvent, | Section | 2926 | | | JSTask, | 4.2.11 | 2927 | | | JSGroup | | 2928 | | | | | 2929 | contentType | String | Link | Section | 2930 | | | | 4.2.7 | 2931 | | | | | 2932 | coordinates | String | Location | Section | 2933 | | | | 4.2.5 | 2934 | | | | | 2935 | count | UnsignedInt | Recurrence | Section | 2936 | | | Rule | 4.3.2 | 2937 | | | | | 2938 | created | UTCDateTime | JSEvent, | Section | 2939 | | | JSTask, | 4.1.5 | 2940 | | | JSGroup | | 2941 | | | | | 2942 | delegatedFrom | String[Boolean] | Participan | Section | 2943 | | | t | 4.4.5 | 2944 | | | | | 2945 | delegatedTo | String[Boolean] | Participan | Section | 2946 | | | t | 4.4.5 | 2947 | | | | | 2948 | description | String | JSEvent, | Section | 2949 | | | JSTask, | 4.2.2, | 2950 | | | Location, | Section | 2951 | | | Participan | 4.2.5, | 2952 | | | t, Virtual | Section | 2953 | | | Location | 4.4.5, | 2954 | | | | Section | 2955 | | | | 4.2.6 | 2956 | | | | | 2957 | descriptionCo | String | JSEvent, | Section | 2958 | ntentType | | JSTask | 4.2.3 | 2959 | | | | | 2960 | display | String | Link | Section | 2961 | | | | 4.2.7 | 2962 | | | | | 2963 | due | LocalDateTime | JSTask | Section | 2964 | | | | 5.2.1 | 2965 | | | | | 2966 | duration | Duration | JSEvent | Section | 2967 | | | | 5.1.2 | 2968 | | | | | 2969 | email | String | Participan | Section | 2970 | | | t | 4.4.5 | 2971 | | | | | 2972 | entries | (JSTask|JSEvent)[] | JSGroup | Section | 2973 | | | | 5.3.1 | 2974 | | | | | 2975 | estimatedDura | Duration | JSTask | Section | 2976 | tion | | | 5.2.3 | 2977 | | | | | 2978 | excluded | Boolean | JSEvent, | Section | 2979 | | | JSTask | 4.3.5 | 2980 | | | | | 2981 | excludedRecur | RecurrenceRule[] | JSEvent, | Section | 2982 | renceRules | | JSTask | 4.3.3 | 2983 | | | | | 2984 | expectReply | Boolean | Participan | Section | 2985 | | | t | 4.4.5 | 2986 | | | | | 2987 | firstDayOfWee | String | Recurrence | Section | 2988 | k | | Rule | 4.3.2 | 2989 | | | | | 2990 | freeBusyStatu | String | JSEvent, | Section | 2991 | s | | JSTask | 4.4.2 | 2992 | | | | | 2993 | frequency | String | Recurrence | Section | 2994 | | | Rule | 4.3.2 | 2995 | | | | | 2996 | href | String | Link | Section | 2997 | | | | 4.2.7 | 2998 | | | | | 2999 | interval | UnsignedInt | Recurrence | Section | 3000 | | | Rule | 4.3.2 | 3001 | | | | | 3002 | invitedBy | String | Participan | Section | 3003 | | | t | 4.4.5 | 3004 | | | | | 3005 | keywords | String[Boolean] | JSEvent, | Section | 3006 | | | JSTask, | 4.2.9 | 3007 | | | JSGroup | | 3008 | | | | | 3009 | kind | String | Participan | Section | 3010 | | | t | 4.4.5 | 3011 | | | | | 3012 | language | String | Participan | Section | 3013 | | | t | 4.4.5 | 3014 | | | | | 3015 | linkIds | Id[Boolean] | Location, | Section | 3016 | | | Participan | 4.2.5, | 3017 | | | t | Section | 3018 | | | | 4.4.5 | 3019 | | | | | 3020 | links | Id[Link] | JSGroup, | Section | 3021 | | | JSEvent, | 4.2.7 | 3022 | | | JSTask | | 3023 | | | | | 3024 | locale | String | JSGroup, | Section | 3025 | | | JSEvent, | 4.2.7 | 3026 | | | JSTask | | 3027 | | | | | 3028 | localizations | String[PatchObject] | JSEvent, | Section | 3029 | | | JSTask | 4.6.1 | 3030 | | | | | 3031 | locationId | String | Participan | Section | 3032 | | | t | 4.4.5 | 3033 | | | | | 3034 | locations | Id[Location] | JSEvent, | Section | 3035 | | | JSTask | 4.2.5 | 3036 | | | | | 3037 | locationTypes | String[Boolean] | Location | Section | 3038 | | | | 4.2.5 | 3039 | | | | | 3040 | memberOf | String[Boolean] | Participan | Section | 3041 | | | t | 4.4.5 | 3042 | | | | | 3043 | method | String | JSEvent, | Section | 3044 | | | JSTask | 4.1.8 | 3045 | | | | | 3046 | name | String | Location, | Section | 3047 | | | VirtualLoc | 4.2.5, | 3048 | | | ation, Par | Section | 3049 | | | ticipant | 4.2.6, | 3050 | | | | Section | 3051 | | | | 4.4.5 | 3052 | | | | | 3053 | offset | SignedDuration | OffsetTrig | Section | 3054 | | | ger | 4.5.2 | 3055 | | | | | 3056 | participants | Id[Participant] | JSEvent, | Section | 3057 | | | JSTask | 4.4.5 | 3058 | | | | | 3059 | participation | String | Participan | Section | 3060 | Comment | | t | 4.4.5 | 3061 | | | | | 3062 | participation | String | Participan | Section | 3063 | Status | | t | 4.4.5 | 3064 | | | | | 3065 | percentComple | UnsignedInt | JSTask, Pa | Section | 3066 | te | | rticipant | 5.2.4 | 3067 | | | | | 3068 | priority | Int | JSEvent, | Section | 3069 | | | JSTask | 4.4.1 | 3070 | | | | | 3071 | privacy | String | JSEvent, | Section | 3072 | | | JSTask | 4.4.3 | 3073 | | | | | 3074 | prodId | String | JSEvent, | Section | 3075 | | | JSTask, | 4.1.4 | 3076 | | | JSGroup | | 3077 | | | | | 3078 | progress | String | JSTask, Pa | Section | 3079 | | | rticipant | 5.2.5 | 3080 | | | | | 3081 | progressUpdat | UTCDateTime | JSTask, Pa | Section | 3082 | ed | | rticipant | 5.2.6 | 3083 | | | | | 3084 | recurrenceId | LocalDateTime | JSEvent, | Section | 3085 | | | JSTask | 4.3.1 | 3086 | | | | | 3087 | recurrenceOve | LocalDateTime[PatchObject] | JSEvent, | Section | 3088 | rrides | | JSTask | 4.3.4 | 3089 | | | | | 3090 | recurrenceRul | RecurrenceRule[] | JSEvent, | Section | 3091 | es | | JSTask | 4.3.2 | 3092 | | | | | 3093 | rel | String | Link | Section | 3094 | | | | 4.2.7 | 3095 | | | | | 3096 | relatedTo | String[Relation] | JSEvent, | Section | 3097 | | | JSTask, | 4.1.3, | 3098 | | | Alert | Section | 3099 | | | | 4.5.2 | 3100 | | | | | 3101 | relation | String[Boolean] | Relation | Section | 3102 | | | | 1.4.10 | 3103 | | | | | 3104 | relativeTo | String | OffsetTrig | Section | 3105 | | | ger, | 4.5.2, | 3106 | | | Location | Section | 3107 | | | | 4.2.5 | 3108 | | | | | 3109 | replyTo | String[String] | JSEvent, | Section | 3110 | | | JSTask | 4.4.4 | 3111 | | | | | 3112 | roles | String[Boolean] | Participan | Section | 3113 | | | t | 4.4.5 | 3114 | | | | | 3115 | rscale | String | Recurrence | Section | 3116 | | | Rule | 4.3.2 | 3117 | | | | | 3118 | scheduleAgent | String | Participan | Section | 3119 | | | t | 4.4.5 | 3120 | | | | | 3121 | scheduleForce | Boolean | Participan | Section | 3122 | Send | | t | 4.4.5 | 3123 | | | | | 3124 | scheduleSeque | UnsignedInt | Participan | Section | 3125 | nce | | t | 4.4.5 | 3126 | | | | | 3127 | scheduleStatu | String[] | Participan | Section | 3128 | s | | t | 4.4.5 | 3129 | | | | | 3130 | scheduleUpdat | UTCDateTime | Participan | Section | 3131 | ed | | t | 4.4.5 | 3132 | | | | | 3133 | sendTo | String[String] | Participan | Section | 3134 | | | t | 4.4.5 | 3135 | | | | | 3136 | sequence | UnsignedInt | JSEvent, | Section | 3137 | | | JSTask | 4.1.7 | 3138 | | | | | 3139 | showWithoutTi | Boolean | JSEvent, | Section | 3140 | me | | JSTask | 4.2.4 | 3141 | | | | | 3142 | size | UnsignedInt | Link | Section | 3143 | | | | 4.2.7 | 3144 | | | | | 3145 | skip | String | Recurrence | Section | 3146 | | | Rule | 4.3.2 | 3147 | | | | | 3148 | source | String | JSGroup | Section | 3149 | | | | 5.3.2 | 3150 | | | | | 3151 | start | LocalDateTime | JSEvent, | Section | 3152 | | | JSTask | 5.1.1, | 3153 | | | | Section | 3154 | | | | 5.2.2 | 3155 | | | | | 3156 | status | String | JSEvent | Section | 3157 | | | | 5.1.3 | 3158 | | | | | 3159 | timeZone | String|null | JSEvent, | Section | 3160 | | | JSTask, | 4.7.1, | 3161 | | | Location | Section | 3162 | | | | 4.2.5 | 3163 | | | | | 3164 | timeZones | String[TimeZone] | JSEvent, | Section | 3165 | | | JSTask | 4.7.2 | 3166 | | | | | 3167 | title | String | JSEvent, | Section | 3168 | | | JSTask, | 4.2.1 | 3169 | | | JSGroup, | | 3170 | | | Link | | 3171 | | | | | 3172 | trigger | OffsetTrigger|AbsoluteTrig | Alert | Section | 3173 | | ger|UnknownTrigger | | 4.5.2 | 3174 | | | | | 3175 | uid | String | JSEvent, | Section | 3176 | | | JSTask, | 4.1.2 | 3177 | | | JSGroup | | 3178 | | | | | 3179 | until | LocalDateTime | Recurrence | Section | 3180 | | | Rule | 4.3.2 | 3181 | | | | | 3182 | updated | UTCDateTime | JSEvent, | Section | 3183 | | | JSTask, | 4.1.6 | 3184 | | | JSGroup | | 3185 | | | | | 3186 | uri | String | VirtualLoc | Section | 3187 | | | ation | 4.2.6 | 3188 | | | | | 3189 | useDefaultAle | Boolean | JSEvent, | Section | 3190 | rts | | JSTask | 4.5.1 | 3191 | | | | | 3192 | virtualLocati | Id[VirtualLocation] | JSEvent, | Section | 3193 | ons | | JSTask | 4.2.6 | 3194 | | | | | 3195 | when | UTCDateTime | AbsoluteTr | Section | 3196 | | | igger | 4.5.2 | 3197 +---------------+----------------------------+------------+---------+ 3199 Table 1 3201 8.3. Creation of "JSCalendar Types" Registry 3203 The IANA will create the "JSCalendar Types" registry to avoid name 3204 collisions and provide a complete reference for all data types used 3205 for JSCalendar property values. The registration process is the same 3206 as for the JSCalendar Properties registry, as defined in Section 8.2. 3208 8.3.1. JSCalendar Types Registry Template 3210 o Type Name: The name of the type. 3212 o Reference or Description: A brief description or RFC number and 3213 section reference where the Type is specified (may be omitted for 3214 "reserved" type names). 3216 o Intended Use: Common, reserved, or obsolete. 3218 o Change Controller: ("IETF" for IETF-stream RFCs). 3220 8.3.2. Initial Contents for the JSCalendar Types Registry 3222 The following table lists the initial entries of the JSCalendar Types 3223 registry. All properties are for common-use. All RFC section 3224 references are for this document. The change controller for all 3225 these properties is "IETF". 3227 +-----------------+--------------------------+ 3228 | Type Name | Reference or Description | 3229 +-----------------+--------------------------+ 3230 | Alert | Section 4.5.2 | 3231 | | | 3232 | Boolean | Section 1.3 | 3233 | | | 3234 | Duration | Section 1.4.5 | 3235 | | | 3236 | Id | Section 1.4.7 | 3237 | | | 3238 | Int | Section 1.4.1 | 3239 | | | 3240 | LocalDateTime | Section 1.4.4 | 3241 | | | 3242 | Link | Section 4.2.7 | 3243 | | | 3244 | Location | Section 4.2.5 | 3245 | | | 3246 | Number | Section 1.3 | 3247 | | | 3248 | Participant | Section 4.4.5 | 3249 | | | 3250 | PatchObject | Section 1.4.8 | 3251 | | | 3252 | RecurrenceRule | Section 4.3.2 | 3253 | | | 3254 | Relation | Section 1.4.10 | 3255 | | | 3256 | SignedDuration | Section 1.4.6 | 3257 | | | 3258 | String | Section 1.3 | 3259 | | | 3260 | TimeZone | Section 4.7.2 | 3261 | | | 3262 | TimeZoneRule | Section 4.7.2 | 3263 | | | 3264 | UnsignedInt | Section 1.4.2 | 3265 | | | 3266 | UTCDateTime | Section 1.4.3 | 3267 | | | 3268 | VirtualLocation | Section 4.2.6 | 3269 +-----------------+--------------------------+ 3271 Table 2 3273 8.4. Creation of "JSCalendar Enum Values" Registry 3275 The IANA will create the "JSCalendar Enum Values" registry to allow 3276 interoperable extension of semantics for properties with enumerable 3277 values. Each such property will have a subregistry of allowed 3278 values. The registration process for a new enum value or adding a 3279 new enumerable property is the same as for the JSCalendar Properties 3280 registry, as defined in Section 8.2. 3282 8.4.1. JSCalendar Enum Property Template 3284 This template is for adding a subregistry for a new enumerable 3285 property to the JSCalendar Enum registry. 3287 o Registry Name: This MUST be of the form "Enum Values for 3288 {property-name} (Context: {context})" where: 3290 {property-name} is the name(s) of the property or properties where 3291 these values may be used. This MUST be registered in the 3292 JSCalendar Properties registry. 3294 {context} is the list of allowed object types where the property 3295 or properties may appear, as registered in the JSCalendar 3296 Properties registry. This disambiguates where there may be two 3297 distinct properties with the same name in different contexts. 3299 o Change Controller: ("IETF" for properties defined in IETF-stream 3300 RFCs). 3302 o Initial Contents: The initial list of defined values for this 3303 enum, using the template defined in Section 8.4.2. 3305 8.4.2. JSCalendar Enum Value Template 3307 This template is for adding a new enum value to a subregistry in the 3308 JSCalendar Enum registry. 3310 o Enum Value: The verbatim value of the enum. 3312 o Reference or Description: A brief description or RFC number and 3313 section reference for the semantics of this value. 3315 8.4.3. Initial Contents for the JSCalendar Enum Registry 3317 For each subregistry created in this section, all RFC section 3318 references are for this document and the change controller is IETF. 3320 ------------------------------------------------------------ 3321 Enum Values for action (Context: Alert) 3323 +------------+--------------------------+ 3324 | Enum Value | Reference or Description | 3325 +------------+--------------------------+ 3326 | display | Section 4.5.2 | 3327 | | | 3328 | email | Section 4.5.2 | 3329 +------------+--------------------------+ 3331 Table 3 3333 ------------------------------------------------------------ 3335 Enum Values for display (Context: Link) 3337 +------------+--------------------------+ 3338 | Enum Value | Reference or Description | 3339 +------------+--------------------------+ 3340 | badge | Section 4.2.7 | 3341 | | | 3342 | graphic | Section 4.2.7 | 3343 | | | 3344 | fullsize | Section 4.2.7 | 3345 | | | 3346 | thumbnail | Section 4.2.7 | 3347 +------------+--------------------------+ 3349 Table 4 3351 ------------------------------------------------------------ 3353 Enum Values for freeBusyStatus (Context: JSEvent, JSTask) 3355 +------------+--------------------------+ 3356 | Enum Value | Reference or Description | 3357 +------------+--------------------------+ 3358 | free | Section 4.4.2 | 3359 | | | 3360 | busy | Section 4.4.2 | 3361 +------------+--------------------------+ 3363 Table 5 3365 ------------------------------------------------------------ 3367 Enum Values for kind (Context: Participant) 3368 +------------+--------------------------+ 3369 | Enum Value | Reference or Description | 3370 +------------+--------------------------+ 3371 | individual | Section 4.4.5 | 3372 | | | 3373 | group | Section 4.4.5 | 3374 | | | 3375 | resource | Section 4.4.5 | 3376 | | | 3377 | location | Section 4.4.5 | 3378 +------------+--------------------------+ 3380 Table 6 3382 ------------------------------------------------------------ 3384 Enum Values for participationStatus (Context: Participant) 3386 +--------------+--------------------------+ 3387 | Enum Value | Reference or Description | 3388 +--------------+--------------------------+ 3389 | needs-action | Section 4.4.5 | 3390 | | | 3391 | accepted | Section 4.4.5 | 3392 | | | 3393 | declined | Section 4.4.5 | 3394 | | | 3395 | tenative | Section 4.4.5 | 3396 | | | 3397 | delegated | Section 4.4.5 | 3398 +--------------+--------------------------+ 3400 Table 7 3402 ------------------------------------------------------------ 3404 Enum Values for privacy (Context: JSEvent, JSTask) 3405 +------------+--------------------------+ 3406 | Enum Value | Reference or Description | 3407 +------------+--------------------------+ 3408 | public | Section 4.4.3 | 3409 | | | 3410 | private | Section 4.4.3 | 3411 | | | 3412 | secret | Section 4.4.3 | 3413 +------------+--------------------------+ 3415 Table 8 3417 ------------------------------------------------------------ 3419 Enum Values for progress (Context: JSTask, Participant) 3421 +--------------+--------------------------+ 3422 | Enum Value | Reference or Description | 3423 +--------------+--------------------------+ 3424 | needs-action | Section 5.2.5 | 3425 | | | 3426 | in-process | Section 5.2.5 | 3427 | | | 3428 | completed | Section 5.2.5 | 3429 | | | 3430 | failed | Section 5.2.5 | 3431 | | | 3432 | cancelled | Section 5.2.5 | 3433 +--------------+--------------------------+ 3435 Table 9 3437 ------------------------------------------------------------ 3439 Enum Values for relation (Context: Relation) 3440 +------------+--------------------------+ 3441 | Enum Value | Reference or Description | 3442 +------------+--------------------------+ 3443 | first | Section 1.4.10 | 3444 | | | 3445 | next | Section 1.4.10 | 3446 | | | 3447 | child | Section 1.4.10 | 3448 | | | 3449 | parent | Section 1.4.10 | 3450 +------------+--------------------------+ 3452 Table 10 3454 ------------------------------------------------------------ 3456 Enum Values for relativeTo (Context: OffsetTrigger, Location) 3458 +------------+--------------------------+ 3459 | Enum Value | Reference or Description | 3460 +------------+--------------------------+ 3461 | start | Section 4.5.2 | 3462 | | | 3463 | end | Section 4.5.2 | 3464 +------------+--------------------------+ 3466 Table 11 3468 ------------------------------------------------------------ 3470 Enum Values for roles (Context: Participant) 3471 +---------------+--------------------------+ 3472 | Enum Value | Reference or Description | 3473 +---------------+--------------------------+ 3474 | owner | Section 4.4.5 | 3475 | | | 3476 | attendee | Section 4.4.5 | 3477 | | | 3478 | optional | Section 4.4.5 | 3479 | | | 3480 | informational | Section 4.4.5 | 3481 | | | 3482 | chair | Section 4.4.5 | 3483 | | | 3484 | contact | Section 4.4.5 | 3485 +---------------+--------------------------+ 3487 Table 12 3489 ------------------------------------------------------------ 3491 Enum Values for scheduleAgent (Context: Participant) 3493 +------------+--------------------------+ 3494 | Enum Value | Reference or Description | 3495 +------------+--------------------------+ 3496 | server | Section 4.4.5 | 3497 | | | 3498 | client | Section 4.4.5 | 3499 | | | 3500 | none | Section 4.4.5 | 3501 +------------+--------------------------+ 3503 Table 13 3505 ------------------------------------------------------------ 3507 Enum Values for status (Context: JSEvent) 3508 +------------+--------------------------+ 3509 | Enum Value | Reference or Description | 3510 +------------+--------------------------+ 3511 | confirmed | Section 5.1.3 | 3512 | | | 3513 | cancelled | Section 5.1.3 | 3514 | | | 3515 | tentative | Section 5.1.3 | 3516 +------------+--------------------------+ 3518 Table 14 3520 9. Acknowledgments 3522 The authors would like to thank the members of CalConnect for their 3523 valuable contributions. This specification originated from the work 3524 of the API technical committee of CalConnect, the Calendaring and 3525 Scheduling Consortium. 3527 10. References 3529 10.1. Normative References 3531 [CLDR] "Unicode Common Locale Data Repository", 3532 . 3534 [COLORS] "CSS Color Module", . 3536 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3537 Requirement Levels", BCP 14, RFC 2119, 3538 DOI 10.17487/RFC2119, March 1997, 3539 . 3541 [RFC2392] Levinson, E., "Content-ID and Message-ID Uniform Resource 3542 Locators", RFC 2392, DOI 10.17487/RFC2392, August 1998, 3543 . 3545 [RFC2397] Masinter, L., "The "data" URL scheme", RFC 2397, 3546 DOI 10.17487/RFC2397, August 1998, 3547 . 3549 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 3550 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 3551 . 3553 [RFC4589] Schulzrinne, H. and H. Tschofenig, "Location Types 3554 Registry", RFC 4589, DOI 10.17487/RFC4589, July 2006, 3555 . 3557 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 3558 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 3559 . 3561 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 3562 Specifications: ABNF", STD 68, RFC 5234, 3563 DOI 10.17487/RFC5234, January 2008, 3564 . 3566 [RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and 3567 Scheduling Core Object Specification (iCalendar)", 3568 RFC 5545, DOI 10.17487/RFC5545, September 2009, 3569 . 3571 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 3572 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 3573 September 2009, . 3575 [RFC5870] Mayrhofer, A. and C. Spanring, "A Uniform Resource 3576 Identifier for Geographic Locations ('geo' URI)", 3577 RFC 5870, DOI 10.17487/RFC5870, June 2010, 3578 . 3580 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 3581 Specifications and Registration Procedures", BCP 13, 3582 RFC 6838, DOI 10.17487/RFC6838, January 2013, 3583 . 3585 [RFC6901] Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., 3586 "JavaScript Object Notation (JSON) Pointer", RFC 6901, 3587 DOI 10.17487/RFC6901, April 2013, 3588 . 3590 [RFC7493] Bray, T., Ed., "The I-JSON Message Format", RFC 7493, 3591 DOI 10.17487/RFC7493, March 2015, 3592 . 3594 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 3595 Writing an IANA Considerations Section in RFCs", BCP 26, 3596 RFC 8126, DOI 10.17487/RFC8126, June 2017, 3597 . 3599 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 3600 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 3601 May 2017, . 3603 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 3604 Interchange Format", STD 90, RFC 8259, 3605 DOI 10.17487/RFC8259, December 2017, 3606 . 3608 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 3609 DOI 10.17487/RFC8288, October 2017, 3610 . 3612 [TZDB] "IANA Time Zone Database", 3613 . 3615 10.2. Informative References 3617 [LINKRELS] 3618 "IANA Link Relation Types", 3619 . 3622 [LOCATIONTYPES] 3623 "IANA Location Types Registry", 3624 . 3627 [MIME] "IANA Media Types", . 3630 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3631 Resource Identifier (URI): Generic Syntax", STD 66, 3632 RFC 3986, DOI 10.17487/RFC3986, January 2005, 3633 . 3635 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 3636 Unique IDentifier (UUID) URN Namespace", RFC 4122, 3637 DOI 10.17487/RFC4122, July 2005, 3638 . 3640 [RFC5546] Daboo, C., Ed., "iCalendar Transport-Independent 3641 Interoperability Protocol (iTIP)", RFC 5546, 3642 DOI 10.17487/RFC5546, December 2009, 3643 . 3645 [RFC6047] Melnikov, A., Ed., "iCalendar Message-Based 3646 Interoperability Protocol (iMIP)", RFC 6047, 3647 DOI 10.17487/RFC6047, December 2010, 3648 . 3650 [RFC6376] Crocker, D., Ed., Hansen, T., Ed., and M. Kucherawy, Ed., 3651 "DomainKeys Identified Mail (DKIM) Signatures", STD 76, 3652 RFC 6376, DOI 10.17487/RFC6376, September 2011, 3653 . 3655 [RFC7265] Kewisch, P., Daboo, C., and M. Douglass, "jCal: The JSON 3656 Format for iCalendar", RFC 7265, DOI 10.17487/RFC7265, May 3657 2014, . 3659 [RFC7529] Daboo, C. and G. Yakushev, "Non-Gregorian Recurrence Rules 3660 in the Internet Calendaring and Scheduling Core Object 3661 Specification (iCalendar)", RFC 7529, 3662 DOI 10.17487/RFC7529, May 2015, 3663 . 3665 [RFC7808] Douglass, M. and C. Daboo, "Time Zone Data Distribution 3666 Service", RFC 7808, DOI 10.17487/RFC7808, March 2016, 3667 . 3669 [RFC7986] Daboo, C., "New Properties for iCalendar", RFC 7986, 3670 DOI 10.17487/RFC7986, October 2016, 3671 . 3673 Authors' Addresses 3675 Neil Jenkins 3676 Fastmail 3677 PO Box 234 3678 Collins St West 3679 Melbourne VIC 8007 3680 Australia 3682 Email: neilj@fastmailteam.com 3683 URI: https://www.fastmail.com 3685 Robert Stepanek 3686 Fastmail 3687 PO Box 234 3688 Collins St West 3689 Melbourne VIC 8007 3690 Australia 3692 Email: rsto@fastmailteam.com 3693 URI: https://www.fastmail.com