idnits 2.17.1 draft-ietf-calext-jscalendar-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (May 25, 2018) is 2163 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 2543 -- Looks like a reference, but probably isn't: '2' on line 2545 -- Looks like a reference, but probably isn't: '3' on line 2548 -- Looks like a reference, but probably isn't: '4' on line 2550 Summary: 0 errors (**), 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: November 26, 2018 May 25, 2018 7 JSCalendar: A JSON representation of calendar data 8 draft-ietf-calext-jscalendar-04 10 Abstract 12 This specification defines a data model and JSON representation of 13 calendar data that can be used for storage and data exchange in a 14 calendaring and scheduling environment. It aims to be an alternative 15 to the widely deployed iCalendar data format and to be unambiguous, 16 extendable and simple to process. 18 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at https://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on November 26, 2018. 35 Copyright Notice 37 Copyright (c) 2018 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (https://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 53 1.1. Relation to the iCalendar format . . . . . . . . . . . . 4 54 1.2. Notational Conventions . . . . . . . . . . . . . . . . . 5 55 2. JSCalendar objects . . . . . . . . . . . . . . . . . . . . . 5 56 2.1. JSEvent . . . . . . . . . . . . . . . . . . . . . . . . . 5 57 2.2. JSTask . . . . . . . . . . . . . . . . . . . . . . . . . 5 58 2.3. JSGroup . . . . . . . . . . . . . . . . . . . . . . . . . 6 59 3. Structure of JSCalendar objects . . . . . . . . . . . . . . . 6 60 3.1. Type signatures . . . . . . . . . . . . . . . . . . . . . 6 61 3.2. Data Types . . . . . . . . . . . . . . . . . . . . . . . 7 62 3.2.1. UTCDate . . . . . . . . . . . . . . . . . . . . . . . 7 63 3.2.2. LocalDate . . . . . . . . . . . . . . . . . . . . . . 7 64 3.2.3. Duration . . . . . . . . . . . . . . . . . . . . . . 7 65 3.2.4. PatchObject . . . . . . . . . . . . . . . . . . . . . 8 66 3.2.5. Identifiers . . . . . . . . . . . . . . . . . . . . . 8 67 3.2.6. Normalisation and equivalence . . . . . . . . . . . . 8 68 3.3. Custom property extensions and values . . . . . . . . . . 9 69 4. Common JSCalendar properties . . . . . . . . . . . . . . . . 9 70 4.1. Metadata properties . . . . . . . . . . . . . . . . . . . 9 71 4.1.1. @type . . . . . . . . . . . . . . . . . . . . . . . . 9 72 4.1.2. uid . . . . . . . . . . . . . . . . . . . . . . . . . 10 73 4.1.3. relatedTo . . . . . . . . . . . . . . . . . . . . . . 10 74 4.1.4. prodId . . . . . . . . . . . . . . . . . . . . . . . 11 75 4.1.5. created . . . . . . . . . . . . . . . . . . . . . . . 11 76 4.1.6. updated . . . . . . . . . . . . . . . . . . . . . . . 11 77 4.1.7. sequence . . . . . . . . . . . . . . . . . . . . . . 12 78 4.1.8. method . . . . . . . . . . . . . . . . . . . . . . . 12 79 4.2. What and where properties . . . . . . . . . . . . . . . . 12 80 4.2.1. title . . . . . . . . . . . . . . . . . . . . . . . . 12 81 4.2.2. description . . . . . . . . . . . . . . . . . . . . . 12 82 4.2.3. htmlDescription . . . . . . . . . . . . . . . . . . . 12 83 4.2.4. locations . . . . . . . . . . . . . . . . . . . . . . 12 84 4.2.5. links . . . . . . . . . . . . . . . . . . . . . . . . 14 85 4.2.6. locale . . . . . . . . . . . . . . . . . . . . . . . 16 86 4.2.7. keywords . . . . . . . . . . . . . . . . . . . . . . 16 87 4.2.8. categories . . . . . . . . . . . . . . . . . . . . . 16 88 4.2.9. color . . . . . . . . . . . . . . . . . . . . . . . . 16 89 4.3. Recurrence properties . . . . . . . . . . . . . . . . . . 16 90 4.3.1. recurrenceRule . . . . . . . . . . . . . . . . . . . 17 91 4.3.2. recurrenceOverrides . . . . . . . . . . . . . . . . . 21 92 4.3.3. excluded . . . . . . . . . . . . . . . . . . . . . . 22 93 4.4. Sharing and scheduling properties . . . . . . . . . . . . 22 94 4.4.1. priority . . . . . . . . . . . . . . . . . . . . . . 22 95 4.4.2. freeBusyStatus . . . . . . . . . . . . . . . . . . . 23 96 4.4.3. privacy . . . . . . . . . . . . . . . . . . . . . . . 23 97 4.4.4. replyTo . . . . . . . . . . . . . . . . . . . . . . . 24 98 4.4.5. participants . . . . . . . . . . . . . . . . . . . . 25 99 4.5. Alerts properties . . . . . . . . . . . . . . . . . . . . 28 100 4.5.1. useDefaultAlerts . . . . . . . . . . . . . . . . . . 28 101 4.5.2. alerts . . . . . . . . . . . . . . . . . . . . . . . 28 102 4.6. Multilingual properties . . . . . . . . . . . . . . . . . 31 103 4.6.1. localizations . . . . . . . . . . . . . . . . . . . . 31 104 5. Type-specific JSCalendar properties . . . . . . . . . . . . . 32 105 5.1. JSEvent properties . . . . . . . . . . . . . . . . . . . 32 106 5.1.1. start . . . . . . . . . . . . . . . . . . . . . . . . 32 107 5.1.2. timeZone . . . . . . . . . . . . . . . . . . . . . . 32 108 5.1.3. duration . . . . . . . . . . . . . . . . . . . . . . 32 109 5.1.4. isAllDay . . . . . . . . . . . . . . . . . . . . . . 33 110 5.1.5. status . . . . . . . . . . . . . . . . . . . . . . . 33 111 5.2. JSTask properties . . . . . . . . . . . . . . . . . . . . 33 112 5.2.1. due . . . . . . . . . . . . . . . . . . . . . . . . . 33 113 5.2.2. start . . . . . . . . . . . . . . . . . . . . . . . . 34 114 5.2.3. timeZone . . . . . . . . . . . . . . . . . . . . . . 34 115 5.2.4. estimatedDuration . . . . . . . . . . . . . . . . . . 34 116 5.2.5. completed . . . . . . . . . . . . . . . . . . . . . . 34 117 5.2.6. isAllDay . . . . . . . . . . . . . . . . . . . . . . 34 118 5.2.7. progress . . . . . . . . . . . . . . . . . . . . . . 35 119 5.2.8. status . . . . . . . . . . . . . . . . . . . . . . . 35 120 5.3. JSGroup properties . . . . . . . . . . . . . . . . . . . 36 121 5.3.1. entries . . . . . . . . . . . . . . . . . . . . . . . 37 122 5.3.2. source . . . . . . . . . . . . . . . . . . . . . . . 37 123 6. Conversion from and to iCalendar . . . . . . . . . . . . . . 37 124 6.1. JSEvent . . . . . . . . . . . . . . . . . . . . . . . . . 37 125 6.2. JSTask . . . . . . . . . . . . . . . . . . . . . . . . . 38 126 6.3. JSGroup . . . . . . . . . . . . . . . . . . . . . . . . . 40 127 6.4. Common properties . . . . . . . . . . . . . . . . . . . . 40 128 6.5. Locations and participants . . . . . . . . . . . . . . . 43 129 6.6. Unknown properties . . . . . . . . . . . . . . . . . . . 45 130 7. JSCalendar object examples . . . . . . . . . . . . . . . . . 46 131 7.1. Simple event . . . . . . . . . . . . . . . . . . . . . . 46 132 7.2. Simple task . . . . . . . . . . . . . . . . . . . . . . . 46 133 7.3. Simple group . . . . . . . . . . . . . . . . . . . . . . 46 134 7.4. All-day event . . . . . . . . . . . . . . . . . . . . . . 47 135 7.5. Task with a due date . . . . . . . . . . . . . . . . . . 47 136 7.6. Event with end time-zone . . . . . . . . . . . . . . . . 48 137 7.7. Floating-time event (with recurrence) . . . . . . . . . . 48 138 7.8. Event with multiple locations and localization . . . . . 49 139 7.9. Recurring event with overrides . . . . . . . . . . . . . 50 140 7.10. Recurring event with participants . . . . . . . . . . . . 51 141 8. Security Considerations . . . . . . . . . . . . . . . . . . . 53 142 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 53 143 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 53 144 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 53 145 11.1. Normative References . . . . . . . . . . . . . . . . . . 53 146 11.2. Informative References . . . . . . . . . . . . . . . . . 55 147 11.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 56 148 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 56 150 1. Introduction 152 This document defines a data model for calendar event and task 153 objects, or groups of such objects, in electronic calendar 154 applications and systems. It aims to be unambiguous, extendable and 155 simple to process. 157 The key design considerations for this data model are as follows: 159 o The attributes of the calendar entry represented must be described 160 as a simple key-value pair, reducing complexity of its 161 representation. 163 o The data model should avoid all ambiguities and make it difficult 164 to make mistakes during implementation. 166 o Most of the initial set of attributes should be taken from the 167 iCalendar data format ([RFC5545], also see Section 1.1), but the 168 specification should add new attributes or value types, or not 169 support existing ones, where appropriate. Conversion between the 170 data formats need not fully preserve semantic meaning. 172 o Extensions, such as new properties and components, MUST NOT lead 173 to requiring an update to this document. 175 The representation of this data model is defined in the I-JSON format 176 [RFC7493], which is a strict subset of the JavaScript Object Notation 177 (JSON) Data Interchange Format [RFC8259]. Using JSON mostly is a 178 pragmatic choice: its widespread use should help to speed up 179 JSCalendar adoption and a wide range of production-ready JSON 180 implementations allows to decrease interoperability issues. 182 1.1. Relation to the iCalendar format 184 The iCalendar data format [RFC5545], a widely deployed interchange 185 format for calendaring and scheduling data, has served calendaring 186 vendors for a long while, but contains some ambiguities and pitfalls 187 that can not be overcome without backward-incompatible changes. 189 For example, iCalendar defines various formats for local times, UTC 190 time and dates, which confuses new users. Other sources for errors 191 are the requirement for custom time-zone definitions within a single 192 calendar component, as well as the iCalendar format itself; the 193 latter causing interoperability issues due to misuse of CR LF 194 terminated strings, line continuations and subtle differences between 195 iCalendar parsers. Lastly, up until recently the iCalendar format 196 did not allow to express the difference between two calendar 197 components, which results in verbose exchanges during scheduling. 199 Some of these issues were addressed by the jCal [RFC7265] format, 200 which is a direct mapping between iCalendar and JSON. However, it 201 did not attempt to extend or update iCalendar semantics. 203 1.2. Notational Conventions 205 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 206 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 207 document are to be interpreted as described in [RFC2119]. 209 The underlying format used for this specification is JSON. 210 Consequently, the terms "object" and "array" as well as the four 211 primitive types (strings, numbers, booleans, and null) are to be 212 interpreted as described in Section 1 of[RFC8259]. 214 Some examples in this document contain "partial" JSON documents used 215 for illustrative purposes. In these examples, three periods "..." 216 are used to indicate a portion of the document that has been removed 217 for compactness. 219 2. JSCalendar objects 221 This section describes the calendar object types specified by 222 JSCalendar. 224 2.1. JSEvent 226 MIME type: "application/calendar+json;type=jsevent" 228 A JSEvent represents a scheduled amount of time on a calendar, 229 typically a meeting, appointment, reminder or anniversary. Multiple 230 participants may partake in the event at multiple locations. 232 The @type (Section 4.1.1) property value MUST be "jsevent". 234 2.2. JSTask 236 MIME type: "application/calendar+json;type=jstask" 238 A JSTask represents an action-item, assignment, to-do or work item . 240 The @type (Section 4.1.1) property value MUST be "jstask". 242 A JSTask may start and be due at certain points in time, may take 243 some estimated time to complete and may recur; none of which is 244 required. This notably differs from JSEvent (Section 2.1) which is 245 required to start at a certain point in time and typically takes some 246 non-zero duration to complete. 248 2.3. JSGroup 250 MIME type: "application/calendar+json;type=jsgroup" 252 A JSGroup is a collection of JSEvent (Section 2.1) and JSTask 253 (Section 2.2) objects. Typically, objects are grouped by topic (e.g. 254 by keywords) or calendar membership. 256 The @type (Section 4.1.1) property value MUST be "jsgroup". 258 3. Structure of JSCalendar objects 260 A JSCalendar object is a JSON object, which MUST be valid I-JSON (a 261 stricter subset of JSON), as specified in [RFC8259]. Property names 262 and values are case-sensitive. 264 The object has a collection of properties, as specified in the 265 following sections. Unless otherwise specified, all properties are 266 optional; omitted properties MUST be treated identically to if that 267 property had the value of "null", unless otherwise specified. 269 3.1. Type signatures 271 Types signatures are given for all JSON objects in this document. 272 The following conventions are used: 274 o "Boolean|String": The value is either a JSON "Boolean" value, or a 275 JSON "String" value. 277 o "Foo": Any name that is not a native JSON type means an object for 278 which the properties (and their types) are defined elsewhere 279 within this document. 281 o "Foo[]": An array of objects of type "Foo". 283 o "String[Foo]": A JSON "Object" being used as a map (associative 284 array), where all the values are of type "Foo". 286 3.2. Data Types 288 In addition to the standard JSON data types, the following data types 289 are used in this specification: 291 3.2.1. UTCDate 293 This is a string in [RFC3339] "date-time" format, with the further 294 restrictions that any letters MUST be in upper-case, the time 295 component MUST be included and the time MUST be in UTC. Fractional 296 second values MUST NOT be included unless non-zero and MUST NOT have 297 trailing zeros, to ensure there is only a single representation for 298 each date-time. 300 For example "2010-10-10T10:10:10.003Z" is OK, but 301 "2010-10-10T10:10:10.000Z" is invalid and MUST be encoded as 302 "2010-10-10T10:10:10Z". 304 In common notation, it should be of the form "YYYY-MM-DDTHH:MM:SSZ". 306 3.2.2. LocalDate 308 This is a date-time string _with no time-zone/offset information_. 309 It is otherwise in the same format as UTCDate: "YYYY-MM-DDTHH:MM:SS". 310 The time-zone to associate the LocalDate with comes from an 311 associated property, or if no time-zone is associated it defines 312 _floating time_. Floating date-times are not tied to any specific 313 time-zone. Instead, they occur in every timezone at the same _wall- 314 clock_ time (as opposed to the same instant point in time). 316 3.2.3. Duration 318 A duration is represented by a subset of ISO8601 duration format, as 319 specified by the following ABNF: 321 dur-secfrac = "." 1*DIGIT 322 dur-second = 1*DIGIT [dur-secfrac] "S" 323 dur-minute = 1*DIGIT "M" [dur-second] 324 dur-hour = 1*DIGIT "H" [dur-minute] 325 dur-time = "T" (dur-hour / dur-minute / dur-second) 326 dur-day = 1*DIGIT "D" 328 duration = "P" (dur-day [dur-time] / dur-time) 330 In addition, the duration MUST NOT include fractional second values 331 unless the fraction is non-zero. A zero duration MUST be represented 332 as "P0D". 334 3.2.4. PatchObject 336 A *PatchObject* is of type "String[*|null]", and represents an 337 unordered set of patches on a JSON object. The keys are a path in a 338 subset of [RFC6901] JSON pointer format, with an implicit leading "/" 339 (i.e. prefix each key with "/" before applying the JSON pointer 340 evaluation algorithm). 342 A patch within a PatchObject is only valid, if all of the following 343 conditions apply: 345 1. The pointer MUST NOT reference inside an array (i.e. it MUST NOT 346 insert/delete from an array; the array MUST be replaced in its 347 entirety instead). 349 2. When evaluating a path, all parts prior to the last (i.e. the 350 value after the final slash) MUST exist. 352 3. There MUST NOT be two patches in the PatchObject where the 353 pointer of one is the prefix of the pointer of the other, e.g. 354 "alerts/1/offset" and "alerts". 356 The value associated with each pointer is either: 358 o "null": Remove the property from the patched object. If not 359 present in the parent, this a no-op. 361 o Anything else: The value to replace the inherited property on the 362 patch object with (if present) or add to the property (if not 363 present). 365 Implementations MUST reject a PatchObject if any of its patches are 366 invalid. 368 3.2.5. Identifiers 370 If not noted otherwise, properties that define identifiers MUST be 371 string values, MUST be at least 1 character in length and maximum 256 372 octets in size, and MUST only contain characters from the "URL and 373 Filename safe" Base 64 Alphabet, as defined in section 5 of 374 [RFC4648]. This is the ASCII alphanumeric characters (A-Za-z0-9), 375 hyphen (-), and underscore (_). 377 3.2.6. Normalisation and equivalence 379 JSCalendar aims to provide unambiguous definitions for value types 380 and properties, but does not define a general normalisation or 381 equivalence method for JSCalendar objects and types. This is because 382 the notion of equivalence might range from byte-level equivalence to 383 semantic equivalence, depending on the respective use case (for 384 example, the CalDAV protocol [RFC4791] requires octet equivalence of 385 the encoded calendar object to determine ETag equivalence). 387 Normalisation of JSCalendar objects is hindered because of the 388 following reasons: 390 o Custom JSCalendar properties may contain arbitrary JSON values, 391 including arrays. However, equivalence of arrays might or might 392 not depend on the order of elements, depending on the respective 393 property definition. 395 o Several JSCalendar property values are defined as URIs and MIME 396 types, but normalisation of these types is inherently protocol and 397 scheme-specific, depending on the use-case of the equivalence 398 definition (see section 6 of [RFC3986]). 400 Considering this, the definition of equivalence and normalisation is 401 left to client and server implementations and to be negotiated by a 402 calendar exchange protocol or defined by another RFC. 404 3.3. Custom property extensions and values 406 Vendors MAY add additional properties to the calendar object to 407 support their custom features. The names of these properties MUST be 408 prefixed with a domain name controlled by the vendor to avoid 409 conflict, e.g. "example.com/customprop". 411 Some JSCalendar properties allow vendor-specific value extensions. 412 If so, vendor specific values MUST be prefixed with a domain name 413 controlled by the vendor, e.g. "example.com/customrel", unless 414 otherwise noted. 416 4. Common JSCalendar properties 418 This section describes the properties that are common to the various 419 JSCalendar object types. Specific JSCalendar object types may only 420 support a subset of these properties. The object type definitions in 421 section Section 5 describe the set of supported properties per type. 423 4.1. Metadata properties 425 4.1.1. @type 427 Type: "String" 428 Specifies the type which this object represents. This MUST be one of 429 the following values, registered in a future RFC, or a vendor- 430 specific value: 432 o "jsevent": a JSCalendar event (Section 2.1). 434 o "jstask": a JSCalendar task (Section 2.2). 436 o "jsgroup": a JSCalendar group (Section 2.3). 438 A valid JSCalendar object MUST include this property. 440 4.1.2. uid 442 Type: "String" 444 A globally unique identifier, used to associate the object as the 445 same across different systems, calendars and views. The value of 446 this property MUST be unique across _all_ JSCalendar objects, even if 447 they are of different type. [RFC4122] describes a range of 448 established algorithms to generate universally unique identifiers 449 (UUID), and the random or pseudo-random version is recommended to 450 use. 452 For compatibility with [RFC5545] UIDs, implementations MUST be able 453 to receive and persist values of at least 255 octets for this 454 property, but they MUST NOT truncate values in the middle of a UTF-8 455 multi-octet sequence. 457 A valid JSCalendar object MUST include this property. 459 4.1.3. relatedTo 461 Type: "String[Relation]|null" 463 Relates the object to other JSCalendar objects. This is represented 464 as a map of the uids of the related objects to information about the 465 relation. 467 A *Relation* object has the following properties: 469 o *relation*: "String[]" Describes how the linked object is related 470 to this object. 472 The strings in the array MUST each be at most one of the following 473 values, registered in a future RFC, or a vendor-specific value: 475 * "first": The linked object is the first in the series this 476 object is part of. 478 * "next": The linked object is the next in the series this object 479 is part of. 481 * "child": The linked object is a subpart of this object. 483 * "parent": This object is part of the overall linked object. 485 If an object is split to make a "this and future" change to a 486 recurrence, the original object MUST be truncated to end at the 487 previous occurrence before this split, and a new object created to 488 represent all the objects after the split. A "relation=["next"]" 489 relatedTo property MUST be set on the original object with the uid of 490 the new object. A "relation=["first"]" relatedTo property with the 491 UID of the first object in the series MUST be set on the new object. 492 Clients can then follow these UIDs to get the complete set of objects 493 if the user wishes to modify them all at once. 495 4.1.4. prodId 497 Type: "String|null" 499 The identifier for the product that created the JSCalendar object. 501 The vendor of the implementation SHOULD ensure that this is a 502 globally unique identifier, using some technique such as an FPI 503 value, as defined in [ISO.9070.1991]. It MUST only use characters of 504 an iCalendar TEXT data value (see section 3.3.11 in [RFC5545]). 506 This property SHOULD NOT be used to alter the interpretation of an 507 JSCalendar object beyond the semantics specified in this document. 508 For example, it is not to be used to further the understanding of 509 non-standard properties. 511 4.1.5. created 513 Type: "UTCDate|null" 515 The date and time this object was initially created. 517 4.1.6. updated 519 Type: "UTCDate" 521 The date and time the data in this object was last modified. 523 4.1.7. sequence 525 Type: "Number" (Defaults to "0" if omitted) 527 Initially zero, this MUST be a non-negative integer that is 528 monotonically incremented each time a change is made to the object. 530 4.1.8. method 532 Type: "String|null" 534 The iTIP ([RFC5546]) method, in lower-case. Used for scheduling. 536 4.2. What and where properties 538 4.2.1. title 540 Type: "String" (Defaults to the empty string if omitted) 542 A short summary of the object. 544 4.2.2. description 546 Type: "String" (Defaults to the empty string if omitted) 548 A longer form description of the object. This is plain text, but a 549 client SHOULD attempt to hyperlink URLs when displaying it. 551 4.2.3. htmlDescription 553 Type: "String|null" (Defaults to null if omitted) 555 A longer form rich-text description of the object. This is HTML text 556 [1] and allows to reference resources in the *links* property by use 557 of CID URLs (see [RFC2392]). To convert a CID URL to the *cid* 558 property value of a *Link* object, implementations MUST follow the 559 conversion described in section 2 of [RFC2392]. Implementations MAY 560 choose not to follow untrusted external CID URLs referenced in the 561 *links* property, in which case they MUST treat the *htmlDescription* 562 property as if omitted. Implementations MUST preserve the value of 563 this property, even if it contains untrusted links. 565 4.2.4. locations 567 Type: "String[Location]|null" 569 A map of location ids to Location objects, representing locations 570 associated with the object. A location id may be any valid [RFC6901] 571 JSON pointer and need only be unique to this object; a UUID is a 572 practical choice. 574 A *Location* object has the following properties. All properties are 575 optional, but every Location object MUST have at least one property: 577 o *name*: "String" (Defaults to the empty string if omitted) The 578 human-readable name of the location. 580 o *description*: "String|null" Human-readable instructions for 581 accessing this location. This may be an address, set of 582 directions, door access code, etc. 584 o *rel*: "String" (Defaults to "unknown" if omitted) The relation 585 type of this location to the JSCalendar object. 587 This MUST be either one of the following values, registered in a 588 future RFC, or a vendor-specific value. Any value the client or 589 server doesn't understand should be treated the same as "unknown". 591 * "start": The JSCalendar object starts at this location. 593 * "end": The JSCalendar object ends at this location. 595 * "virtual": This is not a physical location (e.g. this location 596 is an online chat room where people will meet). 598 * "unknown": The relation of this location to the calendar object 599 is unknown. 601 o *features*: "String[]|null" The features supported by this 602 location. 604 The strings in the array MUST each be either one of the following 605 values, registered in a future RFC, or a vendor-specific value. 606 Any value the client or server doesn't understand should be 607 ignored, but preserved. 609 The features supported by locations with rel-type "virtual" are: 611 * "audio": audio conferencing 613 * "chat": chat or instant messaging 615 * "feed": blog or atom feed 617 * "moderator": provides moderator-specific features 618 * "phone": phone conferencing 620 * "screen": screen sharing 622 * "video": video conferencing 624 * any vendor-prefixed custom value 626 o *timeZone*: "String|null" (Defaults to "null" if omitted) A time- 627 zone for this location. 629 If "null", the *timeZone* from the JSCalendar object MUST be 630 presumed when a time-zone is needed in relation to this location. 632 o *coordinates*: "String|null" An [RFC5870] "geo:" URI for the 633 location. 635 o *uri*: "String|null" A URI that represents how to connect to this 636 location. 638 This may be a telephone number (represented as 639 "tel:+1-555-555-555") for a teleconference, a web address for 640 online chat, or any custom URI. 642 o *linkIds*: "String[]|null" A list of ids for links to alternate 643 representations of this location. 645 For example, an alternative representation could be in vCard 646 format. 648 4.2.5. links 650 Type: "String[Link]|null" 652 A map of link ids to Link objects, representing external resources 653 associated with the object. A link id may be any valid [RFC6901] 654 JSON pointer and need only be unique to this object; the href or a 655 UUID are practical choices. 657 A *Link* object has the following properties: 659 o *href*: "String" A URI from which the resource may be fetched. 661 This MAY be a "data:" URL, but it is recommended that the file be 662 hosted on a server to avoid embedding arbitrary large data in 663 JSCalendar object instances. 665 o *cid* "String|null" The id used within the *htmlDescription* 666 property to reference this link. 668 If not null, this MUST be a valid Content-ID MIME header value 669 without CFWS and angle brackets (see [RFC2392]). The identifier 670 MUST be unique within this JSCalendar object but has no meaning 671 beyond that. Specifically, it MAY be different from the *Link* 672 object identifier in the enclosing *links* property. 674 o *type*: "String|null"(optional, defaults to "null") The content- 675 type [RFC6838] of the resource, if known. 677 o *size*: "Number|null"(optional, defaults to "null") The size, in 678 bytes, of the resource when fully decoded (i.e. the number of 679 bytes in the file the user would download), if known. 681 o *rel*: "String"(optional, defaults to "related") Identifies the 682 relation of the linked resource to the object. The value MUST be 683 a registered relation type (see [RFC8288] and IANA Link Relations 684 [2]). 686 Links with a rel of "enclosure" SHOULD be considered by the client 687 as attachments for download. 689 Links with a rel of "describedby" SHOULD be considered by the 690 client to be an alternate representation of the description and 691 HTML description. 693 Links with a rel of "icon" SHOULD be considered by the client to 694 be an image that it MAY use when presenting the calendar data to a 695 user. The *properties* object of this link MAY include a 696 "display" property indicating the intended purpose of this image. 697 If included, the value MUST be either one of the following values, 698 registered in a future RFC, or a vendor-specific value. 700 * "badge": an image inline with the title of the object 702 * "graphic": a full image replacement for the object itself 704 * "fullsize": an image that is used to enhance the object 706 * "thumbnail": a smaller variant of "fullsize " to be used when 707 space for the image is constrained 709 o *title*: "String|null"(optional, defaults to "null") A human- 710 readable description of the resource. 712 o *properties*: "String[String|null]|null"(optional, defaults to 713 "null") Extra metadata submitted by clients about a link. Server 714 implementations MUST preserve these properties. 716 The keys are as defined in this document, as defined in a future 717 RFC, or URIs that should be owned by the client author to avoid 718 conflicts. 720 4.2.6. locale 722 Type: "String|null" 724 The [RFC5646] language tag that best describes the locale used for 725 the calendar object, if known. 727 4.2.7. keywords 729 Type: "String[]|null" 731 A list of keywords or tags related to the object. The values are 732 free-form and do not have to follow any particular structure. 734 4.2.8. categories 736 Type: "String[]|null" 738 Specifies the categories related to the calendar object. Array 739 values MUST be URIs. In contrast to *keywords*, categories typically 740 are structured. 742 For example, a vendor owning the domain "example.com" might define 743 the categories "http://example.com/categories/sports/american- 744 football"" and "http://example.com/categories/music/r-b". 746 4.2.9. color 748 Type: "String|null" 750 Specifies a color clients MAY use when displaying this calendar 751 object. The value is a case-insensitive color name taken from the 752 CSS3 set of names, defined in Section 4.3 of W3C.REC- 753 css3-color-20110607 [3] or a CSS3 RGB color hex value. 755 4.3. Recurrence properties 756 4.3.1. recurrenceRule 758 Type: "Recurrence" 760 Defines a recurrence rule (repeating pattern) for recurring calendar 761 objects. 763 A *Recurrence* object is a JSON object mapping of a RECUR value type 764 in iCalendar, see [RFC5545] and[RFC7529]. A JSEvent recurs by 765 applying the recurrence rule (and *recurrenceOverrides*) to the 766 *start* date/time. A JSTask recurs by applying the recurrence rule 767 (and *recurrenceOverrides*) to its *start* date/time, if defined. If 768 the task does not define a start date-time, it recurs by its *due* 769 date-time. If it neither defines a start or due date-time, it MUST 770 NOT define a *recurrenceRule*. 772 A Recurrence object has the following properties: 774 o *frequency*: "String" This MUST be one of the following values: 776 * "yearly" 778 * "monthly" 780 * "weekly" 782 * "daily" 784 * "hourly" 786 * "minutely" 788 * "secondly" 790 To convert from iCalendar, simply lower-case the FREQ part. 792 o *interval*: "Number"(optional, defaults to "1") The INTERVAL part 793 from iCal. If included, it MUST be an integer "x >= 1". 795 o *rscale*: "String"(optional, defaults to ""gregorian"") The RSCALE 796 part from iCalendar RSCALE [RFC7529], converted to lower-case. 798 o *skip*: "String"(optional, defaults to ""omit"") The SKIP part 799 from iCalendar RSCALE [RFC7529], converted to lower-case. 801 o *firstDayOfWeek*: "String"(optional, defaults to ""mo"") The WKST 802 part from iCalendar, represented as a lower-case abbreviated two- 803 letter English day of the week. If included, it MUST be one of 804 the following values: ""mo"|"tu"|"we"|"th"|"fr"|"sa"|"su"". 806 o *byDay*: "NDay[]"(optional) An *NDay* object has the following 807 properties: 809 * *day*: "String" The day-of-the-week part of the BYDAY value in 810 iCalendar, lower-cased. MUST be one of the following values: 811 ""mo"|"tu"|"we"|"th"|"fr"|"sa"|"su"". 813 * *nthOfPeriod*: "Number"(optional) The optional ordinal part of 814 the BYDAY value in iCalendar (e.g. ""+1"" or ""-3""). If 815 present, rather than representing every occurrence of the 816 weekday defined in the *day* property of this *NDay*, it 817 represents only a specific instance within the recurrence 818 period. The value can be positive or negative, but MUST NOT be 819 zero. A negative integer means nth-last of period. 821 o *byMonthDay*: "Number[]"(optional) The BYMONTHDAY part from 822 iCalendar. The array MUST have at least one entry if included. 824 o *byMonth*: "String[]"(optional) The BYMONTH part from iCalendar. 825 Each entry is a string representation of a number, starting from 826 "1" for the first month in the calendar (e.g. ""1" " means 827 ""January"" with Gregorian calendar), with an optional ""L"" 828 suffix (see [RFC7529]) for leap months (this MUST be upper-case, 829 e.g. ""3L""). The array MUST have at least one entry if included. 831 o *byYearDay*: "Number[]"(optional) The BYYEARDAY part from 832 iCalendar. The array MUST have at least one entry if included. 834 o *byWeekNo*: "Number[]"(optional) The BYWEEKNO part from iCalendar. 835 The array MUST have at least one entry if included. 837 o *byHour*: "Number[]"(optional) The BYHOUR part from iCalendar. 838 The array MUST have at least one entry if included. 840 o *byMinute*: "Number[]"(optional) The BYMINUTE part from iCalendar. 841 The array MUST have at least one entry if included. 843 o *bySecond*: "Number[]"(optional) The BYSECOND part from iCalendar. 844 The array MUST have at least one entry if included. 846 o *bySetPosition*: "Number[]"(optional) The BYSETPOS part from 847 iCalendar. The array MUST have at least one entry if included. 849 o *count*: "Number"(optional) The COUNT part from iCalendar. This 850 MUST NOT be included if an *until* property is specified. 852 o *until*: "LocalDate"(optional) The UNTIL part from iCalendar. 853 This MUST NOT be included if a *count* property is specified. 854 Note, as in iCalendar, this date is presumed to be in the time- 855 zone specified in *timeZone*. It is not a UTC time. 857 A recurrence rule specifies a set of set of date-times for recurring 858 calendar objects. A recurrence rule has the following semantics: 860 1. A set of candidates is generated. This is every second within a 861 period defined by the frequency property: 863 * *yearly*: every second from midnight on the 1st January 864 (inclusive) to midnight the following 1st January (exclusive) 866 * *monthly*: every second from midnight on the 1st of a month 867 (inclusive) to midnight on the 1st of the following month 868 (exclusive) 870 * *weekly*: every second from midnight (inclusive) on the first 871 day of the week (as defined by the firstDayOfWeek property, or 872 Monday if omitted), to midnight 7 days later (exclusive). 874 * *daily*: every second from midnight at the start of the day 875 (inclusive) to midnight at the end of the day (exclusive). 877 * *hourly*: every second from the beginning of the hour 878 (inclusive) to the beginning of the next hour (exclusive). 880 * *minutely*: every second from the beginning of the minute 881 (inclusive) to the beginning of the next minute (exclusive). 883 * *secondly*: the second itself, only. 885 2. Each date-time candidate is compared against all of the byX 886 properties of the rule except bySetPosition. If any property in 887 the rule does not match the date-time, it is eliminated. Each 888 byX property is an array; the date-time matches the property if 889 it matches any of the values in the array. The properties have 890 the following semantics: 892 * *byMonth*: the date-time is in the given month. 894 * *byMonthDay*: the date-time is on the given day of the month. 895 Negative numbers mean the nth last day of the month. 897 * *byDay*: the date-time is on the given day of the week. If 898 the day is prefixed by a number, it is the nth occurrence of 899 that day of the week within the month (if frequency is 900 monthly) or year (if frequency is yearly). Negative numbers 901 means nth last occurrence within that period. 903 * *byYearDay*: the date-time is on the nth day of year. 904 Negative numbers mean the nth last day of the year. 906 * *byWeekNo*: the date-time is in the nth week of the year. 907 Negative numbers mean the nth last week of the year. This 908 corresponds to weeks according to week numbering as defined in 909 ISO.8601.2004, with a week defined as a seven day period, 910 starting on the firstDayOfWeek property value or Monday if 911 omitted. Week number one of the calendar year is the first 912 week that contains at least four days in that calendar year. 914 * *byHour*: the date-time has the given hour value. 916 * *byMinute*: the date-time has the given minute value. 918 * *bySecond*: the date-time has the given second value. 920 3. If a bySetPosition property is included, this is now applied to 921 the ordered list of remaining dates (this property specifies the 922 indexes of date-times to keep; all others should be eliminated. 923 Negative numbers are indexes from the end of the list, with -1 924 being the list item). 926 4. Any date-times before the start date of the event are eliminated 927 (see below for why this might be needed). 929 5. If further dates are required (we have not reached the until 930 date, or count limit) skip the next (interval - 1) sets of 931 candidates, then continue from step 1. 933 When determining the set of occurrence dates for an event or task, 934 the following extra rules must be applied: 936 1. The start date-time is always the first occurrence in the 937 expansion (and is counted if the recurrence is limited by a 938 "count" property), even if it would normally not match the rule. 940 2. The first set of candidates to consider is that which would 941 contain the start date-time. This means the first set may 942 include candidates before the start; such candidates are 943 eliminated from the results in step (4) as outlined before. 945 3. The following properties MUST be implicitly added to the rule 946 under the given conditions: 948 * If frequency > "secondly" and no bySecond property: Add a 949 bySecond property with the sole value being the seconds value 950 of the start date-time. 952 * If frequency > "minutely" and no byMinute property: Add a 953 byMinute property with the sole value being the minutes value 954 of the start date-time. 956 * If frequency > "hourly" and no byHour property: Add a byHour 957 property with the sole value being the hours value of the 958 start date-time. 960 * If frequency is "weekly" and no byDay property: Add a byDay 961 property with the sole value being the day-of-the-week of the 962 start date-time. 964 * If frequency is "monthly" and no byDay property and no 965 byMonthDay property: Add a byMonthDay property with the sole 966 value being the day-of-the-month of the start date-time. 968 * If frequency is "yearly" and no byDay, byYearDay or byWeekNo 969 properties: 971 + if there is no byMonthDate property: Add a byMonthDay 972 property with the sole value being the day-of-the-month of 973 the start date-time. 975 + if there is no byMonth property: Add a byMonth property 976 with the sole value being the month of the start date-time. 978 4.3.2. recurrenceOverrides 980 Type: "LocalDate[PatchObject|null]|null" 982 A map of the recurrence-ids (the date-time of the start of the 983 occurrence) to an object of patches to apply to the generated 984 occurrence object. 986 If the recurrence-id does not match an expanded start date from a 987 recurrence rule, it is to be treated as an additional occurrence 988 (like an RDATE from iCalendar). The patch object may often be empty 989 in this case. 991 If the patch object defines the *excluded* property to be "true", 992 then the recurring calendar object does not occur at the recurrence- 993 id date-time (like an EXDATE from iCalendar). Such a patch object 994 MUST NOT patch any other property. 996 By default, an occurrence inherits all properties from the main 997 object except the start (or due) date-time, which is shifted to the 998 new start time of the LocalDate key. However, individual properties 999 of the occurrence can be modified by a patch, or multiple patches. 1000 It is valid to patch the start property value, and this patch takes 1001 precedence over the LocalDate key. Both the LocalDate key as well as 1002 the patched start date-time may occur before the original JSCalendar 1003 object's start or due date. 1005 A pointer in the PatchObject MUST NOT start with one of the following 1006 prefixes; any patch with such a key MUST be ignored: 1008 o @type 1010 o uid 1012 o relatedTo 1014 o prodId 1016 o method 1018 o isAllDay 1020 o recurrenceRule 1022 o recurrenceOverrides 1024 o replyTo 1026 4.3.3. excluded 1028 Type: "Boolean"(defaults to "false" if omitted) 1030 Defines if this object is an overridden, excluded instance of a 1031 recurring JSCalendar object (also see Section 4.3.2). If this 1032 property value is "true", this calendar object instance MUST be 1033 treated as if not existent. 1035 4.4. Sharing and scheduling properties 1037 4.4.1. priority 1039 Type: "Number"(defaults to "0" if omitted) 1041 Specifies a priority for the calendar object. This may be used as 1042 part of scheduling systems to help resolve conflicts for a time 1043 period. 1045 The priority is specified as an integer in the range 0 to 9. A value 1046 of 0 specifies an undefined priority. A value of 1 is the highest 1047 priority. A value of 2 is the second highest priority. Subsequent 1048 numbers specify a decreasing ordinal priority. A value of 9 is the 1049 lowest priority. Other integer values are reserved for future use. 1051 4.4.2. freeBusyStatus 1053 Type: "String"(defaults to "busy" if omitted) 1055 Specifies how this property should be treated when calculating free- 1056 busy state. The value MUST be one of: 1058 o ""free"": The object should be ignored when calculating whether 1059 the user is busy. 1061 o ""busy"": The object should be included when calculating whether 1062 the user is busy. 1064 4.4.3. privacy 1066 Type: "String"(defaults to "public" if omitted) 1068 Calendar objects are normally collected together and may be shared 1069 with other users. The privacy property allows the object owner to 1070 indicate that it should not be shared, or should only have the time 1071 information shared but the details withheld. Enforcement of the 1072 restrictions indicated by this property are up to the 1073 implementations. 1075 This property MUST NOT affect the information sent to scheduled 1076 participants; it is only interpreted when the object is shared as 1077 part of a shared calendar. 1079 The value MUST be either one of the following values, registered in a 1080 future RFC, or a vendor-specific value. Vendor specific values MUST 1081 be prefixed with a domain name controlled by the vendor, e.g. 1082 "example.com/topsecret". Any value the client or server doesn't 1083 understand should be preserved but treated as equivalent to 1084 "private". 1086 o "public": The full details of the object are visible to those whom 1087 the object's calendar is shared with. 1089 o "private": The details of the object are hidden; only the basic 1090 time and metadata is shared. Implementations MUST ensure the 1091 following properties are stripped when the object is accessed by a 1092 sharee: 1094 * title 1096 * description 1098 * htmlDescription 1100 * locations 1102 * links 1104 * locale 1106 * localizations 1108 * participants 1110 * replyTo 1112 In addition, any patches in "recurrenceOverrides" whose key is 1113 prefixed with one of the above properties MUST be stripped. 1115 o "secret": The object is hidden completely (as though it did not 1116 exist) when the calendar is shared. 1118 4.4.4. replyTo 1120 Type: "String[String]|null" 1122 Represents methods by which a participant may RSVP to the organizer 1123 of the calendar object. The keys in the property value are the 1124 available methods. The value is a URI to use that method. Future 1125 methods may be defined in future specifications; a calendar client 1126 MUST ignore any method it does not understand. 1128 The following methods are defined: 1130 o "imip": The organizer accepts an iMIP [RFC6047] response. The 1131 value MUST be a "mailto:" URI. 1133 o "web": There is a web page where the user may submit an RSVP using 1134 their browser. The value MUST be a "https:" URI Template 1135 ([RFC6570]) in level 1 format. The template MAY contain variables 1136 that MUST be expanded from the JSCalendar object as defined in 1137 table Table 1. Calendar clients SHOULD be prepared to handle 1138 authentication requests from the respective web page and for the 1139 participant email, but this specification does not mandate any 1140 specific mechanism. 1142 +--------------+----------------------------------------------------+ 1143 | Variable | Expand to | 1144 +--------------+----------------------------------------------------+ 1145 | email | The *email* property value of the replying | 1146 | | *Participant* object. | 1147 | | | 1148 | uid | The *uid* property value of the JSCalendar object. | 1149 | | | 1150 | sequence | The *sequence* property value of the JSCalendar | 1151 | | object. | 1152 | | | 1153 | recurrenceId | The recurrence-id when replying for a single | 1154 | | occurrence of a recurring JSCalendar object. The | 1155 | | LocalDate-typed value is the recurrence-id of a | 1156 | | non-overriden recurrence, or the key of a | 1157 | | recurrenceOverride of this JSCalendar object. | 1158 +--------------+----------------------------------------------------+ 1160 Table 1: replyTo URI Template variables 1162 4.4.5. participants 1164 Type: "String[Participant]|null" 1166 A map of participant ids to participants, describing their 1167 participation in the calendar object. A participant id may be any 1168 valid [RFC6901] JSON pointer and need only be unique to this calendar 1169 object; the email address of the participant is a good choice. 1171 A *Participant* object has the following properties. Properties are 1172 mandatory unless marked otherwise: 1174 o *name*: "String" The display name of the participant (e.g. "Joe 1175 Bloggs"). 1177 o *email*: "String" The email address for the participant. 1179 o *kind*: "String"(optional, defaults to "unknown") What kind of 1180 entity this participant is. 1182 This MUST be either one of the following values, registered in a 1183 future RFC, or a vendor-specific value. Any value the client or 1184 server doesn't understand should be treated the same as "unknown". 1186 * "individual": a single person 1188 * "group": a collection of people invited as a whole 1189 * "resource": a non-human resource, e.g. a projector 1191 * "location": a physical location involved in the calendar object 1192 that needs to be scheduled, e.g. a conference room. 1194 * "unknown": no information is available about the kind of this 1195 participant. 1197 o *roles*: "String[]" A list of roles that this participant fulfils. 1199 At least one value MUST be specified for the participant. This 1200 MUST be either one of the following values, registered in a future 1201 RFC, or a vendor-specific value. Any value the client or server 1202 doesn't understand should be preserved but ignored. 1204 * "owner": The participant is an owner of the object, and allowed 1205 to make alterations to any part of it. 1207 * "attendee": The participant is an attendee of the calendar 1208 object. Attendees are only allowed to alter their own 1209 participation. 1211 * "chair": The participant is in charge of the calendar object 1212 when it occurs. 1214 o *locationId*: "String|null"(optional, defaults to "null") The 1215 location at which this participant is expected to be attending. 1217 If the value does not correspond to any location id in the 1218 locations property of the instance, this MUST be treated the same 1219 as if the participant's locationId were specified as null. 1221 o *rsvpResponse*: "String"(optional, defaults to "needs-action") The 1222 RSVP response, if any, of this participant. 1224 The value MUST be either one of the following values, registered 1225 in a future RFC, or a vendor-specific value: 1227 * "needs-action": No status yet set by the participant. 1229 * "accepted": The invited participant will participate. 1231 * "declined": The invited participant will not participate. 1233 * "tentative": The invited participant may participate. 1235 o *participation*: "String"(optional, defaults to "required") The 1236 required participation of this participant. 1238 The value MUST be either one of the following values, registered 1239 in a future RFC, or a vendor-specific value. Any value the client 1240 or server doesn't understand should be treated the same as 1241 "required". 1243 * "non-participant": Indicates a participant who is copied for 1244 information purposes only. 1246 * "optional": Indicates a participant whose participation is 1247 optional. 1249 * "required": Indicates a participant whose participation is 1250 required. 1252 o *rsvpWanted*: "Boolean"(optional, defaults to "false") If true, 1253 the organizer is expecting the participant to notify them of their 1254 status. 1256 o *scheduleSequence*: "Number"(optional, defaults to "0") The 1257 sequence number of the last response from the participant. If 1258 defined, this MUST be a non-negative integer. 1260 This can be used to determine whether the partcipant has sent a 1261 new RSVP following significant changes to the calendar object, and 1262 to determine if future responses are responding to a current or 1263 older view of the data. 1265 o *scheduleUpdated*: "UTCDate|null"(optional, defaults to "null") 1266 The *updated* property of the last iMIP response from the 1267 participant. 1269 This can be compared to the *updated* timestamp in future iMIP 1270 responses to determine if the response is older or newer than the 1271 current data. 1273 o *invitedBy*: "String|null"(optional, defaults to "null") The 1274 participant id of the participant who invited this one, if known. 1276 o *delegatedTo*: "String[]|null"(optional, defaults to "null") A 1277 list of participant ids of participants that this participant has 1278 delegated their participation to. This MUST be omitted if none 1279 (rather than an empty array). 1281 o *delegatedFrom*: "String[]|null"(optional, defaults to "null") A 1282 list of participant ids that this participant is acting as a 1283 delegate for. This MUST be omitted if none (rather than an empty 1284 array). 1286 o *memberOf*: "String[]|null"(optional, defaults to "null") A list 1287 of group participants that were invited to this calendar object, 1288 which caused this participant to be invited due to their 1289 membership of the group(s). This MUST be omitted if none (rather 1290 than an empty array). 1292 o *linkIds*: "String[]|null"(optional, defaults to "null") Links to 1293 more information about this participant, for example in vCard 1294 format. 1296 4.5. Alerts properties 1298 4.5.1. useDefaultAlerts 1300 Type: "Boolean" (defaults to "false" if omitted) 1302 If "true", use the user's default alerts and ignore the value of the 1303 *alerts* property. Fetching user defaults is dependent on the API 1304 from which this JSCalendar object is being fetched, and is not 1305 defined in this specification. If an implementation cannot determine 1306 the user's default alerts, or none are set, it MUST process the 1307 alerts property as if useDefaultAlerts is set to "false". 1309 4.5.2. alerts 1311 Type: "String[Alert]|null" 1313 A map of alert ids to Alert objects, representing alerts/reminders to 1314 display or send the user for this calendar object. An alert id may 1315 be any valid [RFC6901] JSON pointer and need only be unique to this 1316 calendar object; a globally unique id is a practical choice (also see 1317 Section 4.1.2)). 1319 An *Alert* Object has the following properties: 1321 o *relativeTo*: "String" (optional, defaults to "before-start") 1322 Specifies where the offset is relative to for the alarm to 1323 trigger. The value MUST be one of: 1325 * "before-start" 1327 * "after-start" 1329 * "before-end" 1331 * "after-end" 1333 o *offset*: "Duration" The offset from the start and end/due of the 1334 calendar object to fire the alert. If the calendar object does 1335 not define a time-zone, the user's default time-zone SHOULD be 1336 used when determining the offset, if known. Otherwise, the time- 1337 zone to use is implementation specific. 1339 o *action*: "DisplayAction|EmailAction|UnknownAction" 1341 Describes how to alert the user. 1343 A *DisplayAction* means a message (which is service dependent, but 1344 SHOULD include the title and start or due time of the calendar 1345 object) SHOULD be shown to the user on any client connected to 1346 this account at the specified time. How this message is formatted 1347 (and any sound or other method of drawing the user's attention) is 1348 client specific. It has the following properties: 1350 * *type*: "String" The value MUST be "display". 1352 * *acknowledged*: "UTCDate|null " (optional) 1354 When the user has permanently dismissed the alert the client 1355 MUST set this to the current time in UTC. Other clients which 1356 sync this property can then automatically dismiss or suppress 1357 duplicate alerts (alerts with the same alert id that triggered 1358 on or before this date-time). 1360 For a recurring calendar object, the *acknowledged* property of 1361 the parent object MUST be updated, unless the alert is already 1362 overridden in *recurrenceOverrides*. 1364 * *snoozed*: "UTCDate|null" (optional) 1366 If the user temporarily dismisses the alert, this is the UTC 1367 date-time after which it should be reshown. Clients displaying 1368 this alert SHOULD hide it if the snoozed property is updated to 1369 a time in the future. When that time is reached, the alert 1370 SHOULD be reshown unless acknowledged is now after the original 1371 trigger time. 1373 Setting this property on an instance of a recurring calendar 1374 object MUST update the alarm on the master object, unless the 1375 respective instance already is defined in 1376 "recurrenceOverrides". It MUST NOT generate an override for 1377 the sole use of snoozing an alarm. 1379 * *mediaLinks*: "String[Link]|null " (optional) 1380 A map of link identifiers to links (see Section 4.2.5) that 1381 contain media to display with this alert. Clients SHOULD play 1382 one or more of the link contents that are supported by the 1383 client implementation and are appropriate for the given device 1384 and user context. 1386 An *EmailAction* means an email SHOULD be sent as specified in the 1387 object at the specified time. It has the following properties: 1389 * *type*: "String" The value MUST be "email". 1391 * *to*: "Emailer[]" An array of name/email objects to send the 1392 alert to. 1394 An *Emailer* object has the following properties: 1396 + name: String The name of the recipient. If not known, 1397 clients SHOULD use the empty string. 1399 + email: String The email address of the recipient. 1401 * *subject*: "String" (optional) The subject to use for the 1402 email. If omitted, this is implementation specific, but the 1403 server SHOULD try to choose an appropriate subject, e.g. by 1404 including the summary. 1406 * *textBody*: "String" (optional) The plain-text body to use for 1407 the email. If omitted, the body of the email is implementation 1408 specific, but the server SHOULD include all pertinent details 1409 about the calendar object, such as summary, location and start 1410 time. 1412 * *htmlBody*: "String" (optional) The HTML body to use for the 1413 email, with rich-media content processed as for the 1414 *htmlDescription* property of the JSCalendar object (see 1415 Section 4.2.3), e.g. all CID URLs MUST be embedded in the 1416 generated alert email HTML body, or the *htmlBody* property 1417 ignored completely. If the textBody property of this alert 1418 action is not set, the server SHOULD generate a plain-text 1419 version from the HTML body and include it in a "multipart/ 1420 alternative" MIME message. 1422 * *attachments*: "String[Link]|null" (optional) A map of link 1423 identifiers to links (see Section 4.2.5). Included attachments 1424 SHOULD be embedded in the MIME message with the "Content- 1425 Disposition" header value set to "attachment" (see [RFC2183]). 1426 Implementations MAY refuse to include one or more attachments 1427 when building an alert email, in which case they MUST ignore 1428 the contents of the *attachments* property (e.g. they MUST NOT 1429 include a subset of attachments). 1431 An *UnknownAction* object is an object that contains a *type * 1432 property whose value is not "email" or "string", plus zero or more 1433 other properties. This is for compatibility with client 1434 extensions and future RFCs. The client or server SHOULD NOT 1435 trigger any type of alert for action types they do not understand, 1436 but MUST preserve them. 1438 4.6. Multilingual properties 1440 4.6.1. localizations 1442 Type: "String[PatchObject]|null" 1444 A map of [RFC5646] language tags to patch objects, which localise the 1445 calendar object into the locale of the respective language tag. 1447 See the description of PatchObject (Section 3.2.4) for the structure 1448 of the PatchObject. The patches are applied to the top-level object. 1449 In addition to all the restrictions on patches specified there, the 1450 pointer also MUST NOT start with one of the following prefixes; any 1451 patch with a such a key MUST be ignored: 1453 o @type 1455 o due 1457 o duration 1459 o freeBusyStatus 1461 o localization 1463 o method 1465 o participants 1467 o prodId 1469 o progress 1471 o relatedTo 1473 o sequence 1475 o start 1476 o status 1478 o timeZone 1480 o uid 1482 o useDefaultAlerts 1484 Note that this specification does not define how to maintain validity 1485 of localized content. For example, a client application changing a 1486 JSCalendar object's title property might also need to update any 1487 localizations of this property. Client implementations SHOULD 1488 provide the means to manage localizations, but how to achieve this is 1489 specific to the application's workflow and requirements. 1491 5. Type-specific JSCalendar properties 1493 5.1. JSEvent properties 1495 In addition to the common JSCalendar object properties (Section 4) a 1496 JSEvent has the following properties: 1498 5.1.1. start 1500 Type: "LocalDate" e.g. "2015-09-02T00:00:00" 1502 The date/time the event would start in the event's time-zone. 1504 A valid JSEvent MUST include this property. 1506 5.1.2. timeZone 1508 Type: "String|null" 1510 The IANA Time Zone Database [4] name for the time-zone the event is 1511 scheduled in, or "null" for floating time. If omitted, this MUST be 1512 presumed to be "null" (i.e. floating time). 1514 5.1.3. duration 1516 Type: "Duration", e.g. "P2DT3H" (Defaults to "P0D" if omitted) 1518 The zero or positive duration of the event in absolute time (i.e. in 1519 UTC time; ignoring DST shifts). To get the end date in the event 1520 time-zone, convert start into UTC, then add the duration, then 1521 convert the result into the appropriate time-zone. 1523 A JSEvent MAY be end in a different time-zone (e.g. a plane flight 1524 crossing time-zones). In this case, the JSEvent MUST specify the end 1525 time-zone in a *location* property value that defines its *rel* to be 1526 "end" and the end time-zone in its *timeZone* property. 1528 5.1.4. isAllDay 1530 Type: "Boolean" (optional, defaults to "false") 1532 Specifies if the event an all day event, such as a birthday or public 1533 holiday. 1535 If *isAllDay* is true, then the following restrictions apply: 1537 o the *start* property MUST have a time component of "T00:00:00". 1539 o the *duration* property MUST only include a day component. 1541 Note that all-day events MAY be bound to a specific time-zone, as 1542 defined by the *timeZone* property. 1544 5.1.5. status 1546 Type: "String" 1548 The scheduling status (Section 4.4) of a JSEvent defaults to 1549 "confirmed" if omitted. 1551 If set, it MUST be one of: 1553 o "confirmed": Indicates the event is definite. 1555 o "cancelled": Indicates the event is cancelled. 1557 o "tentative": Indicates the event is tentative. 1559 5.2. JSTask properties 1561 In addition to the common JSCalendar object properties (Section 4) a 1562 JSTask has the following properties: 1564 5.2.1. due 1566 Type: "LocalDate|null" e.g. "2015-09-02T00:00:00" 1568 The date/time the task is due in the task's time-zone. 1570 5.2.2. start 1572 Type: "LocalDate|null" e.g. "2015-09-02T00:00:00" 1574 The date/time the task should start in the task's time-zone. 1576 5.2.3. timeZone 1578 Type: "String|null" 1580 The IANA Time Zone Database name for the time-zone the task is 1581 scheduled in, or "null" for floating time. If omitted, this MUST be 1582 presumed to be "null" (i.e. floating time). 1584 5.2.4. estimatedDuration 1586 Type: "Duration|null", e.g. "P2DT3H" 1588 Specifies the estimated positive duration of time the task takes to 1589 complete. 1591 If the *start* and *due* properties are set, the estimated duration 1592 SHOULD be less than or equal to the time interval between these 1593 properties. 1595 5.2.5. completed 1597 Type: "UTCDate|null", e.g. "2016-06-13T12:00:00Z" 1599 Specifies the date/time the task was completed. 1601 If the task is recurring and has future instances, a client may want 1602 to denote a specific task recurrence as completed but leave other 1603 instances as uncompleted. One way to achieve this is by overriding 1604 the completed property in the task *recurrenceOverrides*. However, 1605 this could produce a long list of completion times for regularly 1606 recurring tasks. An alternative approach is to split the JSTask into 1607 a current, single instance of JSTask with this instance completion 1608 time and a future recurring instance. Also see the definition of the 1609 *relatedTo* on splitting. 1611 5.2.6. isAllDay 1613 Type: "Boolean" (optional, defaults to "false") 1615 Specifies if the task is an all day task. 1617 If *isAllDay* is true, then the *start* and *due* properties MUST 1618 have a time component of "T00:00:00". Note that the 1619 *estimatedDuration* property MAY contain a non-zero time duration. 1620 All-day tasks MAY be bound to a specific time-zone, as defined by the 1621 *timeZone* property. 1623 5.2.7. progress 1625 In addition to the common properties of a *Participant* object 1626 (Section 4.4.5), a Participant within a JSTask supports the following 1627 property: 1629 o *progress*: "ParticipantProgress|null" The progress of the 1630 participant for this task, if known. This property MUST be "null" 1631 if the *rsvpResponse* of this participant is any other value but 1632 "accepted". 1634 A *ParticipantProgress* object has the following properties: 1636 o *status*: "String" Describes the completion status of the 1637 participant's progress. 1639 The value MUST be at most one of the following values, registered 1640 in a future RFC, or a vendor-specific value: 1642 * "completed": The participant completed their progress. 1644 * "in-process": The participant processes this task. 1646 * "failed": The participant failed to complete their progress. 1648 o *timestamp*: "UTCDate" Describes the last time when the 1649 participant progress got updated. 1651 5.2.8. status 1653 Type: "String" 1655 If omitted, the default scheduling status (Section 4.4) of a JSTask 1656 is defined as follows (in order of evaluation): 1658 o "needs-action": if the task has no participants, or if at least 1659 one participant of the task has *rsvpResponse* set to "needs- 1660 action" (eiher explicitly or by default). 1662 o "completed": if all the *ParticipantProgress* status of the task 1663 participants is "completed". 1665 o "failed": if at least one *ParticipantProgress* status of the task 1666 participants is "failed". 1668 o "in-process": if at least one *ParticipantProgress* status of the 1669 task participants is "in-process". 1671 o "pending": If none of the other criteria match. 1673 If set, it MUST be one of: 1675 o "needs-action": Indicates the task needs action. 1677 o "completed": Indicates the task is completed. If this value is 1678 set, then the timestamp in the *completed* property MUST NOT be 1679 null. 1681 o "in-process": Indicates the task is in process. 1683 o "cancelled": Indicates the task is cancelled. 1685 o "pending": Indicates the task has been created, but not yet 1686 started. 1688 o "failed": Indicates the task failed. 1690 5.3. JSGroup properties 1692 JSGroup supports the following JSCalendar properties (Section 4): 1694 o @type 1696 o uid 1698 o created 1700 o updated 1702 o categories 1704 o keywords 1706 o name 1708 o description 1710 o htmlDescription 1712 o color 1713 o links 1715 as well as the following JSGroup-specific properties: 1717 5.3.1. entries 1719 Type: "(JSTask|JSEvent)[]|null" 1721 A list of group members. The list MAY contain multiple object types 1722 and implementations MUST ignore entries of unknown type. The 1723 property value MUST either be "null" or the list MUST NOT be empty. 1725 5.3.2. source 1727 Type: "String|null" (optional, default is "null") 1729 The source from which updated versions of this group may be retrieved 1730 from. If the value is not "null", it MUST be a URI. 1732 6. Conversion from and to iCalendar 1734 This section specifies which JSCalendar properties can be mapped from 1735 and to iCalendar format. Implementations SHOULD follow these 1736 conversion guidelines. Still, JSCalendar does not restrict itself to 1737 iCalendar and conversion between these two formats MAY be lossy. 1739 6.1. JSEvent 1741 The iCalendar counterpart to *JSEvent* is the VEVENT component type 1742 [RFC5545]. A VEVENT component that is a direct child of a VCALENDAR 1743 component is equivalent to a standalone JSEvent. A VEVENT component 1744 *within* a VEVENT maps to the entries of the JSEvent 1745 *recurrenceOverrides* property. 1747 +----------+--------------------------------------------------------+ 1748 | Property | iCalendar counterpart | 1749 +----------+--------------------------------------------------------+ 1750 | isAllDay | True, if the type of the DTSTART property in iCalendar | 1751 | | is DATE. When translating from JSCalendar the | 1752 | | iCalendar DTSTART property is of DATE value type, if | 1753 | | the *isAllDay* property is set to true and the | 1754 | | *timeZone* property is null. | 1755 | | | 1756 | start | Corresponds to the DTSTART property in iCalendar. Note | 1757 | | that time-zone information is stored separately in | 1758 | | JSEvent. | 1759 | | | 1760 | timeZone | Corresponds to the TZID part of the DTSTART property | 1761 | | in iCalendar. If the event has a different end time- | 1762 | | zone to start time-zone, this should be added as a | 1763 | | JSCalendar *location* with just a *timeZone* property | 1764 | | and "rel="end"". | 1765 | | | 1766 | duration | Corresponds to the DURATION or DSTART+DTEND properties | 1767 | | in iCalendar. | 1768 +----------+--------------------------------------------------------+ 1770 Table 2: Translation between JSEvent and iCalendar 1772 6.2. JSTask 1774 The iCalendar counterpart to *JSTask* is the VTODO component type 1775 [RFC5545]. A VTODO component that is a direct child of a VCALENDAR 1776 component is equivalent to a standalone JSTask. A VTODO component 1777 *within* a master VTODO maps to the entries of the JSTask 1778 *recurrenceOverrides* property. 1780 +-------------------+-----------------------------------------------+ 1781 | Property | iCalendar counterpart | 1782 +-------------------+-----------------------------------------------+ 1783 | isAllDay | True, if the type of the DTSTART property in | 1784 | | iCalendar is DATE. When translating from | 1785 | | JSCalendar the iCalendar DTSTART property is | 1786 | | of DATE value type, if the *isAllDay* | 1787 | | property is set to true and the *timeZone* | 1788 | | property is null. | 1789 | | | 1790 | due | Corresponds to the DUE and DTSTART+DURATION | 1791 | | properties in iCalendar. When mapping | 1792 | | iCalendar VTODOs with DTSTART+DURATION, the | 1793 | | due date is the result of adding DURATION to | 1794 | | DTSTART in the DTSTART time-zone. | 1795 | | | 1796 | start | Corresponds to the DTSTART property in | 1797 | | iCalendar. | 1798 | | | 1799 | timeZone | Corresponds to the TZID part of the | 1800 | | DTSTART/DUE properties in iCalendar. If the | 1801 | | task has a different end time-zone to start | 1802 | | or due time-zone, this should be added as a | 1803 | | JSCalendar *location* with just a *timeZone* | 1804 | | property and "rel="end"". | 1805 | | | 1806 | estimatedDuration | Corresponds to the ESTIMATED-DURATION | 1807 | | iCalendar property. *NON-STANDARD*: this | 1808 | | property is currently non-standard, see | 1809 | | [draft-apthorp-ical-tasks]. | 1810 | | | 1811 | completed | Maps to the COMPLETED iCalendar property. | 1812 | | | 1813 | progress | Corresponds to the PARTSTAT and COMPLETED | 1814 | | properties in iCalendar, including the | 1815 | | currently non-standard definitions in | 1816 | | [draft-apthorp-ical-tasks]. | 1817 | | | 1818 | status | Corresponds to the STATUS property in | 1819 | | iCalendar, including the currently non- | 1820 | | standard definitions in | 1821 | | [draft-apthorp-ical-tasks]. | 1822 +-------------------+-----------------------------------------------+ 1824 Table 3: Translation between JSTask and iCalendar 1826 6.3. JSGroup 1828 A JSGroup converts to a iCalendar VCALENDAR containing VEVENT or 1829 VTODO components. 1831 +----------+--------------------------------------------------------+ 1832 | Property | iCalendar counterpart | 1833 +----------+--------------------------------------------------------+ 1834 | entries | The VEVENT and VTODO components within a top-level | 1835 | | VCALENDAR component. | 1836 | | | 1837 | source | Corresponds to the SOURCE property in iCalendar. | 1838 +----------+--------------------------------------------------------+ 1840 Table 4: Translation between JSGroup and iCalendar 1842 6.4. Common properties 1844 +---------------------+---------------------------------------------+ 1845 | Property | iCalendar counterpart | 1846 +---------------------+---------------------------------------------+ 1847 | alerts | An *Alert* corresponds to the VALARM | 1848 | | component in iCalendar, where the *action* | 1849 | | is determined by the iCalendar ACTION | 1850 | | property value (e.g., both "DISPLAY" and | 1851 | | "AUDIO" actions map to a JSCalendar | 1852 | | *DisplayAction* alert, and similarly for an | 1853 | | iCalendar "EMAIL"). The *relativeTo* and | 1854 | | *offset* properties corresponds to the | 1855 | | iCalendar TRIGGER property. The | 1856 | | *attachments* property of an *EmailAction* | 1857 | | alert map to iCalendar ATTACH properties. | 1858 | | For mapping *mediaLinks*, the iCalendar | 1859 | | currently forbids to define ATTACH | 1860 | | properties on VALARMs with DISPLAY action. | 1861 | | Mapping this property is implementation- | 1862 | | specific, but using "X-ATTACH" with the | 1863 | | same semantics as ATTACH is a sane choice. | 1864 | | | 1865 | categories | Corresponds to the STRUCTURED-CATEGORY | 1866 | | property in iCalendar, see. *NON- | 1867 | | STANDARD*: this property is currently non- | 1868 | | standard, see | 1869 | | [draft-ietf-calext-ical-relations]. | 1870 | | | 1871 | color | Corresponds to the COLOR property in | 1872 | | iCalendar, as specified in [RFC7986]. | 1873 | | | 1874 | created | Corresponds to the CREATED property in | 1875 | | iCalendar. | 1876 | | | 1877 | description | Corresponds to the DESCRIPTION property in | 1878 | | iCalendar. | 1879 | | | 1880 | htmlDescription | Corresponds to the ALTREP parameter of the | 1881 | | DESCRIPTION property (e.g. by setting | 1882 | | ALTREP to a "data:text/html" URL containing | 1883 | | the HTML text). Alternatively, use the | 1884 | | STYLED-DESCRIPTION property. *NON- | 1885 | | STANDARD*: the STYLED-DESCRIPTION property | 1886 | | currently is non-standard, see | 1887 | | [draft-ietf-calext-eventpub-extensions]. | 1888 | | | 1889 | freeBusyStatus | Corresponds to the TRANSP property in | 1890 | | iCalendar. | 1891 | | | 1892 | keywords | Corresponds to the CATEGORIES property in | 1893 | | iCalendar, as specified in [RFC7986]. | 1894 | | | 1895 | links | Corresponds to the ATTACH ([RFC5545]) or | 1896 | | IMAGE ([RFC7986]) properties with a URI | 1897 | | value type set to the link "href". | 1898 | | ([RFC7986]). The *type* property | 1899 | | corresponds to the FMTTYPE parameter, the | 1900 | | *size* property to the SIZE parameter. | 1901 | | Mapping all other properties is | 1902 | | implementation-specific. | 1903 | | | 1904 | locale | Corresponds to the LANGUAGE parameter in | 1905 | | iCalendar, which is added to individual | 1906 | | properties. When converting from | 1907 | | iCalendar, one language must be picked as | 1908 | | the main locale for the object, and all | 1909 | | properties in other languages moved to the | 1910 | | localizations JSEvent property. | 1911 | | | 1912 | localizations | Implementation-specific. | 1913 | | | 1914 | locations | See Section 6.5. | 1915 | | | 1916 | method | Corresponds to the METHOD property in | 1917 | | iCalendar. | 1918 | | | 1919 | participants | See Section 6.5. | 1920 | | | 1921 | priority | Corresponds to the PRIORITY property in | 1922 | | iCalendar. | 1923 | | | 1924 | privacy | Corresponds to the CLASS property in | 1925 | | iCalendar. | 1926 | | | 1927 | prodId | Corresponds to the PRODID property in | 1928 | | iCalendar. | 1929 | | | 1930 | recurrenceOverrides | Corresponds to the RDATE and EXDATE | 1931 | | properties in iCalendar, plus VEVENT (for | 1932 | | JSEvent) or VTODO (for JSTask) instances | 1933 | | with a recurrence-id. | 1934 | | | 1935 | recurrenceRule | Corresponds to the RRULE property in | 1936 | | iCalendar. See the property definition at | 1937 | | section Section 4.3.1 how to map a RRULE | 1938 | | value. | 1939 | | | 1940 | relatedTo | Corresponds to the RELATED-TO property in | 1941 | | iCalendar. | 1942 | | | 1943 | replyTo | An iCalendar ORGANIZER with one of the | 1944 | | mapped URIs as value. If URIs are defined | 1945 | | for both the "imip" and "web" type, it is | 1946 | | recommended to map the "imip" value to the | 1947 | | calendar address value of the ORGANIZER. | 1948 | | | 1949 | sequence | Corresponds to the SEQUENCE property in | 1950 | | iCalendar. | 1951 | | | 1952 | status | Corresponds to the STATUS property in | 1953 | | iCalendar (converted to lower-case). | 1954 | | | 1955 | title | Corresponds to the SUMMARY property in | 1956 | | iCalendar. | 1957 | | | 1958 | uid | Corresponds to the UID property in | 1959 | | iCalendar. | 1960 | | | 1961 | updated | Corresponds to the DTSTAMP and LAST- | 1962 | | MODIFIED properties in iCalendar. (These | 1963 | | are only different in the iTIP case, and | 1964 | | the difference is not actually useful.) | 1965 +---------------------+---------------------------------------------+ 1967 Table 5: Translation between JSCalendar and iCalendar 1969 6.5. Locations and participants 1971 Both JSCalendar participants and locations have counterparts in 1972 iCalendar but provide richer representation. 1974 The following table outlines translation of JSCalendar participants. 1975 Where iCalendar has distinct properties for ORGANIZER and ATTENDEE, 1976 these are merged in JSCalendar into the Participant object type. 1978 +--------------------------------------------------+----------------+ 1979 | Property | iCalendar | 1980 | | counterpart | 1981 +--------------------------------------------------+----------------+ 1982 | delegatedFrom | the DELEGATED- | 1983 | | FROM parameter | 1984 | | | 1985 | delegatedTo | email | 1986 | | | 1987 | the value of the ORGANIZER or ATTENDEE property | kind | 1988 | | | 1989 | the CUTYPE parameter | linkIds | 1990 | | | 1991 | Implementation-specific. | locationId | 1992 | | | 1993 | Implementation-specific. When mapping from | memberOf | 1994 | iCalendar to JSCalendar this may be the | | 1995 | JSCalendar identifier of a CONFERENCE property | | 1996 | that has the MODERATOR feature defined in its | | 1997 | FEATURE parameter values. If multiple such | | 1998 | CONFERENCE properties are defined in iCalendar, | | 1999 | then the one with the most interactive features | | 2000 | is chosen. | | 2001 | | | 2002 | the MEMBER parameter | name | 2003 | | | 2004 | the CN parameter | participation | 2005 | | | 2006 | Maps to the standard iCalendar ROLE parameter | roles | 2007 | values REQ-PARTICIPANT, OPT-PARTICIPANT and NON- | | 2008 | PARTICIPANT. | | 2009 | | | 2010 | The "chair" role maps to the standard iCalendar | rsvpResponse | 2011 | ROLE parameter value "chair", with an implicit | | 2012 | participant of value "required". The mapping of | | 2013 | non-required chairs and other roles is | | 2014 | implementation-specific, but using "x-name" | | 2015 | parameter values is recommended. | | 2016 | | | 2017 | the PARTSTAT parameter | the DELEGATED- | 2018 | | TO parameter | 2019 | | | 2020 | scheduleSequence | the SEQUENCE | 2021 | | property of | 2022 | | the | 2023 | | participant's | 2024 | | latest iMIP | 2025 | | message | 2026 | | | 2027 | scheduleUpdated | the DTSTAMP | 2028 | | property of | 2029 | | the | 2030 | | participant's | 2031 | | latest iMIP | 2032 | | message | 2033 +--------------------------------------------------+----------------+ 2035 Table 6: Translation of Participant between JSCalendar and iCalendar 2037 For JSCalendar locations, the iCalendar counterparts are the 2038 [RFC5545] LOCATION and the extended iCalendar [RFC7986] CONFERENCE 2039 properties. Generally, use a LOCATION property if only the name 2040 property is set, CONFERENCE otherwise. For backwards compatibility 2041 with client implementations that do not support the CONFERENCE 2042 property, it is recommended to set use at least one LOCATION 2043 property, if the JSCalendar object contains locations. 2045 +-------------+-----------------------------------------------------+ 2046 | Property | iCalendar counterpart | 2047 +-------------+-----------------------------------------------------+ 2048 | name | For LOCATION: corresponds to the property value. | 2049 | | For CONFERENCE: corresponds to the LABEL parameter. | 2050 | | | 2051 | description | Implementation-specific. | 2052 | | | 2053 | rel | For CONFERENCE: implicitly "virtual". | 2054 | | Implementation-specific for LOCATION. | 2055 | | | 2056 | features | For CONFERENCE: corresponds to the FEATURE | 2057 | | parameter. Implementation-specific for LOCATION. | 2058 | | | 2059 | timeZone | Implementation-specific. | 2060 | | | 2061 | coordinates | Implementation-specific. Consider using a GEO | 2062 | | iCalendar property, along with one LOCATION or | 2063 | | CONFERENCE. | 2064 | | | 2065 | uri | For LOCATION: corresponds to the ALTREP parameter. | 2066 | | For CONFERENCE: corresponds to the property value. | 2067 | | | 2068 | linkIds | Implementation-specific. | 2069 +-------------+-----------------------------------------------------+ 2071 Table 7: Translation of Location between JSCalendar and iCalendar 2073 6.6. Unknown properties 2075 Both JSCalendar and iCalendar calendar objects may contain properties 2076 that are not expressible in the other format. This specification 2077 does not mandate how to preserve these properties. Instead, it 2078 leaves negotiation on how to treat unknown properties to client and 2079 server implementations and their protocol used to exchange calendar 2080 objects. 2082 Two notable options to represent and preserve arbitrary iCalendar 2083 object properties in JSCalendar are: 2085 o *JCal*: Define iCalendar properties in JCal format ([RFC7265]) in 2086 a vendor-specific property of the JCalendar object. The JCal- 2087 formatted value may either only contain iCalendar properties that 2088 were not mapped to JSCalendar properties, or contain the complete 2089 iCalendar object representation. 2091 o *Alternate link*: Define an alternate link (Section 4.2.5) value 2092 pointing to the iCalendar representation of the JSCalendar object. 2094 E.g. the alternative representation of a VEVENT would be 2095 represented as a link with rel "alternate" and type "text/ 2096 calendar;component=VEVENT". 2098 7. JSCalendar object examples 2100 The following examples illustrate several aspects of the JSCalendar 2101 data model and format. The examples may omit mandatory or additional 2102 properties, which is indicated by a placeholder property with key 2103 "...". While most of the examples use calendar event objects, they 2104 are also illustrative for tasks. 2106 7.1. Simple event 2108 This example illustrates a simple one-time event. It specifies a 2109 one-time event that begins on January 15, 2018 at 1pm New York local 2110 time and ends after 1 hour. 2112 { 2113 "@type": "jsevent", 2114 "uid": "2a358cee-6489-4f14-a57f-c104db4dc2f1", 2115 "updated": "2018-01-15T18:00:00Z", 2116 "title": "Some event", 2117 "start": "2018-01-15T13:00:00", 2118 "timeZone": "America/New_York", 2119 "duration": "PT1H" 2120 } 2122 7.2. Simple task 2124 This example illustrates a simple task for a plain to-do item. 2126 { 2127 "@type": "jstask", 2128 "uid": "2a358cee-6489-4f14-a57f-c104db4dc2f2", 2129 "updated": "2018-01-15T18:00:00Z", 2130 "title": "Do something" 2131 } 2133 7.3. Simple group 2135 This example illustrates a simple calendar object group that contains 2136 an event and a task. 2138 { 2139 "@type": "jsgroup", 2140 "uid": "2a358cee-6489-4f14-a57f-c104db4dc343", 2141 "updated": "2018-01-15T18:00:00Z", 2142 "name": "A simple group", 2143 "entries": [ 2144 { 2145 "@type": "jsevent", 2146 "uid": "2a358cee-6489-4f14-a57f-c104db4dc2f1", 2147 "updated": "2018-01-15T18:00:00Z", 2148 "title": "Some event", 2149 "start": "2018-01-15T13:00:00", 2150 "timeZone": "America/New_York", 2151 "duration": "PT1H" 2152 }, 2153 { 2154 "@type": "jstask", 2155 "uid": "2a358cee-6489-4f14-a57f-c104db4dc2f2", 2156 "updated": "2018-01-15T18:00:00Z", 2157 "title": "Do something" 2158 } 2159 ] 2160 } 2162 7.4. All-day event 2164 This example illustrates an event for an international holiday. It 2165 specifies an all-day event on April 1 that occurs every year since 2166 the year 1900. 2168 { 2169 "...": "", 2170 "title": "April Fool's Day", 2171 "isAllDay": true, 2172 "start": "1900-04-01T00:00:00", 2173 "duration": "P1D", 2174 "recurrenceRule": { 2175 "frequency": "yearly" 2176 } 2177 } 2179 7.5. Task with a due date 2181 This example illustrates a task with a due date. It is a reminder to 2182 buy groceries before 6pm Vienna local time on January 19, 2018. The 2183 calendar user expects to need 1 hour for shopping. 2185 { 2186 "...": "", 2187 "title": "Buy groceries", 2188 "due": "2018-01-19T18:00:00", 2189 "timeZone": "Europe/Vienna", 2190 "estimatedDuration": "PT1H" 2191 } 2193 7.6. Event with end time-zone 2195 This example illustrates the use of end time-zones by use of an 2196 international flight. The flight starts on April 1, 2018 at 9am in 2197 Berlin local time. The duration of the flight is scheduled at 10 2198 hours 30 minutes. The time at the flights destination is in the same 2199 time-zone as Tokyo. Calendar clients could use the end time-zone to 2200 display the arrival time in Tokyo local time and highlight the time- 2201 zone difference of the flight. 2203 { 2204 "...": "", 2205 "title": "Flight XY51 from FRA to NRT", 2206 "start": "2018-04-01T09:00:00", 2207 "timeZone": "Europe/Berlin", 2208 "duration": "PT10H30M", 2209 "locations": { 2210 "2a358cee-6489-4f14-a57f-c104db4dc2f1": { 2211 "rel": "end", 2212 "timeZone": "Asia/Tokyo" 2213 } 2214 } 2215 } 2217 7.7. Floating-time event (with recurrence) 2219 This example illustrates the use of floating-time. Since January 1, 2220 2018, a calendar user blocks 30 minutes every day to practice Yoga at 2221 7am local time, in whatever time-zone the user is located on that 2222 date. 2224 { 2225 "...": "", 2226 "title": "Yoga", 2227 "start": "2018-01-01T07:00:00", 2228 "duration": "PT30M", 2229 "recurrenceRule": { 2230 "frequency": "daily" 2231 } 2232 } 2234 7.8. Event with multiple locations and localization 2236 This example illustrates an event that happens at both a physical and 2237 a virtual location. Fans can see a live convert on premises or 2238 online. The event title and descriptions are localized. (Note: the 2239 localization of the event description contains an UTF-8 encoded 2240 German Umlaut. This character may have been replaced with ASCII 2241 characters in the plain-text rendering of this RFC document) 2243 { 2244 "...": "", 2245 "title": "Live from Music Bowl: The Band", 2246 "description": "Go see the biggest music event ever!", 2247 "locale": "en", 2248 "start": "2018-07-04T17:00:00", 2249 "timeZone": "America/New_York", 2250 "duration": "PT3H", 2251 "locations": { 2252 "9366e041-bb4c-4aa4-b249-b4657cab925c": { 2253 "name": "The Music Bowl", 2254 "description": "Music Bowl, Central Park, New York", 2255 "coordinates": "geo:40.7829,73.9654" 2256 }, 2257 "6f3696c6-1e07-47d0-9ce1-f50014b0041a": { 2258 "name": "Free live Stream from Music Bowl", 2259 "rel": "virtual", 2260 "features": [ 2261 "video", 2262 "audio", 2263 "chat" 2264 ], 2265 "uri": "https://stream.example.com/the_band_2018" 2266 } 2267 }, 2268 "localizations": { 2269 "de": { 2270 "title": "Live von der Music Bowl: The Band!", 2271 "description": "Schau dir das groesste Musikereignis an!", 2272 "locations/6f3696c6-1e07-47d0-9ce1-f50014b0041a/name": 2273 "Gratis Live-Stream aus der Music Bowl" 2274 } 2275 } 2276 } 2278 7.9. Recurring event with overrides 2280 This example illustrates the use of recurrence overrides. A math 2281 course at a University is held for the first time on January 8, 2018 2282 at 9am London time and occurs every week until June 25, 2018. Each 2283 lecture lasts for one hour and 30 minutes and is located at the 2284 Mathematics department. This event has exceptional occurrences: at 2285 the last occurrence of the course is an exam, which lasts for 2 hours 2286 and starts at 10am. Also, the location of the exam differs from the 2287 usual location. On April 2 no course is held. On January 5 at 2pm 2288 is an optional introduction course, that occurs before the first 2289 regular lecture. 2291 { 2292 "...": "", 2293 "title": "Calculus I", 2294 "start": "2018-01-08T09:00:00", 2295 "timeZone": "Europe/London", 2296 "duration": "PT1H30M", 2297 "locations": { 2298 "2a358cee-6489-4f14-a57f-c104db4dc2f1": { 2299 "title": "Math lab room 1", 2300 "description": "Math Lab I, Department of Mathematics" 2301 } 2302 }, 2303 "recurrenceRule": { 2304 "frequency": "weekly", 2305 "until": "2018-06-25T09:00:00" 2306 }, 2307 "recurrenceOverrides": { 2308 "2018-01-05T14:00:00": { 2309 "title": "Introduction to Calculus I (optional)" 2310 }, 2311 "2018-04-02T09:00:00": { 2312 "excluded": "true" 2313 }, 2314 "2018-06-25T09:00:00": { 2315 "title": "Calculus I Exam", 2316 "start": "2018-06-25T10:00:00", 2317 "duration": "PT2H", 2318 "locations": { 2319 "2a358cee-6489-4f14-a57f-c104db4dc2f1": { 2320 "title": "Big Auditorium", 2321 "description": "Big Auditorium, Other Road" 2322 } 2323 } 2324 } 2325 } 2326 } 2328 7.10. Recurring event with participants 2330 This example illustrates scheduled events. A team meeting occurs 2331 every week since January 8, 2018 at 9am Johannesburg time. The event 2332 owner also chairs the event. Participants meet in a virtual meeting 2333 room. An attendee has accepted the invitation, but on March 8, 2018 2334 he is unavailable and declined participation for this occurrence. 2336 { 2337 "...": "", 2338 "title": "FooBar team meeting", 2339 "start": "2018-01-08T09:00:00", 2340 "timeZone": "Africa/Johannesburg", 2341 "duration": "PT1H", 2342 "locations": { 2343 "2a358cee-6489-4f14-a57f-c104db4dc2f1": { 2344 "title": "ChatMe meeting room", 2345 "rel": "virtual", 2346 "features": [ 2347 "audio", 2348 "chat", 2349 "video" 2350 ], 2351 "uri": "https://chatme.example.com?id=1234567" 2352 } 2353 }, 2354 "recurrenceRule": { 2355 "frequency": "weekly" 2356 }, 2357 "replyTo": { 2358 "imip": "zoe@foobar.example.com" 2359 }, 2360 "participants": { 2361 "tom@foobar.example.com": { 2362 "name": "Tom Tool", 2363 "email": "tom@foobar.example.com", 2364 "rsvpResponse": "accepted", 2365 "roles": [ 2366 "attendee" 2367 ] 2368 }, 2369 "zoe@foobar.example.com": { 2370 "name": "Zoe Zelda", 2371 "email": "zoe@foobar.example.com", 2372 "rsvpResponse": "accepted", 2373 "roles": [ 2374 "owner", 2375 "chair" 2376 ] 2377 }, 2378 "...": "" 2379 }, 2380 "recurrenceOverrides": { 2381 "2018-03-08T09:00:00": { 2382 "participants/tom@foobar.example.com/rsvpResponse": "declined" 2383 } 2384 } 2385 } 2387 8. Security Considerations 2389 The use of JSON as a format does have its own inherent security risks 2390 as discussed in Section 12 of [RFC8259]. Even though JSON is 2391 considered a safe subset of JavaScript, it should be kept in mind 2392 that a flaw in the parser processing JSON could still impose a 2393 threat, which doesn't arise with conventional iCalendar data. 2395 With this in mind, a parser for JSON data aware of the security 2396 implications should be used for the format described in this 2397 document. For example, the use of JavaScript's "eval()" function is 2398 considered an unacceptable security risk, as described in Section 12 2399 of[RFC8259]. A native parser with full awareness of the JSON format 2400 should be preferred. 2402 9. IANA Considerations 2404 This document amends the "application/calendar" MIME media type 2405 defined in [RFC7265]. 2407 New optional parameter: "type" with value being one of "jsevent", 2408 "jstask", "jsgroup". The parameter MUST NOT occur more than once. 2410 10. Acknowledgments 2412 The authors would like to thank the members of CalConnect for their 2413 valuable contributions. This specification originated from the work 2414 of the API technical committee of CalConnect, the Calendaring and 2415 Scheduling Consortium. 2417 11. References 2419 11.1. Normative References 2421 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2422 Requirement Levels", BCP 14, RFC 2119, 2423 DOI 10.17487/RFC2119, March 1997, 2424 . 2426 [RFC2183] Troost, R., Dorner, S., and K. Moore, Ed., "Communicating 2427 Presentation Information in Internet Messages: The 2428 Content-Disposition Header Field", RFC 2183, 2429 DOI 10.17487/RFC2183, August 1997, 2430 . 2432 [RFC2392] Levinson, E., "Content-ID and Message-ID Uniform Resource 2433 Locators", RFC 2392, DOI 10.17487/RFC2392, August 1998, 2434 . 2436 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 2437 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 2438 . 2440 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2441 Resource Identifier (URI): Generic Syntax", STD 66, 2442 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2443 . 2445 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 2446 Unique IDentifier (UUID) URN Namespace", RFC 4122, 2447 DOI 10.17487/RFC4122, July 2005, 2448 . 2450 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 2451 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 2452 . 2454 [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, 2455 "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, 2456 DOI 10.17487/RFC4791, March 2007, 2457 . 2459 [RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and 2460 Scheduling Core Object Specification (iCalendar)", 2461 RFC 5545, DOI 10.17487/RFC5545, September 2009, 2462 . 2464 [RFC5546] Daboo, C., Ed., "iCalendar Transport-Independent 2465 Interoperability Protocol (iTIP)", RFC 5546, 2466 DOI 10.17487/RFC5546, December 2009, 2467 . 2469 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 2470 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 2471 September 2009, . 2473 [RFC5870] Mayrhofer, A. and C. Spanring, "A Uniform Resource 2474 Identifier for Geographic Locations ('geo' URI)", 2475 RFC 5870, DOI 10.17487/RFC5870, June 2010, 2476 . 2478 [RFC6047] Melnikov, A., Ed., "iCalendar Message-Based 2479 Interoperability Protocol (iMIP)", RFC 6047, 2480 DOI 10.17487/RFC6047, December 2010, 2481 . 2483 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 2484 and D. Orchard, "URI Template", RFC 6570, 2485 DOI 10.17487/RFC6570, March 2012, 2486 . 2488 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 2489 Specifications and Registration Procedures", BCP 13, 2490 RFC 6838, DOI 10.17487/RFC6838, January 2013, 2491 . 2493 [RFC6901] Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., 2494 "JavaScript Object Notation (JSON) Pointer", RFC 6901, 2495 DOI 10.17487/RFC6901, April 2013, 2496 . 2498 [RFC7265] Kewisch, P., Daboo, C., and M. Douglass, "jCal: The JSON 2499 Format for iCalendar", RFC 7265, DOI 10.17487/RFC7265, May 2500 2014, . 2502 [RFC7493] Bray, T., Ed., "The I-JSON Message Format", RFC 7493, 2503 DOI 10.17487/RFC7493, March 2015, 2504 . 2506 [RFC7529] Daboo, C. and G. Yakushev, "Non-Gregorian Recurrence Rules 2507 in the Internet Calendaring and Scheduling Core Object 2508 Specification (iCalendar)", RFC 7529, 2509 DOI 10.17487/RFC7529, May 2015, 2510 . 2512 [RFC7986] Daboo, C., "New Properties for iCalendar", RFC 7986, 2513 DOI 10.17487/RFC7986, October 2016, 2514 . 2516 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 2517 Interchange Format", STD 90, RFC 8259, 2518 DOI 10.17487/RFC8259, December 2017, 2519 . 2521 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 2522 DOI 10.17487/RFC8288, October 2017, 2523 . 2525 11.2. Informative References 2527 [draft-apthorp-ical-tasks] 2528 "Task Extensions to iCalendar", 2529 . 2531 [draft-ietf-calext-eventpub-extensions] 2532 "Event Publishing Extensions to iCalendar", 2533 . 2536 [draft-ietf-calext-ical-relations] 2537 "Support for iCalendar Relationships", 2538 . 2541 11.3. URIs 2543 [1] https://www.w3.org/TR/html/ 2545 [2] https://www.iana.org/assignments/link-relations/link- 2546 relations.xhtml 2548 [3] https://www.w3.org/TR/2011/REC-css3-color-20110607/#svg-color 2550 [4] http://www.iana.org/time-zones 2552 Authors' Addresses 2554 Neil Jenkins 2555 FastMail 2556 PO Box 234 2557 Collins St West 2558 Melbourne VIC 8007 2559 Australia 2561 Email: neilj@fastmailteam.com 2562 URI: https://www.fastmail.com 2564 Robert Stepanek 2565 FastMail 2566 PO Box 234 2567 Collins St West 2568 Melbourne VIC 8007 2569 Australia 2571 Email: rsto@fastmailteam.com 2572 URI: https://www.fastmail.com