idnits 2.17.1 draft-ietf-calext-jscalendar-icalendar-05.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 == Line 722 has weird spacing: '... x-name verba...' -- The document date (July 9, 2021) is 1023 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'RFC6868' is mentioned on line 244, but not defined == Missing Reference: 'RFC4648' is mentioned on line 271, but not defined == Unused Reference: 'RFC5546' is defined on line 2318, but no explicit reference was found in the text ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) Summary: 1 error (**), 0 flaws (~~), 5 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Calendaring extensions N. Jenkins 3 Internet-Draft R. Stepanek 4 Intended status: Standards Track FastMail 5 Expires: January 10, 2022 M. Douglass 6 BCS 7 July 9, 2021 9 JSCalendar: Converting from and to iCalendar 10 draft-ietf-calext-jscalendar-icalendar-05 12 Abstract 14 This document provides the required methods for converting JSCalendar 15 from and to iCalendar. 17 Status of This Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at https://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on January 10, 2022. 34 Copyright Notice 36 Copyright (c) 2021 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (https://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 52 1.1. Note (to be deleted later) . . . . . . . . . . . . . . . 4 53 1.2. Motivation . . . . . . . . . . . . . . . . . . . . . . . 4 54 1.3. Scope and caveats . . . . . . . . . . . . . . . . . . . . 4 55 1.4. Notational Conventions . . . . . . . . . . . . . . . . . 5 56 2. iCalendar pre-processing . . . . . . . . . . . . . . . . . . 5 57 3. Translating iCalendar components to JSCalendar . . . . . . . 6 58 3.1. VALARM . . . . . . . . . . . . . . . . . . . . . . . . . 7 59 3.2. VCALENDAR . . . . . . . . . . . . . . . . . . . . . . . . 9 60 3.3. VEVENT . . . . . . . . . . . . . . . . . . . . . . . . . 10 61 3.4. VLOCATION . . . . . . . . . . . . . . . . . . . . . . . . 10 62 3.5. VTIMEZONE, STANDARD, DAYLIGHT . . . . . . . . . . . . . . 11 63 3.6. VTODO . . . . . . . . . . . . . . . . . . . . . . . . . . 12 64 4. Translating iCalendar properties to JSCalendar . . . . . . . 13 65 4.1. ATTACH . . . . . . . . . . . . . . . . . . . . . . . . . 13 66 4.2. ATTENDEE . . . . . . . . . . . . . . . . . . . . . . . . 13 67 4.3. CALSCALE . . . . . . . . . . . . . . . . . . . . . . . . 16 68 4.4. CATEGORIES . . . . . . . . . . . . . . . . . . . . . . . 16 69 4.5. CLASS . . . . . . . . . . . . . . . . . . . . . . . . . . 16 70 4.6. COLOR . . . . . . . . . . . . . . . . . . . . . . . . . . 17 71 4.7. COMMENT . . . . . . . . . . . . . . . . . . . . . . . . . 17 72 4.8. COMPLETED . . . . . . . . . . . . . . . . . . . . . . . . 17 73 4.9. CONCEPT . . . . . . . . . . . . . . . . . . . . . . . . . 17 74 4.10. CONFERENCE . . . . . . . . . . . . . . . . . . . . . . . 18 75 4.11. CONTACT . . . . . . . . . . . . . . . . . . . . . . . . . 18 76 4.12. CREATED . . . . . . . . . . . . . . . . . . . . . . . . . 19 77 4.13. DESCRIPTION . . . . . . . . . . . . . . . . . . . . . . . 19 78 4.14. DTEND, DTSTART, DUE, DURATION . . . . . . . . . . . . . . 20 79 4.15. ESTIMATED-DURATION . . . . . . . . . . . . . . . . . . . 23 80 4.16. EXDATE . . . . . . . . . . . . . . . . . . . . . . . . . 23 81 4.17. EXRULE . . . . . . . . . . . . . . . . . . . . . . . . . 23 82 4.18. DTSTAMP and LAST-MODIFIED . . . . . . . . . . . . . . . . 23 83 4.19. GEO . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 84 4.20. IMAGE . . . . . . . . . . . . . . . . . . . . . . . . . . 24 85 4.21. LOCATION . . . . . . . . . . . . . . . . . . . . . . . . 24 86 4.22. METHOD . . . . . . . . . . . . . . . . . . . . . . . . . 24 87 4.23. ORGANIZER . . . . . . . . . . . . . . . . . . . . . . . . 25 88 4.24. PERCENT-COMPLETE . . . . . . . . . . . . . . . . . . . . 25 89 4.25. PRIORITY . . . . . . . . . . . . . . . . . . . . . . . . 27 90 4.26. PRODID . . . . . . . . . . . . . . . . . . . . . . . . . 28 91 4.27. RECURRENCE-ID . . . . . . . . . . . . . . . . . . . . . . 28 92 4.28. RELATED-TO . . . . . . . . . . . . . . . . . . . . . . . 28 93 4.29. REQUEST-STATUS . . . . . . . . . . . . . . . . . . . . . 29 94 4.30. RESOURCES . . . . . . . . . . . . . . . . . . . . . . . . 29 95 4.31. RDATE . . . . . . . . . . . . . . . . . . . . . . . . . . 30 96 4.32. RRULE . . . . . . . . . . . . . . . . . . . . . . . . . . 30 97 4.33. SEQUENCE . . . . . . . . . . . . . . . . . . . . . . . . 34 98 4.34. STATUS . . . . . . . . . . . . . . . . . . . . . . . . . 34 99 4.35. STRUCTURED-DATA . . . . . . . . . . . . . . . . . . . . . 34 100 4.36. SUMMARY . . . . . . . . . . . . . . . . . . . . . . . . . 35 101 4.37. TRANSP . . . . . . . . . . . . . . . . . . . . . . . . . 35 102 4.38. UID . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 103 4.39. URL . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 104 5. Translating iCalendar Recurrences . . . . . . . . . . . . . . 36 105 5.1. Translating iCalendar Recurrences: Simple objects with 106 overrides . . . . . . . . . . . . . . . . . . . . . . . . 36 107 5.2. Translating iCalendar Recurrences: Overrides with no 108 master . . . . . . . . . . . . . . . . . . . . . . . . . 36 109 6. Translating iCalendar: Further examples . . . . . . . . . . . 36 110 6.1. Recurring event with ATTACH . . . . . . . . . . . . . . . 37 111 6.2. Simple event with CONTACT . . . . . . . . . . . . . . . . 39 112 6.3. Simple event with RESOURCES . . . . . . . . . . . . . . . 40 113 6.4. Recurring event. Attendees only in overrides . . . . . . 40 114 7. Translating JSCalendar properties to iCalendar components . . 43 115 7.1. jsevent . . . . . . . . . . . . . . . . . . . . . . . . . 43 116 7.2. jsgroup . . . . . . . . . . . . . . . . . . . . . . . . . 44 117 7.3. jstask . . . . . . . . . . . . . . . . . . . . . . . . . 45 118 7.4. timezones . . . . . . . . . . . . . . . . . . . . . . . . 46 119 7.5. alerts . . . . . . . . . . . . . . . . . . . . . . . . . 47 120 7.5.1. action . . . . . . . . . . . . . . . . . . . . . . . 47 121 7.5.2. trigger . . . . . . . . . . . . . . . . . . . . . . . 48 122 7.5.3. todo . . . . . . . . . . . . . . . . . . . . . . . . 49 123 8. Translating JSCalendar properties to iCalendar properties . . 49 124 8.1. categories . . . . . . . . . . . . . . . . . . . . . . . 49 125 8.2. created . . . . . . . . . . . . . . . . . . . . . . . . . 50 126 8.3. duration . . . . . . . . . . . . . . . . . . . . . . . . 50 127 8.4. estimatedDuration . . . . . . . . . . . . . . . . . . . . 51 128 8.5. keywords . . . . . . . . . . . . . . . . . . . . . . . . 51 129 8.6. locations . . . . . . . . . . . . . . . . . . . . . . . . 52 130 8.7. participants . . . . . . . . . . . . . . . . . . . . . . 52 131 9. Security Considerations . . . . . . . . . . . . . . . . . . . 53 132 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 53 133 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 53 134 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 53 135 12.1. Normative References . . . . . . . . . . . . . . . . . . 53 136 12.2. Informative References . . . . . . . . . . . . . . . . . 54 137 Appendix A. Outdated document sections . . . . . . . . . . . . . 55 138 A.1. Note . . . . . . . . . . . . . . . . . . . . . . . . . . 55 139 A.2. JSTask . . . . . . . . . . . . . . . . . . . . . . . . . 55 140 A.3. JSGroup . . . . . . . . . . . . . . . . . . . . . . . . . 55 141 A.4. Common properties . . . . . . . . . . . . . . . . . . . . 56 142 A.4.1. Time properties and types . . . . . . . . . . . . . . 58 143 A.4.2. Locations . . . . . . . . . . . . . . . . . . . . . . 59 144 A.4.3. Participants . . . . . . . . . . . . . . . . . . . . 60 146 A.5. Custom properties . . . . . . . . . . . . . . . . . . . . 61 147 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 62 149 1. Introduction 151 1.1. Note (to be deleted later) 153 This is still very much a work in progress. There are 154 implementations of the mapping but there may be changes over the 155 coming weeks. 157 1.2. Motivation 159 The JSCalendar [draft-ietf-calext-jscalendar] data format is used to 160 represent calendar data, and is meant as an alternative to the widely 161 deployed iCalendar [RFC5545] data format. 163 While new calendaring services and applications might use JSCalendar 164 as their main data format to exchange calendaring data, they are 165 likely to interoperate with services and clients that just support 166 iCalendar. Similarly, existing calendaring data is stored in 167 iCalendar format in databases and other calendar stores, and 168 providers and users might want to represent this data also in 169 JSCalendar. Lastly, there is a requirement to preserve custom 170 iCalendar properties that have no equivalent in JSCalendar when 171 converting between these formats. 173 To support these use cases, this document provides the required 174 approach when converting JSCalendar data from and to iCalendar. 176 1.3. Scope and caveats 178 JSCalendar and iCalendar have a lot of semantics in common, but they 179 are not interchangeable formats: 181 o JSCalendar contains a richer data model to express calendar 182 information such as event locations and participants. while 183 future iCalendar extensions may allow a direct mapping, for now 184 there may be no representation directly in iCalendar of some 185 properties. These values may have to be extracted from a full 186 copy of the iCalendar format provided as a property in the 187 JSCalendar data. 189 o iCalendar may contain arbitrary, non-standardised data with custom 190 properties/attributes. These will be translated using the same 191 approach as jCal. 193 o iCalendar has some obsolete features that have been removed from 194 JSCalendar due to not being useful and/or supported in the real 195 world (e.g. custom email alerts to send to random people). 196 Translating these may lose some of the original fidelity. 198 o Implementations may use a custom property to store data that could 199 not be mapped directly in either direction in the original or a 200 custom format, however this is not interoperable. 202 o JSCalendar supports fractional seconds in time values whereas 203 iCalendar does not. A subsequent specification will define how 204 fractional seconds can be represented in iCalendar. 206 Accordingly, this document defines a canonical translation between 207 iCalendar and JSCalendar, and implementations MUST follow the 208 approaches specified here when iCalendar data is represented in 209 JSCalendar and vice-versa. 211 This document defines mappings for the following specifications. 213 o Internet Calendaring and Scheduling Core Object Specification 214 (iCalendar) 216 o iCalendar Transport-Independent Interoperability Protocol (iTIP) 218 o New Properties for iCalendar 220 o Event Publishing Extensions to iCalendar 222 o Support for iCalendar Relationships 224 o VALARM Extensions for iCalendar 226 Therefore all of these specifications MUST be implemented to follow 227 this specification. 229 1.4. Notational Conventions 231 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 232 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 233 document are to be interpreted as described in [RFC2119]. 235 2. iCalendar pre-processing 237 iCalendar uses a line-folding mechanism to limit lines of data to a 238 maximum line length (typically 75 octets) to ensure the maximum 239 likelihood of preserving data integrity as it is transported via 240 various means (e.g., email) -- see Section 3.1 of [RFC5545]. 242 iCalendar data uses an "escape" character sequence for text values 243 and property parameter values. See Sections 3.1 and 3.3 of [RFC5545] 244 as well as [RFC6868]. 246 There is a subtle difference in the number representations between 247 JSON and iCalendar. While in iCalendar, a number may have leading 248 zeros, as well as a leading plus sign; this is not the case in JSON. 249 Numbers should be represented in whatever way needed for the 250 underlying format. 252 When converting from iCalendar to JSCalendar: First, iCalendar lines 253 MUST be unfolded. Afterwards, any iCalendar escaping MUST be 254 unescaped. Finally, JSON escaping, as described in Section 7 of 255 [RFC7159], MUST be applied. The reverse order applies when 256 converting from JSCalendar to iCalendar, which is further described 257 in Section ?. 259 iCalendar uses a base64 encoding for binary data. However, it does 260 not restrict the encoding from being applied to non-binary value 261 types. So, the following rules are applied when processing a 262 property with the "ENCODING" property parameter set to "BASE64": 264 o If the property value type is "BINARY", the base64 encoding MUST 265 be preserved. 267 o If the value type is not "BINARY", the "ENCODING" property 268 parameter MUST be removed, and the value MUST be base64 decoded. 270 When base64 encoding is used, it MUST conform to Section 4 of 271 [RFC4648], which is the base64 method used in [RFC5545]. 273 One key difference in the formatting of values used in iCalendar and 274 JSCalendar is that, in JSCalendar, the specification uses date/time 275 values aligned with the extended format of [ISO.8601.2004], which is 276 more commonly used in Internet applications that make use of the JSON 277 format. The sections of this document describing the various date 278 and time formats contain more information on the use of the complete 279 representation, reduced accuracy, or truncated representation. 281 3. Translating iCalendar components to JSCalendar 283 This section is an alphabetic list of [RFC5545] components and how 284 they are mapped to JSCalendar. 286 At present VFREEBUSY and VJOURNAL are not mapped in jscalendar. 288 3.1. VALARM 290 An [RFC5545] VALARM component is mapped to a member of a JSCalendar 291 "alerts" object with a type of "Alert" and a small id. 293 BEGIN: VEVENT 294 ... 295 BEGIN: VALARM 296 ... 297 END: VALARM 298 BEGIN: VALARM 299 ... 300 END: VALARM 301 END: VEVENT 303 maps to 305 { 306 "@type": "Event", 307 ... 308 "alerts": { 309 "1": { 310 "@type": "Alert", 311 ... 312 }, 313 "2": { 314 "@type": "Alert", 315 ... 316 } 317 } 318 } 320 The [RFC5545] VALARM has a number of problems which are not carried 321 over into JSCalendar. Clients tend to choose how, and in some cases 322 when to notify the user. 324 For example, if the user has a smart-watch they may get tapped on the 325 wrist. The method of notification may depend on which device is 326 being used and the context, for example a meeting or driving. 328 Also, many clients are taking into consideration the travel time and 329 notifying the user earlier if it seems necessary. 331 Specifying that a client should send emails to all attendees is both 332 annoying and dangerous. Attendees have their own preferences for how 333 and when they should be notified. 335 Accordingly, the specification only allows for "display" and "email" 336 actions and - other than specifying when - does not allow much else. 337 Clients and/or servers will generally use the associated event or 338 task title as identification. User preferences generally indicate 339 what actions they prefer. 341 An [RFC5545] ACTION property can take the defined values "AUDIO" / 342 "DISPLAY" / "EMAIL" whereas the JSCalendar "action" property only 343 supports "display" and "email". 345 An "AUDIO" alarm SHOULD be mapped to a "display" alert. Any 346 attachment MUST be ignored. 348 The [RFC5545] example VALARMs will be mapped as follows, assuming 349 they are all in the same event: 351 BEGIN:VEVENT 352 ... 353 BEGIN:VALARM 354 TRIGGER;VALUE=DATE-TIME:19970317T133000Z 355 REPEAT:4 356 DURATION:PT15M 357 ACTION:AUDIO 358 ATTACH;FMTTYPE=audio/basic:ftp://example.com/pub/ 359 sounds/bell-01.aud 360 END:VALARM 361 BEGIN:VALARM 362 TRIGGER:-PT30M 363 REPEAT:2 364 DURATION:PT15M 365 ACTION:DISPLAY 366 DESCRIPTION:Breakfast meeting with executive\n 367 team at 8:30 AM EST. 368 END:VALARM 369 BEGIN:VALARM 370 TRIGGER;RELATED=END:-P2D 371 ACTION:EMAIL 372 ATTENDEE:mailto:john_doe@example.com 373 SUMMARY:*** REMINDER: SEND AGENDA FOR WEEKLY STAFF MEETING *** 374 DESCRIPTION:A draft agenda needs to be sent out to the attendees 375 to the weekly managers meeting (MGR-LIST). Attached is a 376 pointer the document template for the agenda file. 377 ATTACH;FMTTYPE=application/msword:http://example.com/ 378 templates/agenda.doc 379 END:VALARM 380 END:VEVENT 382 maps to 383 { 384 "@type": "Event", 385 ... 386 "alerts": { 387 "1": { 388 "@type": "Alert", 389 "action": "display", 390 "trigger": { 391 "@type": "AbsoluteTrigger", 392 "when": "19970317T133000Z" 393 } 394 }, 395 "2": { 396 "@type": "Alert", 397 "action": "display", 398 "trigger": { 399 "@type": "OffsetTrigger", 400 "offset": "-PT30M" 401 } 402 } 403 "3": { 404 "@type": "Alert", 405 "action": "email", 406 "trigger": { 407 "@type": "OffsetTrigger", 408 "offset": "-P2D", 409 "relativeTo": "end" 410 } 411 } 412 } 413 } 415 Note that the ATTACH, ATTENDEE, DESCRIPTION, DURATION, REPEAT and 416 SUMMARY properties have been dropped. 418 3.2. VCALENDAR 420 A [RFC5545] VCALENDAR component may be mapped to a JSCalendar object 421 with a type of "jsgroup". 423 BEGIN: VCALENDAR 424 PRODID:-//ABC Corporation//NONSGML My Product//EN 425 ... 426 END: VCALENDAR 428 maps to 430 { 431 "@type": "jsgroup", 432 "prodid": "-//ABC Corporation//NONSGML My Product//EN", 433 ... 434 } 436 Note that a single Event or Task MAY be converted without a 437 surrounding JSGroup if the VCALENDAR component only contains PRODID 438 and CALSCALE properties. In this case the prodid can go in the Event 439 or Task. The CALSCALE property is dropped - there is no equivalence 440 in JSCalendar. 442 3.3. VEVENT 444 A [RFC5545] VEVENT component is mapped to a JSCalendar object with a 445 type of "Event". 447 BEGIN: VEVENT 448 ... 449 END: VEVENT 451 maps to 453 { 454 "@type": "Event", 455 ... 456 } 458 3.4. VLOCATION 460 A [draft-ietf-calext-eventpub-extensions] VLOCATION component is 461 mapped to a JSCalendar object with a type of "Location". Any 462 properties within the VLOCATION must be mapped as described below. 464 BEGIN: VEVENT 465 ... 466 BEGIN: VLOCATION 467 ... 468 END: VLOCATION 469 END: VEVENT 471 maps to 473 { 474 "@type": "jsevent", 475 ... 476 "locations": { 477 "1": { 478 "@type": "Location", 479 ... 480 } 481 } 482 } 484 3.5. VTIMEZONE, STANDARD, DAYLIGHT 486 A [RFC5545] VTIMEZONE component is mapped to a member of a JSCalendar 487 "timezones" object with a type of "TimeZone" and an id which follows 488 the restrictions specified. 490 The STANDARD and DAYLIGHT components map to JSCalendar TimeZoneRule 491 objects as members of the 493 Note that 495 o There is no current approach for defining standalone sets of 496 timezones. 498 o Timezones defined in the IANA timezone database SHOULD NOT be 499 redefined in the object. Only custom timezones will be defined. 501 BEGIN: VTIMEZONE 502 TZID: Example/Somewhere 503 ... 504 END: VTIMEZONE 505 BEGIN: VTIMEZONE 506 TZID: Example/Somewhere-else 507 ... 508 END: VTIMEZONE 509 BEGIN: VEVENT 510 ... 511 END: VEVENT 513 maps to 515 { 516 "@type": "jsevent", 517 ... 518 "timezones": { 519 "/Example/Somewhere: { 520 "@type": "TimeZone", 521 ... 522 }, 523 "/Example/Somewhere-else": { 524 "@type": "TimeZone", 525 ... 526 } 527 } 528 } 530 3.6. VTODO 532 A [RFC5545] VTODO component is mapped to a JSCalendar object with a 533 type of "jstask". 535 BEGIN: VTODO 536 ... 537 END: VTODO 539 maps to 541 { 542 "@type": "jstask", 543 ... 544 } 546 4. Translating iCalendar properties to JSCalendar 548 This section is an alphabetic list of [RFC5545] and [RFC7986] 549 properties and how they are mapped to JSCalendar. 551 4.1. ATTACH 553 A [RFC5545] ATTACH allows for two types of attachment: 555 o A uri value 557 o A binary value 559 Both map to a JSCalendar "link" object with a "rel" of "enclosure" 560 and the "href" set to the value of the property. 562 If the FMTTYPE parameter is set then add a JSCalendar "contentType" 563 property to the link object. 565 For a binary value use a base64 data uri. 567 For an example of a recurring event with ATTACH see Section 6.1 569 4.2. ATTENDEE 571 An [RFC5545] ATTENDEE maps to the JSCalendar "participant" property 572 with a JSCalendar "role" of "attendee". The value for role should 573 always be set. 575 In the simplest case a JSCalendar "participant" property will be 576 created and added to the JSCalendar "participants" property. 578 The value of the ATTENDEE property is used to add an "imip" method to 579 the JSCalendar "sendTo" property. The value of the entry will be the 580 ATTENDEE property value. 582 For example: 584 ... 585 ATTENDEE:mailto:user01@example.org 586 ... 588 maps to 590 { 591 ... 592 "participants": { 593 "be450b70-9bf7-4f6e-8f65-971ede566ce3": { 594 "@type": "Participant", 595 "sendTo": { 596 "imip": "user01@example.org" 597 }, 598 ... 599 } 601 The attendee parameters are mapped to JSCalendar "participant" 602 properties as follows: 604 CN: The value of the CN parameter is used to set the JSCalendar 605 "name" property. 607 CUTYPE: This maps on to the JSCalendar "kind" property as follows: 609 INDIVIDUAL "individual" 611 GROUP "group" 613 RESOURCE "resource" 615 ROOM "location" 617 UNKNOWN No value 619 Any other value should be converted to lower case and assigned to 620 the JSCalendar "kind" property. 622 DELEGATED-FROM: Split the value at any commas and add each resulting 623 element to the JSCalendar "delegatedFrom" property 625 DELEGATED-TO: Split the value at any commas and add each resulting 626 element to the JSCalendar "delegatedFrom" property 628 DIR: If non-null look in the participant "links" property for a 629 JSCalendar "link" property with an href with the same value as the 630 DIR parameter. You may need to search the current override and 631 the master. 633 If none is found create a new one with the JSCalendar "href" 634 property set to the value of the DIR parameter and the JSCalendar 635 "rel" property set to "alternate" 637 LANG: set the JSCalendar "language" property to the value of the 638 LANG parameter. 640 MEMBER: If this is set there should be a corresponding ATTENDEE 641 object with a value equal to the value of the member parameter. 642 If not it is appropriate to skip this parameter. 644 If there is a corresponding ATTENDEE then there should be a 645 corresponding JSCalendar "participant" property. This suggests 646 that CUTYPE=GROUP ATTENDEE properties should be processed ahead of 647 the others. 649 Locate the JSCalendar "participant" property for the group. This 650 may be in the current override or in the master. Add the id to 651 the current participants JSCalendar "memberOf" property. 653 PARTSTAT: If the PARTSTAT parameter is set and is not "NEEDS-ACTION" 654 then set the JSCalendar "participationStatus" property to the 655 lower-cased value of the PARTSTAT. 657 ROLE: This is mapped to the JSCalendar "roles" property as follows: 659 CHAIR "attendee" and "chair" 661 REQ-PARTICIPANT "attendee" 663 OPT-PARTICIPANT "attendee" and "optional" 665 NON-PARTICIPANT "informational" 667 Any other value should be converted to lower case and added to the 668 JSCalendar "roles" property. 670 RSVP: If the value of the RSVP parameter is TRUE set the JSCalendar 671 "expectReply" property to "true" otherwise omit it. 673 SCHEDULE-AGENT: If the value is "CLIENT" (ignoring case) set the 674 JSCalendar "scheduleAgent" property to "client" otherwise omit it. 676 SCHEDULE-FORCE-SEND: Set the JSCalendar "scheduleForceSend" property 677 to the lower-cased value of the [RFC6638] SCHEDULE-FORCE-SEND 678 parameter. 680 SCHEDULE-STATUS: Split the value at any commas and add each 681 resulting element to the JSCalendar "scheduleStatus" property. 683 SENT-BY: The value of the SENT-BY parameter is used to set the 684 JSCalendar "invitedBy" property. 686 4.3. CALSCALE 688 A [RFC5545] CALSCALE has no equivalence in JSCalendar. It is 689 ignored. 691 4.4. CATEGORIES 693 These map on to the JSCalendar "keywords" property with each category 694 being the key to an entry. 696 ... 697 CATEGORIES:APPOINTMENT,EDUCATION 698 CATEGORIES:MEETING 699 ... 701 maps to 703 ... 704 "keywords": { 705 "APPOINTMENT": true, 706 "EDUCATION": true, 707 "MEETING": true 708 }, 709 ... 711 4.5. CLASS 713 Maps to the "privacy" property. The iCalendar property value maps to 714 the JSCalendar value as follows: 716 CONFIDENTIAL "secret" 718 PRIVATE "private" 720 PUBLIC "public" 722 iana-token and x-name verbatim copy 724 4.6. COLOR 726 Maps to the "color" property. Copy the verbatim value. 728 4.7. COMMENT 730 There is no direct mapping for this property which may appear 731 multiple times in [RFC5545]. 733 For a scheduling reply it is presumably a message by the participant 734 so the value or values should be used to set the JSCalendar 735 "participantComment" property. 737 4.8. COMPLETED 739 Set the JSCalendar "progress" property to "completed" and the 740 "progressUpdated" property to the reformatted date/time. 742 ... 743 COMPLETED: "20101010T101010Z" 744 ... 746 maps to 748 ... 749 "progressUpdated": "2010-10-10T10:10:10Z", 750 "progress": "completed", 751 ... 753 4.9. CONCEPT 755 This [draft-ietf-calext-ical-relations] property may appear multiple 756 times in components. 758 Each instance of the property is mapped on to a member of the 759 JSCalendar "categories" property. 761 ... 762 CONCEPT:http://example.com/event-types/arts/music 763 CONCEPT:http://example.com/performance-types/arts/live 764 ... 766 maps to 768 ... 769 "categories": { 770 "http://example.com/event-types/arts/music": true, 771 "http://example.com/performance-types/arts/live": true 772 } 773 ... 775 4.10. CONFERENCE 777 Maps to a "VirtualLocation" object. The property value maps to the 778 "uri" property of the virtual location. 780 Mapping parameters: 782 FEATURE: Maps to the "features" property of the virtual location. 784 LABEL: Maps to the "name" property of the virtual location. 786 LANGUAGE: No mapping. 788 4.11. CONTACT 790 The CONTACT property is mapped on to a participant object with a 791 "roles" property of "contact" and an "order" property of 1 (one). 792 This defines the participant as a primary contact. 794 Mapping parameters: 796 ALTREP Use the same process as for the ATTENDEE DIR parameter: 797 create a link property with the "rel" property set to "alternate" 798 and the "href" property set to the value of the ALTREP parameter. 799 Then add the link to the participants "links" property. 801 LANG Set the participants "language" property. 803 For an example see Section 6.2 805 4.12. CREATED 807 The CREATED property is mapped on to a "created" property with a json 808 formatted form of the date. Example: 810 BEGIN:VEVENT 811 ... 812 CREATED:19960329T133000Z 813 ... 814 END:VEVENT 816 maps to 818 { 819 "@type": "jsevent", 820 ... 821 "created": "1996-03-29T13:30"00Z", 822 ... 823 } 825 4.13. DESCRIPTION 827 Copy the value, preprocessed according to Section 2 into the 828 "description" property. 830 Mapping parameters: 832 ALTREP No mapping. 834 LANG Use the "locale" property. 836 Example: 838 BEGIN:VEVENT 839 ... 840 DESCRIPTION:We are having a meeting all this week at 12 pm fo 841 r one hour\, with an additional meeting on the first day 2 h 842 ours long.\nPlease bring your own lunch for the 12 pm meetin 843 gs. 844 ... 845 END:VEVENT 847 maps to 849 { 850 "@type": "jsevent", 851 ... 852 "description": // Note: comments and string concatenation are not 853 // allowed per the JSON specification and is used here 854 // to avoid long lines. 855 "We are having a meeting all this week at 12 pm for one " + 856 "hour, with an additional meeting on the first day 2 " + 857 "hours long.\nPlease bring your own lunch for the 12 pm " + 858 "meetings.", 859 ... 860 } 862 4.14. DTEND, DTSTART, DUE, DURATION 864 If the DTSTART is a DATE only property then add the JSCalendar 865 showWithoutTime property with the value set to "true". The 866 JSCalendar "start" property is set with zero time values. 868 If the DTSTART has a TZID parameter then set the JSCalendar 869 "timeZone" property to the value of TZID. 871 If the DTSTART has a UTC value then set the JSCalendar "timeZone" 872 property to the value "Etc/UTC". The JSCalendar "start" property is 873 set without any UTC indicator. 875 JSCalendar has no equivalent to DTEND. If the component has a DTEND 876 then calculate a value for "DURATION" from that property and DTSTART 877 and proceed as below. 879 If the DTEND has a TZID parameter with a value that differs from the 880 DTSTART TZID parameter then a "location" object should be created 881 with a "relativeTo" property set to "end" and a "timezone" property 882 set to the value of the "TZID" parameter. 884 Note that a task is not required to have a DTSTART so the JSCalendar 885 "timezone" property needs to be set from the DUE property. 887 Convert a DURATION property to the JSCalendar duration. 889 Example - DTSTART and DTEND in same timezone: 891 BEGIN:VEVENT 892 ... 893 DTSTART;TZID=America/New_York:20170315T150000 894 DTEND;TZID=America/New_York:20170315T160000 896 ... 897 END:VEVENT 899 maps to 901 { 902 "@type": "jsevent", 903 ... 904 "start": "2017-03-15T15:00:00", 905 "timeZone": "America/New_York", 906 "duration": "PT1H" 907 ... 908 } 910 Example - DTSTART and DTEND in different timezone: 912 BEGIN:VEVENT 913 ... 914 DTSTART;TZID=America/New_York:20170315T150000 915 DTEND;TZID=America/LosAngeles:20170315T190000 917 ... 918 END:VEVENT 920 maps to 922 { 923 "@type": "jsevent", 924 ... 925 "start": "2017-03-15T15:00:00", 926 "timeZone": "America/New_York", 927 "duration": "PT7H" 928 ... 929 "locations": { 930 "1": { 931 "@type": "location", 932 "relatedTo": "end", 933 "timeZone": "America/Los_Angeles" 934 } 935 } 936 } 938 Example - 3 day event: 940 BEGIN:VEVENT 941 ... 942 DTSTART;VALUE=DATE:20210315 943 DTEND;VALUE=DATE:20210318 945 ... 946 END:VEVENT 948 maps to 950 { 951 "@type": "jsevent", 952 ... 953 "start": "2017-03-15T00:00:00", 954 "duration": "P3D", 955 "showWithoutTime": true, 956 ... 957 } 959 4.15. ESTIMATED-DURATION 961 Copy the ESTIMATED-DURATION value into the JSCalendar 962 "estimatedDuration" property. 964 For example: 966 ... 967 ESTIMATED-DURATION:PT18H 968 ... 970 maps to 972 ... 973 "estimatedDuration": "PT18H" 974 ... 976 4.16. EXDATE 978 Create a patch object with the recurrence id set from the EXDATE 979 value. Add a single JSCalendar "excluded" property with the value 980 set to true. There MUST NOT be any other properties set - other than 981 "@type". 983 4.17. EXRULE 985 Maps to the "excludedRecurrenceRules" property. Also see 986 Section 4.32. 988 4.18. DTSTAMP and LAST-MODIFIED 990 The mapping depends on whether or not the component is a scheduling 991 entity. 993 Not a scheduling entity: The [RFC5545] DTSTAMP and LAST-MODIFIED 994 properties have essentially the same meaning. If both are present 995 use the value of the latest for the "updated" property. Otherwise 996 set from whichever is present. 998 Is a scheduling entity: DTSTAMP should be used to set the 999 "ScheduleUpdated" property in the "participant" object for the 1000 attendee. 1002 If present LAST-MODIFIED should be used to set the "updated" 1003 property - otherwise set it from the DTSTAMP. 1005 4.19. GEO 1007 Maps to a Location object, with only the "coordinates" property set. 1008 Note that the JSCalendar coordinates property value MUST be a valid 1009 "geo" URI, so replace the ";" character in the iCalendar value with 1010 "," and prepend the resulting string with "geo:". 1012 4.20. IMAGE 1014 Maps to a Link object with the iCalendar property value mapped to the 1015 location "href" property, and the "rel" property set to "icon". 1017 For a binary value use a base64 data uri in the "href" property. 1019 Mapping parameters: 1021 ALTREP No mapping. 1023 FMTTYPE Maps to the "contentType" property of the Link object. 1025 DISPLAY Maps to the "display" property of the Link object. The 1026 property values "BADGE", "GRAPHIC", "FULLSIZE" and "THUMBNAIL" map 1027 to their lower-case equivalent in JSCalendar. 1029 4.21. LOCATION 1031 If any [draft-ietf-calext-eventpub-extensions] "VLOCATION" components 1032 are present, then the [RFC5545]"LOCATION" property should be ignored. 1034 To map the property create a "locations" property with a single 1035 "location" and set the "description" property to the value of the 1036 [RFC5545]"LOCATION" property. 1038 Mapping parameters: 1040 ALTREP Maps to a Link object in the Location "links" property, with 1041 the "href" property set to the parameter value. 1043 4.22. METHOD 1045 Maps to the "method" property of the JSCalendar object. The 1046 JSCalendar property value is the lowercase equivalent of the 1047 iCalendar property value. 1049 4.23. ORGANIZER 1051 Maps to the "replyTo" property of the JSCalendar object. An 1052 iCalendar property value in the "mailto:" URI scheme, maps to the 1053 "imip" method, any other value maps to the "other" method. 1055 If the iCalendar component also contains an ATTENDEE with the same 1056 calendar user address then map that ATTENDEE as defined in 1057 Section 4.2 and add the "owner" role to the Participant "roles" 1058 property. Otherwise, use the ORGANIZER property to map to a 1059 Participant object. The "roles" property of the Participant MUST 1060 only contain the "owner" role and the "expectReply" property value 1061 MUST be "false". Any iCalendar parameters map as defined for 1062 ATTENDEE. 1064 TBD: SENT-BY parameter. Example. 1066 4.24. PERCENT-COMPLETE 1068 For all methods other than REPLY (or no method), the PERCENT-COMPLETE 1069 applies to the VTODO as a whole. In this case it the value is used 1070 to set the JSCalendar "percentComplete" property in the task object. 1072 BEGIN: VCALENDAR 1073 PRODID:-//ABC Corporation//NONSGML My Product//EN 1074 METHOD:PUBLISH 1075 BEGIN:VTODO 1076 ... 1077 PERCENT-COMPLETE:39 1078 END:VTODO 1079 END: VCALENDAR 1081 maps to 1083 { 1084 "@type": "jstask", 1085 "prodid": "-//ABC Corporation//NONSGML My Product//EN", 1086 ... 1087 "percentComplete": 39 1088 } 1090 PERCENT-COMPLETE in a REPLY is used to indicate the level of 1091 completeness of the ATTENDEE. There should only be a single ATTENDEE 1092 in the VTODO object. 1094 As ever recurrences complicate matters. For a non-recurring event or 1095 an override that contains the single participant, set the JSCalendar 1096 "percentComplete" property in the JSCalendar "participant" object 1097 representing the attendee. 1099 BEGIN: VCALENDAR 1100 PRODID:-//ABC Corporation//NONSGML My Product//EN 1101 METHOD:REPLY 1102 BEGIN:VTODO 1103 ... 1104 ATTENDEE:mailto:douglm@example.org 1105 PERCENT-COMPLETE:39 1106 END:VTODO 1107 END: VCALENDAR 1109 maps to 1111 { 1112 "@type": "jstask", 1113 "prodid": "-//ABC Corporation//NONSGML My Product//EN", 1114 ... 1115 "participants": { 1116 "be450b70-9bf7-4f6e-8f65-971ede566ce3": { 1117 "@type": "Participant", 1118 "sendTo": { 1119 "imip": "mailto:douglm@example.org" 1120 }, 1121 "percentComplete": 39, 1122 "roles": { 1123 "attendee": true 1124 } 1125 }, 1126 ... 1127 } 1129 In the case of an override with the participant appearing in the 1130 master then add a patch to the override. 1132 BEGIN: VCALENDAR 1133 PRODID:-//ABC Corporation//NONSGML My Product//EN 1134 METHOD:REPLY 1135 BEGIN:VTODO 1136 ... 1137 ATTENDEE:mailto:douglm@example.org 1138 END:VTODO 1139 BEGIN:VTODO 1140 ... 1141 RECURRENCE-ID:20200523T120000 1142 ... 1143 ATTENDEE:mailto:douglm@example.org 1144 PERCENT-COMPLETE:39 1145 END:VTODO 1146 END: VCALENDAR 1148 maps to 1150 { 1151 "@type": "jstask", 1152 "prodid": "-//ABC Corporation//NONSGML My Product//EN", 1153 ... 1154 "participants": { 1155 "be450b70-9bf7-4f6e-8f65-971ede566ce3": { 1156 "@type": "Participant", 1157 "sendTo": { 1158 "imip": "mailto:douglm@example.org" 1159 }, 1160 "roles": { 1161 "attendee": true 1162 } 1163 }, 1164 "recurrenceOverrides": { 1165 "2020-05-23T12:00:00": { 1166 "participants/be4...6ce3/percentComplete": 39 1167 }, 1168 ... 1169 } 1170 } 1172 4.25. PRIORITY 1174 Simply copy value into the JSCalendar "priority" property. 1176 4.26. PRODID 1178 For a vcalendar JSGroup object with multiple JSEvent and/or JSTask 1179 object the [RFC5545] VCALENDAR PRODID is mapped to a JSCalendar 1180 "prodid" property in the group. 1182 When mapping to a single JSEvent and/or JSTask object the [RFC5545] 1183 VCALENDAR PRODID is mapped to a JSCalendar "prodid" property in the 1184 group 1186 BEGIN: VCALENDAR 1187 PRODID:-//ABC Corporation//NONSGML My Product//EN 1188 BEGIN:VEVENT 1189 ... 1190 END:VEVENT 1191 END: VCALENDAR 1193 maps to 1195 { 1196 "@type": "jsevent", 1197 "prodid": "-//ABC Corporation//NONSGML My Product//EN", 1198 ... 1199 } 1201 4.27. RECURRENCE-ID 1203 Refer to Section 5 for information on mapping recurrence ids. 1205 4.28. RELATED-TO 1207 This is mapped to the JSCalendar "relatedTo" property which is a map 1208 of relations with the target UID as the keys. The iCalendar relation 1209 is by default a PARENT relationship. There is no default for 1210 JSCalendar so the relationship must be explicitly specified. 1212 The RELTYPE parameter values map to their lowercase equivalents in 1213 the "relation" property. 1215 Also note that the iCalendar relationship types are not identical. 1216 CHILD and PARENT map to JSCalendar "child" and "parent" but the best 1217 match for iCalendar SIBLING is "next" 1218 ... 1219 RELATED-TO:jsmith.part7.19960817T083000.xyzMail@example.com 1220 RELATED-TO;RELTYPE=SIBLING: 1221 19960401-080045-4000F192713-0052@example.com 1222 ... 1224 maps to 1226 "relatedTo" : { 1227 "jsmith.part7.19960817T083000.xyzMail@example.com" : { 1228 "@type" : "Relation", 1229 "relation" : { 1230 "parent" : true 1231 } 1232 }, 1233 "19960401-080045-4000F192713-0052@example.com" : { 1234 "@type" : "Relation", 1235 "relation" : { 1236 "next" : true 1237 } 1238 }, 1239 }, 1240 { 1241 "@type": "jsevent", 1242 "prodid": "-//ABC Corporation//NONSGML My Product//EN", 1243 ... 1244 } 1246 4.29. REQUEST-STATUS 1248 Copy the value into the JSCalendar "requestStatus" property. 1250 4.30. RESOURCES 1252 The RESOURCES property value is a comma-separated list of resources. 1253 First split this into the separate resource names and then each 1254 resource is mapped on a participant object with a "kind" property of 1255 "resource" and the "name" property set to the resource name. 1257 Mapping parameters: 1259 ALTREP Use the same process as for the ATTENDEE DIR parameter: 1260 create a link property with the "rel" property set to "alternate" 1261 and the "href" property set to the value of the ALTREP parameter. 1262 Then add the link to the participants "links" property. 1264 LANG Set the participants "language" property. 1266 For an example see Section 6.3 1268 4.31. RDATE 1270 If the RDATE has a RANGE=THISANDFUTURE parameter then the recurrence 1271 MUST be split at this RDATE. 1273 Truncate the original object before this RDATE, create a new master 1274 representing the object and link them by setting the jscalendar 1275 "relatedTo" property in both. 1277 Otherwise create a patch object with the recurrence id set from the 1278 RDATE value. If the instance has overrides the differences will also 1279 be set in the object. 1281 4.32. RRULE 1283 Each RRULE is converted to an object in the JSCalendar 1284 "recurrenceRules" property. Each entry has the type 1285 "RecurrenceRule". 1287 ... 1288 RRULE:... 1289 ... 1291 maps to 1293 ... 1294 "recurrenceRules" : [{ 1295 "@type" : "RecurrenceRule", 1296 ... 1297 }], 1298 ... 1300 The recurrence rule object has one property for each element of the 1301 recurrence rule. The iCalendar rule has to be parsed out and the 1302 individual jscalendar property values set. Most take the same type 1303 but there are exceptions. 1305 FREQ (mandatory) Copy into the jscalendar "frequency" property 1306 converted to lowercase. 1308 INTERVAL If present and not 1 copy into the jscalendar "interval" 1309 property. 1311 RSCALE If present copy into the jscalendar "rscale" property 1312 converted to lowercase. 1314 SKIP If present copy into the jscalendar "skip" property converted 1315 to lowercase. 1317 WKST If present copy into the jscalendar "firstDayOfWeek" property 1318 converted to lowercase. 1320 BYDAY If present each element becomes an entry in the jsCalendar 1321 "byDay" propety. This is an array of NDay objects which may have 1322 2 properties: 1324 day The two character weekday abbreviation. 1326 nthOfPeriod If the weekday abbreviation is preceded by a signed 1327 integer value set the jscalendar "nthOfPeriod" property. 1329 ... 1330 RRULE:...,BYDAY=-1MO 1331 ... 1333 maps to 1335 ... 1336 "recurrenceRules" : [{ 1337 "@type" : "RecurrenceRule", 1338 ... 1339 "byday": [{ 1340 "day": "mo", 1341 "nthOfPeriod": -1 1342 }] 1343 ... 1344 }], 1345 ... 1347 BYMONTHDAY If present each element will be an element in the 1348 jscalendar "byMonthDay" property. 1350 BYMONTH If present each element will be an element in the jscalendar 1351 "byMonth" property. 1353 Note that the iCalendar values are numeric but the JSCalendar 1354 values are strings. This is because of the possible "L" suffix 1355 for leap months. 1357 BYYEARDAY If present each element will be an element in the 1358 jscalendar "byYearDay" property. 1360 BYWEEKNO If present each element will be an element in the 1361 jscalendar "byWeekNo" property. 1363 BYHOUR If present each element will be an element in the jscalendar 1364 "byHour" property. 1366 BYMINUTE If present each element will be an element in the 1367 jscalendar "byMinute" property. 1369 BYSECOND If present each element will be an element in the 1370 jscalendar "bySecond" property. 1372 BYSETPOS If present each element will be an element in the 1373 jscalendar "bySetPosition" property. 1375 COUNT If present set in the jscalendar "count" property. 1377 UNTIL If present set the jscalendar "until" property with the 1378 appropriately reformatted value. If the is no time part append a 1379 0 time and reformat as a jscalendar local date/time. 1381 Some examples: 1383 ... 1384 RRULE:FREQ=DAILY;COUNT=10 1385 ... 1387 maps to 1389 ... 1390 "recurrenceRules" : [{ 1391 "@type" : "RecurrenceRule", 1392 "frequency": "daily", 1393 "count": 10 1394 }], 1395 ... 1397 ... 1398 RRULE:FREQ=YEARLY;UNTIL=20220512T140000Z; 1399 BYMONTH=1;BYDAY=SU,MO,TU,WE,TH,FR,SA 1400 ... 1402 maps to 1404 ... 1405 "recurrenceRules" : [{ 1406 "@type" : "RecurrenceRule", 1407 "frequency": "yearly", 1408 "byMonth": ["1"], 1409 "byDay": [{ 1410 "day": "su" 1411 }, 1412 } 1413 "day": "mo" 1414 }, 1415 } 1416 "day": "tu" 1417 }, 1418 } 1419 "day": "we" 1420 }, 1421 } 1422 "day": "th" 1423 }, 1424 } 1425 "day": "fr" 1426 }, 1427 } 1428 "day": "sa" 1429 }], 1430 "until": "2022-05-12T10:00:00" 1431 }], 1432 ... 1434 ... 1435 RRULE:FREQ=MONTHLY;COUNT=6;BYDAY=-2MO 1436 ... 1438 maps to 1440 ... 1441 "recurrenceRules" : [{ 1442 "@type" : "RecurrenceRule", 1443 "frequency": "monthly", 1444 "byDay": [{ 1445 "day": "mo", 1446 "nthOfPeriod": -2 1447 }], 1448 "count": 6 1449 }], 1450 ... 1452 4.33. SEQUENCE 1454 Copy the value into the JSCalendar "sequence" property. 1456 4.34. STATUS 1458 For a VEVENT copy the lower-cased value into the JSCalendar "status" 1459 property. 1461 For a VTODO copy the lower-cased value into the JSCalendar "progress" 1462 property. 1464 4.35. STRUCTURED-DATA 1466 This property is mapped on to a JSCalendar "link" object with the 1467 value mapped on to the JSCalendar "href" property in a manner 1468 depending on the "STRUCTURED-DATA" "VALUE" parameter: 1470 VALUE=TEXT Copy the value as a [RFC2397] data uri either as plain 1471 text or by encoding as a base64 value. If plain text the value 1472 may need escaping as per [RFC2397]. 1474 VALUE=BINARY Copy the value as a [RFC2397] data uri speifying base64 1475 encoding. 1477 VALUE=URI Copy the value as-is into the href. 1479 The "STRUCTURED-DATA" "SCHEMA" parameter is mapped on to a JSCalendar 1480 "schema" property within the link object. 1482 The "STRUCTURED-DATA" "FMTTYPE" parameter is mapped on to a 1483 JSCalendar "contentType" property within the link object. 1485 For example: 1487 ... 1488 STRUCTURED-DATA;FMTTYPE=application/ld+json; 1489 SCHEMA="https://schema.org/SportsEvent"; 1490 VALUE=TEXT:{\n 1491 "@context": "http://schema.org"\,\n 1492 "@type": "SportsEvent"\,\n 1493 "homeTeam": "Pittsburgh Pirates"\,\n 1494 "awayTeam": "San Francisco Giants"\n 1495 }\n 1496 ... 1498 maps to (with data truncated) 1500 ... 1501 "links": { 1502 "1": { 1503 "@type" : "Link", 1504 "contentType": "application/ld+json", 1505 "schema": "https://schema.org/SportsEvent", 1506 "href": "data:base64;ewogICAgICAgICJAY29udGV4dCI6IC..." 1507 } 1508 } 1509 ... 1511 4.36. SUMMARY 1513 Copy the value into the JSCalendar "title" property. 1515 Mapping parameters: 1517 ALTREP No mapping. 1519 LANG Use the "locale" property. 1521 4.37. TRANSP 1523 If the value of the TRANSP property (ignoring case) is "opaque" set 1524 the JSCalendar "freeBusyStatus" property to the value "busy". 1526 Otherwise set the JSCalendar "freeBusyStatus" property to the value 1527 "free". 1529 4.38. UID 1531 Copy the value into the JSCalendar "uid" property. 1533 4.39. URL 1535 Maps to a Link object in the JSCalendar object's "links" property, 1536 with the URL property value mapped to the Link "href" property. 1538 5. Translating iCalendar Recurrences 1540 5.1. Translating iCalendar Recurrences: Simple objects with overrides 1542 A simple object with overrides will be converted to a jsCalendar 1543 master event with the rules, recurrence dates and exclusion dates 1544 translated appropriately. 1546 Overrides MUST be mapped on to a jsCalendar patch object and added to 1547 the "recurrenceOverrides" property of the master event with the key 1548 being the value of the iCalendar RECURRENCE-ID translated to a json 1549 format. 1551 Any override property with the same value as the master SHOULD be 1552 ommitted. Remaining properties MAY be added in full. Where 1553 appropriate, differences SHOULD be expressed as a patch. 1555 This can result in a significant reduction in size for objects with 1556 small changes to overrides, for example changing the participation 1557 status of an attendee. 1559 5.2. Translating iCalendar Recurrences: Overrides with no master 1561 When inviting an attendee to a single instance of a recurring event, 1562 only that override should be sent to the attendee. In this case the 1563 override should be a complete jsCalendar object with the type set to 1564 the type of the master. 1566 Additionally, there MUST be a recurrenceId property set to the value 1567 of the recurrence id for that override. If the timezone of the start 1568 of the instance is different from the master value, then there must 1569 also be a "recurrenceIdTimeZone" property set to the start timezone 1570 of the master. 1572 6. Translating iCalendar: Further examples 1574 This section provides more complete examples of translating from 1575 [RFC5545] to JSCalendar. 1577 As usual note that json string values may be split because of line 1578 width limits. This is not legal json. 1580 6.1. Recurring event with ATTACH 1582 This is an example of a recurring event with overrides. The first 1583 override removes an ATTACH property and adds an ATTACH property. The 1584 second override removes all ATTACH properties. 1586 BEGIN:VCALENDAR 1587 CALSCALE:GREGORIAN 1588 PRODID:-//example.org//EN 1589 VERSION:2.0 1590 BEGIN:VEVENT 1591 DTSTAMP:20200522T142047Z 1592 DTSTART;TZID=America/New_York:20200522T120000 1593 DURATION:PT1H 1594 RRULE:FREQ=DAILY;COUNT=8 1595 SUMMARY:recurring daily 8 times 1596 UID:6252D6C40A8308BFE25BBDErecur-1 1597 ATTACH;FMTTYPE=text/plain:http://example.org/doc1.txt 1598 ATTACH;FMTTYPE=text/plain:http://example.org/doc2.txt 1599 ATTACH;FMTTYPE=text/plain:http://example.org/doc3.txt 1600 END:VEVENT 1601 BEGIN:VEVENT 1602 DTSTAMP:20200522T142047Z 1603 DTSTART;TZID=America/New_York:20200523T120000 1604 DURATION:PT1H 1605 RECURRENCE-ID;TZID=America/New_York:20200523T120000 1606 SUMMARY:recurring daily 8 times 1607 UID:6252D6C40A8308BFE25BBDErecur-1 1608 ATTACH;FMTTYPE=text/plain:http://example.org/doc2.txt 1609 ATTACH;FMTTYPE=text/plain:http://example.org/doc3.txt 1610 ATTACH;FMTTYPE=text/plain:http://example.org/doc4.txt 1611 END:VEVENT 1612 BEGIN:VEVENT 1613 DTSTAMP:20200522T142047Z 1614 DTSTART;TZID=America/New_York:20200524T120000 1615 DURATION:PT1H 1616 RECURRENCE-ID;TZID=America/New_York:20200524T120000 1617 SUMMARY:recurring daily 8 times 1618 UID:6252D6C40A8308BFE25BBDErecur-1 1619 END:VEVENT 1620 END:VCALENDAR 1622 maps to 1624 { 1625 "prodId": "//example.org//EN", 1626 "entries": [ 1627 { 1628 "links": { 1629 "1": { 1630 "@type": "Link", 1631 "rel": "enclosure", 1632 "contentType": "text/plain", 1633 "href": "http://example.org/doc1.txt" 1634 }, 1635 "2": { 1636 "@type": "Link", 1637 "rel": "enclosure", 1638 "contentType": "text/plain", 1639 "href": "http://example.org/doc2.txt" 1640 }, 1641 "3": { 1642 "@type": "Link", 1643 "rel": "enclosure", 1644 "contentType": "text/plain", 1645 "href": "http://example.org/doc3.txt" 1646 } 1647 }, 1648 "created ": "2020-05-23T17:04:50Z", 1649 "start": "2020-05-22T12:00:00", 1650 "timeZone": "America/New_York", 1651 "duration": "PT1H", 1652 "title": "recurring daily 8 times", 1653 "uid": "6252D6C40A8308BFE25BBDErecur-1", 1654 "recurrenceRules": [ 1655 { 1656 "@type": "RecurrenceRule", 1657 "frequency": "daily", 1658 "count": 8 1659 } 1660 ], 1661 "recurrenceOverrides": { 1662 "2020-05-23T12:00:00": { 1663 "recurrenceId": "2020-05-23T12:00:00", 1664 "links/d4a618d4-929c-4c81-ae5b-322afe407a00": null, 1665 "links/fb75b76a-a159-4a86-bd3d-7ace6b39c6c3": { 1666 "@type": "Link", 1667 "rel": "enclosure", 1668 "contentType": "text/plain", 1669 "href": "http://example.org/doc4.txt" 1670 } 1671 }, 1672 "2020-05-24T12:00:00": { 1673 "recurrenceId": "2020-05-24T12:00:00", 1674 "links/d4a618d4-929c-4c81-ae5b-322afe407a00": null, 1675 "links/6c54e72e-3413-487c-ae14-fb318a90db43": null, 1676 "links/44087e9a-132c-4a5d-b25d-4ce580edb004": null 1677 } 1678 } 1679 } 1680 ] 1681 } 1683 6.2. Simple event with CONTACT 1685 This example shows the conversion of a simple event with a single 1686 CONTACT property in JSCalendar. 1688 BEGIN:VCALENDAR 1689 CALSCALE:GREGORIAN 1690 PRODID:-//Example//EN 1691 VERSION:2.0 1692 BEGIN:VEVENT 1693 DTSTAMP:20200522T142047Z 1694 DTSTART;TZID=America/New_York:20200622T120000 1695 DURATION:PT1H 1696 SUMMARY:event with contact 1697 UID:6252D6C40A8308BFE25BBEFcontact-1 1698 CONTACT;ALTREP="ldap://example.com:6666/o=ABC%20Industries\, 1699 c=US???(cn=Jim%20Dolittle)":Jim Dolittle\, ABC Industries\, 1700 +1-919-555-1234 1701 END:VEVENT 1702 END:VCALENDAR 1704 translates to 1706 { 1707 "@type": "jsgroup", 1708 "prodId": "//Example.org//Example V3.13.2//EN", 1709 "entries": [ 1710 { 1711 "@type": "jsevent", 1712 "participants": { 1713 "40288108-733187c1-0173-3188007b-00000001": { 1714 "@type": "Participant", 1715 "roles": { 1716 "contact": true 1717 }, 1718 "description": "Jim Dolittle, ABC Industries,\ 1719 +1-919-555-1234", 1720 "links": { 1721 "1": { 1722 "@type": "Link", 1723 "href": "ldap://example.com:6666/o=ABC%20Industries,\ 1724 c=US???(cn=Jim%20Dolittle)", 1725 "rel": "alternate" 1726 } 1727 } 1728 } 1729 }, 1730 "created ": "2020-07-09T03:04:23Z", 1731 "start": "2020-06-22T12:00:00", 1732 "timeZone": "America/New_York", 1733 "duration": "PT1H", 1734 "title": "event with contact", 1735 "uid": "6252D6C40A8308BFE25BBEFcontact-1" 1736 } 1737 ] 1738 } 1740 6.3. Simple event with RESOURCES 1742 TBD 1744 6.4. Recurring event. Attendees only in overrides 1746 In this more complex example there is no ORGANIZER or ATTENDEEs in 1747 the master event. There are overrides which invite one or more 1748 attendees. 1750 For one overrride the ORGANIZER is also an ATTENDEE. In the other 1751 that is not the case. This is reflected in the "roles" property for 1752 the organizer. 1754 Note that each override has its own "participants" property and the 1755 first has a links property to handle the DIR parameter on one 1756 attendee. 1758 BEGIN:VCALENDAR 1759 PRODID://Example.org//Example V3.13.2//EN 1760 VERSION:2.0 1761 BEGIN:VEVENT 1762 CREATED:20200704T035515Z 1763 DURATION:PT1H 1764 DTSTAMP:20200704T035706Z 1765 DTSTART;TZID=America/New_York:20200522T120000 1766 LAST-MODIFIED:20200704T035706Z 1767 SUMMARY:recurring daily 8 times 1768 UID:6252D6C40A8308BFE25BBEFrecur1-1 1769 RRULE:FREQ=DAILY;COUNT=8 1770 END:VEVENT 1771 BEGIN:VEVENT 1772 RECURRENCE-ID;TZID=America/New_York:20200523T120000 1773 ATTENDEE:mailto:douglm@example.org 1774 ATTENDEE;RSVP=TRUE;SCHEDULE-STATUS=1.2;DIR="http://example.org/ 1775 vcards/vbede.vcf":mailto:vbede@example.org 1776 CREATED:20200704T035515Z 1777 DURATION:PT1H 1778 DTSTAMP:20200704T035706Z 1779 DTSTART;TZID=America/New_York:20200523T120000 1780 LAST-MODIFIED:20200704T035706Z 1781 ORGANIZER:mailto:douglm@example.org 1782 SUMMARY:recurring daily 8 times 1783 UID:6252D6C40A8308BFE25BBEFrecur1-1 1784 END:VEVENT 1785 BEGIN:VEVENT 1786 RECURRENCE-ID;TZID=America/New_York:20200524T120000 1787 ATTENDEE;RSVP=TRUE;SCHEDULE-STATUS=1.2:mailto:user01@example.org 1788 ATTENDEE;RSVP=TRUE;SCHEDULE-STATUS=1.2:mailto:vbede@example.org 1789 CREATED:20200704T035515Z 1790 DURATION:PT1H 1791 DTSTAMP:20200704T035706Z 1792 DTSTART;TZID=America/New_York:20200524T120000 1793 LAST-MODIFIED:20200704T035706Z 1794 ORGANIZER:mailto:douglm@example.org 1795 SUMMARY:recurring daily 8 times 1796 UID:6252D6C40A8308BFE25BBEFrecur1-1 1797 END:VEVENT 1798 END:VCALENDAR 1800 translates to 1802 { 1803 "@type": "jsgroup", 1804 "prodId": "//Example.org//Example V3.13.2//EN", 1805 "entries": [ 1806 { 1807 "@type": "jsevent", 1808 "created ": "2020-07-04T03:57:06Z", 1809 "start": "2020-05-22T12:00:00", 1810 "timeZone": "America/New_York", 1811 "duration": "PT1H", 1812 "title": "recurring daily 8 times", 1813 "uid": "6252D6C40A8308BFE25BBEFrecur1-1", 1814 "recurrenceRules": [ 1815 { 1816 "@type": "RecurrenceRule", 1817 "frequency": "daily", 1818 "count": 8 1819 } 1820 ], 1821 "recurrenceOverrides": { 1822 "2020-05-23T12:00:00": { 1823 "participants": { 1824 "be450b70-9bf7-4f6e-8f65-971ede566ce3": { 1825 "@type": "Participant", 1826 "sendTo": { 1827 "imip": "mailto:douglm@example.org" 1828 }, 1829 "roles": { 1830 "attendee": true, 1831 "owner": true 1832 } 1833 }, 1834 "a539dfe3-4463-4f28-b9de-17d3a0e99faf": { 1835 "@type": "Participant", 1836 "sendTo": { 1837 "imip": "mailto:vbede@example.org" 1838 }, 1839 "expectReply": true, 1840 "links": { 1841 "1": { 1842 "@type": "Link", 1843 "href": "http://example.org/vcards/vbede.vcf", 1844 "rel": "alternate" 1845 } 1846 }, 1847 "roles": { 1848 "attendee": true 1849 }, 1850 "scheduleStatus": "1.2" 1851 } 1852 }, 1853 "replyTo": { 1854 "imip": "mailto:douglm@example.org" 1855 } 1856 }, 1857 "2020-05-24T12:00:00": { 1858 "participants": { 1859 "daeae4cf-6f6a-4ce3-9f4d-6bd884650d3d": { 1860 "@type": "Participant", 1861 "sendTo": { 1862 "imip": "mailto:user01@example.org" 1863 }, 1864 "expectReply": true, 1865 "roles": { 1866 "attendee": true 1867 }, 1868 "scheduleStatus": "1.2" 1869 }, 1870 "a6de6de3-271f-4679-9241-1b3bca6b602d": { 1871 "@type": "Participant", 1872 "sendTo": { 1873 "imip": "mailto:vbede@example.org" 1874 }, 1875 "expectReply": true, 1876 "roles": { 1877 "attendee": true 1878 }, 1879 "scheduleStatus": "1.2" 1880 }, 1881 "aaa8483b-b18b-4dbd-b218-77d8db027d35": { 1882 "@type": "Participant", 1883 "sendTo": { 1884 "imip": "mailto:douglm@example.org" 1885 }, 1886 "roles": { 1887 "owner": true 1888 } 1889 } 1890 }, 1891 "replyTo": { 1892 "imip": "mailto:douglm@example.org" 1893 } 1894 } 1895 } 1896 } 1897 ] 1898 } 1900 7. Translating JSCalendar properties to iCalendar components 1902 This section lists JSCalendar property types that map on to [RFC5545] 1903 components. 1905 7.1. jsevent 1907 A JSCalendar object with a type of "jsevent" is mapped on to a 1908 [RFC5545] VEVENT component. 1910 If it is a single VEVENT then a [RFC5545] VCALENDAR component must 1911 surround it and the JSCalendar "prodid" property will be converted to 1912 a [RFC5545] PRODID. 1914 { 1915 "@type": "jsevent", 1916 "prodid": "-//ABC Corporation//NONSGML My Product//EN", 1917 ... 1918 } 1920 maps to 1922 BEGIN: VCALENDAR 1923 PRODID:-//ABC Corporation//NONSGML My Product//EN 1924 BEGIN:VEVENT 1925 ... 1926 END:VEVENT 1927 END: VCALENDAR 1929 When converting multiple JSEvent or JSTask objects the surrounding 1930 [RFC5545] VCALENDAR object must have a [RFC5545] PRODID set from 1931 either the JSGroup "prodid" or generated. 1933 7.2. jsgroup 1935 A JSCalendar object with a type of "jsgroup" is mapped on to a 1936 [RFC5545] VCALENDAR component. 1938 { 1939 "@type": "jsgroup", 1940 "prodid": "-//ABC Corporation//NONSGML My Product//EN", 1941 ... 1942 { 1943 "@type": "jsevent", 1944 ... 1945 } 1946 { 1947 "@type": "jsevent", 1948 ... 1949 } 1950 } 1952 maps to 1954 BEGIN: VCALENDAR 1955 PRODID:-//ABC Corporation//NONSGML My Product//EN 1956 BEGIN:VEVENT 1957 ... 1958 END:VEVENT 1959 BEGIN:VEVENT 1960 ... 1961 END:VEVENT 1962 END: VCALENDAR 1964 7.3. jstask 1966 A JSCalendar object with a type of "jstask" is mapped on to a 1967 [RFC5545] VTODO component. 1969 If it is a single VTODO then a [RFC5545] VCALENDAR component must 1970 surround it and the JSCalendar "prodid" property will be converted to 1971 a [RFC5545] PRODID. 1973 { 1974 "@type": "jstask", 1975 "prodid": "-//ABC Corporation//NONSGML My Product//EN", 1976 ... 1977 } 1979 maps to 1981 BEGIN: VCALENDAR 1982 PRODID:-//ABC Corporation//NONSGML My Product//EN 1983 BEGIN:VTODO 1984 ... 1985 END:VTODO 1986 END: VCALENDAR 1988 When converting multiple JSEvent or JSTask objects the surrounding 1989 [RFC5545] VCALENDAR object must have a [RFC5545] PRODID set from 1990 either the JSGroup "prodid" or generated. 1992 7.4. timezones 1994 The JSCalendar TimeZone objects within a "timezones" property are 1995 mapped on to [RFC5545] VTIMEZONE components within the surrounding 1996 VCALENDAR component. Each mapped TimeZone MUST only appear once. 1998 { 1999 "@type": "jsevent", 2000 ... 2001 "timezones": { 2002 "/Example/Somewhere: { 2003 "@type": "TimeZone", 2004 ... 2005 }, 2006 "/Example/Somewhere-else": { 2007 "@type": "TimeZone", 2008 ... 2009 } 2010 } 2011 } 2013 maps to 2015 BEGIN: VTIMEZONE 2016 TZID: /Example/Somewhere 2017 ... 2018 END: VTIMEZONE 2019 BEGIN: VTIMEZONE 2020 TZID: /Example/Somewhere-else 2021 ... 2022 END: VTIMEZONE 2023 BEGIN: VEVENT 2024 ... 2025 END: VEVENT 2027 When converting multiple JSEvent or JSTask objects the surrounding 2028 [RFC5545] VCALENDAR object must have a [RFC5545] PRODID set from 2029 either the JSGroup "prodid" or generated. 2031 7.5. alerts 2033 Each member of a JSCalendar alerts property maps to a [RFC5545] 2034 VALARM component. Only display and email alarms are allowed in 2035 JSCalendar. 2037 7.5.1. action 2039 The JSCalendar "alert" property maps to the [RFC5545] ACTION 2040 property. The value SHOULD be the uppercased version if the 2041 JSCalendar "alert" property. 2043 For example: 2045 ... 2046 "action": "display", 2047 ... 2049 maps to 2051 ACTION:DISPLAY 2053 and 2055 ... 2056 "action": "email", 2057 ... 2059 maps to 2061 ACTION:EMAIL 2063 7.5.2. trigger 2065 A JSCalendar trigger with a type of "AbsoluteTrigger" maps on to a 2066 [RFC5545] TRIGGER property with a "VALUE" parameter of "DATE-TIME" 2067 and a value taken from the JSCalendar "when" property. 2069 For example: 2071 "trigger": { 2072 "@type": "AbsoluteTrigger", 2073 "when": "20210315T133000Z" 2074 } 2076 maps to 2078 TRIGGER;VALUE=DATE-TIME:20210315T133000Z 2080 A JSCalendar trigger with a type of "OffsetTrigger" maps on to a 2081 [RFC5545] TRIGGER property with a duration value taken from the 2082 JSCalendar "offset" property. 2084 If the JSCalendar trigger has a "relativeTo" property with the value 2085 "end" then the [RFC5545] TRIGGER property will have a RELATED=END 2086 parameter. 2088 For example: 2090 "trigger": { 2091 "@type": "OffsetTrigger", 2092 "offset": "-P2D", 2093 "relativeTo": "end" 2094 } 2096 maps to 2098 TRIGGER;RELATED=END:-P2D 2100 and 2102 "trigger": { 2103 "@type": "OffsetTrigger", 2104 "offset": "-PT30M" 2105 } 2107 maps to 2109 TRIGGER:-PT30M 2111 7.5.3. todo 2113 Need to deal with "acknowledged" and "relatedTo". Also in the 2114 icalendar to jscalendar. 2116 8. Translating JSCalendar properties to iCalendar properties 2118 This section is an alphabetic list of all JSCalendar property types 2119 that map on to [RFC5545] properties. 2121 8.1. categories 2123 Each member of the JSCalendar "categories" property maps on to a 2124 [draft-ietf-calext-eventpub-extensions] CONCEPT property with the 2125 value being the key of each member. 2127 For example: 2129 ... 2130 "categories": { 2131 "http://example.com/event-types/arts/music": true, 2132 "http://example.com/performance-types/arts/live": true 2133 } 2134 ... 2136 maps to 2138 ... 2139 CONCEPT:http://example.com/event-types/arts/music 2140 CONCEPT:http://example.com/performance-types/arts/live 2141 ... 2143 8.2. created 2145 The JSCalendar "created" property maps on to a [RFC5545] CREATED 2146 property with the value being the [RFC5545] UTC date-time derived 2147 from the value of the property. 2149 For example: 2151 ... 2152 "created": "2021-03-15T13:30"00Z" 2153 ... 2155 maps to 2157 ... 2158 CREATED:20210315T133000Z 2159 ... 2161 8.3. duration 2163 The JSCalendar "duration" property is only valid for event objects. 2164 Copy the JSCalendar "duration" property in to the [RFC5545] DURATION 2165 property. 2167 For example: 2169 ... 2170 "duration": "PT1H" 2171 ... 2173 maps to 2175 ... 2176 DURATION:PT1H 2177 ... 2179 8.4. estimatedDuration 2181 The JSCalendar "estimatedDuration" property is only valid for task 2182 objects. Copy the JSCalendar "estimatedDuration" property in to the 2183 [RFC5545] ESTIMATED-DURATION property. 2185 For example: 2187 ... 2188 "estimatedDuration": "PT18H" 2189 ... 2191 maps to 2193 ... 2194 ESTIMATED-DURATION:PT18H 2195 ... 2197 8.5. keywords 2199 Each member of the JSCalendar "categories" property maps on to a 2200 [RFC5545] CATEGORIES property with the value being the key of each 2201 member. 2203 For example: 2205 ... 2206 "keywords": { 2207 "APPOINTMENT": true, 2208 "EDUCATION": true, 2209 "MEETING": true 2210 }, 2211 ... 2213 maps to 2215 ... 2216 CATEGORIES:APPOINTMENT 2217 CATEGORIES:EDUCATION 2218 CATEGORIES:MEETING 2219 ... 2221 or alternatively 2223 ... 2224 CATEGORIES:APPOINTMENT,EDUCATION,MEETING 2225 ... 2227 8.6. locations 2229 JSCalendar locations should be mapped on to 2230 [draft-ietf-calext-eventpub-extensions]VLOCATION components. 2231 Additionally, for backwards compatibility, a location should be 2232 mapped on to a [RFC5545] LOCATION property. This property should be 2233 mapped from the only location or the one related to the start. 2235 8.7. participants 2237 JSCalendar participants will be mapped on to different iCalendar 2238 properties and components depending on their jsCalendar role values. 2240 A participant with a role containing "contact" MUST be mapped on to 2241 an iCalendar CONTACT property and SHOULD also be mapped on to a 2242 [draft-ietf-calext-eventpub-extensions]PARTICIPANT component which 2243 provides a better mapping. 2245 A participant with a role containing "owner" MUST be mapped on to an 2246 iCalendar ORGANIZER property and SHOULD also be mapped on to a 2247 [draft-ietf-calext-eventpub-extensions]PARTICIPANT component which 2248 provides a better mapping. 2250 A participant with a role containing any of "attendee", "optional" or 2251 "informational" MUST be mapped on to an iCalendar ATTENDEE property 2252 and SHOULD also be mapped on to a 2254 [draft-ietf-calext-eventpub-extensions]PARTICIPANT component which 2255 provides a better mapping. 2257 A more complete mapping may be achieved by creating a 2258 [draft-ietf-calext-eventpub-extensions]PARTICIPANT component. 2260 For all properties the participants jsCalendar "language" property, 2261 if present, is mapped on to the iCalendar "LANG" property parameter. 2263 For all properties if the participant contains a jsCalendar "link" 2264 with a "rel" of "alternate" then the value of the link is used for 2265 the iCalendar "ALTREP" property parameter. 2267 Where do we get the cua? 2269 9. Security Considerations 2271 The same security considerations as for 2272 [draft-ietf-calext-jscalendar] apply. 2274 10. IANA Considerations 2276 None. 2278 11. Acknowledgments 2280 The authors would like to thank the members of CalConnect for their 2281 valuable contributions. This specification originated from the work 2282 of the API technical committee of CalConnect, the Calendaring and 2283 Scheduling Consortium. 2285 12. References 2287 12.1. Normative References 2289 [draft-ietf-calext-eventpub-extensions] 2290 "Event Publishing Extensions to iCalendar", 2291 . 2294 [draft-ietf-calext-ical-relations] 2295 "Support for iCalendar Relationships", 2296 . 2299 [draft-ietf-calext-valarm-extensions] 2300 "VALARM Extensions for iCalendar", 2301 . 2304 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2305 Requirement Levels", BCP 14, RFC 2119, 2306 DOI 10.17487/RFC2119, March 1997, 2307 . 2309 [RFC2397] Masinter, L., "The "data" URL scheme", RFC 2397, 2310 DOI 10.17487/RFC2397, August 1998, 2311 . 2313 [RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and 2314 Scheduling Core Object Specification (iCalendar)", 2315 RFC 5545, DOI 10.17487/RFC5545, September 2009, 2316 . 2318 [RFC5546] Daboo, C., Ed., "iCalendar Transport-Independent 2319 Interoperability Protocol (iTIP)", RFC 5546, 2320 DOI 10.17487/RFC5546, December 2009, 2321 . 2323 [RFC6638] Daboo, C. and B. Desruisseaux, "Scheduling Extensions to 2324 CalDAV", RFC 6638, DOI 10.17487/RFC6638, June 2012, 2325 . 2327 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 2328 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 2329 2014, . 2331 [RFC7265] Kewisch, P., Daboo, C., and M. Douglass, "jCal: The JSON 2332 Format for iCalendar", RFC 7265, DOI 10.17487/RFC7265, May 2333 2014, . 2335 [RFC7986] Daboo, C., "New Properties for iCalendar", RFC 7986, 2336 DOI 10.17487/RFC7986, October 2016, 2337 . 2339 12.2. Informative References 2341 [draft-apthorp-ical-tasks] 2342 "Task Extensions to iCalendar", 2343 . 2345 [draft-ietf-calext-jscalendar] 2346 "Task Extensions to iCalendar", 2347 . 2350 Appendix A. Outdated document sections 2352 A.1. Note 2354 The sections following this one are all the original ones from draft 2355 1 writen by Robert/Neil - there for reference. 2357 A.2. JSTask 2359 A JSTask object maps to the iCalendar VTODO component type [RFC5545]. 2360 The following tables maps the JSTask-specific properties to 2361 iCalendar: 2363 +-----------------+-------------------------------------------------+ 2364 | Property | iCalendar counterpart | 2365 +-----------------+-------------------------------------------------+ 2366 | due | Maps to the DUE property. See Appendix A.4.1. | 2367 | | | 2368 | statusUpdatedAt | COMPLETED property. The JSTask status property | 2369 | | MUST have value "completed". | 2370 | | | 2371 | progress | PARTSTAT and COMPLETED properties, including | 2372 | | the definitions in the RFC draft | 2373 | | [draft-apthorp-ical-tasks]. | 2374 | | | 2375 | status | STATUS property, including the definitions in | 2376 | | the RFC draft [draft-apthorp-ical-tasks]. | 2377 +-----------------+-------------------------------------------------+ 2379 Table 1: Mapping JSTask properties 2381 A.3. JSGroup 2383 A JSGroup maps to a iCalendar VCALENDAR containing VEVENT or VTODO 2384 components. 2386 +----------+--------------------------------------------------------+ 2387 | Property | iCalendar counterpart | 2388 +----------+--------------------------------------------------------+ 2389 | entries | VEVENT and VTODO components embedded in a VCALENDAR | 2390 | | component. | 2391 | | | 2392 | source | SOURCE property. | 2393 +----------+--------------------------------------------------------+ 2395 Table 2: Mapping JSGroup properties 2397 A.4. Common properties 2399 This section contains recommendations how to map JSCalendar from and 2400 to iCalendar. It lists all common JSCalendar object properties in 2401 alphabetical order. 2403 +------------------------+------------------------------------------+ 2404 | Property | iCalendar counterpart | 2405 +------------------------+------------------------------------------+ 2406 | @type | Determined by the iCalendar component | 2407 | | type: "jsevent" for VEVENT, "jstask" for | 2408 | | VTODO, "jsgroup" for VCALENDAR. | 2409 | | | 2410 | alerts | Each entry maps to a VALARM component. | 2411 | | The action property maps to iCalendar | 2412 | | ACTION, where both iCalendar "DISPLAY" | 2413 | | and "AUDIO" values map to the "display" | 2414 | | action. An EMAIL value maps to a | 2415 | | JSCalendar "email" action. _relativeTo_ | 2416 | | and _offset_ map to the TRIGGER | 2417 | | property. | 2418 | | | 2419 | color | COLOR property, as specified in | 2420 | | [RFC7986]. | 2421 | | | 2422 | created | CREATED property. | 2423 | | | 2424 | description | DESCRIPTION property. | 2425 | | | 2426 | descriptionContentType | Implementation-specific. | 2427 | | | 2428 | excluded | EXDATE property. | 2429 | | | 2430 | freeBusyStatus | TRANSP property. | 2431 | | | 2432 | invitedBy | Implementation-specific. | 2433 | | | 2434 | keywords | CATEGORIES property, as specified in | 2435 | | [RFC7986]. | 2436 | | | 2437 | links | ATTACH ([RFC5545]), URL or IMAGE | 2438 | | ([RFC7986]) properties with URI value | 2439 | | types map to the the Link _href_. The | 2440 | | FMTTYPE parameter maps to _type_, the | 2441 | | SIZE parameter to _size_. Mapping other | 2442 | | properties is implementation-specific. | 2443 | | | 2444 | locale | LANGUAGE parameter of the SUMMARY or | 2445 | | DESCRIPTION property. | 2446 | | | 2447 | localizations | Implementation-specific. | 2448 | | | 2449 | locations | See Appendix A.4.2. | 2450 | | | 2451 | method | METHOD property of the embedding | 2452 | | VCALENDAR. | 2453 | | | 2454 | participants | See Appendix A.4.3. | 2455 | | | 2456 | priority | PRIORITY property. | 2457 | | | 2458 | privacy | CLASS property. | 2459 | | | 2460 | prodId | PRODID property. | 2461 | | | 2462 | recurrenceOverrides | RDATE and EXDATE properties, and any | 2463 | | VEVENT or VTODO instances with a | 2464 | | recurrence-id and same UID as the mapped | 2465 | | main object. | 2466 | | | 2467 | recurrenceRule | RRULE property. For all-day calendar | 2468 | | objects, map the _until_ property value | 2469 | | to an iCalendar DATE (effectively | 2470 | | removing the time component). To convert | 2471 | | a DATE-typed UNTIL from iCalendar, set | 2472 | | the time components of the LocalDateTime | 2473 | | value to "23:59:59". If the iCalendar | 2474 | | UNTIL value is a UTC date time, convert | 2475 | | it to the local time in the JSCalendar | 2476 | | calendar object time zone. To convert to | 2477 | | iCalendar where the DTSTART or DUE | 2478 | | property is of type DATE, omit the time | 2479 | | component of the LocalDateTime value. | 2480 | | | 2481 | relatedTo | RELATED-TO property. | 2482 | | | 2483 | replyTo | An iCalendar ORGANIZER with a mailto: | 2484 | | URI mapped to the "imip" method, or any | 2485 | | other URI mapped to the "other" method. | 2486 | | Mapping multiple methods is | 2487 | | implementation-specific. | 2488 | | | 2489 | sequence | SEQUENCE property. | 2490 | | | 2491 | showWithoutTime | Implementation-specific. | 2492 | | | 2493 | start | Maps to the DTSTART property. See | 2494 | | Appendix A.4.1. | 2495 | | | 2496 | status | STATUS property. | 2497 | | | 2498 | timeZone | Maps to the TZID parameter. See | 2499 | | Appendix A.4.1. | 2500 | | | 2501 | timeZones | Each entry in the property maps to a | 2502 | | VTIMEZONE in the embedding VCALENDAR | 2503 | | component. | 2504 | | | 2505 | title | SUMMARY property. | 2506 | | | 2507 | uid | UID property. | 2508 | | | 2509 | updated | DTSTAMP and LAST-MODIFIED properties. | 2510 | | | 2511 | useDefaultAlerts | Implementation-specific. | 2512 | | | 2513 | virtualLocations | See Appendix A.4.2. | 2514 +------------------------+------------------------------------------+ 2516 Table 3: Translation between JSCalendar and iCalendar 2518 A.4.1. Time properties and types 2520 iCalendar defines two different time types, DATE and DATE-TIME, where 2521 the latter may occur in three forms (with local time, with UTC time, 2522 with local time and time zone reference). In contrast, JSCalendar 2523 does not define a distinct type for dates, and date times are defined 2524 with the LocalDateTime type only. 2526 A JSCalendar time maps to the iCalendar DATE type if all of the 2527 following criteria apply: 2529 o The "start" ("due") property value has zero time, or is not set. 2531 o The "duration" ("estimatedDuration") property value has zero time, 2532 or is a multiple of days or weeks, or is not set. 2534 o The "timeZone" property value is null, or is not set. 2536 o The "showWithoutTime" property value is not set or "true". 2538 o The recurrenceRule.frequency is at most daily. 2540 o All recurrenceOverrides recurrence ids have zero time 2542 For all other cases, the time maps to an iCalendar DATE-TIME: 2544 o With local time and time zone reference, if the "timeZone" 2545 property value is set and does not equal "Etc/UTC". 2547 o With UTC time, if the "timeZone" property value equals "Etc/UTC". 2549 o With local time, if the "timeZone" property value is null or not 2550 set. 2552 A.4.2. Locations 2554 The iCalendar counterpart for JSCalendar Location objects is the 2555 iCalendar [RFC5545] LOCATION property, or implementation-specific. 2557 +-------------+----------------------------------+ 2558 | Property | iCalendar counterpart | 2559 +-------------+----------------------------------+ 2560 | coordinates | GEO property. | 2561 | | | 2562 | description | Implementation-specific. | 2563 | | | 2564 | name | LOCATION property value. | 2565 | | | 2566 | rel | Implementation-specific. | 2567 | | | 2568 | timeZone | Implementation-specific. | 2569 | | | 2570 | uri | The LOCATION ALTREP parameter. | 2571 +-------------+----------------------------------+ 2573 Table 4: Mapping Location properties 2575 The iCalendar counterpart for JSCalendar VirtualLocation objects is 2576 the iCalendar [RFC7986] CONFERENCE property. 2578 +-------------+------------------------------+ 2579 | Property | iCalendar counterpart | 2580 +-------------+------------------------------+ 2581 | description | Implementation-specific. | 2582 | | | 2583 | name | LABEL parameter. | 2584 | | | 2585 | uri | CONFERENCE property value. | 2586 +-------------+------------------------------+ 2588 Table 5: Mapping virtualLocation properties 2590 A.4.3. Participants 2592 The following table outlines translation of JSCalendar participants. 2593 An iCalendar ORGANIZER maps to both the replyTo property and a 2594 participant with role "owner". If an ATTENDEE with the same CAL- 2595 ADDRESS value exists, then it maps to the same participant as the 2596 ORGANIZER participant. Other participants map to ATTENDEEs. 2598 +---------------------+---------------------------------------------+ 2599 | Property | iCalendar counterpart | 2600 +---------------------+---------------------------------------------+ 2601 | attendance | ROLE parameter values REQ-PARTICIPANT, OPT- | 2602 | | PARTICIPANT and NON-PARTICIPANT. | 2603 | | | 2604 | delegatedFrom | DELEGATED-FROM parameter | 2605 | | | 2606 | delegatedTo | DELEGATED-TO parameter | 2607 | | | 2608 | email | EMAIL parameter, if defined. Otherwise the | 2609 | | CAL-ADDRESS property value, if it is a | 2610 | | mailto: URI. | 2611 | | | 2612 | expectReply | RSVP parameter | 2613 | | | 2614 | kind | CUTYPE parameter | 2615 | | | 2616 | locationId | Implementation-specific. | 2617 | | | 2618 | memberOf | MEMBER parameter | 2619 | | | 2620 | name | CN parameter | 2621 | | | 2622 | participationStatus | PARTSTAT parameter | 2623 | | | 2624 | roles | ROLE parameter. | 2625 | | | 2626 | scheduleSequence | SEQUENCE property of the participant's | 2627 | | latest iMIP message | 2628 | | | 2629 | scheduleUpdated | DTSTAMP property of the participant's | 2630 | | latest iMIP message | 2631 | | | 2632 | sendTo | A CAL-ADDRESS with a mailto: URI maps to | 2633 | | the JSCalendar "imip" method, any other URI | 2634 | | to the "other" method. Mapping multiple | 2635 | | methods is implementation-specific. | 2636 +---------------------+---------------------------------------------+ 2638 Table 6: Mapping Participant properties 2640 A.5. Custom properties 2642 Mapping custom or unknown properties between JSCalendar and iCalendar 2643 is implementation-specific. Implementations might use vendor- 2644 extension properties, which could also serve as basis for discussion 2645 for a JSCalendar standard extension. Alternatively, an 2646 implementation could preserve iCalendar properties and components in 2647 JSCalendar by use of a vendor-extension property formatted as jCal 2648 [RFC7265] data. 2650 Authors' Addresses 2652 Neil Jenkins 2653 FastMail 2654 PO Box 234 2655 Collins St West 2656 Melbourne VIC 8007 2657 Australia 2659 Email: neilj@fastmailteam.com 2660 URI: https://www.fastmail.com 2662 Robert Stepanek 2663 FastMail 2664 PO Box 234 2665 Collins St West 2666 Melbourne VIC 8007 2667 Australia 2669 Email: rsto@fastmailteam.com 2670 URI: https://www.fastmail.com 2672 Michael Douglass 2673 Bedework Commercial Services 2674 226 3rd Street 2675 Troy, NY 12180 2676 United States of America 2678 Email: mdouglass@bedework.com 2679 URI: http://bedework.com