idnits 2.17.1 draft-ietf-calext-jscalendar-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- 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 9, 2018) is 2150 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 2332 -- Looks like a reference, but probably isn't: '2' on line 2334 -- Looks like a reference, but probably isn't: '3' on line 2337 -- Looks like a reference, but probably isn't: '4' on line 2339 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 10, 2018 May 9, 2018 7 JSCalendar: A JSON representation of calendar data 8 draft-ietf-calext-jscalendar-03 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 10, 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 . . . . . . . . . . . . . . . . . . . . . . . 6 62 3.2.1. UTCDate . . . . . . . . . . . . . . . . . . . . . . . 6 63 3.2.2. LocalDate . . . . . . . . . . . . . . . . . . . . . . 7 64 3.2.3. Duration . . . . . . . . . . . . . . . . . . . . . . 7 65 3.2.4. PatchObject . . . . . . . . . . . . . . . . . . . . . 7 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 . . . . . . . . . . . . . . . . . . . . . . 11 78 4.1.8. method . . . . . . . . . . . . . . . . . . . . . . . 11 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 . . . . . . . . . . . . . . . . . . . . . . . 15 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 . . . . . . . . . . . . . . . . . . . 16 91 4.3.2. recurrenceOverrides . . . . . . . . . . . . . . . . . 18 92 4.4. Sharing and scheduling properties . . . . . . . . . . . . 19 93 4.4.1. priority . . . . . . . . . . . . . . . . . . . . . . 19 94 4.4.2. freeBusyStatus . . . . . . . . . . . . . . . . . . . 19 95 4.4.3. privacy . . . . . . . . . . . . . . . . . . . . . . . 20 96 4.4.4. replyTo . . . . . . . . . . . . . . . . . . . . . . . 21 97 4.4.5. participants . . . . . . . . . . . . . . . . . . . . 22 99 4.5. Alerts properties . . . . . . . . . . . . . . . . . . . . 25 100 4.5.1. useDefaultAlerts . . . . . . . . . . . . . . . . . . 25 101 4.5.2. alerts . . . . . . . . . . . . . . . . . . . . . . . 25 102 5. Type-specific JSCalendar properties . . . . . . . . . . . . . 28 103 5.1. JSEvent properties . . . . . . . . . . . . . . . . . . . 28 104 5.1.1. start . . . . . . . . . . . . . . . . . . . . . . . . 28 105 5.1.2. timeZone . . . . . . . . . . . . . . . . . . . . . . 28 106 5.1.3. duration . . . . . . . . . . . . . . . . . . . . . . 28 107 5.1.4. isAllDay . . . . . . . . . . . . . . . . . . . . . . 29 108 5.1.5. status . . . . . . . . . . . . . . . . . . . . . . . 29 109 5.2. JSTask properties . . . . . . . . . . . . . . . . . . . . 29 110 5.2.1. due . . . . . . . . . . . . . . . . . . . . . . . . . 29 111 5.2.2. start . . . . . . . . . . . . . . . . . . . . . . . . 29 112 5.2.3. timeZone . . . . . . . . . . . . . . . . . . . . . . 30 113 5.2.4. estimatedDuration . . . . . . . . . . . . . . . . . . 30 114 5.2.5. completed . . . . . . . . . . . . . . . . . . . . . . 30 115 5.2.6. isAllDay . . . . . . . . . . . . . . . . . . . . . . 30 116 5.2.7. progress . . . . . . . . . . . . . . . . . . . . . . 31 117 5.2.8. status . . . . . . . . . . . . . . . . . . . . . . . 31 118 5.3. JSGroup properties . . . . . . . . . . . . . . . . . . . 32 119 5.3.1. entries . . . . . . . . . . . . . . . . . . . . . . . 33 120 5.3.2. source . . . . . . . . . . . . . . . . . . . . . . . 33 121 6. Conversion from and to iCalendar . . . . . . . . . . . . . . 33 122 6.1. JSEvent . . . . . . . . . . . . . . . . . . . . . . . . . 33 123 6.2. JSTask . . . . . . . . . . . . . . . . . . . . . . . . . 34 124 6.3. JSGroup . . . . . . . . . . . . . . . . . . . . . . . . . 36 125 6.4. Common properties . . . . . . . . . . . . . . . . . . . . 36 126 6.5. Locations and participants . . . . . . . . . . . . . . . 38 127 6.6. Unknown properties . . . . . . . . . . . . . . . . . . . 41 128 7. JSCalendar object examples . . . . . . . . . . . . . . . . . 42 129 7.1. Simple event . . . . . . . . . . . . . . . . . . . . . . 42 130 7.2. Simple task . . . . . . . . . . . . . . . . . . . . . . . 42 131 7.3. Simple group . . . . . . . . . . . . . . . . . . . . . . 42 132 7.4. All-day event . . . . . . . . . . . . . . . . . . . . . . 43 133 7.5. Task with a due date . . . . . . . . . . . . . . . . . . 43 134 7.6. Event with end time-zone . . . . . . . . . . . . . . . . 44 135 7.7. Floating-time event (with recurrence) . . . . . . . . . . 44 136 7.8. Event with multiple locations . . . . . . . . . . . . . . 45 137 7.9. Recurring event with overrides . . . . . . . . . . . . . 45 138 7.10. Recurring event with participants . . . . . . . . . . . . 46 139 8. Security Considerations . . . . . . . . . . . . . . . . . . . 48 140 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 48 141 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 48 142 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 48 143 11.1. Normative References . . . . . . . . . . . . . . . . . . 48 144 11.2. Informative References . . . . . . . . . . . . . . . . . 50 145 11.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 51 146 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 51 148 1. Introduction 150 This document defines a data model for calendar event and task 151 objects, or groups of such objects, in electronic calendar 152 applications and systems. It aims to be unambiguous, extendable and 153 simple to process. 155 The key design considerations for this data model are as follows: 157 o The attributes of the calendar entry represented must be described 158 as a simple key-value pair, reducing complexity of its 159 representation. 161 o The data model should avoid all ambiguities and make it difficult 162 to make mistakes during implementation. 164 o Most of the initial set of attributes should be taken from the 165 iCalendar data format ([RFC5545], also see Section 1.1), but the 166 specification should add new attributes or value types, or not 167 support existing ones, where appropriate. Conversion between the 168 data formats need not fully preserve semantic meaning. 170 o Extensions, such as new properties and components, MUST NOT lead 171 to requiring an update to this document. 173 The representation of this data model is defined in the I-JSON format 174 [RFC7493], which is a strict subset of the JavaScript Object Notation 175 (JSON) Data Interchange Format [RFC8259]. Using JSON mostly is a 176 pragmatic choice: its widespread use should help to speed up 177 JSCalendar adoption and a wide range of production-ready JSON 178 implementations allows to decrease interoperability issues. 180 1.1. Relation to the iCalendar format 182 The iCalendar data format [RFC5545], a widely deployed interchange 183 format for calendaring and scheduling data, has served calendaring 184 vendors for a long while, but contains some ambiguities and pitfalls 185 that can not be overcome without backward-incompatible changes. 187 For example, iCalendar defines various formats for local times, UTC 188 time and dates, which confuses new users. Other sources for errors 189 are the requirement for custom time-zone definitions within a single 190 calendar component, as well as the iCalendar format itself; the 191 latter causing interoperability issues due to misuse of CR LF 192 terminated strings, line continuations and subtle differences between 193 iCalendar parsers. Lastly, up until recently the iCalendar format 194 did not allow to express the difference between two calendar 195 components, which results in verbose exchanges during scheduling. 197 Some of these issues were addressed by the jCal [RFC7265] format, 198 which is a direct mapping between iCalendar and JSON. However, it 199 did not attempt to extend or update iCalendar semantics. 201 1.2. Notational Conventions 203 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 204 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 205 document are to be interpreted as described in [RFC2119]. 207 The underlying format used for this specification is JSON. 208 Consequently, the terms "object" and "array" as well as the four 209 primitive types (strings, numbers, booleans, and null) are to be 210 interpreted as described in Section 1 of[RFC8259]. 212 Some examples in this document contain "partial" JSON documents used 213 for illustrative purposes. In these examples, three periods "..." 214 are used to indicate a portion of the document that has been removed 215 for compactness. 217 2. JSCalendar objects 219 This section describes the calendar object types specified by 220 JSCalendar. 222 2.1. JSEvent 224 MIME type: "application/calendar+json;type=jsevent" 226 A JSEvent represents a scheduled amount of time on a calendar, 227 typically a meeting, appointment, reminder or anniversary. Multiple 228 participants may partake in the event at multiple locations. 230 The @type (Section 4.1.1) property value MUST be "jsevent". 232 2.2. JSTask 234 MIME type: "application/calendar+json;type=jstask" 236 A JSTask represents an action-item, assignment, to-do or work item . 238 The @type (Section 4.1.1) property value MUST be "jstask". 240 A JSTask may start and be due at certain points in time, may take 241 some estimated time to complete and may recur; none of which is 242 required. This notably differs from JSEvent (Section 2.1) which is 243 required to start at a certain point in time and typically takes some 244 non-zero duration to complete. 246 2.3. JSGroup 248 MIME type: "application/calendar+json;type=jsgroup" 250 A JSGroup is a collection of JSEvent (Section 2.1) and JSTask 251 (Section 2.2) objects. Typically, objects are grouped by topic (e.g. 252 by keywords) or calendar membership. 254 The @type (Section 4.1.1) property value MUST be "jsgroup". 256 3. Structure of JSCalendar objects 258 A JSCalendar object is a JSON object, which MUST be valid I-JSON (a 259 stricter subset of JSON), as specified in [RFC8259]. Property names 260 and values are case-sensitive. 262 The object has a collection of properties, as specified in the 263 following sections. Unless otherwise specified, all properties are 264 optional; omitted properties MUST be treated identically to if that 265 property had the value of "null", unless otherwise specified. 267 3.1. Type signatures 269 Types signatures are given for all JSON objects in this document. 270 The following conventions are used: 272 o "Boolean|String": The value is either a JSON "Boolean" value, or a 273 JSON "String" value. 275 o "Foo": Any name that is not a native JSON type means an object for 276 which the properties (and their types) are defined elsewhere 277 within this document. 279 o "Foo[]": An array of objects of type "Foo". 281 o "String[Foo]": A JSON "Object" being used as a map (associative 282 array), where all the values are of type "Foo". 284 3.2. Data Types 286 In addition to the standard JSON data types, the following data types 287 are used in this specification: 289 3.2.1. UTCDate 291 This is a string in [RFC3339] "date-time" format, with the further 292 restrictions that any letters MUST be in upper-case, the time 293 component MUST be included and the time MUST be in UTC. Fractional 294 second values MUST NOT be included unless non-zero and MUST NOT have 295 trailing zeros, to ensure there is only a single representation for 296 each date-time. 298 For example "2010-10-10T10:10:10.003Z" is OK, but 299 "2010-10-10T10:10:10.000Z" is invalid and MUST be encoded as 300 "2010-10-10T10:10:10Z". 302 In common notation, it should be of the form "YYYY-MM-DDTHH:MM:SSZ". 304 3.2.2. LocalDate 306 This is a date-time string _with no time-zone/offset information_. 307 It is otherwise in the same format as UTCDate: "YYYY-MM-DDTHH:MM:SS". 308 The time-zone to associate the LocalDate with comes from an 309 associated property, or if no time-zone is associated it defines 310 _floating time_. Floating date-times are not tied to any specific 311 time-zone. Instead, they occur in every timezone at the same _wall- 312 clock_ time (as opposed to the same instant point in time). 314 3.2.3. Duration 316 A duration is represented by a subset of ISO8601 duration format, as 317 specified by the following ABNF: 319 dur-secfrac = "." 1*DIGIT 320 dur-second = 1*DIGIT [dur-secfrac] "S" 321 dur-minute = 1*DIGIT "M" [dur-second] 322 dur-hour = 1*DIGIT "H" [dur-minute] 323 dur-time = "T" (dur-hour / dur-minute / dur-second) 324 dur-day = 1*DIGIT "D" 326 duration = "P" (dur-day [dur-time] / dur-time) 328 In addition, the duration MUST NOT include fractional second values 329 unless the fraction is non-zero. A zero duration MUST be represented 330 as "P0D". 332 3.2.4. PatchObject 334 A *PatchObject* is of type "String[*|null]", and represents an 335 unordered set of patches on a JSON object. The keys are a path in a 336 subset of [RFC6901] JSON pointer format, with an implicit leading "/" 337 (i.e. prefix each key with "/" before applying the JSON pointer 338 evaluation algorithm). 340 A patch within a PatchObject is only valid, if all of the following 341 conditions apply: 343 1. The pointer MUST NOT reference inside an array (i.e. it MUST NOT 344 insert/delete from an array; the array MUST be replaced in its 345 entirety instead). 347 2. When evaluating a path, all parts prior to the last (i.e. the 348 value after the final slash) MUST exist. 350 3. There MUST NOT be two patches in the PatchObject where the 351 pointer of one is the prefix of the pointer of the other, e.g. 352 "alerts/1/offset" and "alerts". 354 The value associated with each pointer is either: 356 o "null": Remove the property from the patched object. If not 357 present in the parent, this a no-op. 359 o Anything else: The value to replace the inherited property on the 360 patch object with (if present) or add to the property (if not 361 present). 363 Implementations MUST reject a PatchObject if any of its patches are 364 invalid. 366 3.2.5. Identifiers 368 If not noted otherwise, properties that define identifiers MUST be 369 string values, MUST be at least 1 character in length and maximum 256 370 octets in size, and MUST only contain characters from the "URL and 371 Filename safe" Base 64 Alphabet, as defined in section 5 of 372 [RFC4648]. This is the ASCII alphanumeric characters (A-Za-z0-9), 373 hyphen (-), and underscore (_). 375 3.2.6. Normalisation and equivalence 377 JSCalendar aims to provide unambiguous definitions for value types 378 and properties, but does not define a general normalisation or 379 equivalence method for JSCalendar objects and types. This is because 380 the notion of equivalence might range from byte-level equivalence to 381 semantic equivalence, depending on the respective use case (for 382 example, the CalDAV protocol [RFC4791] requires octet equivalence of 383 the encoded calendar object to determine ETag equivalence). 385 Normalisation of JSCalendar objects is hindered because of the 386 following reasons: 388 o Custom JSCalendar properties may contain arbitrary JSON values, 389 including arrays. However, equivalence of arrays might or might 390 not depend on the order of elements, depending on the respective 391 property definition. 393 o Several JSCalendar property values are defined as URIs and MIME 394 types, but normalisation of these types is inherently protocol and 395 scheme-specific, depending on the use-case of the equivalence 396 definition (see section 6 of [RFC3986]). 398 Considering this, the definition of equivalence and normalisation is 399 left to client and server implementations and to be negotiated by a 400 calendar exchange protocol or defined by another RFC. 402 3.3. Custom property extensions and values 404 Vendors MAY add additional properties to the calendar object to 405 support their custom features. The names of these properties MUST be 406 prefixed with a domain name controlled by the vendor to avoid 407 conflict, e.g. "example.com/customprop". 409 Some JSCalendar properties allow vendor-specific value extensions. 410 If so, vendor specific values MUST be prefixed with a domain name 411 controlled by the vendor, e.g. "example.com/customrel", unless 412 otherwise noted. 414 4. Common JSCalendar properties 416 This section describes the properties that are common to the various 417 JSCalendar object types. Specific JSCalendar object types may only 418 support a subset of these properties. The object type definitions in 419 section Section 5 describe the set of supported properties per type. 421 4.1. Metadata properties 423 4.1.1. @type 425 Type: "String" 427 Specifies the type which this object represents. This MUST be one of 428 the following values, registered in a future RFC, or a vendor- 429 specific value: 431 o "jsevent": a JSCalendar event (Section 2.1). 433 o "jstask": a JSCalendar task (Section 2.2). 435 o "jsgroup": a JSCalendar group (Section 2.3). 437 A valid JSCalendar object MUST include this property. 439 4.1.2. uid 441 Type: "String" 443 A globally unique identifier, used to associate the object as the 444 same across different systems, calendars and views. The value of 445 this property MUST be unique across _all_ JSCalendar objects, even if 446 they are of different type. [RFC4122] describes a range of 447 established algorithms to generate universally unique identifiers 448 (UUID), and the random or pseudo-random version is recommended to 449 use. 451 For compatibility with [RFC5545] UIDs, implementations MUST be able 452 to receive and persist values of at least 255 octets for this 453 property, but they MUST NOT truncate values in the middle of a UTF-8 454 multi-octet sequence. 456 A valid JSCalendar object MUST include this property. 458 4.1.3. relatedTo 460 Type: "String[Relation]|null" 462 Relates the object to other JSCalendar objects. This is represented 463 as a map of the uids of the related objects to information about the 464 relation. 466 A *Relation* object has the following properties: 468 o *relation*: "String[]" Describes how the linked object is related 469 to this object. 471 The strings in the array MUST each be at most one of the following 472 values, registered in a future RFC, or a vendor-specific value: 474 * "first": The linked object is the first in the series this 475 object is part of. 477 * "next": The linked object is the next in the series this object 478 is part of. 480 * "child": The linked object is a subpart of this object. 482 * "parent": This object is part of the overall linked object. 484 If an object is split to make a "this and future" change to a 485 recurrence, the original object MUST be truncated to end at the 486 previous occurrence before this split, and a new object created to 487 represent all the objects after the split. A "relation=["next"]" 488 relatedTo property MUST be set on the original object with the uid of 489 the new object. A "relation=["first"]" relatedTo property with the 490 UID of the first object in the series MUST be set on the new object. 491 Clients can then follow these UIDs to get the complete set of objects 492 if the user wishes to modify them all at once. 494 4.1.4. prodId 496 Type: "String|null" 498 The identifier for the product that created the JSCalendar object. 500 The vendor of the implementation SHOULD ensure that this is a 501 globally unique identifier, using some technique such as an FPI 502 value, as defined in [ISO.9070.1991]. It MUST only use characters of 503 an iCalendar TEXT data value (see section 3.3.11 in [RFC5545]). 505 This property SHOULD NOT be used to alter the interpretation of an 506 JSCalendar object beyond the semantics specified in this document. 507 For example, it is not to be used to further the understanding of 508 non-standard properties. 510 4.1.5. created 512 Type: "UTCDate|null" 514 The date and time this object was initially created. 516 4.1.6. updated 518 Type: "UTCDate" 520 The date and time the data in this object was last modified. 522 4.1.7. sequence 524 Type: "Number" (Defaults to "0" if omitted) 526 Initially zero, this MUST be a non-negative integer that is 527 monotonically incremented each time a change is made to the object. 529 4.1.8. method 531 Type: "String|null" 533 The iTIP ([RFC5546]) method, in lower-case. Used for scheduling. 535 4.2. What and where properties 537 4.2.1. title 539 Type: "String" (Defaults to the empty string if omitted) 541 A short summary of the object. 543 4.2.2. description 545 Type: "String" (Defaults to the empty string if omitted) 547 A longer form description of the object. This is plain text, but a 548 client SHOULD attempt to hyperlink URLs when displaying it. 550 4.2.3. htmlDescription 552 Type: "String|null" (Defaults to null if omitted) 554 A longer form rich-text description of the object. This is HTML text 555 [1] and allows to reference resources in the *links* property by use 556 of CID URLs (see [RFC2392]). To convert a CID URL to the *cid* 557 property value of a *Link* object, implementations MUST follow the 558 conversion described in section 2 of [RFC2392]. Implementations MAY 559 choose not to follow untrusted external CID URLs referenced in the 560 *links* property, in which case they MUST treat the *htmlDescription* 561 property as if omitted. Implementations MUST preserve the value of 562 this property, even if it contains untrusted links. 564 4.2.4. locations 566 Type: "String[Location]|null" 568 A map of location ids to Location objects, representing locations 569 associated with the object. A location id may be any valid [RFC6901] 570 JSON pointer and need only be unique to this object; a UUID is a 571 practical choice. 573 A *Location* object has the following properties. All properties are 574 optional, but every Location object MUST have at least one property: 576 o *name*: "String" (Defaults to the empty string if omitted) The 577 human-readable name of the location. 579 o *description*: "String|null" Human-readable instructions for 580 accessing this location. This may be an address, set of 581 directions, door access code, etc. 583 o *rel*: "String" (Defaults to "unknown" if omitted) The relation 584 type of this location to the JSCalendar object. 586 This MUST be either one of the following values, registered in a 587 future RFC, or a vendor-specific value. Any value the client or 588 server doesn't understand should be treated the same as "unknown". 590 * "start": The JSCalendar object starts at this location. 592 * "end": The JSCalendar object ends at this location. 594 * "virtual": This is not a physical location (e.g. this location 595 is an online chat room where people will meet). 597 * "unknown": The relation of this location to the calendar object 598 is unknown. 600 o *features*: "String[]|null" The features supported by this 601 location. 603 The strings in the array MUST each be either one of the following 604 values, registered in a future RFC, or a vendor-specific value. 605 Any value the client or server doesn't understand should be 606 ignored, but preserved. 608 The features supported by locations with rel-type "virtual" are: 610 * "audio": audio conferencing 612 * "chat": chat or instant messaging 614 * "feed": blog or atom feed 616 * "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 757 4.3.1. recurrenceRule 759 Type: "Recurrence" 761 Defines a recurrence rule (repeating pattern) for recurring calendar 762 objects. 764 A *Recurrence* object is a JSON object mapping of a RECUR value type 765 in iCalendar, see [RFC5545] and[RFC7529]. Objects recur by applying 766 the recurrence rule (and *recurrenceOverrides*) to the *start* date/ 767 time. A JSTask (Section 2.2) without a *start* property value recurs 768 by its *due* date/time, if defined. 770 A Recurrence object has the following properties: 772 o *frequency*: "String" This MUST be one of the following values: 774 * "yearly" 775 * "monthly" 777 * "weekly" 779 * "daily" 781 * "hourly" 783 * "minutely" 785 * "secondly" 787 To convert from iCalendar, simply lower-case the FREQ part. 789 o *interval*: "Number"(optional, defaults to "1") The INTERVAL part 790 from iCal. If included, it MUST be an integer "x >= 1". 792 o *rscale*: "String"(optional, defaults to ""gregorian"") The RSCALE 793 part from iCalendar RSCALE [RFC7529], converted to lower-case. 795 o *skip*: "String"(optional, defaults to ""omit"") The SKIP part 796 from iCalendar RSCALE [RFC7529], converted to lower-case. 798 o *firstDayOfWeek*: "String"(optional, defaults to ""mo"") The WKST 799 part from iCalendar, represented as a lower-case abbreviated two- 800 letter English day of the week. If included, it MUST be one of 801 the following values: ""mo"|"tu"|"we"|"th"|"fr"|"sa"|"su"". 803 o *byDay*: "NDay[]"(optional) An *NDay* object has the following 804 properties: 806 * *day*: "String" The day-of-the-week part of the BYDAY value in 807 iCalendar, lower-cased. MUST be one of the following values: 808 ""mo"|"tu"|"we"|"th"|"fr"|"sa"|"su"". 810 * *nthOfPeriod*: "Number"(optional) The optional ordinal part of 811 the BYDAY value in iCalendar (e.g. ""+1"" or ""-3""). If 812 present, rather than representing every occurrence of the 813 weekday defined in the *day* property of this *NDay*, it 814 represents only a specific instance within the recurrence 815 period. The value can be positive or negative, but MUST NOT be 816 zero. A negative integer means nth-last of period. 818 o *byMonthDay*: "Number[]"(optional) The BYMONTHDAY part from 819 iCalendar. The array MUST have at least one entry if included. 821 o *byMonth*: "String[]"(optional) The BYMONTH part from iCalendar. 822 Each entry is a string representation of a number, starting from 823 "1" for the first month in the calendar (e.g. ""1" " means 824 ""January"" with Gregorian calendar), with an optional ""L"" 825 suffix (see [RFC7529]) for leap months (this MUST be upper-case, 826 e.g. ""3L""). The array MUST have at least one entry if included. 828 o *byYearDay*: "Number[]"(optional) The BYYEARDAY part from 829 iCalendar. The array MUST have at least one entry if included. 831 o *byWeekNo*: "Number[]"(optional) The BYWEEKNO part from iCalendar. 832 The array MUST have at least one entry if included. 834 o *byHour*: "Number[]"(optional) The BYHOUR part from iCalendar. 835 The array MUST have at least one entry if included. 837 o *byMinute*: "Number[]"(optional) The BYMINUTE part from iCalendar. 838 The array MUST have at least one entry if included. 840 o *bySecond*: "Number[]"(optional) The BYSECOND part from iCalendar. 841 The array MUST have at least one entry if included. 843 o *bySetPosition*: "Number[]"(optional) The BYSETPOS part from 844 iCalendar. The array MUST have at least one entry if included. 846 o *count*: "Number"(optional) The COUNT part from iCalendar. This 847 MUST NOT be included if an *until* property is specified. 849 o *until*: "LocalDate"(optional) The UNTIL part from iCalendar. 850 This MUST NOT be included if a *count* property is specified. 851 Note, as in iCalendar, this date is presumed to be in the time- 852 zone specified in *timeZone*. It is not a UTC time. 854 4.3.2. recurrenceOverrides 856 Type: "LocalDate[PatchObject|null]|null" 858 A map of the recurrence-ids (the date-time of the start of the 859 occurrence) to either "null", to indicate the occurrence should be 860 deleted, or an object of patches to apply to the generated occurrence 861 object. 863 If the recurrence-id does not match an expanded start date from a 864 recurrence rule, it is to be treated as an additional occurrence 865 (like an RDATE from iCalendar). The patch object may often be empty 866 in this case. 868 By default, an occurrence inherits all properties from the main 869 object except the start (or due) date-time, which is shifted to the 870 new start time. However, individual properties of the occurrence can 871 be modified by a patch, or multiple patches. 873 A pointer in the PatchObject MUST NOT start with one of the following 874 prefixes; any patch with such a key MUST be ignored: 876 o @type 878 o uid 880 o relatedTo 882 o prodId 884 o method 886 o isAllDay 888 o recurrenceRule 890 o recurrenceOverrides 892 o replyTo 894 4.4. Sharing and scheduling properties 896 4.4.1. priority 898 Type: "Number"(defaults to "0" if omitted) 900 Specifies a priority for the calendar object. This may be used as 901 part of scheduling systems to help resolve conflicts for a time 902 period. 904 The priority is specified as an integer in the range 0 to 9. A value 905 of 0 specifies an undefined priority. A value of 1 is the highest 906 priority. A value of 2 is the second highest priority. Subsequent 907 numbers specify a decreasing ordinal priority. A value of 9 is the 908 lowest priority. Other integer values are reserved for future use. 910 4.4.2. freeBusyStatus 912 Type: "String"(defaults to "busy" if omitted) 914 Specifies how this property should be treated when calculating free- 915 busy state. The value MUST be one of: 917 o ""free"": The object should be ignored when calculating whether 918 the user is busy. 920 o ""busy"": The object should be included when calculating whether 921 the user is busy. 923 4.4.3. privacy 925 Type: "String"(defaults to "public" if omitted) 927 Calendar objects are normally collected together and may be shared 928 with other users. The privacy property allows the object owner to 929 indicate that it should not be shared, or should only have the time 930 information shared but the details withheld. Enforcement of the 931 restrictions indicated by this property are up to the 932 implementations. 934 This property MUST NOT affect the information sent to scheduled 935 participants; it is only interpreted when the object is shared as 936 part of a shared calendar. 938 The value MUST be either one of the following values, registered in a 939 future RFC, or a vendor-specific value. Vendor specific values MUST 940 be prefixed with a domain name controlled by the vendor, e.g. 941 "example.com/topsecret". Any value the client or server doesn't 942 understand should be preserved but treated as equivalent to 943 "private". 945 o "public": The full details of the object are visible to those whom 946 the object's calendar is shared with. 948 o "private": The details of the object are hidden; only the basic 949 time and metadata is shared. Implementations MUST ensure the 950 following properties are stripped when the object is accessed by a 951 sharee: 953 * title 955 * description 957 * htmlDescription 959 * locations 961 * links 963 * locale 964 * participants 966 * replyTo 968 In addition, any patches in "recurrenceOverrides" whose key is 969 prefixed with one of the above properties MUST be stripped. 971 o "secret": The object is hidden completely (as though it did not 972 exist) when the calendar is shared. 974 4.4.4. replyTo 976 Type: "String[String]|null" 978 Represents methods by which a participant may RSVP to the organizer 979 of the calendar object. The keys in the property value are the 980 available methods. The value is a URI to use that method. Future 981 methods may be defined in future specifications; a calendar client 982 MUST ignore any method it does not understand. 984 The following methods are defined: 986 o "imip": The organizer accepts an iMIP [RFC6047] response. The 987 value MUST be a "mailto:" URI. 989 o "web": There is a web page where the user may submit an RSVP using 990 their browser. The value MUST be an "http:" or "https:" URI 991 Template ([RFC6570]) in level 1 format. The template MAY contain 992 variables that MUST be expanded from the JSCalendar object as 993 defined in table Table 1. Calendar clients SHOULD be prepared to 994 handle authentication requests from the respective web page and 995 for the participant email, but this specification does not mandate 996 any specific mechanism. 998 +--------------+----------------------------------------------------+ 999 | Variable | Expand to | 1000 +--------------+----------------------------------------------------+ 1001 | email | The *email* property value of the replying | 1002 | | *Participant* object. | 1003 | | | 1004 | uid | The *uid* property value of the JSCalendar object. | 1005 | | | 1006 | sequence | The *sequence* property value of the JSCalendar | 1007 | | object. | 1008 | | | 1009 | recurrenceId | The recurrence-id when replying for a single | 1010 | | occurrence of a recurring JSCalendar object. The | 1011 | | value is the date-time of the non-overridden start | 1012 | | as determined by expanding the *recurrenceRule* of | 1013 | | the JSCalendar object. | 1014 +--------------+----------------------------------------------------+ 1016 Table 1: replyTo URI Template variables 1018 4.4.5. participants 1020 Type: "String[Participant]|null" 1022 A map of participant ids to participants, describing their 1023 participation in the calendar object. A participant id may be any 1024 valid [RFC6901] JSON pointer and need only be unique to this calendar 1025 object; the email address of the participant is a good choice. 1027 A *Participant* object has the following properties. Properties are 1028 mandatory unless marked otherwise: 1030 o *name*: "String" The display name of the participant (e.g. "Joe 1031 Bloggs"). 1033 o *email*: "String" The email address for the participant. 1035 o *kind*: "String"(optional, defaults to "unknown") What kind of 1036 entity this participant is. 1038 This MUST be either one of the following values, registered in a 1039 future RFC, or a vendor-specific value. Any value the client or 1040 server doesn't understand should be treated the same as "unknown". 1042 * "individual": a single person 1044 * "group": a collection of people invited as a whole 1045 * "resource": a non-human resource, e.g. a projector 1047 * "location": a physical location involved in the calendar object 1048 that needs to be scheduled, e.g. a conference room. 1050 * "unknown": no information is available about the kind of this 1051 participant. 1053 o *roles*: "String[]" A list of roles that this participant fulfils. 1055 At least one value MUST be specified for the participant. This 1056 MUST be either one of the following values, registered in a future 1057 RFC, or a vendor-specific value. Any value the client or server 1058 doesn't understand should be preserved but ignored. 1060 * "owner": The participant is an owner of the object, and allowed 1061 to make alterations to any part of it. 1063 * "attendee": The participant is an attendee of the calendar 1064 object. Attendees are only allowed to alter their own 1065 participation. 1067 * "chair": The participant is in charge of the calendar object 1068 when it occurs. 1070 o *locationId*: "String|null"(optional, defaults to "null") The 1071 location at which this participant is expected to be attending. 1073 If the value does not correspond to any location id in the 1074 locations property of the instance, this MUST be treated the same 1075 as if the participant's locationId were specified as null. 1077 o *rsvpResponse*: "String"(optional, defaults to "needs-action") The 1078 RSVP response, if any, of this participant. 1080 The value MUST be either one of the following values, registered 1081 in a future RFC, or a vendor-specific value: 1083 * "needs-action": No status yet set by the participant. 1085 * "accepted": The invited participant will participate. 1087 * "declined": The invited participant will not participate. 1089 * "tentative": The invited participant may participate. 1091 o *participation*: "String"(optional, defaults to "required") The 1092 required participation of this participant. 1094 The value MUST be either one of the following values, registered 1095 in a future RFC, or a vendor-specific value. Any value the client 1096 or server doesn't understand should be treated the same as 1097 "required". 1099 * "non-participant": Indicates a participant who is copied for 1100 information purposes only. 1102 * "optional": Indicates a participant whose participation is 1103 optional. 1105 * "required": Indicates a participant whose participation is 1106 required. 1108 o *rsvpWanted*: "Boolean"(optional, defaults to "false") If true, 1109 the organizer is expecting the participant to notify them of their 1110 status. 1112 o *scheduleSequence*: "Number"(optional, defaults to "0") The 1113 sequence number of the last response from the participant. If 1114 defined, this MUST be a non-negative integer. 1116 This can be used to determine whether the partcipant has sent a 1117 new RSVP following significant changes to the calendar object, and 1118 to determine if future responses are responding to a current or 1119 older view of the data. 1121 o *scheduleUpdated*: "UTCDate|null"(optional, defaults to "null") 1122 The *updated* property of the last iMIP response from the 1123 participant. 1125 This can be compared to the *updated* timestamp in future iMIP 1126 responses to determine if the response is older or newer than the 1127 current data. 1129 o *invitedBy*: "String|null"(optional, defaults to "null") The 1130 participant id of the participant who invited this one, if known. 1132 o *delegatedTo*: "String[]|null"(optional, defaults to "null") A 1133 list of participant ids of participants that this participant has 1134 delegated their participation to. This MUST be omitted if none 1135 (rather than an empty array). 1137 o *delegatedFrom*: "String[]|null"(optional, defaults to "null") A 1138 list of participant ids that this participant is acting as a 1139 delegate for. This MUST be omitted if none (rather than an empty 1140 array). 1142 o *memberOf*: "String[]|null"(optional, defaults to "null") A list 1143 of group participants that were invited to this calendar object, 1144 which caused this participant to be invited due to their 1145 membership of the group(s). This MUST be omitted if none (rather 1146 than an empty array). 1148 o *linkIds*: "String[]|null"(optional, defaults to "null") Links to 1149 more information about this participant, for example in vCard 1150 format. 1152 4.5. Alerts properties 1154 4.5.1. useDefaultAlerts 1156 Type: "Boolean" (defaults to "false" if omitted) 1158 If "true", use the user's default alerts and ignore the value of the 1159 *alerts* property. Fetching user defaults is dependent on the API 1160 from which this JSCalendar object is being fetched, and is not 1161 defined in this specification. If an implementation cannot determine 1162 the user's default alerts, or none are set, it MUST process the 1163 alerts property as if useDefaultAlerts is set to "false". 1165 4.5.2. alerts 1167 Type: "String[Alert]|null" 1169 A map of alert ids to Alert objects, representing alerts/reminders to 1170 display or send the user for this calendar object. An alert id may 1171 be any valid [RFC6901] JSON pointer and need only be unique to this 1172 calendar object; a globally unique id is a practical choice (also see 1173 Section 4.1.2)). 1175 An *Alert* Object has the following properties: 1177 o *relativeTo*: "String" (optional, defaults to "before-start") 1178 Specifies where the offset is relative to for the alarm to 1179 trigger. The value MUST be one of: 1181 * "before-start" 1183 * "after-start" 1185 * "before-end" 1187 * "after-end" 1189 o *offset*: "Duration" The offset from the start and end/due of the 1190 calendar object to fire the alert. If the calendar object does 1191 not define a time-zone, the user's default time-zone SHOULD be 1192 used when determining the offset, if known. Otherwise, the time- 1193 zone to use is implementation specific. 1195 o *action*: "DisplayAction|EmailAction|UnknownAction" 1197 Describes how to alert the user. 1199 A *DisplayAction* means a message (which is service dependent, but 1200 SHOULD include the title and start or due time of the calendar 1201 object) SHOULD be shown to the user on any client connected to 1202 this account at the specified time. How this message is formatted 1203 (and any sound or other method of drawing the user's attention) is 1204 client specific. It has the following properties: 1206 * *type*: "String" The value MUST be "display". 1208 * *acknowledged*: "UTCDate|null " (optional) 1210 When the user has permanently dismissed the alert the client 1211 MUST set this to the current time in UTC. Other clients which 1212 sync this property can then automatically dismiss or suppress 1213 duplicate alerts (alerts with the same alert id that triggered 1214 on or before this date-time). 1216 For a recurring calendar object, the *acknowledged* property of 1217 the parent object MUST be updated, unless the alert is already 1218 overridden in *recurrenceOverrides*. 1220 * *snoozed*: "UTCDate|null" (optional) 1222 If the user temporarily dismisses the alert, this is the UTC 1223 date-time after which it should be reshown. Clients displaying 1224 this alert SHOULD hide it if the snoozed property is updated to 1225 a time in the future. When that time is reached, the alert 1226 SHOULD be reshown unless acknowledged is now after the original 1227 trigger time. 1229 Setting this property on an instance of a recurring calendar 1230 object MUST update the alarm on the master object, unless the 1231 respective instance already is defined in 1232 "recurrenceOverrides". It MUST NOT generate an override for 1233 the sole use of snoozing an alarm. 1235 * *mediaLinks*: "String[Link]|null " (optional) 1236 A map of link identifiers to links (see Section 4.2.5) that 1237 contain media to display with this alert. Clients SHOULD play 1238 one or more of the link contents that are supported by the 1239 client implementation and are appropriate for the given device 1240 and user context. 1242 An *EmailAction* means an email SHOULD be sent as specified in the 1243 object at the specified time. It has the following properties: 1245 * *type*: "String" The value MUST be "email". 1247 * *to*: "Emailer[]" An array of name/email objects to send the 1248 alert to. 1250 An *Emailer* object has the following properties: 1252 + name: String The name of the recipient. If not known, 1253 clients SHOULD use the empty string. 1255 + email: String The email address of the recipient. 1257 * *subject*: "String" (optional) The subject to use for the 1258 email. If omitted, this is implementation specific, but the 1259 server SHOULD try to choose an appropriate subject, e.g. by 1260 including the summary. 1262 * *textBody*: "String" (optional) The plain-text body to use for 1263 the email. If omitted, the body of the email is implementation 1264 specific, but the server SHOULD include all pertinent details 1265 about the calendar object, such as summary, location and start 1266 time. 1268 * *htmlBody*: "String" (optional) The HTML body to use for the 1269 email, with rich-media content processed as for the 1270 *htmlDescription* property of the JSCalendar object (see 1271 Section 4.2.3), e.g. all CID URLs MUST be embedded in the 1272 generated alert email HTML body, or the *htmlBody* property 1273 ignored completely. If the textBody property of this alert 1274 action is not set, the server SHOULD generate a plain-text 1275 version from the HTML body and include it in a "multipart/ 1276 alternative" MIME message. 1278 * *attachments*: "String[Link]|null" (optional) A map of link 1279 identifiers to links (see Section 4.2.5). Included attachments 1280 SHOULD be embedded in the MIME message with the "Content- 1281 Disposition" header value set to "attachment" (see [RFC2183]). 1282 Implementations MAY refuse to include one or more attachments 1283 when building an alert email, in which case they MUST ignore 1284 the contents of the *attachments* property (e.g. they MUST NOT 1285 include a subset of attachments). 1287 An *UnknownAction* object is an object that contains a *type * 1288 property whose value is not "email" or "string", plus zero or more 1289 other properties. This is for compatibility with client 1290 extensions and future RFCs. The client or server SHOULD NOT 1291 trigger any type of alert for action types they do not understand, 1292 but MUST preserve them. 1294 5. Type-specific JSCalendar properties 1296 5.1. JSEvent properties 1298 In addition to the common JSCalendar object properties (Section 4) a 1299 JSEvent has the following properties: 1301 5.1.1. start 1303 Type: "LocalDate" e.g. "2015-09-02T00:00:00" 1305 The date/time the event would start in the event's time-zone. 1307 A valid JSEvent MUST include this property. 1309 5.1.2. timeZone 1311 Type: "String|null" 1313 The IANA Time Zone Database [4] name for the time-zone the event is 1314 scheduled in, or "null" for floating time. If omitted, this MUST be 1315 presumed to be "null" (i.e. floating time). 1317 5.1.3. duration 1319 Type: "Duration", e.g. "P2DT3H" (Defaults to "P0D" if omitted) 1321 The zero or positive duration of the event in absolute time (i.e. in 1322 UTC time; ignoring DST shifts). To get the end date in the event 1323 time-zone, convert start into UTC, then add the duration, then 1324 convert the result into the appropriate time-zone. 1326 A JSEvent MAY be end in a different time-zone (e.g. a plane flight 1327 crossing time-zones). In this case, the JSEvent MUST specify the end 1328 time-zone in a *location* property value that defines its *rel* to be 1329 "end" and the end time-zone in its *timeZone* property. 1331 5.1.4. isAllDay 1333 Type: "Boolean" (optional, defaults to "false") 1335 Specifies if the event an all day event, such as a birthday or public 1336 holiday. 1338 If *isAllDay* is true, then the following restrictions apply: 1340 o the *start* property MUST have a time component of "T00:00:00". 1342 o the *duration* property MUST only include a day component. 1344 Note that all-day events MAY be bound to a specific time-zone, as 1345 defined by the *timeZone* property. 1347 5.1.5. status 1349 Type: "String" 1351 The scheduling status (Section 4.4) of a JSEvent defaults to 1352 "confirmed" if omitted. 1354 If set, it MUST be one of: 1356 o "confirmed": Indicates the event is definite. 1358 o "cancelled": Indicates the event is cancelled. 1360 o "tentative": Indicates the event is tentative. 1362 5.2. JSTask properties 1364 In addition to the common JSCalendar object properties (Section 4) a 1365 JSTask has the following properties: 1367 5.2.1. due 1369 Type: "LocalDate|null" e.g. "2015-09-02T00:00:00" 1371 The date/time the task is due in the task's time-zone. 1373 5.2.2. start 1375 Type: "LocalDate|null" e.g. "2015-09-02T00:00:00" 1377 The date/time the task should start in the task's time-zone. 1379 5.2.3. timeZone 1381 Type: "String|null" 1383 The IANA Time Zone Database name for the time-zone the task is 1384 scheduled in, or "null" for floating time. If omitted, this MUST be 1385 presumed to be "null" (i.e. floating time). 1387 5.2.4. estimatedDuration 1389 Type: "Duration|null", e.g. "P2DT3H" 1391 Specifies the estimated positive duration of time the task takes to 1392 complete. 1394 If the *start* and *due* properties are set, the estimated duration 1395 SHOULD be less than or equal to the time interval between these 1396 properties. 1398 5.2.5. completed 1400 Type: "UTCDate|null", e.g. "2016-06-13T12:00:00Z" 1402 Specifies the date/time the task was completed. 1404 If the task is recurring and has future instances, a client may want 1405 to denote a specific task recurrence as completed but leave other 1406 instances as uncompleted. One way to achieve this is by overriding 1407 the completed property in the task *recurrenceOverrides*. However, 1408 this could produce a long list of completion times for regularly 1409 recurring tasks. An alternative approach is to split the JSTask into 1410 a current, single instance of JSTask with this instance completion 1411 time and a future recurring instance. Also see the definition of the 1412 *relatedTo* on splitting. 1414 5.2.6. isAllDay 1416 Type: "Boolean" (optional, defaults to "false") 1418 Specifies if the task is an all day task. 1420 If *isAllDay* is true, then the *start* and *due* properties MUST 1421 have a time component of "T00:00:00". Note that the 1422 *estimatedDuration* property MAY contain a non-zero time duration. 1423 All-day tasks MAY be bound to a specific time-zone, as defined by the 1424 *timeZone* property. 1426 5.2.7. progress 1428 In addition to the common properties of a *Participant* object 1429 (Section 4.4.5), a Participant within a JSTask supports the following 1430 property: 1432 o *progress*: "ParticipantProgress|null" The progress of the 1433 participant for this task, if known. This property MUST be "null" 1434 if the *rsvpResponse* of this participant is any other value but 1435 "accepted". 1437 A *ParticipantProgress* object has the following properties: 1439 o *status*: "String" Describes the completion status of the 1440 participant's progress. 1442 The value MUST be at most one of the following values, registered 1443 in a future RFC, or a vendor-specific value: 1445 * "completed": The participant completed their progress. 1447 * "in-process": The participant processes this task. 1449 * "failed": The participant failed to complete their progress. 1451 o *timestamp*: "UTCDate" Describes the last time when the 1452 participant progress got updated. 1454 5.2.8. status 1456 Type: "String" 1458 If omitted, the default scheduling status (Section 4.4) of a JSTask 1459 is defined as follows (in order of evaluation): 1461 o "needs-action": if the task has no participants, or if at least 1462 one participant of the task has *rsvpResponse* set to "needs- 1463 action" (eiher explicitly or by default). 1465 o "completed": if all the *ParticipantProgress* status of the task 1466 participants is "completed". 1468 o "failed": if at least one *ParticipantProgress* status of the task 1469 participants is "failed". 1471 o "in-process": if at least one *ParticipantProgress* status of the 1472 task participants is "in-process". 1474 o "pending": If none of the other criteria match. 1476 If set, it MUST be one of: 1478 o "needs-action": Indicates the task needs action. 1480 o "completed": Indicates the task is completed. If this value is 1481 set, then the timestamp in the *completed* property MUST NOT be 1482 null. 1484 o "in-process": Indicates the task is in process. 1486 o "cancelled": Indicates the task is cancelled. 1488 o "pending": Indicates the task has been created, but not yet 1489 started. 1491 o "failed": Indicates the task failed. 1493 5.3. JSGroup properties 1495 JSGroup supports the following JSCalendar properties (Section 4): 1497 o @type 1499 o uid 1501 o created 1503 o updated 1505 o categories 1507 o keywords 1509 o name 1511 o description 1513 o htmlDescription 1515 o color 1517 o links 1519 as well as the following JSGroup-specific properties: 1521 5.3.1. entries 1523 Type: "(JSTask|JSEvent)[]|null" 1525 A list of group members. The list MAY contain multiple object types 1526 and implementations MUST ignore entries of unknown type. The 1527 property value MUST either be "null" or the list MUST NOT be empty. 1529 5.3.2. source 1531 Type: "String|null" (optional, default is "null") 1533 The source from which updated versions of this group may be retrieved 1534 from. If the value is not "null", it MUST be a URI. 1536 6. Conversion from and to iCalendar 1538 This section specifies which JSCalendar properties can be mapped from 1539 and to iCalendar format. Implementations SHOULD follow these 1540 conversion guidelines. Still, JSCalendar does not restrict itself to 1541 iCalendar and conversion between these two formats MAY be lossy. 1543 6.1. JSEvent 1545 The iCalendar counterpart to *JSEvent* is the VEVENT component type 1546 [RFC5545]. A VEVENT component that is a direct child of a VCALENDAR 1547 component is equivalent to a standalone JSEvent. A VEVENT component 1548 *within* a VEVENT maps to the entries of the JSEvent 1549 *recurrenceOverrides* property. 1551 +----------+--------------------------------------------------------+ 1552 | Property | iCalendar counterpart | 1553 +----------+--------------------------------------------------------+ 1554 | isAllDay | True, if the type of the DTSTART property in iCalendar | 1555 | | is DATE. When translating from JSCalendar the | 1556 | | iCalendar DTSTART property is of DATE value type, if | 1557 | | the *isAllDay* property is set to true and the | 1558 | | *timeZone* property is null. | 1559 | | | 1560 | start | Corresponds to the DTSTART property in iCalendar. Note | 1561 | | that time-zone information is stored separately in | 1562 | | JSEvent. | 1563 | | | 1564 | timeZone | Corresponds to the TZID part of the DTSTART property | 1565 | | in iCalendar. If the event has a different end time- | 1566 | | zone to start time-zone, this should be added as a | 1567 | | JSCalendar *location* with just a *timeZone* property | 1568 | | and "rel="end"". | 1569 | | | 1570 | duration | Corresponds to the DURATION or DSTART+DTEND properties | 1571 | | in iCalendar. | 1572 +----------+--------------------------------------------------------+ 1574 Table 2: Translation between JSEvent and iCalendar 1576 6.2. JSTask 1578 The iCalendar counterpart to *JSTask* is the VTODO component type 1579 [RFC5545]. A VTODO component that is a direct child of a VCALENDAR 1580 component is equivalent to a standalone JSTask. A VTODO component 1581 *within* a master VTODO maps to the entries of the JSTask 1582 *recurrenceOverrides* property. 1584 +-------------------+-----------------------------------------------+ 1585 | Property | iCalendar counterpart | 1586 +-------------------+-----------------------------------------------+ 1587 | isAllDay | True, if the type of the DTSTART property in | 1588 | | iCalendar is DATE. When translating from | 1589 | | JSCalendar the iCalendar DTSTART property is | 1590 | | of DATE value type, if the *isAllDay* | 1591 | | property is set to true and the *timeZone* | 1592 | | property is null. | 1593 | | | 1594 | due | Corresponds to the DUE and DTSTART+DURATION | 1595 | | properties in iCalendar. When mapping | 1596 | | iCalendar VTODOs with DTSTART+DURATION, the | 1597 | | due date is the result of adding DURATION to | 1598 | | DTSTART in the DTSTART time-zone. | 1599 | | | 1600 | start | Corresponds to the DTSTART property in | 1601 | | iCalendar. | 1602 | | | 1603 | timeZone | Corresponds to the TZID part of the | 1604 | | DTSTART/DUE properties in iCalendar. If the | 1605 | | task has a different end time-zone to start | 1606 | | or due time-zone, this should be added as a | 1607 | | JSCalendar *location* with just a *timeZone* | 1608 | | property and "rel="end"". | 1609 | | | 1610 | estimatedDuration | Corresponds to the ESTIMATED-DURATION | 1611 | | iCalendar property. *NON-STANDARD*: this | 1612 | | property is currently non-standard, see | 1613 | | [draft-apthorp-ical-tasks]. | 1614 | | | 1615 | completed | Maps to the COMPLETED iCalendar property. | 1616 | | | 1617 | progress | Corresponds to the PARTSTAT and COMPLETED | 1618 | | properties in iCalendar, including the | 1619 | | currently non-standard definitions in | 1620 | | [draft-apthorp-ical-tasks]. | 1621 | | | 1622 | status | Corresponds to the STATUS property in | 1623 | | iCalendar, including the currently non- | 1624 | | standard definitions in | 1625 | | [draft-apthorp-ical-tasks]. | 1626 +-------------------+-----------------------------------------------+ 1628 Table 3: Translation between JSTask and iCalendar 1630 6.3. JSGroup 1632 A JSGroup converts to a iCalendar VCALENDAR containing VEVENT or 1633 VTODO components. 1635 +----------+--------------------------------------------------------+ 1636 | Property | iCalendar counterpart | 1637 +----------+--------------------------------------------------------+ 1638 | entries | The VEVENT and VTODO components within a top-level | 1639 | | VCALENDAR component. | 1640 | | | 1641 | source | Corresponds to the SOURCE property in iCalendar. | 1642 +----------+--------------------------------------------------------+ 1644 Table 4: Translation between JSGroup and iCalendar 1646 6.4. Common properties 1648 +---------------------+---------------------------------------------+ 1649 | Property | iCalendar counterpart | 1650 +---------------------+---------------------------------------------+ 1651 | alerts | An *Alert* corresponds to the VALARM | 1652 | | component in iCalendar, where the *action* | 1653 | | is determined by the iCalendar ACTION | 1654 | | property value (e.g., both "DISPLAY" and | 1655 | | "AUDIO" actions map to a JSCalendar | 1656 | | *DisplayAction* alert, and similarly for an | 1657 | | iCalendar "EMAIL"). The *relativeTo* and | 1658 | | *offset* properties corresponds to the | 1659 | | iCalendar TRIGGER property. The | 1660 | | *attachments* property of an *EmailAction* | 1661 | | alert map to iCalendar ATTACH properties. | 1662 | | For mapping *mediaLinks*, the iCalendar | 1663 | | currently forbids to define ATTACH | 1664 | | properties on VALARMs with DISPLAY action. | 1665 | | Mapping this property is implementation- | 1666 | | specific, but using "X-ATTACH" with the | 1667 | | same semantics as ATTACH is a sane choice. | 1668 | | | 1669 | categories | Corresponds to the STRUCTURED-CATEGORY | 1670 | | property in iCalendar, see. *NON- | 1671 | | STANDARD*: this property is currently non- | 1672 | | standard, see | 1673 | | [draft-ietf-calext-ical-relations]. | 1674 | | | 1675 | color | Corresponds to the COLOR property in | 1676 | | iCalendar, as specified in [RFC7986]. | 1677 | | | 1678 | created | Corresponds to the CREATED property in | 1679 | | iCalendar. | 1680 | | | 1681 | description | Corresponds to the DESCRIPTION property in | 1682 | | iCalendar. | 1683 | | | 1684 | htmlDescription | Corresponds to the ALTREP parameter of the | 1685 | | DESCRIPTION property (e.g. by setting | 1686 | | ALTREP to a "data:text/html" URL containing | 1687 | | the HTML text). Alternatively, use the | 1688 | | STYLED-DESCRIPTION property. *NON- | 1689 | | STANDARD*: the STYLED-DESCRIPTION property | 1690 | | currently is non-standard, see | 1691 | | [draft-ietf-calext-eventpub-extensions]. | 1692 | | | 1693 | freeBusyStatus | Corresponds to the TRANSP property in | 1694 | | iCalendar. | 1695 | | | 1696 | keywords | Corresponds to the CATEGORIES property in | 1697 | | iCalendar, as specified in [RFC7986]. | 1698 | | | 1699 | links | Corresponds to the ATTACH ([RFC5545]) or | 1700 | | IMAGE ([RFC7986]) properties with a URI | 1701 | | value type set to the link "href". | 1702 | | ([RFC7986]). The *type* property | 1703 | | corresponds to the FMTTYPE parameter, the | 1704 | | *size* property to the SIZE parameter. | 1705 | | Mapping all other properties is | 1706 | | implementation-specific. | 1707 | | | 1708 | locale | Corresponds to the LANGUAGE parameter in | 1709 | | iCalendar, which is added to individual | 1710 | | properties. When converting from | 1711 | | iCalendar, one language must be picked as | 1712 | | the main locale. | 1713 | | | 1714 | locations | See Section 6.5. | 1715 | | | 1716 | method | Corresponds to the METHOD property in | 1717 | | iCalendar. | 1718 | | | 1719 | participants | See Section 6.5. | 1720 | | | 1721 | priority | Corresponds to the PRIORITY property in | 1722 | | iCalendar. | 1723 | | | 1724 | privacy | Corresponds to the CLASS property in | 1725 | | iCalendar. | 1726 | | | 1727 | prodId | Corresponds to the PRODID property in | 1728 | | iCalendar. | 1729 | | | 1730 | recurrenceOverrides | Corresponds to the RDATE and EXDATE | 1731 | | properties in iCalendar, plus VEVENT (for | 1732 | | JSEvent) or VTODO (for JSTask) instances | 1733 | | with a recurrence-id. | 1734 | | | 1735 | recurrenceRule | Corresponds to the RRULE property in | 1736 | | iCalendar. See the property definition at | 1737 | | section Section 4.3.1 how to map a RRULE | 1738 | | value. | 1739 | | | 1740 | relatedTo | Corresponds to the RELATED-TO property in | 1741 | | iCalendar. | 1742 | | | 1743 | replyTo | An iCalendar ORGANIZER with one of the | 1744 | | mapped URIs as value. If URIs are defined | 1745 | | for both the "imip" and "web" type, it is | 1746 | | recommended to map the "imip" value to the | 1747 | | calendar address value of the ORGANIZER. | 1748 | | | 1749 | sequence | Corresponds to the SEQUENCE property in | 1750 | | iCalendar. | 1751 | | | 1752 | status | Corresponds to the STATUS property in | 1753 | | iCalendar (converted to lower-case). | 1754 | | | 1755 | title | Corresponds to the SUMMARY property in | 1756 | | iCalendar. | 1757 | | | 1758 | uid | Corresponds to the UID property in | 1759 | | iCalendar. | 1760 | | | 1761 | updated | Corresponds to the DTSTAMP and LAST- | 1762 | | MODIFIED properties in iCalendar. (These | 1763 | | are only different in the iTIP case, and | 1764 | | the difference is not actually useful.) | 1765 +---------------------+---------------------------------------------+ 1767 Table 5: Translation between JSCalendar and iCalendar 1769 6.5. Locations and participants 1771 Both JSCalendar participants and locations have counterparts in 1772 iCalendar but provide richer representation. 1774 The following table outlines translation of JSCalendar participants. 1775 Where iCalendar has distinct properties for ORGANIZER and ATTENDEE, 1776 these are merged in JSCalendar into the Participant object type. 1778 +--------------------------------------------------+----------------+ 1779 | Property | iCalendar | 1780 | | counterpart | 1781 +--------------------------------------------------+----------------+ 1782 | delegatedFrom | the DELEGATED- | 1783 | | FROM parameter | 1784 | | | 1785 | delegatedTo | email | 1786 | | | 1787 | the value of the ORGANIZER or ATTENDEE property | kind | 1788 | | | 1789 | the CUTYPE parameter | linkIds | 1790 | | | 1791 | Implementation-specific. | locationId | 1792 | | | 1793 | Implementation-specific. When mapping from | memberOf | 1794 | iCalendar to JSCalendar this may be the | | 1795 | JSCalendar identifier of a CONFERENCE property | | 1796 | that has the MODERATOR feature defined in its | | 1797 | FEATURE parameter values. If multiple such | | 1798 | CONFERENCE properties are defined in iCalendar, | | 1799 | then the one with the most interactive features | | 1800 | is chosen. | | 1801 | | | 1802 | the MEMBER parameter | name | 1803 | | | 1804 | the CN parameter | participation | 1805 | | | 1806 | Maps to the standard iCalendar ROLE parameter | roles | 1807 | values REQ-PARTICIPANT, OPT-PARTICIPANT and NON- | | 1808 | PARTICIPANT. | | 1809 | | | 1810 | The "chair" role maps to the standard iCalendar | rsvpResponse | 1811 | ROLE parameter value "chair", with an implicit | | 1812 | participant of value "required". The mapping of | | 1813 | non-required chairs and other roles is | | 1814 | implementation-specific, but using "x-name" | | 1815 | parameter values is recommended. | | 1816 | | | 1817 | the PARTSTAT parameter | the DELEGATED- | 1818 | | TO parameter | 1819 | | | 1820 | scheduleSequence | the SEQUENCE | 1821 | | property of | 1822 | | the | 1823 | | participant's | 1824 | | latest iMIP | 1825 | | message | 1826 | | | 1827 | scheduleUpdated | the DTSTAMP | 1828 | | property of | 1829 | | the | 1830 | | participant's | 1831 | | latest iMIP | 1832 | | message | 1833 +--------------------------------------------------+----------------+ 1835 Table 6: Translation of Participant between JSCalendar and iCalendar 1837 For JSCalendar locations, the iCalendar counterparts are the 1838 [RFC5545] LOCATION and the extended iCalendar [RFC7986] CONFERENCE 1839 properties. Generally, use a LOCATION property if only the name 1840 property is set, CONFERENCE otherwise. For backwards compatibility 1841 with client implementations that do not support the CONFERENCE 1842 property, it is recommended to set use at least one LOCATION 1843 property, if the JSCalendar object contains locations. 1845 +-------------+-----------------------------------------------------+ 1846 | Property | iCalendar counterpart | 1847 +-------------+-----------------------------------------------------+ 1848 | name | For LOCATION: corresponds to the property value. | 1849 | | For CONFERENCE: corresponds to the LABEL parameter. | 1850 | | | 1851 | description | Implementation-specific. | 1852 | | | 1853 | rel | For CONFERENCE: implicitly "virtual". | 1854 | | Implementation-specific for LOCATION. | 1855 | | | 1856 | features | For CONFERENCE: corresponds to the FEATURE | 1857 | | parameter. Implementation-specific for LOCATION. | 1858 | | | 1859 | timeZone | Implementation-specific. | 1860 | | | 1861 | coordinates | Implementation-specific. Consider using a GEO | 1862 | | iCalendar property, along with one LOCATION or | 1863 | | CONFERENCE. | 1864 | | | 1865 | uri | For LOCATION: corresponds to the ALTREP parameter. | 1866 | | For CONFERENCE: corresponds to the property value. | 1867 | | | 1868 | linkIds | Implementation-specific. | 1869 +-------------+-----------------------------------------------------+ 1871 Table 7: Translation of Location between JSCalendar and iCalendar 1873 6.6. Unknown properties 1875 Both JSCalendar and iCalendar calendar objects may contain properties 1876 that are not expressible in the other format. This specification 1877 does not mandate how to preserve these properties. Instead, it 1878 leaves negotiation on how to treat unknown properties to client and 1879 server implementations and their protocol used to exchange calendar 1880 objects. 1882 Two notable options to represent and preserve arbitrary iCalendar 1883 object properties in JSCalendar are: 1885 o *JCal*: Define iCalendar properties in JCal format ([RFC7265]) in 1886 a vendor-specific property of the JCalendar object. The JCal- 1887 formatted value may either only contain iCalendar properties that 1888 were not mapped to JSCalendar properties, or contain the complete 1889 iCalendar object representation. 1891 o *Alternate link*: Define an alternate link (Section 4.2.5) value 1892 pointing to the iCalendar representation of the JSCalendar object. 1894 E.g. the alternative representation of a VEVENT would be 1895 represented as a link with rel "alternate" and type "text/ 1896 calendar;component=VEVENT". 1898 7. JSCalendar object examples 1900 The following examples illustrate several aspects of the JSCalendar 1901 data model and format. The examples may omit mandatory or additional 1902 properties, which is indicated by a placeholder property with key 1903 "...". While most of the examples use calendar event objects, they 1904 are also illustrative for tasks. 1906 7.1. Simple event 1908 This example illustrates a simple one-time event. It specifies a 1909 one-time event that begins on January 15, 2018 at 1pm New York local 1910 time and ends after 1 hour. 1912 { 1913 "@type": "jsevent", 1914 "uid": "2a358cee-6489-4f14-a57f-c104db4dc2f1", 1915 "updated": "2018-01-15T18:00:00Z", 1916 "title": "Some event", 1917 "start": "2018-01-15T13:00:00", 1918 "timeZone": "America/New_York", 1919 "duration": "PT1H" 1920 } 1922 7.2. Simple task 1924 This example illustrates a simple task for a plain to-do item. 1926 { 1927 "@type": "jstask", 1928 "uid": "2a358cee-6489-4f14-a57f-c104db4dc2f2", 1929 "updated": "2018-01-15T18:00:00Z", 1930 "title": "Do something" 1931 } 1933 7.3. Simple group 1935 This example illustrates a simple calendar object group that contains 1936 an event and a task. 1938 { 1939 "@type": "jsgroup", 1940 "uid": "2a358cee-6489-4f14-a57f-c104db4dc343", 1941 "updated": "2018-01-15T18:00:00Z", 1942 "name": "A simple group", 1943 "entries": [ 1944 { 1945 "@type": "jsevent", 1946 "uid": "2a358cee-6489-4f14-a57f-c104db4dc2f1", 1947 "updated": "2018-01-15T18:00:00Z", 1948 "title": "Some event", 1949 "start": "2018-01-15T13:00:00", 1950 "timeZone": "America/New_York", 1951 "duration": "PT1H" 1952 }, 1953 { 1954 "@type": "jstask", 1955 "uid": "2a358cee-6489-4f14-a57f-c104db4dc2f2", 1956 "updated": "2018-01-15T18:00:00Z", 1957 "title": "Do something" 1958 } 1959 ] 1960 } 1962 7.4. All-day event 1964 This example illustrates an event for an international holiday. It 1965 specifies an all-day event on April 1 that occurs every year since 1966 the year 1900. 1968 { 1969 "...": "", 1970 "title": "April Fool's Day", 1971 "isAllDay": true, 1972 "start": "1900-04-01T00:00:00", 1973 "duration": "P1D", 1974 "recurrenceRule": { 1975 "frequency": "yearly" 1976 } 1977 } 1979 7.5. Task with a due date 1981 This example illustrates a task with a due date. It is a reminder to 1982 buy groceries before 6pm Vienna local time on January 19, 2018. The 1983 calendar user expects to need 1 hour for shopping. 1985 { 1986 "...": "", 1987 "title": "Buy groceries", 1988 "due": "2018-01-19T18:00:00", 1989 "timeZone": "Europe/Vienna", 1990 "estimatedDuration": "PT1H" 1991 } 1993 7.6. Event with end time-zone 1995 This example illustrates the use of end time-zones by use of an 1996 international flight. The flight starts on April 1, 2018 at 9am in 1997 Berlin local time. The duration of the flight is scheduled at 10 1998 hours 30 minutes. The time at the flights destination is in the same 1999 time-zone as Tokyo. Calendar clients could use the end time-zone to 2000 display the arrival time in Tokyo local time and highlight the time- 2001 zone difference of the flight. 2003 { 2004 "...": "", 2005 "title": "Flight XY51 from FRA to NRT", 2006 "start": "2018-04-01T09:00:00", 2007 "timeZone": "Europe/Berlin", 2008 "duration": "PT10H30M", 2009 "locations": { 2010 "2a358cee-6489-4f14-a57f-c104db4dc2f1": { 2011 "rel": "end", 2012 "timeZone": "Asia/Tokyo" 2013 } 2014 } 2015 } 2017 7.7. Floating-time event (with recurrence) 2019 This example illustrates the use of floating-time. Since January 1, 2020 2018, a calendar user blocks 30 minutes every day to practice Yoga at 2021 7am local time, in whatever time-zone the user is located on that 2022 date. 2024 { 2025 "...": "", 2026 "title": "Yoga", 2027 "start": "2018-01-01T07:00:00", 2028 "duration": "PT30M", 2029 "recurrenceRule": { 2030 "frequency": "daily" 2031 } 2032 } 2034 7.8. Event with multiple locations 2036 This example illustrates an event that happens at both a physical and 2037 a virtual location. Fans can see a live convert on premises or 2038 online. 2040 { 2041 "...": "", 2042 "title": "Live from Music Bowl: The Band", 2043 "description": "Go see the biggest music event ever!", 2044 "locale": "en", 2045 "start": "2018-07-04T17:00:00", 2046 "timeZone": "America/New_York", 2047 "duration": "PT3H", 2048 "locations": { 2049 "9366e041-bb4c-4aa4-b249-b4657cab925c": { 2050 "name": "The Music Bowl", 2051 "description": "Music Bowl, Central Park, New York", 2052 "coordinates": "geo:40.7829,73.9654" 2053 }, 2054 "6f3696c6-1e07-47d0-9ce1-f50014b0041a": { 2055 "name": "Free live Stream from Music Bowl", 2056 "rel": "virtual", 2057 "features": [ 2058 "video", 2059 "audio", 2060 "chat" 2061 ], 2062 "uri": "https://stream.example.com/the_band_2018" 2063 } 2064 } 2065 } 2067 7.9. Recurring event with overrides 2069 This example illustrates the use of recurrence overrides. A math 2070 course at a University is held for the first time on January 8, 2018 2071 at 9am London time and occurs every week until June 25, 2018. Each 2072 lecture lasts for one hour and 30 minutes and is located at the 2073 Mathematics department. This event has exceptional occurrences: at 2074 the last occurrence of the course is an exam, which lasts for 2 hours 2075 and starts at 10am. Also, the location of the exam differs from the 2076 usual location. On April 2, May 7 and May 28 no course is held. 2078 { 2079 "...": "", 2080 "title": "Calculus I", 2081 "start": "2018-01-08T09:00:00", 2082 "timeZone": "Europe/London", 2083 "duration": "PT1H30M", 2084 "locations": { 2085 "2a358cee-6489-4f14-a57f-c104db4dc2f1": { 2086 "title": "Math lab room 1", 2087 "description": "Math Lab I, Department of Mathematics" 2088 } 2089 }, 2090 "recurrenceRule": { 2091 "frequency": "weekly", 2092 "until": "2018-06-25T09:00:00" 2093 }, 2094 "recurrenceOverrides": { 2095 "2018-04-02T09:00:00": null, 2096 "2018-05-07T09:00:00": null, 2097 "2018-05-28T09:00:00": null, 2098 "2018-06-25T09:00:00": { 2099 "title": "Calculus I Exam", 2100 "start": "2018-06-25T10:00:00", 2101 "duration": "PT2H", 2102 "locations": { 2103 "2a358cee-6489-4f14-a57f-c104db4dc2f1": { 2104 "title": "Big Auditorium", 2105 "description": "Big Auditorium, Other Road" 2106 } 2107 } 2108 } 2109 } 2110 } 2112 7.10. Recurring event with participants 2114 This example illustrates scheduled events. A team meeting occurs 2115 every week since January 8, 2018 at 9am Johannesburg time. The event 2116 owner also chairs the event. Participants meet in a virtual meeting 2117 room. An attendee has accepted the invitation, but on March 8, 2018 2118 he is unavailable and declined participation for this occurrence. 2120 { 2121 "...": "", 2122 "title": "FooBar team meeting", 2123 "start": "2018-01-08T09:00:00", 2124 "timeZone": "Africa/Johannesburg", 2125 "duration": "PT1H", 2126 "locations": { 2127 "2a358cee-6489-4f14-a57f-c104db4dc2f1": { 2128 "title": "ChatMe meeting room", 2129 "rel": "virtual", 2130 "features": [ 2131 "audio", 2132 "chat", 2133 "video" 2134 ], 2135 "uri": "https://chatme.example.com?id=1234567" 2136 } 2137 }, 2138 "recurrenceRule": { 2139 "frequency": "weekly" 2140 }, 2141 "replyTo": { 2142 "imip": "zoe@foobar.example.com" 2143 }, 2144 "participants": { 2145 "tom@foobar.example.com": { 2146 "name": "Tom Tool", 2147 "email": "tom@foobar.example.com", 2148 "rsvpResponse": "accepted", 2149 "roles": [ 2150 "attendee" 2151 ] 2152 }, 2153 "zoe@foobar.example.com": { 2154 "name": "Zoe Zelda", 2155 "email": "zoe@foobar.example.com", 2156 "rsvpResponse": "accepted", 2157 "roles": [ 2158 "owner", 2159 "chair" 2160 ] 2161 }, 2162 "...": "" 2163 }, 2164 "recurrenceOverrides": { 2165 "2018-03-08T09:00:00": { 2166 "participants/tom@foobar.example.com/rsvpResponse": "declined" 2167 } 2168 } 2169 } 2171 8. Security Considerations 2173 The use of JSON as a format does have its own inherent security risks 2174 as discussed in Section 12 of [RFC8259]. Even though JSON is 2175 considered a safe subset of JavaScript, it should be kept in mind 2176 that a flaw in the parser processing JSON could still impose a 2177 threat, which doesn't arise with conventional iCalendar data. 2179 With this in mind, a parser for JSON data aware of the security 2180 implications should be used for the format described in this 2181 document. For example, the use of JavaScript's "eval()" function is 2182 considered an unacceptable security risk, as described in Section 12 2183 of[RFC8259]. A native parser with full awareness of the JSON format 2184 should be preferred. 2186 9. IANA Considerations 2188 This document amends the "application/calendar" MIME media type 2189 defined in [RFC7265]. 2191 New optional parameter: "type" with value being one of "jsevent", 2192 "jstask", "jsgroup". The parameter MUST NOT occur more than once. 2194 10. Acknowledgments 2196 The authors would like to thank the members of CalConnect for their 2197 valuable contributions. This specification originated from the work 2198 of the API technical committee of CalConnect, the Calendaring and 2199 Scheduling Consortium. 2201 11. References 2203 11.1. Normative References 2205 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2206 Requirement Levels", BCP 14, RFC 2119, 2207 DOI 10.17487/RFC2119, March 1997, 2208 . 2210 [RFC2183] Troost, R., Dorner, S., and K. Moore, Ed., "Communicating 2211 Presentation Information in Internet Messages: The 2212 Content-Disposition Header Field", RFC 2183, 2213 DOI 10.17487/RFC2183, August 1997, 2214 . 2216 [RFC2392] Levinson, E., "Content-ID and Message-ID Uniform Resource 2217 Locators", RFC 2392, DOI 10.17487/RFC2392, August 1998, 2218 . 2220 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 2221 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 2222 . 2224 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2225 Resource Identifier (URI): Generic Syntax", STD 66, 2226 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2227 . 2229 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 2230 Unique IDentifier (UUID) URN Namespace", RFC 4122, 2231 DOI 10.17487/RFC4122, July 2005, 2232 . 2234 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 2235 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 2236 . 2238 [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, 2239 "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, 2240 DOI 10.17487/RFC4791, March 2007, 2241 . 2243 [RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and 2244 Scheduling Core Object Specification (iCalendar)", 2245 RFC 5545, DOI 10.17487/RFC5545, September 2009, 2246 . 2248 [RFC5546] Daboo, C., Ed., "iCalendar Transport-Independent 2249 Interoperability Protocol (iTIP)", RFC 5546, 2250 DOI 10.17487/RFC5546, December 2009, 2251 . 2253 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 2254 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 2255 September 2009, . 2257 [RFC5870] Mayrhofer, A. and C. Spanring, "A Uniform Resource 2258 Identifier for Geographic Locations ('geo' URI)", 2259 RFC 5870, DOI 10.17487/RFC5870, June 2010, 2260 . 2262 [RFC6047] Melnikov, A., Ed., "iCalendar Message-Based 2263 Interoperability Protocol (iMIP)", RFC 6047, 2264 DOI 10.17487/RFC6047, December 2010, 2265 . 2267 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 2268 and D. Orchard, "URI Template", RFC 6570, 2269 DOI 10.17487/RFC6570, March 2012, 2270 . 2272 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 2273 Specifications and Registration Procedures", BCP 13, 2274 RFC 6838, DOI 10.17487/RFC6838, January 2013, 2275 . 2277 [RFC6901] Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., 2278 "JavaScript Object Notation (JSON) Pointer", RFC 6901, 2279 DOI 10.17487/RFC6901, April 2013, 2280 . 2282 [RFC7265] Kewisch, P., Daboo, C., and M. Douglass, "jCal: The JSON 2283 Format for iCalendar", RFC 7265, DOI 10.17487/RFC7265, May 2284 2014, . 2286 [RFC7493] Bray, T., Ed., "The I-JSON Message Format", RFC 7493, 2287 DOI 10.17487/RFC7493, March 2015, 2288 . 2290 [RFC7529] Daboo, C. and G. Yakushev, "Non-Gregorian Recurrence Rules 2291 in the Internet Calendaring and Scheduling Core Object 2292 Specification (iCalendar)", RFC 7529, 2293 DOI 10.17487/RFC7529, May 2015, 2294 . 2296 [RFC7986] Daboo, C., "New Properties for iCalendar", RFC 7986, 2297 DOI 10.17487/RFC7986, October 2016, 2298 . 2300 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 2301 Interchange Format", STD 90, RFC 8259, 2302 DOI 10.17487/RFC8259, December 2017, 2303 . 2305 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 2306 DOI 10.17487/RFC8288, October 2017, 2307 . 2309 11.2. Informative References 2311 [draft-apthorp-ical-tasks] 2312 "Task Extensions to iCalendar", 2313 . 2315 [draft-daboo-valarm-extensions] 2316 "VALARM Extensions for iCalendar", 2317 . 2320 [draft-ietf-calext-eventpub-extensions] 2321 "Event Publishing Extensions to iCalendar", 2322 . 2325 [draft-ietf-calext-ical-relations] 2326 "Support for iCalendar Relationships", 2327 . 2330 11.3. URIs 2332 [1] https://www.w3.org/TR/html/ 2334 [2] https://www.iana.org/assignments/link-relations/link- 2335 relations.xhtml 2337 [3] https://www.w3.org/TR/2011/REC-css3-color-20110607/#svg-color 2339 [4] http://www.iana.org/time-zones 2341 Authors' Addresses 2343 Neil Jenkins 2344 FastMail 2345 PO Box 234 2346 Collins St West 2347 Melbourne VIC 8007 2348 Australia 2350 Email: neilj@fastmailteam.com 2351 URI: https://www.fastmail.com 2353 Robert Stepanek 2354 FastMail 2355 PO Box 234 2356 Collins St West 2357 Melbourne VIC 8007 2358 Australia 2360 Email: rsto@fastmailteam.com 2361 URI: https://www.fastmail.com