idnits 2.17.1 draft-ietf-calext-jscalendar-18.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 8 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 23, 2019) is 1733 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) -- Looks like a reference, but probably isn't: '1' on line 2574 -- Looks like a reference, but probably isn't: '2' on line 2576 -- Looks like a reference, but probably isn't: '3' on line 2579 -- Looks like a reference, but probably isn't: '4' on line 2581 Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 5 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 24, 2020 July 23, 2019 7 JSCalendar: A JSON representation of calendar data 8 draft-ietf-calext-jscalendar-18 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 15 alternative, and over time successor to, the widely deployed 16 iCalendar data format and to be unambiguous, extendable and simple to 17 process. In contrast to the JSON-based jCal format, it is not a 18 direct mapping from iCalendar and expands semantics where 19 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 24, 2020. 38 Copyright Notice 40 Copyright (c) 2019 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 . . . . . . . . . . . . . . . . . 5 58 1.3. Type Signatures . . . . . . . . . . . . . . . . . . . . . 6 59 1.4. Data Types . . . . . . . . . . . . . . . . . . . . . . . 6 60 1.4.1. Int . . . . . . . . . . . . . . . . . . . . . . . . . 6 61 1.4.2. UnsignedInt . . . . . . . . . . . . . . . . . . . . . 6 62 1.4.3. UTCDateTime . . . . . . . . . . . . . . . . . . . . . 7 63 1.4.4. LocalDateTime . . . . . . . . . . . . . . . . . . . . 7 64 1.4.5. Duration . . . . . . . . . . . . . . . . . . . . . . 7 65 1.4.6. SignedDuration . . . . . . . . . . . . . . . . . . . 8 66 1.4.7. Id . . . . . . . . . . . . . . . . . . . . . . . . . 8 67 1.4.8. PatchObject . . . . . . . . . . . . . . . . . . . . . 8 68 1.4.9. Time Zones . . . . . . . . . . . . . . . . . . . . . 9 69 2. JSCalendar Objects . . . . . . . . . . . . . . . . . . . . . 9 70 2.1. JSEvent . . . . . . . . . . . . . . . . . . . . . . . . . 9 71 2.2. JSTask . . . . . . . . . . . . . . . . . . . . . . . . . 9 72 2.3. JSGroup . . . . . . . . . . . . . . . . . . . . . . . . . 10 73 3. Structure of JSCalendar Objects . . . . . . . . . . . . . . . 10 74 3.1. Normalization and Equivalence . . . . . . . . . . . . . . 10 75 3.2. Custom Property Extensions and Values . . . . . . . . . . 11 76 4. Common JSCalendar Properties . . . . . . . . . . . . . . . . 11 77 4.1. Metadata Properties . . . . . . . . . . . . . . . . . . . 11 78 4.1.1. @type . . . . . . . . . . . . . . . . . . . . . . . . 11 79 4.1.2. uid . . . . . . . . . . . . . . . . . . . . . . . . . 12 80 4.1.3. relatedTo . . . . . . . . . . . . . . . . . . . . . . 12 81 4.1.4. prodId . . . . . . . . . . . . . . . . . . . . . . . 13 82 4.1.5. created . . . . . . . . . . . . . . . . . . . . . . . 13 83 4.1.6. updated . . . . . . . . . . . . . . . . . . . . . . . 13 84 4.1.7. sequence . . . . . . . . . . . . . . . . . . . . . . 13 85 4.1.8. method . . . . . . . . . . . . . . . . . . . . . . . 14 86 4.2. What and Where Properties . . . . . . . . . . . . . . . . 14 87 4.2.1. title . . . . . . . . . . . . . . . . . . . . . . . . 14 88 4.2.2. description . . . . . . . . . . . . . . . . . . . . . 14 89 4.2.3. descriptionContentType . . . . . . . . . . . . . . . 14 90 4.2.4. showWithoutTime . . . . . . . . . . . . . . . . . . . 14 91 4.2.5. locations . . . . . . . . . . . . . . . . . . . . . . 15 92 4.2.6. virtualLocations . . . . . . . . . . . . . . . . . . 16 93 4.2.7. links . . . . . . . . . . . . . . . . . . . . . . . . 16 94 4.2.8. locale . . . . . . . . . . . . . . . . . . . . . . . 18 95 4.2.9. keywords . . . . . . . . . . . . . . . . . . . . . . 18 96 4.2.10. categories . . . . . . . . . . . . . . . . . . . . . 18 97 4.2.11. color . . . . . . . . . . . . . . . . . . . . . . . . 18 98 4.3. Recurrence Properties . . . . . . . . . . . . . . . . . . 19 99 4.3.1. recurrenceId . . . . . . . . . . . . . . . . . . . . 19 100 4.3.2. recurrenceRule . . . . . . . . . . . . . . . . . . . 19 101 4.3.3. recurrenceOverrides . . . . . . . . . . . . . . . . . 27 102 4.3.4. excluded . . . . . . . . . . . . . . . . . . . . . . 28 103 4.4. Sharing and Scheduling Properties . . . . . . . . . . . . 28 104 4.4.1. priority . . . . . . . . . . . . . . . . . . . . . . 28 105 4.4.2. freeBusyStatus . . . . . . . . . . . . . . . . . . . 29 106 4.4.3. privacy . . . . . . . . . . . . . . . . . . . . . . . 29 107 4.4.4. replyTo . . . . . . . . . . . . . . . . . . . . . . . 30 108 4.4.5. participants . . . . . . . . . . . . . . . . . . . . 31 109 4.5. Alerts Properties . . . . . . . . . . . . . . . . . . . . 35 110 4.5.1. useDefaultAlerts . . . . . . . . . . . . . . . . . . 35 111 4.5.2. alerts . . . . . . . . . . . . . . . . . . . . . . . 35 112 4.6. Multilingual Properties . . . . . . . . . . . . . . . . . 37 113 4.6.1. localizations . . . . . . . . . . . . . . . . . . . . 37 114 4.7. Time Zone Properties . . . . . . . . . . . . . . . . . . 37 115 4.7.1. timeZone . . . . . . . . . . . . . . . . . . . . . . 38 116 4.7.2. timeZones . . . . . . . . . . . . . . . . . . . . . . 38 117 5. Type-specific JSCalendar Properties . . . . . . . . . . . . . 40 118 5.1. JSEvent Properties . . . . . . . . . . . . . . . . . . . 40 119 5.1.1. start . . . . . . . . . . . . . . . . . . . . . . . . 40 120 5.1.2. duration . . . . . . . . . . . . . . . . . . . . . . 40 121 5.1.3. status . . . . . . . . . . . . . . . . . . . . . . . 41 122 5.2. JSTask Properties . . . . . . . . . . . . . . . . . . . . 41 123 5.2.1. due . . . . . . . . . . . . . . . . . . . . . . . . . 41 124 5.2.2. start . . . . . . . . . . . . . . . . . . . . . . . . 41 125 5.2.3. estimatedDuration . . . . . . . . . . . . . . . . . . 41 126 5.2.4. statusUpdatedAt . . . . . . . . . . . . . . . . . . . 41 127 5.2.5. progress . . . . . . . . . . . . . . . . . . . . . . 42 128 5.2.6. status . . . . . . . . . . . . . . . . . . . . . . . 42 129 5.3. JSGroup Properties . . . . . . . . . . . . . . . . . . . 43 130 5.3.1. entries . . . . . . . . . . . . . . . . . . . . . . . 44 131 5.3.2. source . . . . . . . . . . . . . . . . . . . . . . . 44 132 6. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 44 133 6.1. Simple Event . . . . . . . . . . . . . . . . . . . . . . 44 134 6.2. Simple Task . . . . . . . . . . . . . . . . . . . . . . . 44 135 6.3. Simple Group . . . . . . . . . . . . . . . . . . . . . . 45 136 6.4. All-day Event . . . . . . . . . . . . . . . . . . . . . . 45 137 6.5. Task with a Due Date . . . . . . . . . . . . . . . . . . 46 138 6.6. Event with End Time Zone . . . . . . . . . . . . . . . . 46 139 6.7. Floating-time Event (with Recurrence) . . . . . . . . . . 47 140 6.8. Event with Multiple Locations and Localization . . . . . 47 141 6.9. Recurring Event with Overrides . . . . . . . . . . . . . 48 142 6.10. Recurring Event with Participants . . . . . . . . . . . . 49 143 7. Security Considerations . . . . . . . . . . . . . . . . . . . 51 144 7.1. Expanding Recurrences . . . . . . . . . . . . . . . . . . 51 145 7.2. JSON Parsing . . . . . . . . . . . . . . . . . . . . . . 51 146 7.3. URI Values . . . . . . . . . . . . . . . . . . . . . . . 52 147 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 52 148 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 53 149 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 53 150 10.1. Normative References . . . . . . . . . . . . . . . . . . 53 151 10.2. Informative References . . . . . . . . . . . . . . . . . 55 152 10.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 55 153 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 56 155 1. Introduction 157 This document defines a data model for calendar event and task 158 objects, or groups of such objects, in electronic calendar 159 applications and systems. It aims to be unambiguous, extendable and 160 simple to process. 162 The key design considerations for this data model are as follows: 164 o The attributes of the calendar entry represented must be described 165 as a simple key-value pair. Simple events are simple to 166 represent, complex events can be modelled accurately. 168 o Wherever possible, there should be only one way to express the 169 desired semantics, reducing complexity. 171 o The data model should avoid ambiguities and make it difficult to 172 make mistakes during implementation. 174 o The data model should be compatible with the iCalendar data format 175 [RFC5545] [RFC7986] and extensions, but the specification should 176 add new attributes where the iCalendar format currently lacks 177 expressivity, and drop widely unused, obsolete or redundant 178 properties. This means translation with no loss of semantics 179 should be easy with most common iCalendar files but is not 180 guaranteed with the full specification. 182 o Extensions, such as new properties and components, MUST NOT lead 183 to requiring an update to this document. 185 The representation of this data model is defined in the I-JSON format 186 [RFC7493], which is a strict subset of the JavaScript Object Notation 187 (JSON) Data Interchange Format [RFC8259]. Using JSON is mostly a 188 pragmatic choice: its widespread use makes JSCalendar easier to 189 adopt, and the ready availability of production-ready JSON 190 implementations eliminates a whole category of parser-related 191 interoperability issues, which iCalendar has often suffered from. 193 1.1. Motivation and Relation to iCalendar and jCal 195 The iCalendar data format [RFC5545], a widely deployed interchange 196 format for calendaring and scheduling data, has served calendaring 197 vendors for a long while, but contains some ambiguities and pitfalls 198 that can not be overcome without backward-incompatible changes. 200 For example, iCalendar defines various formats for local times, UTC 201 time and dates, which confuses new users and often leads to 202 implementation errors. Other sources for errors are the requirement 203 for custom time zone definitions within a single calendar component, 204 as well as the iCalendar format itself; the latter causing 205 interoperability issues due to misuse of CR LF terminated strings, 206 line continuations and subtle differences between iCalendar parsers. 207 The definition of recurrence rules is ambiguous and has resulted in 208 differing understandings even between experienced calendar 209 developers. 211 In recent years, many new products and services have appeared that 212 wish to use a JSON representation of calendar data within their API. 213 The JSON format for iCalendar data, jCal [RFC7265], is a direct 214 mapping between iCalendar and JSON. In its effort to represent full 215 iCalendar semantics, it inherits all the same pitfalls and uses a 216 complicated JSON structure unlike most common JSON data 217 representations. 219 As a consequence, since the standardization of jCal, the majority of 220 implementations and service providers either kept using iCalendar, or 221 came up with their own proprietary JSON representations, which are 222 incompatible with each other and often suffer from common pitfalls, 223 such as storing event start times in UTC (which become incorrect if 224 the timezone's rules change in the future). JSCalendar is intended 225 to meet this demand for JSON-formatted calendar data, and to provide 226 a standard, elegant representation as an alternative to new 227 proprietary formats. 229 1.2. Notational Conventions 231 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 232 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 233 document are to be interpreted as described in [RFC2119]. 235 The underlying format used for this specification is JSON. 236 Consequently, the terms "object" and "array" as well as the four 237 primitive types (strings, numbers, booleans, and null) are to be 238 interpreted as described in Section 1 of [RFC8259]. 240 Some examples in this document contain "partial" JSON documents used 241 for illustrative purposes. In these examples, three periods "..." 242 are used to indicate a portion of the document that has been removed 243 for compactness. 245 1.3. Type Signatures 247 Type signatures are given for all JSON values in this document. The 248 following conventions are used: 250 o "*" - The type is undefined (the value could be any type, although 251 permitted values may be constrained by the context of this value). 253 o "String" - The JSON string type. 255 o "Number" - The JSON number type. 257 o "Boolean" - The JSON boolean type. 259 o "A[B]" - A JSON object where the keys are all of type "A", and the 260 values are all of type "B". 262 o "A[]" - An array of values of type "A". 264 o "A|B" - The value is either of type "A" or of type "B". 266 Other types may also be given, with their representation defined 267 elsewhere in this document. 269 1.4. Data Types 271 In addition to the standard JSON data types, the following data types 272 are used in this specification: 274 1.4.1. Int 276 Where "Int" is given as a data type, it means an integer in the range 277 -2^53+1 <= value <= 2^53-1, the safe range for integers stored in a 278 floating-point double, represented as a JSON "Number". 280 1.4.2. UnsignedInt 282 Where "UnsignedInt" is given as a data type, it means an "Int" where 283 the value MUST be in the range 0 <= value <= 2^53-1. 285 1.4.3. UTCDateTime 287 This is a string in [RFC3339] "date-time" format, with the further 288 restrictions that any letters MUST be in uppercase, the time 289 component MUST be included and the time offset MUST be the character 290 "Z". Fractional second values MUST NOT be included unless non-zero 291 and MUST NOT have trailing zeros, to ensure there is only a single 292 representation for each date-time. 294 For example "2010-10-10T10:10:10.003Z" is OK, but 295 "2010-10-10T10:10:10.000Z" is invalid and MUST be encoded as 296 "2010-10-10T10:10:10Z". 298 In common notation, it should be of the form "YYYY-MM-DDTHH:MM:SSZ". 300 1.4.4. LocalDateTime 302 This is a date-time string with no time zone/offset information. It 303 is otherwise in the same format as UTCDateTime, including fractional 304 seconds. For example "2006-01-02T15:04:05" and 305 "2006-01-02T15:04:05.003" are both valid. The time zone to associate 306 the LocalDateTime with comes from an associated property, or if no 307 time zone is associated it defines *floating time*. Floating date- 308 times are not tied to any specific time zone. Instead, they occur in 309 every time zone at the same wall-clock time (as opposed to the same 310 instant point in time). 312 1.4.5. Duration 314 Where Duration is given as a type, it means a length of time 315 represented by a subset of ISO8601 duration format, as specified by 316 the following ABNF: 318 dur-secfrac = "." 1*DIGIT 319 dur-second = 1*DIGIT [dur-secfrac] "S" 320 dur-minute = 1*DIGIT "M" [dur-second] 321 dur-hour = 1*DIGIT "H" [dur-minute] 322 dur-time = "T" (dur-hour / dur-minute / dur-second) 323 dur-day = 1*DIGIT "D" 324 dur-week = 1*DIGIT "W" 326 duration = "P" (dur-day [dur-time] / dur-time / dur-week) 328 In addition, the duration MUST NOT include fractional second values 329 unless the fraction is non-zero. 331 1.4.6. SignedDuration 333 A SignedDuration represents a length of time that may be positive or 334 negative and is typically used to express the offset of a point in 335 time relative to an associated time. It is represented as a 336 Duration, optionally preceded by a sign character. It is specified 337 by the following ABNF: 339 signed-duration = (["+"] / "-") duration 341 A negative sign indicates a point in time at or before the associated 342 time, a positive or no sign a time at or after the associated time. 344 1.4.7. Id 346 Where "Id" is given as a data type, it means a "String" of at least 1 347 and a maximum of 255 octets in size, and it MUST only contain 348 characters from the "URL and Filename Safe" base64 alphabet, as 349 defined in Section 5 of [RFC4648], excluding the pad character ("="). 350 This means the allowed characters are the ASCII alphanumeric 351 characters ("A-Za-z0-9"), hyphen ("-"), and underscore ("_"). 353 Unless otherwise specified, Ids are arbitrary and only have meaning 354 within the object where they are being used. Ids need not be unique 355 between different objects. For example, two JSEvent objects MAY use 356 the same ids in their respective "links" properties. Or within the 357 same JSEvent object the same Id could appear in the "participants" 358 and "alerts" properties. This does not imply any semantic connection 359 between the two. 361 Nevertheless, a UUID is typically a good choice. 363 1.4.8. PatchObject 365 A PatchObject is of type "String[*]", and represents an unordered set 366 of patches on a JSON object. The keys are a path in a subset of 367 [RFC6901] JSON pointer format, with an implicit leading "/" (i.e. 368 prefix each key with "/" before applying the JSON pointer evaluation 369 algorithm). 371 A patch within a PatchObject is only valid if all of the following 372 conditions apply: 374 1. The pointer MUST NOT reference inside an array (i.e. it MUST NOT 375 insert/delete from an array; the array MUST be replaced in its 376 entirety instead). 378 2. When evaluating a path, all parts prior to the last (i.e. the 379 value after the final slash) MUST exist. 381 3. There MUST NOT be two patches in the PatchObject where the 382 pointer of one is the prefix of the pointer of the other, e.g. 383 "alerts/foo/offset" and "alerts". 385 The value associated with each pointer is either: 387 o null: Remove the property from the patched object. If not present 388 in the parent, this a no-op. 390 o Anything else: The value to set for this property (this may be a 391 replacement or addition to the object being patched). 393 Implementations MUST reject a PatchObject if any of its patches are 394 invalid. 396 1.4.9. Time Zones 398 By default, time zones in JSCalendar are identified by their name in 399 the IANA Time Zone Database [1], and the zone rules of the respective 400 zone record apply. 402 Implementations MAY embed the definition of custom time zones in the 403 "timeZones" property (see Section 4.7.2). 405 2. JSCalendar Objects 407 This section describes the calendar object types specified by 408 JSCalendar. 410 2.1. JSEvent 412 MIME type: "application/jscalendar+json;type=jsevent" 414 A JSEvent represents a scheduled amount of time on a calendar, 415 typically a meeting, appointment, reminder or anniversary. Multiple 416 participants may partake in the event at multiple locations. 418 The @type (Section 4.1.1) property value MUST be "jsevent". 420 2.2. JSTask 422 MIME type: "application/jscalendar+json;type=jstask" 424 A JSTask represents an action-item, assignment, to-do or work item. 426 The @type (Section 4.1.1) property value MUST be "jstask". 428 A JSTask may start and be due at certain points in time, may take 429 some estimated time to complete and may recur; none of which is 430 required. This notably differs from JSEvent (Section 2.1) which is 431 required to start at a certain point in time and typically takes some 432 non-zero duration to complete. 434 2.3. JSGroup 436 MIME type: "application/jscalendar+json;type=jsgroup" 438 A JSGroup is a collection of JSEvent (Section 2.1) and/or JSTask 439 (Section 2.2) objects. Typically, objects are grouped by topic (e.g. 440 by keywords) or calendar membership. 442 The @type (Section 4.1.1) property value MUST be "jsgroup". 444 3. Structure of JSCalendar Objects 446 A JSCalendar object is a JSON object, which MUST be valid I-JSON (a 447 stricter subset of JSON), as specified in [RFC8259]. Property names 448 and values are case-sensitive. 450 The object has a collection of properties, as specified in the 451 following sections. Properties are specified as being either 452 mandatory or optional. Optional properties may have a default value, 453 if explicitly specified in the property definition. 455 3.1. Normalization and Equivalence 457 JSCalendar aims to provide unambiguous definitions for value types 458 and properties, but does not define a general normalization or 459 equivalence method for JSCalendar objects and types. This is because 460 the notion of equivalence might range from byte-level equivalence to 461 semantic equivalence, depending on the respective use case (for 462 example, the CalDAV protocol [RFC4791] requires octet equivalence of 463 the encoded calendar object to determine ETag equivalence). 465 Normalization of JSCalendar objects is hindered because of the 466 following reasons: 468 o Custom JSCalendar properties may contain arbitrary JSON values, 469 including arrays. However, equivalence of arrays might or might 470 not depend on the order of elements, depending on the respective 471 property definition. 473 o Several JSCalendar property values are defined as URIs and MIME 474 types, but normalization of these types is inherently protocol and 475 scheme-specific, depending on the use-case of the equivalence 476 definition (see Section 6 of [RFC3986]). 478 Considering this, the definition of equivalence and normalization is 479 left to client and server implementations and to be negotiated by a 480 calendar exchange protocol or defined by another RFC. 482 3.2. Custom Property Extensions and Values 484 Vendors MAY add additional properties to the calendar object to 485 support their custom features. The names of these properties MUST be 486 prefixed with a domain name controlled by the vendor to avoid 487 conflict, e.g. "example.com/customprop". 489 Some JSCalendar properties allow vendor-specific value extensions. 490 If so, vendor specific values MUST be prefixed with a domain name 491 controlled by the vendor, e.g. "example.com/customrel", unless 492 otherwise noted. 494 Vendors are strongly encouraged to standardize any new property 495 values or extensions that are useful to other systems as well, rather 496 than use a vendor-specific prefix. 498 4. Common JSCalendar Properties 500 This section describes the properties that are common to the various 501 JSCalendar object types. Specific JSCalendar object types may only 502 support a subset of these properties. The object type definitions in 503 Section 5 describe the set of supported properties per type. 505 4.1. Metadata Properties 507 4.1.1. @type 509 Type: "String" (mandatory). 511 Specifies the type which this object represents. This MUST be one of 512 the following values, registered in a future RFC, or a vendor- 513 specific value: 515 o "jsevent": a JSCalendar event (Section 2.1). 517 o "jstask": a JSCalendar task (Section 2.2). 519 o "jsgroup": a JSCalendar group (Section 2.3). 521 4.1.2. uid 523 Type: "String" (mandatory). 525 A globally unique identifier, used to associate the object as the 526 same across different systems, calendars and views. The value of 527 this property MUST be unique across all JSCalendar objects, even if 528 they are of different type. [RFC4122] describes a range of 529 established algorithms to generate universally unique identifiers 530 (UUID), and the random or pseudo-random version is recommended. 532 For compatibility with [RFC5545] UIDs, implementations MUST be able 533 to receive and persist values of at least 255 octets for this 534 property, but they MUST NOT truncate values in the middle of a UTF-8 535 multi-octet sequence. 537 4.1.3. relatedTo 539 Type: "String[Relation]" (optional). 541 Relates the object to other JSCalendar objects. This is represented 542 as a map of the UIDs of the related objects to information about the 543 relation. 545 A Relation object has the following property: 547 o relation: "String[Boolean]" (optional) 549 Describes how the linked object is related to this object as a set 550 of relation types. If specified, the set MUST NOT be empty. If 551 ommitted, the relationship between the two objects is unspecified. 553 Keys in the set MUST be one of the following values, defined in a 554 future specification or a vendor-specific value: 556 * "first": The linked object is the first in the series this 557 object is part of. 559 * "next": The linked object is the next in the series this object 560 is part of. 562 * "child": The linked object is a subpart of this object. 564 * "parent": This object is part of the overall linked object. 566 The value for each key in the set MUST be true. 568 Note, the Relation object only has one property; it is specified as 569 an object with a single property rather than mapping directly from 570 the UID to relation types to allow for extension in the future. 572 If an object is split to make a "this and future" change to a 573 recurrence, the original object MUST be truncated to end at the 574 previous occurrence before this split, and a new object created to 575 represent all the occurrences after the split. A "next" relation 576 MUST be set on the original object's relatedTo property for the UID 577 of the new object. A "first" relation for the UID of the first 578 object in the series MUST be set on the new object. Clients can then 579 follow these UIDs to get the complete set of objects if the user 580 wishes to modify them all at once. 582 4.1.4. prodId 584 Type: "String" (optional). 586 The identifier for the product that created the JSCalendar object. 588 The vendor of the implementation SHOULD ensure that this is a 589 globally unique identifier, using some technique such as an FPI 590 value, as defined in [ISO.9070.1991]. It MUST only use characters of 591 an iCalendar TEXT data value (see Section 3.3.11 of [RFC5545]). 593 This property SHOULD NOT be used to alter the interpretation of a 594 JSCalendar object beyond the semantics specified in this document. 595 For example, it is not to be used to further the understanding of 596 non-standard properties. 598 4.1.5. created 600 Type: "UTCDateTime" (optional). 602 The date and time this object was initially created. 604 4.1.6. updated 606 Type: "UTCDateTime" (mandatory). 608 The date and time the data in this object was last modified. 610 4.1.7. sequence 612 Type: "UnsignedInt" (optional, default: 0). 614 Initially zero, this MUST be incremented by one every time a change 615 is made to the object, except if the change only modifies the 616 "participants" property (see Section 4.4.5). 618 This is used as part of iTIP [RFC5546] to know which version of the 619 object a scheduling message relates to. 621 4.1.8. method 623 Type: "String" (optional). 625 The iTIP [RFC5546] method, in lowercase. This MUST only be present 626 if the JSCalendar object represents an iTIP scheduling message. 628 4.2. What and Where Properties 630 4.2.1. title 632 Type: "String" (optional, default: empty String). 634 A short summary of the object. 636 4.2.2. description 638 Type: "String" (optional, default: empty String). 640 A longer-form text description of the object. The content is 641 formatted according to the "descriptionContentType" property. 643 4.2.3. descriptionContentType 645 Type: "String" (optional, default: "text/plain"). 647 Describes the media type [RFC6838] of the contents of the 648 "description" property. Media types MUST be sub-types of type 649 "text", and SHOULD be "text/plain" or "text/html" [MIME]. They MAY 650 define parameters and the "charset" parameter value MUST be "utf-8", 651 if specified. Descriptions of type "text/html" MAY contain "cid" 652 URLs [RFC2392] to reference links in the calendar object by use of 653 the "cid" property of the Link object. 655 4.2.4. showWithoutTime 657 Type: "Boolean" (optional, default: false). 659 Indicates the time is not important to display to the user when 660 rendering this calendar object, for example an event that 661 conceptually occurs all day or across multiple days, such as "New 662 Year's Day" or "Italy Vacation". While the time component is 663 important for free-busy calculations and checking for scheduling 664 clashes, calendars may choose to omit displaying it and/or display 665 the object separately to other objects to enhance the user's view of 666 their schedule. 668 Such events are also commonly known as "all-day" events. 670 4.2.5. locations 672 Type: "Id[Location]" (optional). 674 A map of location ids to Location objects, representing locations 675 associated with the object. 677 A Location object has the following properties. It MUST have at 678 least one property other than the "relativeTo" property. 680 o name: "String" (optional) 682 The human-readable name of the location. 684 o description: "String" (optional) 686 Human-readable, plain-text instructions for accessing this 687 location. This may be an address, set of directions, door access 688 code, etc. 690 o relativeTo: "String" (optional) 692 The relation type of this location to the JSCalendar object. 694 This MUST be either one of the following values, registered in a 695 future RFC, or a vendor-specific value. Any value the client or 696 server doesn't understand should be treated the same as if this 697 property is omitted. 699 * "start": The JSCalendar object starts at this location. 701 * "end": The JSCalendar object ends at this location. 703 o timeZone: "String" (optional) 705 A time zone for this location. See also Section 1.4.9. 707 o coordinates: "String" (optional) 709 A "geo:" URI [RFC5870] for the location. 711 o linkIds: "Id[Boolean]" (optional) 713 A set of link ids for links to alternate representations of this 714 location. Each key in the set MUST be the id of a Link object 715 defined in the "links" property of this calendar object. The 716 value for each key in the set MUST be true. This MUST be omitted 717 if none (rather than an empty set). 719 For example, an alternative representation could be in vCard 720 format. 722 4.2.6. virtualLocations 724 Type: "Id[VirtualLocation]" (optional). 726 A map of ids to VirtualLocation objects, representing virtual 727 locations, such as video conferences or chat rooms, associated with 728 the object. 730 A VirtualLocation object has the following properties. 732 o name: "String" (optional, default: empty String) 734 The human-readable name of the virtual location. 736 o description: "String" (optional) 738 Human-readable plain-text instructions for accessing this 739 location. This may be an address, set of directions, door access 740 code, etc. 742 o uri: "String" (mandatory) 744 A URI that represents how to connect to this virtual location. 746 This may be a telephone number (represented using the "tel:" 747 scheme, e.g., "tel:+1-555-555-555") for a teleconference, a web 748 address for online chat, or any custom URI. 750 4.2.7. links 752 Type: "Id[Link]" (optional). 754 A map of link ids to Link objects, representing external resources 755 associated with the object. 757 A Link object has the following properties: 759 o href: "String" (mandatory) 761 A URI from which the resource may be fetched. 763 This MAY be a "data:" URL, but it is recommended that the file be 764 hosted on a server to avoid embedding arbitrarily large data in 765 JSCalendar object instances. 767 o cid: "String" (optional) 769 This MUST be a valid "content-id" value according to the 770 definition of Section 2 in [RFC2392]. The value MUST be unique 771 within this Link object but has no meaning beyond that. It MAY be 772 different from the link id for this Link object. 774 o type: "String" (optional) 776 The content-type [RFC6838] of the resource, if known. 778 o size: "UnsignedInt" (optional) 780 The size, in octets, of the resource when fully decoded (i.e. the 781 number of octets in the file the user would download), if known. 783 o rel: "String" (optional) 785 Identifies the relation of the linked resource to the object. If 786 set, the value MUST be a registered relation type (see [RFC8288] 787 and IANA Link Relations [2]). 789 Links with a rel of "enclosure" SHOULD be considered by the client 790 as attachments for download. 792 Links with a rel of "describedby" SHOULD be considered by the 793 client to be an alternate representation of the description. 795 Links with a rel of "icon" SHOULD be considered by the client to 796 be an image that it MAY use when presenting the calendar data to a 797 user. The "display" property MAY be set to indicate the purpose 798 of this image. 800 o display: "String" (optional) 802 Describes the intended purpose of a link to an image. If set, the 803 "rel" property MUST be set to "icon". The value MUST be either 804 one of the following values, registered in a future RFC, or a 805 vendor-specific value: 807 * "badge": an image inline with the title of the object. 809 * "graphic": a full image replacement for the object itself. 811 * "fullsize": an image that is used to enhance the object. 813 * "thumbnail": a smaller variant of "fullsize" to be used when 814 space for the image is constrained. 816 o title: "String" (optional) 818 A human-readable plain-text description of the resource. 820 4.2.8. locale 822 Type: "String" (optional). 824 The language tag as defined in [RFC5646] that best describes the 825 locale used for the text in the calendar object, if known. 827 4.2.9. keywords 829 Type: "String[Boolean]" (optional). 831 A set of keywords or tags that relate to the object. The set is 832 represented as a map, with the keys being the keywords. The value 833 for each key in the map MUST be true. 835 4.2.10. categories 837 Type: "String[Boolean]" (optional). 839 A set of categories that relate to the calendar object. The set is 840 represented as a map, with the keys being the categories specified as 841 URIs. The value for each key in the map MUST be true. 843 In contrast to keywords, categories typically are structured. For 844 example, a vendor owning the domain "example.com" might define the 845 categories "http://example.com/categories/sports/american-football"" 846 and "http://example.com/categories/music/r-b". 848 4.2.11. color 850 Type: "String" (optional). 852 A color clients MAY use when displaying this calendar object. The 853 value is a case-insensitive color name taken from the CSS3 set of 854 names, defined in Section 4.3 of W3C.REC-css3-color-20110607 [3] or a 855 CSS3 RGB color hex value. 857 4.3. Recurrence Properties 859 Some events and tasks occur at regular, or indeed irregular, 860 intervals. Rather than having to copy the data for every occurrence, 861 you can instead have a master event with a recurrence rule generating 862 the occurrences, and/or overrides that add extra dates or exceptions 863 to the rule. 865 4.3.1. recurrenceId 867 Type: "LocalDateTime" (optional). 869 If present, this JSCalendar object represents one occurrence of a 870 recurring JSCalendar object. If present the "recurrenceRule" and 871 "recurrenceOverrides" properties MUST NOT be present. 873 The value is a date-time either produced by the "recurrenceRule" of 874 the master event, or added as a key to the "recurrenceOverrides" 875 property of the master event. 877 4.3.2. recurrenceRule 879 Type: "Recurrence" (optional). 881 Defines a recurrence rule (repeating pattern) for recurring calendar 882 objects. 884 A JSEvent recurs by applying the recurrence rule to the "start" date- 885 time. 887 A JSTask recurs by applying the recurrence rule to the "start" date- 888 time, if defined, otherwise it recurs by the "due" date-time, if 889 defined. If the task defines neither a "start" nor "due" date-time, 890 its "recurrenceRule" property value MUST be null. 892 A Recurrence object is a JSON object mapping of a RECUR value type in 893 iCalendar [RFC5545] [RFC7529] and has the same semantics. It has the 894 following properties: 896 o frequency: "String" (mandatory) 898 The time span covered by each iteration of this recurrence rule 899 (see Section 4.3.2.1 for full semantics). This MUST be one of the 900 following values: 902 * "yearly" 904 * "monthly" 906 * "weekly" 908 * "daily" 910 * "hourly" 912 * "minutely" 914 * "secondly" 916 This is the FREQ part from iCalendar, converted to lowercase. 918 o interval: "UnsignedInt" (optional, default: 1) 920 The interval of iteration periods at which the recurrence repeats. 921 If included, it MUST be an integer >= 1. 923 This is the INTERVAL part from iCalendar. 925 o rscale: "String" (optional, default: "gregorian") 927 The calendar system in which this recurrence rule operates, in 928 lowercase. This MUST be either a CLDR-registered calendar system 929 name, or a non-standard, experimental calendar system name 930 prefixed with the characters "x-". 932 This is the RSCALE part from iCalendar RSCALE [RFC7529], converted 933 to lowercase. 935 o skip: "String" (optional, default: "omit") 937 The behaviour to use when the expansion of the recurrence produces 938 invalid dates. This MUST be one of the following values: 940 * "omit" 942 * "backward" 944 * "forward" 946 This is the SKIP part from iCalendar RSCALE [RFC7529], converted 947 to lowercase. 949 o firstDayOfWeek: "String" (optional, default: "mo") 950 The day on which the week is considered to start, represented as a 951 lowercase abbreviated two-letter English day of the week. If 952 included, it MUST be one of the following values: 954 * "mo" 956 * "tu" 958 * "we" 960 * "th" 962 * "fr" 964 * "sa" 966 * "su" 968 This is the WKST part from iCalendar. 970 o byDay: "NDay[]" (optional) 972 Days of the week on which to repeat. An *NDay* object has the 973 following properties: 975 * day: "String" (mandatory) 977 A day of the week on which to repeat; the allowed values are 978 the same as for the "firstDayOfWeek" Recurrence property. 980 This is the day-of-the-week of the BYDAY part in iCalendar, 981 converted to lowercase. 983 * nthOfPeriod: "Int" (optional) 985 If present, rather than representing every occurrence of the 986 weekday defined in the "day" property, it represents only a 987 specific instance within the recurrence period. The value can 988 be positive or negative, but MUST NOT be zero. A negative 989 integer means nth-last of period. 991 This is the ordinal part of the BYDAY value in iCalendar (e.g. 992 1 or -3). 994 o byMonthDay: "Int[]" (optional) 995 Days of the month on which to repeat. Valid values are 1 to 31 or 996 -31 to -1. Negative values offset from the end of the month. The 997 array MUST have at least one entry if included. 999 This is the BYMONTHDAY part in iCalendar. 1001 o byMonth: "String[]" (optional) 1003 The months in which to repeat. Each entry is a string 1004 representation of a number, starting from "1" for the first month 1005 in the calendar (e.g. "1" means January with the Gregorian 1006 calendar), with an optional "L" suffix (see [RFC7529]) for leap 1007 months (this MUST be uppercase, e.g. "3L"). The array MUST have 1008 at least one entry if included. 1010 This is the BYMONTH part from iCalendar. 1012 o byYearDay: "Int[]" (optional) 1014 The days of the year on which to repeat. Valid values are 1 to 1015 366 or -366 to -1. Negative values offset from the end of the 1016 year. The array MUST have at least one entry if included. 1018 This is the BYYEARDAY part from iCalendar. 1020 o byWeekNo: "Int[]" (optional) 1022 Weeks of the year in which to repeat. Valid values are 1 to 53 or 1023 -53 to -1. The array MUST have at least one entry if included. 1025 This is the BYWEEKNO part from iCalendar. 1027 o byHour: "UnsignedInt[]" (optional) 1029 The hours of the day in which to repeat. Valid values are 0 to 1030 23. The array MUST have at least one entry if included. This is 1031 the BYHOUR part from iCalendar. 1033 o byMinute: "UnsignedInt[]" (optional) 1035 The minutes of the hour in which to repeat. Valid values are 0 to 1036 59. The array MUST have at least one entry if included. 1038 This is the BYMINUTE part from iCalendar. 1040 o bySecond: "UnsignedInt[]" (optional) 1041 The seconds of the minute in which to repeat. Valid values are 0 1042 to 60. The array MUST have at least one entry if included. 1044 This is the BYSECOND part from iCalendar. 1046 o bySetPosition: "Int[]" (optional) 1048 The occurrences within the recurrence interval to include in the 1049 final results. Negative values offset from the end of the list of 1050 occurrences. The array MUST have at least one entry if included. 1051 This is the BYSETPOS part from iCalendar. 1053 o count: "UnsignedInt" (optional) 1055 The number of occurrences at which to range-bound the recurrence. 1056 This MUST NOT be included if an "until" property is specified. 1058 This is the COUNT part from iCalendar. 1060 o until: "LocalDateTime" (optional) 1062 The date-time at which to finish recurring. The last occurrence 1063 is on or before this date-time. This MUST NOT be included if a 1064 "count" property is specified. Note: if not specified otherwise 1065 for a specific JSCalendar object, this date is to be interpreted 1066 in the time zone specified in the JSCalendar object's "timeZone" 1067 property. 1069 This is the UNTIL part from iCalendar. 1071 4.3.2.1. Interpreting recurrence rules 1073 A recurrence rule specifies a set of date-times for recurring 1074 calendar objects. A recurrence rule has the following semantics. 1075 Note, wherever "year", "month" or "day of month" is used, this is 1076 within the calendar system given by the "rscale" property, which 1077 defaults to gregorian if omitted. 1079 1. A set of candidates is generated. This is every second within a 1080 period defined by the frequency property value: 1082 * "yearly": every second from midnight on the 1st day of a year 1083 (inclusive) to midnight the 1st day of the following year 1084 (exclusive). 1086 If skip is not "omit", the calendar system has leap months and 1087 there is a byMonth property, generate candidates for the leap 1088 months even if they don't occur in this year. 1090 If skip is not "omit" and there is a byMonthDay property, 1091 presume each month has the maximum number of days any month 1092 may have in this calendar system when generating candidates, 1093 even if it's more than this month actually has. 1095 * "monthly": every second from midnight on the 1st day of a 1096 month (inclusive) to midnight on the 1st of the following 1097 month (exclusive). 1099 If skip is not "omit" and there is a byMonthDay property, 1100 presume the month has the maximum number of days any month may 1101 have in this calendar system when generating candidates, even 1102 if it's more than this month actually has. 1104 * "weekly": every second from midnight (inclusive) on the first 1105 day of the week (as defined by the firstDayOfWeek property, or 1106 Monday if omitted), to midnight 7 days later (exclusive). 1108 * "daily": every second from midnight at the start of the day 1109 (inclusive) to midnight at the end of the day (exclusive). 1111 * "hourly": every second from the beginning of the hour 1112 (inclusive) to the beginning of the next hour (exclusive). 1114 * "minutely": every second from the beginning of the minute 1115 (inclusive) to the beginning of the next minute (exclusive). 1117 * "secondly": the second itself, only. 1119 2. Each date-time candidate is compared against all of the byX 1120 properties of the rule except bySetPosition. If any property in 1121 the rule does not match the date-time, it is eliminated. Each 1122 byX property is an array; the date-time matches the property if 1123 it matches any of the values in the array. The properties have 1124 the following semantics: 1126 * byMonth: the date-time is in the given month. 1128 * byWeekNo: the date-time is in the nth week of the year. 1129 Negative numbers mean the nth last week of the year. This 1130 corresponds to weeks according to week numbering as defined in 1131 ISO.8601.2004, with a week defined as a seven day period, 1132 starting on the firstDayOfWeek property value or Monday if 1133 omitted. Week number one of the calendar year is the first 1134 week that contains at least four days in that calendar year. 1136 If the date-time is not valid (this may happen when generating 1137 candidates with a skip property in effect), it is always 1138 eliminated by this property. 1140 * byYearDay: the date-time is on the nth day of year. Negative 1141 numbers mean the nth last day of the year. 1143 If the date-time is not valid (this may happen when generating 1144 candidates with a skip property in effect), it is always 1145 eliminated by this property. 1147 * byMonthDay: the date-time is on the given day of the month. 1148 Negative numbers mean the nth last day of the month. 1150 * byDay: the date-time is on the given day of the week. If the 1151 day is prefixed by a number, it is the nth occurrence of that 1152 day of the week within the month (if frequency is monthly) or 1153 year (if frequency is yearly). Negative numbers means nth 1154 last occurrence within that period. 1156 * byHour: the date-time has the given hour value. 1158 * byMinute: the date-time has the given minute value. 1160 * bySecond: the date-time has the given second value. 1162 If a skip property is defined and is not "omit", there may be 1163 candidates that do not correspond to valid dates (e.g. 31st 1164 February in the gregorian calendar). In this case, the 1165 properties MUST be considered in the order above and: 1167 1. After applying the byMonth filter, if the candidate's month 1168 is invalid for the given year increment it (if skip is 1169 "forward") or decrement it (if skip is "backward") until a 1170 valid month is found, incrementing/decrementing the year as 1171 well if you pass through the beginning/end of the year. This 1172 only applies to calendar systems with leap months. 1174 2. After applying the byMonthDay filter, if the day of the month 1175 is invalid for the given month and year, change the date to 1176 the first day of the next month (if skip == "forward") or the 1177 last day of the current month (if skip == "backward"). 1179 3. If any valid date produced after applying the skip is already 1180 a candidate, eliminate the duplicate. (For example after 1181 adjusting, 30th February and 31st February would both become 1182 the same "real" date, so one is eliminated as a duplicate.) 1184 3. If a bySetPosition property is included, this is now applied to 1185 the ordered list of remaining dates. This property specifies the 1186 indexes of date-times to keep; all others should be eliminated. 1187 Negative numbers are indexes from the end of the list, with -1 1188 being the last item. 1190 4. Any date-times before the start date of the event are eliminated 1191 (see below for why this might be needed). 1193 5. If a skip property is included and is not "omit", eliminate any 1194 date-times that have already been produced by previous iterations 1195 of the algorithm. (This is not possible if skip == "omit".) 1197 6. If further dates are required (we have not reached the until 1198 date, or count limit) skip the next (interval - 1) sets of 1199 candidates, then continue from step 1. 1201 When determining the set of occurrence dates for an event or task, 1202 the following extra rules must be applied: 1204 1. The initial date-time to which the rule is applied (the "start" 1205 date-time for events; the "start" or "due" date-time for tasks) 1206 is always the first occurrence in the expansion (and is counted 1207 if the recurrence is limited by a "count" property), even if it 1208 would normally not match the rule. 1210 2. The first set of candidates to consider is that which would 1211 contain the initial date-time. This means the first set may 1212 include candidates before the initial date-time; such candidates 1213 are eliminated from the results in step (4) as outlined before. 1215 3. The following properties MUST be implicitly added to the rule 1216 under the given conditions: 1218 * If frequency is not "secondly" and no bySecond property: Add a 1219 bySecond property with the sole value being the seconds value 1220 of the initial date-time. 1222 * If frequency is not "secondly" or "minutely", and no byMinute 1223 property: Add a byMinute property with the sole value being 1224 the minutes value of the initial date-time. 1226 * If frequency is not "secondly", "minutely" or "hourly" and no 1227 byHour property: Add a byHour property with the sole value 1228 being the hours value of the initial date-time. 1230 * If frequency is "weekly" and no byDay property: Add a byDay 1231 property with the sole value being the day-of-the-week of the 1232 initial date-time. 1234 * If frequency is "monthly" and no byDay property and no 1235 byMonthDay property: Add a byMonthDay property with the sole 1236 value being the day-of-the-month of the initial date-time. 1238 * If frequency is "yearly" and no byYearDay property: 1240 + If there are no byMonth or byWeekNo properties, and either 1241 there is a byMonthDay property or there is no byDay 1242 property: Add a byMonth property with the sole value being 1243 the month of the initial date-time. 1245 + If there is no byMonthDay, byWeekNo or byDay properties: 1246 Add a byMonthDay property with the sole value being the 1247 day-of-the-month of the initial date-time. 1249 + If there is a byWeekNo property and no byMonthDay or byDay 1250 properties: Add a byDay property with the sole value being 1251 the day-of-the-week of the initial date-time. 1253 4.3.3. recurrenceOverrides 1255 Type: "LocalDateTime[PatchObject]" (optional). 1257 A map of the recurrence ids (the date-time produced by the recurrence 1258 rule) to an object of patches to apply to the generated occurrence 1259 object. 1261 If the recurrence id does not match a date-time from the recurrence 1262 rule (or no rule is specified), it is to be treated as an additional 1263 occurrence (like an RDATE from iCalendar). The patch object may 1264 often be empty in this case. 1266 If the patch object defines the "excluded" property value to be true, 1267 then the recurring calendar object does not occur at the recurrence 1268 id date-time (like an EXDATE from iCalendar). Such a patch object 1269 MUST NOT patch any other property. 1271 By default, an occurrence inherits all properties from the main 1272 object except the start (or due) date-time, which is shifted to match 1273 the recurrence id LocalDateTime. However, individual properties of 1274 the occurrence can be modified by a patch, or multiple patches. It 1275 is valid to patch the "start" property value, and this patch takes 1276 precedence over the value generated from the recurrence id. Both the 1277 recurrence id as well as the patched "start" date-time may occur 1278 before the original JSCalendar object's "start" or "due" date. 1280 A pointer in the PatchObject MUST be ignored if it starts with one of 1281 the following prefixes: 1283 o @type 1285 o method 1287 o prodId 1289 o recurrenceId 1291 o recurrenceOverrides 1293 o recurrenceRule 1295 o relatedTo 1297 o replyTo 1299 o uid 1301 4.3.4. excluded 1303 Type: "Boolean" (optional, default: false). 1305 Defines if this object is an overridden, excluded instance of a 1306 recurring JSCalendar object (see Section 4.3.3). If this property 1307 value is true, this calendar object instance MUST be removed from the 1308 occurrence expansion. The absence of this property or its default 1309 value false indicates that this instance MUST be included in the 1310 occurrence expansion. 1312 4.4. Sharing and Scheduling Properties 1314 4.4.1. priority 1316 Type: "Int" (optional, default: 0). 1318 Specifies a priority for the calendar object. This may be used as 1319 part of scheduling systems to help resolve conflicts for a time 1320 period. 1322 The priority is specified as an integer in the range 0 to 9. A value 1323 of 0 specifies an undefined priority. A value of 1 is the highest 1324 priority. A value of 2 is the second highest priority. Subsequent 1325 numbers specify a decreasing ordinal priority. A value of 9 is the 1326 lowest priority. Other integer values are reserved for future use. 1328 4.4.2. freeBusyStatus 1330 Type: "String" (optional, default: "busy"). 1332 Specifies how this property should be treated when calculating free- 1333 busy state. The value MUST be one of: 1335 o "free": The object should be ignored when calculating whether the 1336 user is busy. 1338 o "busy": The object should be included when calculating whether the 1339 user is busy. 1341 4.4.3. privacy 1343 Type: "String" (optional, default: "public"). 1345 Calendar objects are normally collected together and may be shared 1346 with other users. The privacy property allows the object owner to 1347 indicate that it should not be shared, or should only have the time 1348 information shared but the details withheld. Enforcement of the 1349 restrictions indicated by this property are up to the API via which 1350 this object is accessed. 1352 This property MUST NOT affect the information sent to scheduled 1353 participants; it is only interpreted when the object is shared as 1354 part of a shared calendar. 1356 The value MUST be either one of the following values, registered in a 1357 future RFC, or a vendor-specific value. Vendor specific values MUST 1358 be prefixed with a domain name controlled by the vendor, e.g. 1359 "example.com/topsecret". Any value the client or server doesn't 1360 understand should be preserved but treated as equivalent to 1361 "private". 1363 o "public": The full details of the object are visible to those whom 1364 the object's calendar is shared with. 1366 o "private": The details of the object are hidden; only the basic 1367 time and metadata is shared. The following properties MAY be 1368 shared, any other properties MUST NOT be shared: 1370 * @type 1372 * created 1373 * due 1375 * duration 1377 * estimatedDuration 1379 * freeBusyStatus 1381 * privacy 1383 * recurrenceOverrides. Only patches which apply to another 1384 permissible property are allowed to be shared. 1386 * sequence 1388 * showWithoutTime 1390 * start 1392 * timeZone 1394 * timeZones 1396 * uid 1398 * updated 1400 o "secret": The object is hidden completely (as though it did not 1401 exist) when the calendar this object is in is shared. 1403 4.4.4. replyTo 1405 Type: "String[String]" (optional). 1407 Represents methods by which participants may submit their RSVP 1408 response to the organizer of the calendar object. The keys in the 1409 property value are the available methods and MUST only contain ASCII 1410 alphanumeric characters (A-Za-z0-9). The value is a URI to use that 1411 method. Future methods may be defined in future specifications; a 1412 calendar client MUST ignore any method it does not understand, but 1413 MUST preserve the method key and URI. This property MUST be omitted 1414 if no method is defined (rather than an empty object). If this 1415 property is set, the "participants" property of this calendar object 1416 MUST contain at least one participant. 1418 The following methods are defined: 1420 o "imip": The organizer accepts an iMIP [RFC6047] response at this 1421 email address. The value MUST be a "mailto:" URI. 1423 o "web": Opening this URI in a web browser will provide the user 1424 with a page where they can submit a reply to the organizer. 1426 o "other": The organizer is identified by this URI but the method 1427 how to submit the RSVP is undefined. 1429 4.4.5. participants 1431 Type: "Id[Participant]" (optional). 1433 A map of participant ids to participants, describing their 1434 participation in the calendar object. 1436 If this property is set, then the "replyTo" property of this calendar 1437 object MUST define at least one reply method. 1439 A Participant object has the following properties: 1441 o name: "String" (optional) 1443 The display name of the participant (e.g. "Joe Bloggs"). 1445 o email: "String" (optional) 1447 The email address for the participant. 1449 o sendTo: "String[String]" (mandatory) 1451 Represents methods by which the participant may receive the 1452 invitation and updates to the calendar object. 1454 The keys in the property value are the available methods and MUST 1455 only contain ASCII alphanumeric characters (A-Za-z0-9). The value 1456 is a URI to use that method. Future methods may be defined in 1457 future specifications; a calendar client MUST ignore any method it 1458 does not understand, but MUST preserve the method key and URI. 1459 This property MUST be omitted if no method is defined (rather than 1460 an empty object). 1462 The following methods are defined: 1464 * "imip": The participant accepts an iMIP [RFC6047] request at 1465 this email address. The value MUST be a "mailto:" URI. It MAY 1466 be different from the value of the participant's "email" 1467 property. 1469 * "other": The participant is identified by this URI but the 1470 method how to submit the invitation or update is undefined. 1472 o kind: "String" (optional) 1474 What kind of entity this participant is, if known. 1476 This MUST be either one of the following values, registered in a 1477 future RFC, or a vendor-specific value. Any value the client or 1478 server doesn't understand should be treated the same as if this 1479 property is omitted. 1481 * "individual": a single person 1483 * "group": a collection of people invited as a whole 1485 * "resource": a non-human resource, e.g. a projector 1487 * "location": a physical location involved in the calendar object 1488 that needs to be scheduled, e.g. a conference room. 1490 o roles: "String[Boolean]" (mandatory) 1492 A set of roles that this participant fulfills. 1494 At least one role MUST be specified for the participant. The keys 1495 in the set MUST be either one of the following values, registered 1496 in a future RFC, or a vendor-specific value: 1498 * "owner": The participant is an owner of the object. This 1499 signifies they have permission to make changes to it that 1500 affect the other participants. Non-owner participants may only 1501 change properties that just affect themself (for example 1502 setting their own alerts). 1504 * "attendee": The participant is an attendee of the calendar 1505 object. 1507 * "chair": The participant is in charge of the calendar object 1508 when it occurs. 1510 The value for each key in the set MUST be true. Roles that are 1511 unknown to the implementation MUST be preserved. 1513 o locationId: "String" (optional) 1515 The location at which this participant is expected to be 1516 attending. 1518 If the value does not correspond to any location id in the 1519 "locations" property of the JSCalendar object, this MUST be 1520 treated the same as if the participant's locationId were omitted. 1522 o participationStatus: "String" (optional, default: "needs-action") 1524 The participation status, if any, of this participant. 1526 The value MUST be either one of the following values, registered 1527 in a future RFC, or a vendor-specific value: 1529 * "needs-action": No status yet set by the participant. 1531 * "accepted": The invited participant will participate. 1533 * "declined": The invited participant will not participate. 1535 * "tentative": The invited participant may participate. 1537 o participationComment: "String" (optional) 1539 A note from the participant to explain their participation status. 1541 o attendance: "String" (optional, default: "required") 1543 The required attendance of this participant. 1545 The value MUST be either one of the following values, registered 1546 in a future RFC, or a vendor-specific value. Any value the client 1547 or server doesn't understand should be treated the same as 1548 "required". 1550 * "none": Indicates a participant who is copied for information 1551 purposes only. 1553 * "optional": Indicates a participant whose attendance is 1554 optional. 1556 * "required": Indicates a participant whose attendance is 1557 required. 1559 o expectReply: "Boolean" (optional, default: false) 1561 If true, the organizer is expecting the participant to notify them 1562 of their participation status. 1564 o scheduleSequence: "UnsignedInt" (optional, default: 0) 1565 The sequence number of the last response from the participant. If 1566 defined, this MUST be a non-negative integer. 1568 This can be used to determine whether the participant has sent a 1569 new RSVP following significant changes to the calendar object, and 1570 to determine if future responses are responding to a current or 1571 older view of the data. 1573 o scheduleUpdated: "UTCDateTime" (optional) 1575 The "updated" property of the last iTIP response from the 1576 participant. 1578 This can be compared to the "updated" property timestamp in future 1579 iTIP responses to determine if the response is older or newer than 1580 the current data. 1582 o invitedBy: "String" (optional) 1584 The participant id of the participant who invited this one, if 1585 known. 1587 o delegatedTo: "String[Boolean]" (optional) 1589 A set of participant ids that this participant has delegated their 1590 participation to. Each key in the set MUST be the id of a 1591 participant. The value for each key in the set MUST be true. 1592 This MUST be omitted if none (rather than an empty set). 1594 o delegatedFrom: "String[Boolean]" (optional) 1596 A set of participant ids that this participant is acting as a 1597 delegate for. Each key in the set MUST be the id of a 1598 participant. The value for each key in the set MUST be true. 1599 This MUST be omitted if none (rather than an empty set). 1601 o memberOf: "String[Boolean]" (optional) 1603 A set of group participants that were invited to this calendar 1604 object, which caused this participant to be invited due to their 1605 membership of the group(s). Each key in the set MUST be the id of 1606 a participant. The value for each key in the set MUST be true. 1607 This MUST be omitted if none (rather than an empty set). 1609 o linkIds: "String[Boolean]" (optional) 1611 A set of links to more information about this participant, for 1612 example in vCard format. The keys in the set MUST be the id of a 1613 Link object in the calendar object's "links" property. The value 1614 for each key in the set MUST be true. This MUST be omitted if 1615 none (rather than an empty set). 1617 4.5. Alerts Properties 1619 4.5.1. useDefaultAlerts 1621 Type: "Boolean" (optional, default: false). 1623 If true, use the user's default alerts and ignore the value of the 1624 "alerts" property. Fetching user defaults is dependent on the API 1625 from which this JSCalendar object is being fetched, and is not 1626 defined in this specification. If an implementation cannot determine 1627 the user's default alerts, or none are set, it MUST process the 1628 alerts property as if "useDefaultAlerts" is set to false. 1630 4.5.2. alerts 1632 Type: "Id[Alert]" (optional). 1634 A map of alert ids to Alert objects, representing alerts/reminders to 1635 display or send to the user for this calendar object. 1637 An Alert Object has the following properties: 1639 o trigger: "OffsetTrigger|AbsoluteTrigger|UnknownTrigger" 1641 Defines when to trigger the alert. New types may be defined in 1642 future RFCs. 1644 An *OffsetTrigger* object has the following properties: 1646 * type: "String" (mandatory) 1648 The value of this property MUST be "offset". 1650 * offset: "SignedDuration" (mandatory). 1652 Defines the offset at which to trigger the alert relative to 1653 the time property defined in the "relativeTo" property of the 1654 alert. If the calendar object does not define a time zone, the 1655 user's default time zone SHOULD be used when determining the 1656 offset, if known. Otherwise, the time zone to use is 1657 implementation specific. 1659 * relativeTo: "String" (optional, default: "start") 1660 Specifies the time property that the alert offset is relative 1661 to. The value MUST be one of: 1663 + "start": triggers the alert relative to the start of the 1664 calendar object 1666 + "end": triggers the alert relative to the end/due time of 1667 the calendar object 1669 An *AbsoluteTrigger* object has the following properties: 1671 * type: "String" (mandatory) 1673 The value of this property MUST be "absolute". 1675 * when: "UTCDateTime" (mandatory). 1677 Defines a specific UTC date-time when the alert is triggered. 1679 An *UnknownTrigger* object is an object that contains a *type* 1680 property whose value is not recognized (i.e., not "offset" or 1681 "absolute"), plus zero or more other properties. This is for 1682 compatibility with client extensions and future RFCs. 1683 Implementations SHOULD NOT trigger for trigger types they do not 1684 understand, but MUST preserve them. 1686 o acknowledged: "UTCDateTime" (optional) 1688 This records when an alert was last acknowledged. This is set 1689 when the user has dismissed the alert; other clients that sync 1690 this property SHOULD automatically dismiss or suppress duplicate 1691 alerts (alerts with the same alert id that triggered on or before 1692 this date-time). 1694 For a recurring calendar object, the "acknowledged" property of 1695 the parent object MUST be updated, unless the alert is already 1696 overridden in the "recurrenceOverrides" property. 1698 Certain kinds of alert action may not provide feedback as to when 1699 the user sees them, for example email based alerts. For those 1700 kinds of alerts, this property SHOULD be set immediately when the 1701 alert is triggered and the action successfully carried out. 1703 o action: "String" (optional, default: "display") 1705 Describes how to alert the user. 1707 The value MUST be at most one of the following values, registered 1708 in a future RFC, or a vendor-specific value: 1710 * "display": The alert should be displayed as appropriate for the 1711 current device and user context. 1713 * "email": The alert should trigger an email sent out to the 1714 user, notifying about the alert. This action is typically only 1715 appropriate for server implementations. 1717 4.6. Multilingual Properties 1719 4.6.1. localizations 1721 Type: "String[PatchObject]" (optional). 1723 A map of [RFC5646] language tags to patch objects, which localize the 1724 calendar object into the locale of the respective language tag. 1726 See the description of PatchObject (Section 1.4.8) for the structure 1727 of the PatchObject. The patches are applied to the top-level 1728 calendar object. In addition, the "locale" property of the patched 1729 object is set to the language tag. All pointers for patches MUST end 1730 with one of the following suffixes; any patch that does not follow 1731 this MUST be ignored unless otherwise specified in a future RFC: 1733 o title 1735 o description 1737 o name 1739 For example, a patch to "recurrenceOverrides/2018-01- 1740 05T14:00:00/locations/abcd1234/title" is permissible, but a patch to 1741 "uid" is not. 1743 Note that this specification does not define how to maintain validity 1744 of localized content. For example, a client application changing a 1745 JSCalendar object's title property might also need to update any 1746 localizations of this property. Client implementations SHOULD 1747 provide the means to manage localizations, but how to achieve this is 1748 specific to the application's workflow and requirements. 1750 4.7. Time Zone Properties 1751 4.7.1. timeZone 1753 Type: "String|null" (optional, default: null). 1755 Identifies the time zone the object is scheduled in, or null for 1756 floating time. This is either a name from the IANA Time Zone 1757 Database [4] or the id of a custom time zone from the "timeZones" 1758 property (see Section 1.4.9). If omitted, this MUST be presumed to 1759 be null (i.e., floating time). 1761 4.7.2. timeZones 1763 Type: "String[TimeZone]" (optional). 1765 Maps identifiers of custom time zones to their time zone definition. 1766 The following restrictions apply for each key in the map: 1768 o It MUST start with the "/" character (ASCII decimal 47; also see 1769 Sections 3.2.19 of [RFC5545] and 3.6. of [RFC7808] for discussion 1770 of the forward slash character in time zone identifiers). 1772 o It MUST be a valid "paramtext" value as specified in Section 3.1. 1773 of [RFC5545]. 1775 o At least one other property in the same JSCalendar object MUST 1776 reference a time zone using this identifier (i.e. orphaned time 1777 zones are not allowed). 1779 An identifier need only be unique to this JSCalendar object. 1781 A TimeZone object maps a VTIMEZONE component from iCalendar [RFC5545] 1782 and the semantics are as defined there. A valid time zone MUST 1783 define at least one transition rule in the "standard" or "daylight" 1784 property. Its properties are: 1786 o tzId: "String" (mandatory). 1788 The TZID property from iCalendar. 1790 o lastModified: "UTCDateTime" (optional) 1792 The LAST-MODIFIED property from iCalendar. 1794 o url: "String" (optional) 1796 The TZURL property from iCalendar. 1798 o validUntil: "UTCDateTime" (optional) 1799 The TZUNTIL property from iCalendar specified in [RFC7808]. 1801 o aliases: "String[Boolean]" (optional) 1803 Maps the TZID-ALIAS-OF properties from iCalendar specified in 1804 [RFC7808] to a JSON set of aliases. The set is represented as an 1805 object, with the keys being the aliases. The value for each key 1806 in the set MUST be true. 1808 o standard: "TimeZoneRule[]" (optional) 1810 The STANDARD sub-components from iCalendar. The order MUST be 1811 preserved during conversion. 1813 o daylight: "TimeZoneRule[]" (optional). 1815 The DAYLIGHT sub-components from iCalendar. The order MUST be 1816 preserved during conversion. 1818 A TimeZoneRule object maps a STANDARD or DAYLIGHT sub-component from 1819 iCalendar, with the restriction that at most one recurrence rule is 1820 allowed per rule. It has the following properties: 1822 o start: "LocalDateTime" (mandatory) 1824 The DTSTART property from iCalendar. 1826 o offsetTo: "String" (mandatory) 1828 The TZOFFSETTO property from iCalendar. 1830 o offsetFrom: "String" (mandatory) 1832 The TZOFFSETFROM property from iCalendar. 1834 o recurrenceRule: "RecurrenceRule" (optional) 1836 The RRULE property mapped as specified in Section 4.3.2. During 1837 recurrence rule evaluation, the "until" property value MUST be 1838 interpreted as a local time in the UTC time zone. 1840 o recurrenceDates: "LocalDateTime[Boolean]" (optional) 1842 Maps the RDATE properties from iCalendar to a JSON set. The set 1843 is represented as an object, with the keys being the recurrence 1844 dates. The value for each key in the set MUST be true. 1846 o names: "String[Boolean]" (optional) 1847 Maps the TZNAME properties from iCalendar to a JSON set. The set 1848 is represented as an object, with the keys being the names. The 1849 value for each key in the set MUST be true. 1851 o comments: "String[]" (optional). Maps the COMMENT properties from 1852 iCalendar. The order MUST be preserved during conversion. 1854 5. Type-specific JSCalendar Properties 1856 5.1. JSEvent Properties 1858 In addition to the common JSCalendar object properties (Section 4) a 1859 JSEvent has the following properties: 1861 5.1.1. start 1863 Type: "LocalDateTime" (mandatory). 1865 The date/time the event starts in the event's time zone (as specified 1866 in the "timeZone" property, see Section 4.7.1). 1868 5.1.2. duration 1870 Type: "Duration" (optional, default: "PT0S"). 1872 The zero or positive duration of the event in the event's start time 1873 zone. 1875 Note that a duration specified using weeks or days does not always 1876 correspond to an exact multiple of 24 hours. The number of 1877 hours/minutes/seconds may vary if it overlaps a period of 1878 discontinuity in the event's time zone, for example a change from 1879 standard time to daylight-savings time. Leap seconds MUST NOT be 1880 considered when computing an exact duration. When computing an exact 1881 duration, the greatest order time components MUST be added first, 1882 that is, the number of days MUST be added first, followed by the 1883 number of hours, number of minutes, and number of seconds. 1884 Fractional seconds MUST be added last. These semantics match the 1885 iCalendar DURATION value type ([RFC5545], Section 3.3.6). 1887 A JSEvent MAY involve start and end locations that are in different 1888 time zones (e.g. a trans-continental flight). This can be expressed 1889 using the "relativeTo" and "timeZone" properties of the JSEvent's 1890 Location objects (see Section 4.2.5). 1892 5.1.3. status 1894 Type: "String" (optional, default: "confirmed"). 1896 The scheduling status (Section 4.4) of a JSEvent. If set, it MUST be 1897 one of: 1899 o "confirmed": Indicates the event is definitely happening. 1901 o "cancelled": Indicates the event has been cancelled. 1903 o "tentative": Indicates the event may happen. 1905 5.2. JSTask Properties 1907 In addition to the common JSCalendar object properties (Section 4) a 1908 JSTask has the following properties: 1910 5.2.1. due 1912 Type: "LocalDateTime" (optional). 1914 The date/time the task is due in the task's time zone. 1916 5.2.2. start 1918 Type: "LocalDateTime" (optional). 1920 The date/time the task should start in the task's time zone. 1922 5.2.3. estimatedDuration 1924 Type: "Duration" (optional). 1926 Specifies the estimated positive duration of time the task takes to 1927 complete. 1929 5.2.4. statusUpdatedAt 1931 Type: "UTCDateTime" (optional). 1933 Specifies the date/time the "status" property of either the task 1934 overall (Section 5.2.6) or a specific participant (Section 5.2.5) was 1935 last updated. 1937 If the task is recurring and has future instances, a client may want 1938 to keep track of the last status update timestamp of a specific task 1939 recurrence, but leave other instances unchanged. One way to achieve 1940 this is by overriding the statusUpdatedAt property in the task 1941 "recurrenceOverrides" property. However, this could produce a long 1942 list of timestamps for regularly recurring tasks. An alternative 1943 approach is to split the JSTask into a current, single instance of 1944 JSTask with this instance status update time and a future recurring 1945 instance. See also Section 4.1.3 on splitting. 1947 5.2.5. progress 1949 In addition to the common properties of a Participant object 1950 (Section 4.4.5), a Participant within a JSTask supports the following 1951 property: 1953 o progress: ParticipantProgress (optional). The progress of the 1954 participant for this task, if known. This property MUST NOT be 1955 set if the "participationStatus" of this participant is any other 1956 value but "accepted". 1958 A ParticipantProgress object has the following properties: 1960 o status: "String" (mandatory) 1962 Describes the completion status of the participant's progress. 1964 The value MUST be at most one of the following values, registered 1965 in a future RFC, or a vendor-specific value: 1967 * "completed": The participant completed this task. 1969 * "in-process": The participant has started this task. 1971 * "failed": The participant failed to complete this task. 1973 o timestamp: "UTCDateTime" (mandatory) 1975 Represents the last time the participant progress was updated. 1977 5.2.6. status 1979 Type: "String" (optional). 1981 Defines the overall status of this task. If omitted, the default 1982 status (Section 4.4) of a JSTask is defined as follows (in order of 1983 evaluation): 1985 o "completed": if the "status" property value of all participant 1986 progresses is "completed". 1988 o "failed": if at least one "status" property value of the 1989 participant progresses is "failed". 1991 o "in-process": if at least one "status" property value of the 1992 participant progresses is "in-process". 1994 o "needs-action": If none of the other criteria match. 1996 If set, it MUST be one of: 1998 o "needs-action": Indicates the task needs action. 2000 o "completed": Indicates the task is completed. 2002 o "in-process": Indicates the task is in process. 2004 o "cancelled": Indicates the task is cancelled. 2006 o "pending": Indicates the task has been created and accepted for 2007 processing, but not yet started. 2009 o "failed": Indicates the task failed. 2011 5.3. JSGroup Properties 2013 JSGroup supports the following common JSCalendar properties 2014 (Section 4): 2016 o @type 2018 o uid 2020 o created 2022 o updated 2024 o categories 2026 o keywords 2028 o title 2030 o description 2032 o color 2034 o links 2035 In addition, the following JSGroup-specific properties are supported: 2037 5.3.1. entries 2039 Type: "String[JSTask|JSEvent]" (mandatory). 2041 A collection of group members. This is represented as a map of the 2042 "uid" property value to the JSCalendar object member having that uid. 2043 Implementations MUST ignore entries of unknown type. 2045 5.3.2. source 2047 Type: "String" (optional). 2049 The source from which updated versions of this group may be retrieved 2050 from. The value MUST be a URI. 2052 6. Examples 2054 The following examples illustrate several aspects of the JSCalendar 2055 data model and format. The examples may omit mandatory or additional 2056 properties, which is indicated by a placeholder property with key 2057 "...". While most of the examples use calendar event objects, they 2058 are also illustrative for tasks. 2060 6.1. Simple Event 2062 This example illustrates a simple one-time event. It specifies a 2063 one-time event that begins on January 15, 2018 at 1pm New York local 2064 time and ends at 2pm. 2066 { 2067 "@type": "jsevent", 2068 "uid": "2a358cee-6489-4f14-a57f-c104db4dc2f1", 2069 "updated": "2018-01-01T12:00:00Z", 2070 "title": "Some event", 2071 "start": "2018-01-15T13:00:00", 2072 "timeZone": "America/New_York", 2073 "duration": "PT1H" 2074 } 2076 6.2. Simple Task 2078 This example illustrates a simple task for a plain to-do item. 2080 { 2081 "@type": "jstask", 2082 "uid": "2a358cee-6489-4f14-a57f-c104db4dc2f2", 2083 "updated": "2018-01-19T18:00:00Z", 2084 "title": "Do something" 2085 } 2087 6.3. Simple Group 2089 This example illustrates a simple calendar object group that contains 2090 an event and a task. 2092 { 2093 "@type": "jsgroup", 2094 "uid": "2a358cee-6489-4f14-a57f-c104db4dc343", 2095 "updated": "2018-01-15T18:00:00Z", 2096 "title": "A simple group", 2097 "entries": [ 2098 { 2099 "@type": "jsevent", 2100 "uid": "2a358cee-6489-4f14-a57f-c104db4dc2f1", 2101 "updated": "2018-01-15T18:00:00Z", 2102 "title": "Some event", 2103 "start": "2018-01-15T13:00:00", 2104 "timeZone": "America/New_York", 2105 "duration": "PT1H" 2106 }, 2107 { 2108 "@type": "jstask", 2109 "uid": "2a358cee-6489-4f14-a57f-c104db4dc2f2", 2110 "updated": "2018-01-15T18:00:00Z", 2111 "title": "Do something" 2112 } 2113 ] 2114 } 2116 6.4. All-day Event 2118 This example illustrates an event for an international holiday. It 2119 specifies an all-day event on April 1 that occurs every year since 2120 the year 1900. 2122 { 2123 "...": "", 2124 "title": "April Fool's Day", 2125 "showWithoutTime": true, 2126 "start": "1900-04-01T00:00:00", 2127 "duration": "P1D", 2128 "recurrenceRule": { 2129 "frequency": "yearly" 2130 } 2131 } 2133 6.5. Task with a Due Date 2135 This example illustrates a task with a due date. It is a reminder to 2136 buy groceries before 6pm Vienna local time on January 19, 2018. The 2137 calendar user expects to need 1 hour for shopping. 2139 { 2140 "...": "", 2141 "title": "Buy groceries", 2142 "due": "2018-01-19T18:00:00", 2143 "timeZone": "Europe/Vienna", 2144 "estimatedDuration": "PT1H" 2145 } 2147 6.6. Event with End Time Zone 2149 This example illustrates the use of end time-zones by use of an 2150 international flight. The flight starts on April 1, 2018 at 9am in 2151 Berlin local time. The duration of the flight is scheduled at 10 2152 hours 30 minutes. The time at the flights destination is in the same 2153 time-zone as Tokyo. Calendar clients could use the end time-zone to 2154 display the arrival time in Tokyo local time and highlight the time- 2155 zone difference of the flight. The location names can serve as input 2156 for navigation systems. 2158 { 2159 "...": "", 2160 "title": "Flight XY51 to Tokyo", 2161 "start": "2018-04-01T09:00:00", 2162 "timeZone": "Europe/Berlin", 2163 "duration": "PT10H30M", 2164 "locations": { 2165 "2a358cee-6489-4f14-a57f-c104db4dc2f1": { 2166 "rel": "start", 2167 "name": "Frankfurt Airport (FRA)" 2168 }, 2169 "c2c7ac67-dc13-411e-a7d4-0780fb61fb08": { 2170 "rel": "end", 2171 "name": "Narita International Airport (NRT)", 2172 "timeZone": "Asia/Tokyo" 2173 } 2174 } 2175 } 2177 6.7. Floating-time Event (with Recurrence) 2179 This example illustrates the use of floating-time. Since January 1, 2180 2018, a calendar user blocks 30 minutes every day to practice Yoga at 2181 7am local time, in whatever time-zone the user is located on that 2182 date. 2184 { 2185 "...": "", 2186 "title": "Yoga", 2187 "start": "2018-01-01T07:00:00", 2188 "duration": "PT30M", 2189 "recurrenceRule": { 2190 "frequency": "daily" 2191 } 2192 } 2194 6.8. Event with Multiple Locations and Localization 2196 This example illustrates an event that happens at both a physical and 2197 a virtual location. Fans can see a live convert on premises or 2198 online. The event title and descriptions are localized. 2200 { 2201 "...": "", 2202 "title": "Live from Music Bowl: The Band", 2203 "description": "Go see the biggest music event ever!", 2204 "locale": "en", 2205 "start": "2018-07-04T17:00:00", 2206 "timeZone": "America/New_York", 2207 "duration": "PT3H", 2208 "locations": { 2209 "c0503d30-8c50-4372-87b5-7657e8e0fedd": { 2210 "name": "The Music Bowl", 2211 "description": "Music Bowl, Central Park, New York", 2212 "coordinates": "geo:40.7829,73.9654" 2213 } 2214 }, 2215 "virtualLocations": { 2216 "6f3696c6-1e07-47d0-9ce1-f50014b0041a": { 2217 "name": "Free live Stream from Music Bowl", 2218 "uri": "https://stream.example.com/the_band_2018" 2219 } 2220 }, 2221 "localizations": { 2222 "de": { 2223 "title": "Live von der Music Bowl: The Band!", 2224 "description": "Schau dir das groesste Musikereignis an!", 2225 "virtualLocations/6f3696c6-1e07-47d0-9ce1-f50014b0041a/name": 2226 "Gratis Live-Stream aus der Music Bowl" 2227 } 2228 } 2229 } 2231 6.9. Recurring Event with Overrides 2233 This example illustrates the use of recurrence overrides. A math 2234 course at a University is held for the first time on January 8, 2018 2235 at 9am London time and occurs every week until June 25, 2018 2236 (inclusive). Each lecture lasts for one hour and thirty minutes and 2237 is located at the Mathematics department. This event has exceptional 2238 occurrences: at the last occurrence of the course is an exam, which 2239 lasts for 2 hours and starts at 10am. Also, the location of the exam 2240 differs from the usual location. On April 2 no course is held. On 2241 January 5 at 2pm is an optional introduction course, that occurs 2242 before the first regular lecture. 2244 { 2245 "...": "", 2246 "title": "Calculus I", 2247 "start": "2018-01-08T09:00:00", 2248 "timeZone": "Europe/London", 2249 "duration": "PT1H30M", 2250 "locations": { 2251 "2a358cee-6489-4f14-a57f-c104db4dc2f1": { 2252 "title": "Math lab room 1", 2253 "description": "Math Lab I, Department of Mathematics\n1 University Drive" 2254 } 2255 }, 2256 "recurrenceRule": { 2257 "frequency": "weekly", 2258 "until": "2018-06-25T09:00:00" 2259 }, 2260 "recurrenceOverrides": { 2261 "2018-01-05T14:00:00": { 2262 "title": "Introduction to Calculus I (optional)" 2263 }, 2264 "2018-04-02T09:00:00": { 2265 "excluded": true 2266 }, 2267 "2018-06-25T09:00:00": { 2268 "title": "Calculus I Exam", 2269 "start": "2018-06-25T10:00:00", 2270 "duration": "PT2H", 2271 "locations": { 2272 "2a358cee-6489-4f14-a57f-c104db4dc2f1": { 2273 "title": "Big Auditorium", 2274 "description": "Big Auditorium, Other Road" 2275 } 2276 } 2277 } 2278 } 2279 } 2281 6.10. Recurring Event with Participants 2283 This example illustrates scheduled events. A team meeting occurs 2284 every week since January 8, 2018 at 9am Johannesburg time. The event 2285 owner also chairs the event. Participants meet in a virtual meeting 2286 room. An attendee has accepted the invitation, but on March 8, 2018 2287 he is unavailable and declined participation for this occurrence, 2288 leaving a short explanation for the organizer. 2290 { 2291 "...": "", 2292 "title": "FooBar team meeting", 2293 "start": "2018-01-08T09:00:00", 2294 "timeZone": "Africa/Johannesburg", 2295 "duration": "PT1H", 2296 "virtualLocations": { 2297 "2a358cee-6489-4f14-a57f-c104db4dc2f1": { 2298 "name": "ChatMe meeting room", 2299 "uri": "https://chatme.example.com?id=1234567" 2300 } 2301 }, 2302 "recurrenceRule": { 2303 "frequency": "weekly" 2304 }, 2305 "replyTo": { 2306 "imip": "mailto:6489-4f14-a57f-c1@schedule.example.com" 2307 }, 2308 "participants": { 2309 "dG9tQGZvb2Jhci5leGFtcGxlLmNvbQ": { 2310 "name": "Tom Tool", 2311 "email": "tom@foobar.example.com", 2312 "sendTo": { 2313 "imip": "mailto:41f3-8b10-516a4d0f42bc@calendar.example.com" 2314 }, 2315 "participationStatus": "accepted", 2316 "roles": { 2317 "attendee": true 2318 } 2319 }, 2320 "em9lQGZvb2Jhci5leGFtcGxlLmNvbQ": { 2321 "name": "Zoe Zelda", 2322 "email": "zoe@foobar.example.com", 2323 "sendTo": { 2324 "imip": "mailto:zoe@foobar.example.com" 2325 }, 2326 "participationStatus": "accepted", 2327 "roles": { 2328 "owner": true, 2329 "attendee": true, 2330 "chair": true 2331 } 2332 }, 2333 "...": "" 2334 }, 2335 "recurrenceOverrides": { 2336 "2018-03-08T09:00:00": { 2337 "participants/dG9tQGZvb2Jhci5leGFtcGxlLmNvbQ/participationStatus": 2338 "declined", 2339 "participants/dG9tQGZvb2Jhci5leGFtcGxlLmNvbQ/participationComment": 2341 "Sorry, kid's recital this week, can't make it." 2342 } 2343 } 2344 } 2346 7. Security Considerations 2348 Calendaring and scheduling information is very privacy-sensitive. 2349 The transmission of such information must be careful to protect it 2350 from possible threats, such as eavesdropping, replay, message 2351 insertion, deletion, modification, and man-in-the-middle attacks. 2352 This document just defines the data format; such considerations are 2353 primarily the concern of the API or method of storage and 2354 transmission of such files. 2356 7.1. Expanding Recurrences 2358 A recurrence rule may produce infinite occurrences of an event. 2359 Implementations MUST handle expansions carefully to prevent 2360 accidental or deliberate resource exhaustion. 2362 Conversely, a recurrence rule may be specified that does not expand 2363 to anything. It is not always possible to tell this through static 2364 analysis of the rule, so implementations MUST be careful to avoid 2365 getting stuck in an infinite loop, or otherwise exhausting resources, 2366 searching for the next occurrence. 2368 7.2. JSON Parsing 2370 The Security Considerations of [RFC8259] apply to the use of JSON as 2371 the data interchange format. 2373 As for any serialization format, parsers need to thoroughly check the 2374 syntax of the supplied data. JSON uses opening and closing tags for 2375 several types and structures, and it is possible that the end of the 2376 supplied data will be reached when scanning for a matching closing 2377 tag; this is an error condition, and implementations need to stop 2378 scanning at the end of the supplied data. 2380 JSON also uses a string encoding with some escape sequences to encode 2381 special characters within a string. Care is needed when processing 2382 these escape sequences to ensure that they are fully formed before 2383 the special processing is triggered, with special care taken when the 2384 escape sequences appear adjacent to other (non-escaped) special 2385 characters or adjacent to the end of data (as in the previous 2386 paragraph). 2388 If parsing JSON into a non-textual structured data format, 2389 implementations may need to allocate storage to hold JSON string 2390 elements. Since JSON does not use explicit string lengths, the risk 2391 of denial of service due to resource exhaustion is small, but 2392 implementations may still wish to place limits on the size of 2393 allocations they are willing to make in any given context, to avoid 2394 untrusted data causing excessive memory allocation. 2396 7.3. URI Values 2398 Several JSCalendar properties contain URIs as values, and processing 2399 these properties requires extra care. Section 7 of [RFC3986] 2400 discusses security risk related to URIs. 2402 8. IANA Considerations 2404 This document defines a MIME media type for use with JSCalendar data 2405 formatted in JSON. 2407 Type name: application 2409 Subtype name: jscalendar+json 2411 Required parameters: type 2413 The "type" parameter conveys the type of the JSCalendar data in 2414 the body part, with the value being one of "jsevent", "jstask", or 2415 "jsgroup". The parameter MUST NOT occur more than once. It MUST 2416 match the value of the "@type" property of the JSON-formatted 2417 JSCalendar object in the body. 2419 Optional parameters: none 2421 Encoding considerations: Same as encoding considerations of 2422 application/json as specified in RFC8529, Section 11 [RFC8259]. 2424 Security considerations: See Section 7 of this document. 2426 Interoperability considerations: This media type provides an 2427 alternative to iCalendar, jCal and proprietary JSON-based 2428 calendaring data formats. 2430 Published specification: This specification. 2432 Applications that use this media type: Applications that currently 2433 make use of the text/calendar and application/calendar+json media 2434 types can use this as an alternative. Similarly, applications 2435 that use the application/json media type to transfer calendaring 2436 data can use this to further specify the content. 2438 Fragment identifier considerations: N/A 2440 Additional information: 2442 Magic number(s): N/A 2444 File extensions(s): N/A 2446 Macintosh file type code(s): N/A 2448 Person & email address to contact for further information: 2449 calext@ietf.org 2451 Intended usage: COMMON 2453 Restrictions on usage: N/A 2455 Author: See the "Author's Address" section of this document. 2457 Change controller: IETF 2459 9. Acknowledgments 2461 The authors would like to thank the members of CalConnect for their 2462 valuable contributions. This specification originated from the work 2463 of the API technical committee of CalConnect, the Calendaring and 2464 Scheduling Consortium. 2466 10. References 2468 10.1. Normative References 2470 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2471 Requirement Levels", BCP 14, RFC 2119, 2472 DOI 10.17487/RFC2119, March 1997, 2473 . 2475 [RFC2392] Levinson, E., "Content-ID and Message-ID Uniform Resource 2476 Locators", RFC 2392, DOI 10.17487/RFC2392, August 1998, 2477 . 2479 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 2480 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 2481 . 2483 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2484 Resource Identifier (URI): Generic Syntax", STD 66, 2485 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2486 . 2488 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 2489 Unique IDentifier (UUID) URN Namespace", RFC 4122, 2490 DOI 10.17487/RFC4122, July 2005, 2491 . 2493 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 2494 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 2495 . 2497 [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, 2498 "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, 2499 DOI 10.17487/RFC4791, March 2007, 2500 . 2502 [RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and 2503 Scheduling Core Object Specification (iCalendar)", 2504 RFC 5545, DOI 10.17487/RFC5545, September 2009, 2505 . 2507 [RFC5546] Daboo, C., Ed., "iCalendar Transport-Independent 2508 Interoperability Protocol (iTIP)", RFC 5546, 2509 DOI 10.17487/RFC5546, December 2009, 2510 . 2512 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 2513 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 2514 September 2009, . 2516 [RFC5870] Mayrhofer, A. and C. Spanring, "A Uniform Resource 2517 Identifier for Geographic Locations ('geo' URI)", 2518 RFC 5870, DOI 10.17487/RFC5870, June 2010, 2519 . 2521 [RFC6047] Melnikov, A., Ed., "iCalendar Message-Based 2522 Interoperability Protocol (iMIP)", RFC 6047, 2523 DOI 10.17487/RFC6047, December 2010, 2524 . 2526 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 2527 Specifications and Registration Procedures", BCP 13, 2528 RFC 6838, DOI 10.17487/RFC6838, January 2013, 2529 . 2531 [RFC6901] Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., 2532 "JavaScript Object Notation (JSON) Pointer", RFC 6901, 2533 DOI 10.17487/RFC6901, April 2013, 2534 . 2536 [RFC7265] Kewisch, P., Daboo, C., and M. Douglass, "jCal: The JSON 2537 Format for iCalendar", RFC 7265, DOI 10.17487/RFC7265, May 2538 2014, . 2540 [RFC7493] Bray, T., Ed., "The I-JSON Message Format", RFC 7493, 2541 DOI 10.17487/RFC7493, March 2015, 2542 . 2544 [RFC7529] Daboo, C. and G. Yakushev, "Non-Gregorian Recurrence Rules 2545 in the Internet Calendaring and Scheduling Core Object 2546 Specification (iCalendar)", RFC 7529, 2547 DOI 10.17487/RFC7529, May 2015, 2548 . 2550 [RFC7808] Douglass, M. and C. Daboo, "Time Zone Data Distribution 2551 Service", RFC 7808, DOI 10.17487/RFC7808, March 2016, 2552 . 2554 [RFC7986] Daboo, C., "New Properties for iCalendar", RFC 7986, 2555 DOI 10.17487/RFC7986, October 2016, 2556 . 2558 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 2559 Interchange Format", STD 90, RFC 8259, 2560 DOI 10.17487/RFC8259, December 2017, 2561 . 2563 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 2564 DOI 10.17487/RFC8288, October 2017, 2565 . 2567 10.2. Informative References 2569 [MIME] "IANA Media Types", . 2572 10.3. URIs 2574 [1] https://www.iana.org/time-zones 2576 [2] https://www.iana.org/assignments/link-relations/link- 2577 relations.xhtml 2579 [3] https://www.w3.org/TR/2011/REC-css3-color-20110607/#svg-color 2581 [4] https://www.iana.org/time-zones 2583 Authors' Addresses 2585 Neil Jenkins 2586 Fastmail 2587 PO Box 234 2588 Collins St West 2589 Melbourne VIC 8007 2590 Australia 2592 Email: neilj@fastmailteam.com 2593 URI: https://www.fastmail.com 2595 Robert Stepanek 2596 Fastmail 2597 PO Box 234 2598 Collins St West 2599 Melbourne VIC 8007 2600 Australia 2602 Email: rsto@fastmailteam.com 2603 URI: https://www.fastmail.com