idnits 2.17.1 draft-ietf-calext-jscalendar-icalendar-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 753 has weird spacing: '... x-name verba...' -- The document date (February 21, 2021) is 1153 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 275, but not defined == Missing Reference: 'RFC4648' is mentioned on line 302, but not defined == Unused Reference: 'RFC5546' is defined on line 1963, 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: August 25, 2021 M. Douglass 6 BCS 7 February 21, 2021 9 JSCalendar: Converting from and to iCalendar 10 draft-ietf-calext-jscalendar-icalendar-04 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 August 25, 2021. 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 . . . . . . . . . . . . . . . . . . . . . . . . 3 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. New iCalendar parameters . . . . . . . . . . . . . . . . . . 5 57 2.1. FRACTIONAL parameter . . . . . . . . . . . . . . . . . . 5 58 3. iCalendar pre-processing . . . . . . . . . . . . . . . . . . 6 59 4. Translating iCalendar components to JSCalendar . . . . . . . 7 60 4.1. VALARM . . . . . . . . . . . . . . . . . . . . . . . . . 7 61 4.2. VCALENDAR . . . . . . . . . . . . . . . . . . . . . . . . 10 62 4.3. VEVENT . . . . . . . . . . . . . . . . . . . . . . . . . 11 63 4.4. VLOCATION . . . . . . . . . . . . . . . . . . . . . . . . 11 64 4.5. VTIMEZONE, STANDARD, DAYLIGHT . . . . . . . . . . . . . . 12 65 4.6. VTODO . . . . . . . . . . . . . . . . . . . . . . . . . . 13 66 5. Translating iCalendar properties to JSCalendar . . . . . . . 13 67 5.1. ATTACH . . . . . . . . . . . . . . . . . . . . . . . . . 13 68 5.2. ATTENDEE . . . . . . . . . . . . . . . . . . . . . . . . 13 69 5.3. CALSCALE . . . . . . . . . . . . . . . . . . . . . . . . 16 70 5.4. CATEGORIES . . . . . . . . . . . . . . . . . . . . . . . 16 71 5.5. CLASS . . . . . . . . . . . . . . . . . . . . . . . . . . 16 72 5.6. COLOR . . . . . . . . . . . . . . . . . . . . . . . . . . 17 73 5.7. COMMENT . . . . . . . . . . . . . . . . . . . . . . . . . 17 74 5.8. COMPLETED . . . . . . . . . . . . . . . . . . . . . . . . 17 75 5.9. CONCEPT . . . . . . . . . . . . . . . . . . . . . . . . . 17 76 5.10. CONFERENCE . . . . . . . . . . . . . . . . . . . . . . . 18 77 5.11. CONTACT . . . . . . . . . . . . . . . . . . . . . . . . . 18 78 5.12. CREATED . . . . . . . . . . . . . . . . . . . . . . . . . 19 79 5.13. DESCRIPTION . . . . . . . . . . . . . . . . . . . . . . . 19 80 5.14. DTEND, DTSTART, DUE, DURATION . . . . . . . . . . . . . . 20 81 5.15. EXDATE . . . . . . . . . . . . . . . . . . . . . . . . . 23 82 5.16. EXRULE . . . . . . . . . . . . . . . . . . . . . . . . . 23 83 5.17. DTSTAMP and LAST-MODIFIED . . . . . . . . . . . . . . . . 23 84 5.18. GEO . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 85 5.19. IMAGE . . . . . . . . . . . . . . . . . . . . . . . . . . 23 86 5.20. LOCATION . . . . . . . . . . . . . . . . . . . . . . . . 24 87 5.21. METHOD . . . . . . . . . . . . . . . . . . . . . . . . . 24 88 5.22. ORGANIZER . . . . . . . . . . . . . . . . . . . . . . . . 24 89 5.23. PERCENT-COMPLETE . . . . . . . . . . . . . . . . . . . . 24 90 5.24. PRIORITY . . . . . . . . . . . . . . . . . . . . . . . . 27 91 5.25. PRODID . . . . . . . . . . . . . . . . . . . . . . . . . 28 92 5.26. RECURRENCE-ID . . . . . . . . . . . . . . . . . . . . . . 28 93 5.27. RELATED-TO . . . . . . . . . . . . . . . . . . . . . . . 28 94 5.28. REQUEST-STATUS . . . . . . . . . . . . . . . . . . . . . 29 95 5.29. RESOURCES . . . . . . . . . . . . . . . . . . . . . . . . 29 96 5.30. RDATE . . . . . . . . . . . . . . . . . . . . . . . . . . 30 97 5.31. RRULE . . . . . . . . . . . . . . . . . . . . . . . . . . 30 98 5.32. SEQUENCE . . . . . . . . . . . . . . . . . . . . . . . . 34 99 5.33. STATUS . . . . . . . . . . . . . . . . . . . . . . . . . 34 100 5.34. STRUCTURED-DATA . . . . . . . . . . . . . . . . . . . . . 34 101 5.35. SUMMARY . . . . . . . . . . . . . . . . . . . . . . . . . 35 102 5.36. TRANSP . . . . . . . . . . . . . . . . . . . . . . . . . 35 103 5.37. UID . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 104 5.38. URL . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 105 6. Translating iCalendar Recurrences . . . . . . . . . . . . . . 36 106 6.1. Translating iCalendar Recurrences: Simple objects with 107 overrides . . . . . . . . . . . . . . . . . . . . . . . . 36 108 6.2. Translating iCalendar Recurrences: Overrides with no 109 master . . . . . . . . . . . . . . . . . . . . . . . . . 36 110 7. Translating iCalendar: Further examples . . . . . . . . . . . 36 111 7.1. Recurring event with ATTACH . . . . . . . . . . . . . . . 37 112 7.2. Simple event with CONTACT . . . . . . . . . . . . . . . . 39 113 7.3. Simple event with RESOURCES . . . . . . . . . . . . . . . 40 114 7.4. Recurring event. Attendees only in overrides . . . . . . 40 115 8. Security Considerations . . . . . . . . . . . . . . . . . . . 43 116 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 43 117 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 44 118 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 44 119 11.1. Normative References . . . . . . . . . . . . . . . . . . 44 120 11.2. Informative References . . . . . . . . . . . . . . . . . 45 121 Appendix A. Outdated document sections . . . . . . . . . . . . . 45 122 A.1. Translating JSCalendar properties to iCalendar components 45 123 A.1.1. jsevent . . . . . . . . . . . . . . . . . . . . . . . 45 124 A.1.2. jsgroup . . . . . . . . . . . . . . . . . . . . . . . 46 125 A.1.3. jstask . . . . . . . . . . . . . . . . . . . . . . . 47 126 A.1.4. timezones . . . . . . . . . . . . . . . . . . . . . . 48 127 A.1.5. locations . . . . . . . . . . . . . . . . . . . . . . 49 128 A.1.6. participants . . . . . . . . . . . . . . . . . . . . 49 129 A.2. Note . . . . . . . . . . . . . . . . . . . . . . . . . . 50 130 A.3. JSEvent . . . . . . . . . . . . . . . . . . . . . . . . . 50 131 A.4. JSTask . . . . . . . . . . . . . . . . . . . . . . . . . 51 132 A.5. JSGroup . . . . . . . . . . . . . . . . . . . . . . . . . 52 133 A.6. Common properties . . . . . . . . . . . . . . . . . . . . 52 134 A.6.1. Time properties and types . . . . . . . . . . . . . . 55 135 A.6.2. Locations . . . . . . . . . . . . . . . . . . . . . . 55 136 A.6.3. Participants . . . . . . . . . . . . . . . . . . . . 56 137 A.7. Custom properties . . . . . . . . . . . . . . . . . . . . 57 138 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 58 140 1. Introduction 141 1.1. Note (to be deleted later) 143 This is still very much a work in progress. There are 144 implementations of the mapping but there may be changes over the 145 coming weeks. 147 1.2. Motivation 149 The JSCalendar [draft-ietf-calext-jscalendar] data format is used to 150 represent calendar data, and is meant as an alternative to the widely 151 deployed iCalendar [RFC5545] data format. 153 While new calendaring services and applications might use JSCalendar 154 as their main data format to exchange calendaring data, they are 155 likely to interoperate with services and clients that just support 156 iCalendar. Similarly, existing calendaring data is stored in 157 iCalendar format in databases and other calendar stores, and 158 providers and users might want to represent this data also in 159 JSCalendar. Lastly, there is a requirement to preserve custom 160 iCalendar properties that have no equivalent in JSCalendar when 161 converting between these formats. 163 To support these use cases, this document provides the required 164 approach when converting JSCalendar data from and to iCalendar. 166 1.3. Scope and caveats 168 JSCalendar and iCalendar have a lot of semantics in common, but they 169 are not interchangeable formats: 171 o JSCalendar contains a richer data model to express calendar 172 information such as event locations and participants. while 173 future iCalendar extensions may allow a direct mapping, for now 174 there may be no representation directly in iCalendar of some 175 properties. These values may have to be extracted from a full 176 copy of the iCalendar format provided as a property in the 177 JSCalendar data. 179 o iCalendar may contain arbitrary, non-standardised data with custom 180 properties/attributes. These will be translated using the same 181 approach as jCal. 183 o iCalendar has some obsolete features that have been removed from 184 JSCalendar due to not being useful and/or supported in the real 185 world (e.g. custom email alerts to send to random people). 186 Translating these may lose some of the original fidelity. 188 o Implementations may use a custom property to store data that could 189 not be mapped directly in either direction in the original or a 190 custom format, however this is not interoperable. 192 Accordingly, this document defines a canonical translation between 193 iCalendar and JSCalendar, and implementations MUST follow the 194 approaches specified here when iCalendar data is represented in 195 JSCalendar and vice-versa. 197 This document defines mappings for the following specifications. 199 o Internet Calendaring and Scheduling Core Object Specification 200 (iCalendar) 202 o iCalendar Transport-Independent Interoperability Protocol (iTIP) 204 o New Properties for iCalendar 206 o Event Publishing Extensions to iCalendar 208 o Support for iCalendar Relationships 210 o VALARM Extensions for iCalendar 212 Therefore all of these specifications MUST be implemented to follow 213 this specification. 215 1.4. Notational Conventions 217 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 218 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 219 document are to be interpreted as described in [RFC2119]. 221 2. New iCalendar parameters 223 2.1. FRACTIONAL parameter 225 Parameter name: FRACTIONAL 227 Purpose: This parameter is used to contain a value with fractional 228 seconds for time values and durations. FRACTIONAL MUST NOT be 229 used in date-time calculations or comparisons in iCalendar. It is 230 meant to preserve time precision on time values and duration with 231 sub-second precision, without increasing the time value range 232 within iCalendar. 234 Description: This parameter MAY be specified on properties of type 235 DATE-TIME or DURATION. It MUST be a valid iCalendar DATE-TIME or 236 DURATION value with the addition of fractional seconds. The value 237 MUST NOT be negative for durations but MAY be negative for alarm 238 triggers. iCalendar implementations SHOULD ignore this parameter 239 in date time arithmetic. Implementations MUST ignore presence of 240 the FRACTIONAL parameter on RECURRENCE-ID properties when 241 determining recurrence overrides. 243 Applications receiving a property with a FRACTIONAL parameter MUST 244 ensure its value is consistent with the value of the property. 245 The property value must match: 246 - a positive FRACTIONAL value rounded up to the next non- 247 fractional second or 248 - a negative FRACTIONAL value rounded down the next non-fractional 249 second 251 If the values do not match the the application MUST assume that 252 the property value has been updated by an application that is 253 unaware of the FRACTIONAL parameter. The parameter should be 254 ignored in this case. 256 Format Definition: 258 This parameter is defined by the following notation: 260 fractional-param = DATE-TIME or DURATION 262 Example: 264 DTSTART;FRACTIONAL=20190605T133015.03:20190605T133015 266 3. iCalendar pre-processing 268 iCalendar uses a line-folding mechanism to limit lines of data to a 269 maximum line length (typically 75 octets) to ensure the maximum 270 likelihood of preserving data integrity as it is transported via 271 various means (e.g., email) -- see Section 3.1 of [RFC5545]. 273 iCalendar data uses an "escape" character sequence for text values 274 and property parameter values. See Sections 3.1 and 3.3 of [RFC5545] 275 as well as [RFC6868]. 277 There is a subtle difference in the number representations between 278 JSON and iCalendar. While in iCalendar, a number may have leading 279 zeros, as well as a leading plus sign; this is not the case in JSON. 280 Numbers should be represented in whatever way needed for the 281 underlying format. 283 When converting from iCalendar to JSCalendar: First, iCalendar lines 284 MUST be unfolded. Afterwards, any iCalendar escaping MUST be 285 unescaped. Finally, JSON escaping, as described in Section 7 of 286 [RFC7159], MUST be applied. The reverse order applies when 287 converting from JSCalendar to iCalendar, which is further described 288 in Section ?. 290 iCalendar uses a base64 encoding for binary data. However, it does 291 not restrict the encoding from being applied to non-binary value 292 types. So, the following rules are applied when processing a 293 property with the "ENCODING" property parameter set to "BASE64": 295 o If the property value type is "BINARY", the base64 encoding MUST 296 be preserved. 298 o If the value type is not "BINARY", the "ENCODING" property 299 parameter MUST be removed, and the value MUST be base64 decoded. 301 When base64 encoding is used, it MUST conform to Section 4 of 302 [RFC4648], which is the base64 method used in [RFC5545]. 304 One key difference in the formatting of values used in iCalendar and 305 JSCalendar is that, in JSCalendar, the specification uses date/time 306 values aligned with the extended format of [ISO.8601.2004], which is 307 more commonly used in Internet applications that make use of the JSON 308 format. The sections of this document describing the various date 309 and time formats contain more information on the use of the complete 310 representation, reduced accuracy, or truncated representation. 312 4. Translating iCalendar components to JSCalendar 314 This section is an alphabetic list of [RFC5545] components and how 315 they are mapped to JSCalendar. 317 At present VFREEBUSY and VJOURNAL are not mapped in jscalendar. 319 4.1. VALARM 321 An [RFC5545] VALARM component is mapped to a member of a JSCalendar 322 "alerts" object with a type of "Alert" and a small id. 324 BEGIN: VEVENT 325 ... 326 BEGIN: VALARM 327 ... 328 END: VALARM 329 BEGIN: VALARM 330 ... 331 END: VALARM 332 END: VEVENT 334 maps to 336 { 337 "@type": "jsevent", 338 ... 339 "alerts": { 340 "1": { 341 "@type": "Alert", 342 ... 343 }, 344 "2": { 345 "@type": "Alert", 346 ... 347 } 348 } 349 } 351 The [RFC5545] VALARM has a number of problems which are not carried 352 over into JSCalendar. Clients tend to choose how, and in some cases 353 when to notify the user. 355 For example, if the user has a smart-watch they may get tapped on the 356 wrist. The method of notification may depend on which device is 357 being used and the context, for example a meeting or driving. 359 Also, many clients are taking into consideration the travel time and 360 notifying the user earlier if it seems necessary. 362 Specifying that a client should send emails to all attendees is both 363 annoying and dangerous. Attendees have their own preferences for how 364 and when they should be notified. 366 Accordingly, the specification only allows for "display" and "email" 367 actions and - other than specifying when - does not allow much else. 368 Clients and/or servers will generally use the associated event or 369 task title as identification. User preferences generally indicate 370 what actions they prefer. 372 An [RFC5545] ACTION property can take the defined values "AUDIO" / 373 "DISPLAY" / "EMAIL" whereas the JSCalendar "action" property only 374 supports "display" and "email". 376 An "AUDIO" alarm SHOULD be mapped to a "display" alert. Any 377 attachment MUST be ignored. 379 The [RFC5545] example VALARMs will be mapped as follows, assuming 380 they are all in the same event: 382 BEGIN:VEVENT 383 ... 384 BEGIN:VALARM 385 TRIGGER;VALUE=DATE-TIME:19970317T133000Z 386 REPEAT:4 387 DURATION:PT15M 388 ACTION:AUDIO 389 ATTACH;FMTTYPE=audio/basic:ftp://example.com/pub/ 390 sounds/bell-01.aud 391 END:VALARM 392 BEGIN:VALARM 393 TRIGGER:-PT30M 394 REPEAT:2 395 DURATION:PT15M 396 ACTION:DISPLAY 397 DESCRIPTION:Breakfast meeting with executive\n 398 team at 8:30 AM EST. 399 END:VALARM 400 BEGIN:VALARM 401 TRIGGER;RELATED=END:-P2D 402 ACTION:EMAIL 403 ATTENDEE:mailto:john_doe@example.com 404 SUMMARY:*** REMINDER: SEND AGENDA FOR WEEKLY STAFF MEETING *** 405 DESCRIPTION:A draft agenda needs to be sent out to the attendees 406 to the weekly managers meeting (MGR-LIST). Attached is a 407 pointer the document template for the agenda file. 408 ATTACH;FMTTYPE=application/msword:http://example.com/ 409 templates/agenda.doc 410 END:VALARM 411 END:VEVENT 413 maps to 415 { 416 "@type": "jsevent", 417 ... 418 "alerts": { 419 "1": { 420 "@type": "Alert", 421 "action": "display", 422 "trigger": { 423 "@type": "AbsoluteTrigger", 424 "when": "19970317T133000Z" 425 } 426 }, 427 "2": { 428 "@type": "Alert", 429 "action": "display", 430 "trigger": { 431 "@type": "OffsetTrigger", 432 "offset": "-PT30M" 433 } 434 } 435 "3": { 436 "@type": "Alert", 437 "action": "email", 438 "trigger": { 439 "@type": "OffsetTrigger", 440 "offset": "-P2D", 441 "relativeTo": "end" 442 } 443 } 444 } 445 } 447 Note that the ATTACH, ATTENDEE, DESCRIPTION, DURATION, REPEAT and 448 SUMMARY properties have been dropped. 450 4.2. VCALENDAR 452 A [RFC5545] VCALENDAR component may be mapped to a JSCalendar object 453 with a type of "jsgroup". 455 BEGIN: VCALENDAR 456 PRODID:-//ABC Corporation//NONSGML My Product//EN 457 ... 458 END: VCALENDAR 460 maps to 462 { 463 "@type": "jsgroup", 464 "prodid": "-//ABC Corporation//NONSGML My Product//EN", 465 ... 466 } 468 Note that a single JSEvent or JSTask MAY be converted without a 469 surrounding JSGroup if the VCALENDAR component only contains PRODID 470 and CALSCALE properties. In this case the prddid can go in the 471 JSEvent or JSTask. The CALSCALE property is dropped - there is no 472 equivalence in JSCalendar. 474 4.3. VEVENT 476 A [RFC5545] VEVENT component is mapped to a JSCalendar object with a 477 type of "jsevent". 479 BEGIN: VEVENT 480 ... 481 END: VEVENT 483 maps to 485 { 486 "@type": "jsevent", 487 ... 488 } 490 4.4. VLOCATION 492 A [draft-ietf-calext-eventpub-extensions] VLOCATION component is 493 mapped to a JSCalendar object with a type of "Location". Any 494 properties within the VLOCATION must be mapped as described below. 496 BEGIN: VEVENT 497 ... 498 BEGIN: VLOCATION 499 ... 500 END: VLOCATION 501 END: VEVENT 503 maps to 505 { 506 "@type": "jsevent", 507 ... 508 "locations": { 509 "1": { 510 "@type": "Location", 511 ... 512 } 513 } 514 } 516 4.5. VTIMEZONE, STANDARD, DAYLIGHT 518 A [RFC5545] VTIMEZONE component is mapped to a member of a JSCalendar 519 "timezones" object with a type of "TimeZone" and an id which follows 520 the restrictions specified. 522 The STANDARD and DAYLIGHT components map to JSCalendar TimeZoneRule 523 objects as members of the 525 Note that 527 o There is no current approach for defining standalone sets of 528 timezones. 530 o Timezones defined in the IANA timezone database SHOULD NOT be 531 redefined in the object. Only custom timezones will be defined. 533 BEGIN: VTIMEZONE 534 TZID: Example/Somewhere 535 ... 536 END: VTIMEZONE 537 BEGIN: VTIMEZONE 538 TZID: Example/Somewhere-else 539 ... 540 END: VTIMEZONE 541 BEGIN: VEVENT 542 ... 543 END: VEVENT 545 maps to 547 { 548 "@type": "jsevent", 549 ... 550 "timezones": { 551 "/Example/Somewhere: { 552 "@type": "TimeZone", 553 ... 554 }, 555 "/Example/Somewhere-else": { 556 "@type": "TimeZone", 557 ... 558 } 559 } 560 } 562 4.6. VTODO 564 A [RFC5545] VTODO component is mapped to a JSCalendar object with a 565 type of "jstask". 567 BEGIN: VTODO 568 ... 569 END: VTODO 571 maps to 573 { 574 "@type": "jstask", 575 ... 576 } 578 5. Translating iCalendar properties to JSCalendar 580 This section is an alphabetic list of [RFC5545] and [RFC7986] 581 properties and how they are mapped to JSCalendar. 583 5.1. ATTACH 585 A [RFC5545] ATTACH allows for two types of attachment: 587 o A uri value 589 o A binary value 591 Both map to a JSCalendar "link" object with a "rel" of "enclosure" 592 and the "href" set to the value of the property. 594 If the FMTTYPE parameter is set then add a JSCalendar "contentType" 595 property to the link object. 597 For a binary value use a base64 data uri. 599 For an example of a recurring event with ATTACH see Section 7.1 601 5.2. ATTENDEE 603 An [RFC5545] ATTENDEE maps to the JSCalendar "participant" property 604 with a JSCalendar "role" of "attendee". The value for role should 605 always be set. 607 In the simplest case a JSCalendar "participant" property will be 608 created and added to the JSCalendar "participants" property. 610 The value of the ATTENDEE property is used to add an "imip" method to 611 the JSCalendar "sendTo" property. The value of the entry will be the 612 ATTENDEE property value. 614 For example: 616 ... 617 ATTENDEE:mailto:user01@example.org 618 ... 620 maps to 622 { 623 ... 624 "participants": { 625 "be450b70-9bf7-4f6e-8f65-971ede566ce3": { 626 "@type": "Participant", 627 "sendTo": { 628 "imip": "user01@example.org" 629 }, 630 ... 631 } 633 The attendee parameters are mapped to JSCalendar "participant" 634 properties as follows: 636 CN: The value of the CN parameter is used to set the JSCalendar 637 "name" property. 639 CUTYPE: This maps on to the JSCalendar "kind" property as follows: 641 INDIVIDUAL "individual" 643 GROUP "group" 645 RESOURCE "resource" 647 ROOM "location" 649 UNKNOWN No value 651 Any other value should be converted to lower case and assigned to 652 the JSCalendar "kind" property. 654 DELEGATED-FROM: Split the value at any commas and add each resulting 655 element to the JSCalendar "delegatedFrom" property 657 DELEGATED-TO: Split the value at any commas and add each resulting 658 element to the JSCalendar "delegatedFrom" property 660 DIR: If non-null look in the participant "links" property for a 661 JSCalendar "link" property with an href with the same value as the 662 DIR parameter. You may need to search the current override and 663 the master. 665 If none is found create a new one with the JSCalendar "href" 666 property set to the value of the DIR parameter and the JSCalendar 667 "rel" property set to "alternate" 669 LANG: set the JSCalendar "language" property to the value of the 670 LANG parameter. 672 MEMBER: If this is set there should be a corresponding ATTENDEE 673 object with a value equal to the value of the member parameter. 674 If not it is appropriate to skip this parameter. 676 If there is a corresponding ATTENDEE then there should be a 677 corresponding JSCalendar "participant" property. This suggests 678 that CUTYPE=GROUP ATTENDEE properties should be processed ahead of 679 the others. 681 Locate the JSCalendar "participant" property for the group. This 682 may be in the current override or in the master. Add the id to 683 the current participants JSCalendar "memberOf" property. 685 PARTSTAT: If the PARTSTAT parameter is set and is not "NEEDS-ACTION" 686 then set the JSCalendar "participationStatus" property to the 687 lower-cased value of the PARTSTAT. 689 ROLE: This is mapped to the JSCalendar "roles" property as follows: 691 CHAIR "attendee" and "chair" 693 REQ-PARTICIPANT "attendee" 695 OPT-PARTICIPANT "attendee" and "optional" 697 NON-PARTICIPANT "informational" 699 Any other value should be converted to lower case and added to the 700 JSCalendar "roles" property. 702 RSVP: If the value of the RSVP parameter is TRUE set the JSCalendar 703 "expectReply" property to "true" otherwise omit it. 705 SCHEDULE-AGENT: If the value is "CLIENT" (ignoring case) set the 706 JSCalendar "scheduleAgent" property to "client" otherwise omit it. 708 SCHEDULE-FORCE-SEND: Set the JSCalendar "scheduleForceSend" property 709 to the lower-cased value of the [RFC6638] SCHEDULE-FORCE-SEND 710 parameter. 712 SCHEDULE-STATUS: Split the value at any commas and add each 713 resulting element to the JSCalendar "scheduleStatus" property. 715 SENT-BY: The value of the SENT-BY parameter is used to set the 716 JSCalendar "invitedBy" property. 718 5.3. CALSCALE 720 A [RFC5545] CALSCALE has no equivalence in JSCalendar. It is 721 ignored. 723 5.4. CATEGORIES 725 These map on to the JSCalendar "keywords" property with each category 726 being the key to an entry. 728 ... 729 CATEGORIES:APPOINTMENT,EDUCATION 730 CATEGORIES:MEETING 731 ... 733 maps to 735 ... 736 "keywords": { 737 "APPOINTMENT": true, 738 "EDUCATION": true, 739 "MEETING": true 740 }, 741 ... 743 5.5. CLASS 745 Maps to the "privacy" property. The iCalendar property value maps to 746 the JSCalendar value as follows: 748 CONFIDENTIAL "secret" 749 PRIVATE "private" 751 PUBLIC "public" 753 iana-token and x-name verbatim copy 755 5.6. COLOR 757 Maps to the "color" property. Copy the verbatim value. 759 5.7. COMMENT 761 There is no direct mapping for this property which may appear 762 multiple times in [RFC5545]. 764 For a scheduling reply it is presumably a message by the participant 765 so the value or values should be used to set the JSCalendar 766 "participantComment" property. 768 5.8. COMPLETED 770 Set the JSCalendar "progress" property to "completed" and the 771 "progressUpdated" property to the reformatted date/time. 773 ... 774 COMPLETED: "20101010T101010Z" 775 ... 777 maps to 779 ... 780 "progressUpdated": "2010-10-10T10:10:10Z", 781 "progress": "completed", 782 ... 784 5.9. CONCEPT 786 This [draft-ietf-calext-ical-relations] property may appear multiple 787 times in components. 789 Each instance of the property is mapped on to a member of the 790 JSCalendar "categories" property. 792 ... 793 CONCEPT:http://example.com/event-types/arts/music 794 CONCEPT:http://example.com/performance-types/arts/live 795 ... 797 maps to 799 ... 800 "categories": { 801 "http://example.com/event-types/arts/music": true, 802 "http://example.com/performance-types/arts/live": true 803 } 804 ... 806 5.10. CONFERENCE 808 Maps to a "VirtualLocation" object. The property value maps to the 809 "uri" property of the virtual location. 811 Mapping parameters: 813 FEATURE: Maps to the "features" property of the virtual location. 815 LABEL: Maps to the "name" property of the virtual location. 817 LANGUAGE: No mapping. 819 5.11. CONTACT 821 The CONTACT property is mapped on to a participant object with a 822 "roles" property of "contact" and an "order" property of 1 (one). 823 This defines the participant as a primary contact. 825 Mapping parameters: 827 ALTREP Use the same process as for the ATTENDEE DIR parameter: 828 create a link property with the "rel" property set to "alternate" 829 and the "href" property set to the value of the ALTREP parameter. 830 Then add the link to the participants "links" property. 832 LANG Set the participants "language" property. 834 For an example see Section 7.2 836 5.12. CREATED 838 The CREATED property is mapped on to a "created" property with a json 839 formatted form of the date. Example: 841 BEGIN:VEVENT 842 ... 843 CREATED:19960329T133000Z 844 ... 845 END:VEVENT 847 maps to 849 { 850 "@type": "jsevent", 851 ... 852 "created": "1996-03-29T13:30"00Z", 853 ... 854 } 856 5.13. DESCRIPTION 858 Copy the value, preprocessed according to Section 3 into the 859 "description" property. 861 Mapping parameters: 863 ALTREP No mapping. 865 LANG Use the "locale" property. 867 Example: 869 BEGIN:VEVENT 870 ... 871 DESCRIPTION:We are having a meeting all this week at 12 pm fo 872 r one hour\, with an additional meeting on the first day 2 h 873 ours long.\nPlease bring your own lunch for the 12 pm meetin 874 gs. 875 ... 876 END:VEVENT 878 maps to 880 { 881 "@type": "jsevent", 882 ... 883 "description": // Note: comments and string concatenation are not 884 // allowed per the JSON specification and is used here 885 // to avoid long lines. 886 "We are having a meeting all this week at 12 pm for one " + 887 "hour, with an additional meeting on the first day 2 " + 888 "hours long.\nPlease bring your own lunch for the 12 pm " + 889 "meetings.", 890 ... 891 } 893 5.14. DTEND, DTSTART, DUE, DURATION 895 If the DTSTART is a DATE only property then add the JSCalendar 896 showWithoutTime property with the value set to "true". The 897 JSCalendar "start" property is set with zero time values. 899 If the DTSTART has a TZID parameter then set the JSCalendar 900 "timeZone" property to the value of TZID. 902 If the DTSTART has a UTC value then set the JSCalendar "timeZone" 903 property to the value "Etc/UTC". The JSCalendar "start" property is 904 set without any UTC indicator. 906 JSCalendar has no equivalent to DTEND. If the component has a DTEND 907 then calculate a value for "DURATION" from that property and DTSTART 908 and proceed as below. 910 If the DTEND has a TZID parameter with a value that differs from the 911 DTSTART TZID parameter then a "location" object should be created 912 with a "relativeTo" property set to "end" and a "timezone" property 913 set to the value of the "TZID" parameter. 915 Note that a task is not required to have a DTSTART so the JSCalendar 916 "timezone" property needs to be set from the DUE property. 918 Convert a DURATION property to the JSCalendar duration. 920 Example - DTSTART and DTEND in same timezone: 922 BEGIN:VEVENT 923 ... 924 DTSTART;TZID=America/New_York:20170315T150000 925 DTEND;TZID=America/New_York:20170315T160000 927 ... 928 END:VEVENT 930 maps to 932 { 933 "@type": "jsevent", 934 ... 935 "start": "2017-03-15T15:00:00", 936 "timeZone": "America/New_York", 937 "duration": "PT1H" 938 ... 939 } 941 Example - DTSTART and DTEND in different timezone: 943 BEGIN:VEVENT 944 ... 945 DTSTART;TZID=America/New_York:20170315T150000 946 DTEND;TZID=America/LosAngeles:20170315T190000 948 ... 949 END:VEVENT 951 maps to 953 { 954 "@type": "jsevent", 955 ... 956 "start": "2017-03-15T15:00:00", 957 "timeZone": "America/New_York", 958 "duration": "PT7H" 959 ... 960 "locations": { 961 "1": { 962 "@type": "location", 963 "relatedTo": "end", 964 "timeZone": "America/Los_Angeles" 965 } 966 } 967 } 969 Example - 3 day event: 971 BEGIN:VEVENT 972 ... 973 DTSTART;VALUE=DATE:20210315 974 DTEND;VALUE=DATE:20210318 976 ... 977 END:VEVENT 979 maps to 981 { 982 "@type": "jsevent", 983 ... 984 "start": "2017-03-15T00:00:00", 985 "duration": "P3D", 986 "showWithoutTime": true, 987 ... 988 } 990 5.15. EXDATE 992 Create a patch object with the recurrence id set from the EXDATE 993 value. Add a single JSCalendar "excluded" property with the value 994 set to true. There MUST NOT be any other properties set - other than 995 "@type". 997 5.16. EXRULE 999 Maps to the "excludedRecurrenceRules" property. Also see 1000 Section 5.31. 1002 5.17. DTSTAMP and LAST-MODIFIED 1004 The mapping depends on whether or not the component is a scheduling 1005 entity. 1007 Not a scheduling entity: The [RFC5545] DTSTAMP and LAST-MODIFIED 1008 properties have essentially the same meaning. If both are present 1009 use the value of the latest for the "updated" property. Otherwise 1010 set from whichever is present. 1012 Is a scheduling entity: DTSTAMP should be used to set the 1013 "ScheduleUpdated" property in the "participant" object for the 1014 attendee. 1016 If present LAST-MODIFIED should be used to set the "updated" 1017 property - otherwise set it from the DTSTAMP. 1019 5.18. GEO 1021 Maps to a Location object, with only the "coordinates" property set. 1022 Note that the JSCalendar coordinates property value MUST be a valid 1023 "geo" URI, so replace the ";" character in the iCalendar value with 1024 "," and prepend the resulting string with "geo:". 1026 5.19. IMAGE 1028 Maps to a Link object with the iCalendar property value mapped to the 1029 location "href" property, and the "rel" property set to "icon". 1031 For a binary value use a base64 data uri in the "href" property. 1033 Mapping parameters: 1035 ALTREP No mapping. 1037 FMTTYPE Maps to the "contentType" property of the Link object. 1039 DISPLAY Maps to the "display" property of the Link object. The 1040 property values "BADGE", "GRAPHIC", "FULLSIZE" and "THUMBNAIL" map 1041 to their lower-case equivalent in JSCalendar. 1043 5.20. LOCATION 1045 If any [draft-ietf-calext-eventpub-extensions] "VLOCATION" components 1046 are present, then the [RFC5545]"LOCATION" property should be ignored. 1048 To map the property create a "locations" property with a single 1049 "location" and set the "description" property to the value of the 1050 [RFC5545]"LOCATION" property. 1052 Mapping parameters: 1054 ALTREP Maps to a Link object in the Location "links" property, with 1055 the "href" property set to the parameter value. 1057 5.21. METHOD 1059 Maps to the "method" property of the JSCalendar object. The 1060 JSCalendar property value is the lowercase equivalent of the 1061 iCalendar property value. 1063 5.22. ORGANIZER 1065 Maps to the "replyTo" property of the JSCalendar object. An 1066 iCalendar property value in the "mailto:" URI scheme, maps to the 1067 "imip" method, any other value maps to the "other" method. 1069 If the iCalendar component also contains an ATTENDEE with the same 1070 calendar user address then map that ATTENDEE as defined in 1071 Section 5.2 and add the "owner" role to the Participant "roles" 1072 property. Otherwise, use the ORGANIZER property to map to a 1073 Participant object. The "roles" property of the Participant MUST 1074 only contain the "owner" role and the "expectReply" property value 1075 MUST be "false". Any iCalendar parameters map as defined for 1076 ATTENDEE. 1078 TBD: SENT-BY parameter. Example. 1080 5.23. PERCENT-COMPLETE 1082 For all methods other than REPLY (or no method), the PERCENT-COMPLETE 1083 applies to the VTODO as a whole. In this case it the value is used 1084 to set the JSCalendar "percentComplete" property in the task object. 1086 BEGIN: VCALENDAR 1087 PRODID:-//ABC Corporation//NONSGML My Product//EN 1088 METHOD:PUBLISH 1089 BEGIN:VTODO 1090 ... 1091 PERCENT-COMPLETE:39 1092 END:VTODO 1093 END: VCALENDAR 1095 maps to 1097 { 1098 "@type": "jstask", 1099 "prodid": "-//ABC Corporation//NONSGML My Product//EN", 1100 ... 1101 "percentComplete": 39 1102 } 1104 PERCENT-COMPLETE in a REPLY is used to indicate the level of 1105 completeness of the ATTENDEE. There should only be a single ATTENDEE 1106 in the VTODO object. 1108 As ever recurrences complicate matters. For a non-recurring event or 1109 an override that contains the single participant, set the JSCalendar 1110 "percentComplete" property in the JSCalendar "participant" object 1111 representing the attendee. 1113 BEGIN: VCALENDAR 1114 PRODID:-//ABC Corporation//NONSGML My Product//EN 1115 METHOD:REPLY 1116 BEGIN:VTODO 1117 ... 1118 ATTENDEE:mailto:douglm@example.org 1119 PERCENT-COMPLETE:39 1120 END:VTODO 1121 END: VCALENDAR 1123 maps to 1125 { 1126 "@type": "jstask", 1127 "prodid": "-//ABC Corporation//NONSGML My Product//EN", 1128 ... 1129 "participants": { 1130 "be450b70-9bf7-4f6e-8f65-971ede566ce3": { 1131 "@type": "Participant", 1132 "sendTo": { 1133 "imip": "mailto:douglm@example.org" 1134 }, 1135 "percentComplete": 39, 1136 "roles": { 1137 "attendee": true 1138 } 1139 }, 1140 ... 1141 } 1143 In the case of an override with the participant appearing in the 1144 master then add a patch to the override. 1146 BEGIN: VCALENDAR 1147 PRODID:-//ABC Corporation//NONSGML My Product//EN 1148 METHOD:REPLY 1149 BEGIN:VTODO 1150 ... 1151 ATTENDEE:mailto:douglm@example.org 1152 END:VTODO 1153 BEGIN:VTODO 1154 ... 1155 RECURRENCE-ID:20200523T120000 1156 ... 1157 ATTENDEE:mailto:douglm@example.org 1158 PERCENT-COMPLETE:39 1159 END:VTODO 1160 END: VCALENDAR 1162 maps to 1164 { 1165 "@type": "jstask", 1166 "prodid": "-//ABC Corporation//NONSGML My Product//EN", 1167 ... 1168 "participants": { 1169 "be450b70-9bf7-4f6e-8f65-971ede566ce3": { 1170 "@type": "Participant", 1171 "sendTo": { 1172 "imip": "mailto:douglm@example.org" 1173 }, 1174 "roles": { 1175 "attendee": true 1176 } 1177 }, 1178 "recurrenceOverrides": { 1179 "2020-05-23T12:00:00": { 1180 "participants/be4...6ce3/percentComplete": 39 1181 }, 1182 ... 1183 } 1184 } 1186 5.24. PRIORITY 1188 Simply copy value into the JSCalendar "priority" property. 1190 5.25. PRODID 1192 For a vcalendar JSGroup object with multiple JSEvent and/or JSTask 1193 object the [RFC5545] VCALENDAR PRODID is mapped to a JSCalendar 1194 "prodid" property in the group. 1196 When mapping to a single JSEvent and/or JSTask object the [RFC5545] 1197 VCALENDAR PRODID is mapped to a JSCalendar "prodid" property in the 1198 group 1200 BEGIN: VCALENDAR 1201 PRODID:-//ABC Corporation//NONSGML My Product//EN 1202 BEGIN:VEVENT 1203 ... 1204 END:VEVENT 1205 END: VCALENDAR 1207 maps to 1209 { 1210 "@type": "jsevent", 1211 "prodid": "-//ABC Corporation//NONSGML My Product//EN", 1212 ... 1213 } 1215 5.26. RECURRENCE-ID 1217 Refer to Section 6 for information on mapping recurrence ids. 1219 5.27. RELATED-TO 1221 This is mapped to the JSCalendar "relatedTo" property which is a map 1222 of relations with the target UID as the keys. The iCalendar relation 1223 is by default a PARENT relationship. There is no default for 1224 JSCalendar so the relationship must be explicitly specified. 1226 The RELTYPE parameter values map to their lowercase equivalents in 1227 the "relation" property. 1229 Also note that the iCalendar relationship types are not identical. 1230 CHILD and PARENT map to JSCalendar "child" and "parent" but the best 1231 match for iCalendar SIBLING is "next" 1232 ... 1233 RELATED-TO:jsmith.part7.19960817T083000.xyzMail@example.com 1234 RELATED-TO;RELTYPE=SIBLING: 1235 19960401-080045-4000F192713-0052@example.com 1236 ... 1238 maps to 1240 "relatedTo" : { 1241 "jsmith.part7.19960817T083000.xyzMail@example.com" : { 1242 "@type" : "Relation", 1243 "relation" : { 1244 "parent" : true 1245 } 1246 }, 1247 "19960401-080045-4000F192713-0052@example.com" : { 1248 "@type" : "Relation", 1249 "relation" : { 1250 "next" : true 1251 } 1252 }, 1253 }, 1254 { 1255 "@type": "jsevent", 1256 "prodid": "-//ABC Corporation//NONSGML My Product//EN", 1257 ... 1258 } 1260 5.28. REQUEST-STATUS 1262 Copy the value into the JSCalendar "requestStatus" property. 1264 5.29. RESOURCES 1266 The RESOURCES property value is a comma-separated list of resources. 1267 First split this into the separate resource names and then each 1268 resource is mapped on a participant object with a "kind" property of 1269 "resource" and the "name" property set to the resource name. 1271 Mapping parameters: 1273 ALTREP Use the same process as for the ATTENDEE DIR parameter: 1274 create a link property with the "rel" property set to "alternate" 1275 and the "href" property set to the value of the ALTREP parameter. 1276 Then add the link to the participants "links" property. 1278 LANG Set the participants "language" property. 1280 For an example see Section 7.3 1282 5.30. RDATE 1284 If the RDATE has a RANGE=THISANDFUTURE parameter then the recurrence 1285 MUST be split at this RDATE. 1287 Truncate the original object before this RDATE, create a new master 1288 representing the object and link them by setting the jscalendar 1289 "relatedTo" property in both. 1291 Otherwise create a patch object with the recurrence id set from the 1292 RDATE value. If the instance has overrides the differences will also 1293 be set in the object. 1295 5.31. RRULE 1297 Each RRULE is converted to an object in the JSCalendar 1298 "recurrenceRules" property. Each entry has the type 1299 "RecurrenceRule". 1301 ... 1302 RRULE:... 1303 ... 1305 maps to 1307 ... 1308 "recurrenceRules" : [{ 1309 "@type" : "RecurrenceRule", 1310 ... 1311 }], 1312 ... 1314 The recurrence rule object has one property for each element of the 1315 recurrence rule. The iCalendar rule has to be parsed out and the 1316 individual jscalendar property values set. Most take the same type 1317 but there are exceptions. 1319 FREQ (mandatory) Copy into the jscalendar "frequency" property 1320 converted to lowercase. 1322 INTERVAL If present and not 1 copy into the jscalendar "interval" 1323 property. 1325 RSCALE If present copy into the jscalendar "rscale" property 1326 converted to lowercase. 1328 SKIP If present copy into the jscalendar "skip" property converted 1329 to lowercase. 1331 WKST If present copy into the jscalendar "firstDayOfWeek" property 1332 converted to lowercase. 1334 BYDAY If present each element becomes an entry in the jsCalendar 1335 "byDay" propety. This is an array of NDay objects which may have 1336 2 properties: 1338 day The two character weekday abbreviation. 1340 nthOfPeriod If the weekday abbreviation is preceded by a signed 1341 integer value set the jscalendar "nthOfPeriod" property. 1343 ... 1344 RRULE:...,BYDAY=-1MO 1345 ... 1347 maps to 1349 ... 1350 "recurrenceRules" : [{ 1351 "@type" : "RecurrenceRule", 1352 ... 1353 "byday": [{ 1354 "day": "mo", 1355 "nthOfPeriod": -1 1356 }] 1357 ... 1358 }], 1359 ... 1361 BYMONTHDAY If present each element will be an element in the 1362 jscalendar "byMonthDay" property. 1364 BYMONTH If present each element will be an element in the jscalendar 1365 "byMonth" property. 1367 Note that the iCalendar values are numeric but the JSCalendar 1368 values are strings. This is because of the possible "L" suffix 1369 for leap months. 1371 BYYEARDAY If present each element will be an element in the 1372 jscalendar "byYearDay" property. 1374 BYWEEKNO If present each element will be an element in the 1375 jscalendar "byWeekNo" property. 1377 BYHOUR If present each element will be an element in the jscalendar 1378 "byHour" property. 1380 BYMINUTE If present each element will be an element in the 1381 jscalendar "byMinute" property. 1383 BYSECOND If present each element will be an element in the 1384 jscalendar "bySecond" property. 1386 BYSETPOS If present each element will be an element in the 1387 jscalendar "bySetPosition" property. 1389 COUNT If present set in the jscalendar "count" property. 1391 UNTIL If present set the jscalendar "until" property with the 1392 appropriately reformatted value. If the is no time part append a 1393 0 time and reformat as a jscalendar local date/time. 1395 Some examples: 1397 ... 1398 RRULE:FREQ=DAILY;COUNT=10 1399 ... 1401 maps to 1403 ... 1404 "recurrenceRules" : [{ 1405 "@type" : "RecurrenceRule", 1406 "frequency": "daily", 1407 "count": 10 1408 }], 1409 ... 1411 ... 1412 RRULE:FREQ=YEARLY;UNTIL=20220512T140000Z; 1413 BYMONTH=1;BYDAY=SU,MO,TU,WE,TH,FR,SA 1414 ... 1416 maps to 1418 ... 1419 "recurrenceRules" : [{ 1420 "@type" : "RecurrenceRule", 1421 "frequency": "yearly", 1422 "byMonth": ["1"], 1423 "byDay": [{ 1424 "day": "su" 1425 }, 1426 } 1427 "day": "mo" 1428 }, 1429 } 1430 "day": "tu" 1431 }, 1432 } 1433 "day": "we" 1434 }, 1435 } 1436 "day": "th" 1437 }, 1438 } 1439 "day": "fr" 1440 }, 1441 } 1442 "day": "sa" 1443 }], 1444 "until": "2022-05-12T10:00:00" 1445 }], 1446 ... 1448 ... 1449 RRULE:FREQ=MONTHLY;COUNT=6;BYDAY=-2MO 1450 ... 1452 maps to 1454 ... 1455 "recurrenceRules" : [{ 1456 "@type" : "RecurrenceRule", 1457 "frequency": "monthly", 1458 "byDay": [{ 1459 "day": "mo", 1460 "nthOfPeriod": -2 1461 }], 1462 "count": 6 1463 }], 1464 ... 1466 5.32. SEQUENCE 1468 Copy the value into the JSCalendar "sequence" property. 1470 5.33. STATUS 1472 For a VEVENT copy the lower-cased value into the JSCalendar "status" 1473 property. 1475 For a VTODO copy the lower-cased value into the JSCalendar "progress" 1476 property. 1478 5.34. STRUCTURED-DATA 1480 This property is mapped on to a JSCalendar "link" object with the 1481 value mapped on to the JSCalendar "href" property in a manner 1482 depending on the "STRUCTURED-DATA" "VALUE" parameter: 1484 VALUE=TEXT Copy the value as a [RFC2397] data uri either as plain 1485 text or by encoding as a base64 value. If plain text the value 1486 may need escaping as per [RFC2397]. 1488 VALUE=BINARY Copy the value as a [RFC2397] data uri speifying base64 1489 encoding. 1491 VALUE=URI Copy the value as-is into the href. 1493 The "STRUCTURED-DATA" "SCHEMA" parameter is mapped on to a JSCalendar 1494 "schema" property within the link object. 1496 The "STRUCTURED-DATA" "FMTTYPE" parameter is mapped on to a 1497 JSCalendar "contentType" property within the link object. 1499 For example: 1501 ... 1502 STRUCTURED-DATA;FMTTYPE=application/ld+json; 1503 SCHEMA="https://schema.org/SportsEvent"; 1504 VALUE=TEXT:{\n 1505 "@context": "http://schema.org"\,\n 1506 "@type": "SportsEvent"\,\n 1507 "homeTeam": "Pittsburgh Pirates"\,\n 1508 "awayTeam": "San Francisco Giants"\n 1509 }\n 1510 ... 1512 maps to (with data truncated) 1514 ... 1515 "links": { 1516 "1": { 1517 "@type" : "Link", 1518 "contentType": "application/ld+json", 1519 "schema": "https://schema.org/SportsEvent", 1520 "href": "data:base64;ewogICAgICAgICJAY29udGV4dCI6IC..." 1521 } 1522 } 1523 ... 1525 5.35. SUMMARY 1527 Copy the value into the JSCalendar "title" property. 1529 Mapping parameters: 1531 ALTREP No mapping. 1533 LANG Use the "locale" property. 1535 5.36. TRANSP 1537 If the value of the TRANSP property (ignoring case) is "opaque" set 1538 the JSCalendar "freeBusyStatus" property to the value "busy". 1540 Otherwise set the JSCalendar "freeBusyStatus" property to the value 1541 "free". 1543 5.37. UID 1545 Copy the value into the JSCalendar "uid" property. 1547 5.38. URL 1549 Maps to a Link object in the JSCalendar object's "links" property, 1550 with the URL property value mapped to the Link "href" property. 1552 6. Translating iCalendar Recurrences 1554 6.1. Translating iCalendar Recurrences: Simple objects with overrides 1556 A simple object with overrides will be converted to a jsCalendar 1557 master event with the rules, recurrence dates and exclusion dates 1558 translated appropriately. 1560 Overrides MUST be mapped on to a jsCalendar patch object and added to 1561 the "recurrenceOverrides" property of the master event with the key 1562 being the value of the iCalendar RECURRENCE-ID translated to a json 1563 format. 1565 Any override property with the same value as the master SHOULD be 1566 ommitted. Remaining properties MAY be added in full. Where 1567 appropriate, differences SHOULD be expressed as a patch. 1569 This can result in a significant reduction in size for objects with 1570 small changes to overrides, for example changing the participation 1571 status of an attendee. 1573 6.2. Translating iCalendar Recurrences: Overrides with no master 1575 When inviting an attendee to a single instance of a recurring event, 1576 only that override should be sent to the attendee. In this case the 1577 override should be a complete jsCalendar object with the type set to 1578 the type of the master. 1580 Additionally, there MUST be a recurrenceId property set to the value 1581 of the recurrence id for that override. If the timezone of the start 1582 of the instance is different from the master value, then there must 1583 also be a "recurrenceIdTimeZone" property set to the start timezone 1584 of the master. 1586 7. Translating iCalendar: Further examples 1588 This section provides more complete examples of translating from 1589 [RFC5545] to JSCalendar. 1591 As usual note that json string values may be split because of line 1592 width limits. This is not legal json. 1594 7.1. Recurring event with ATTACH 1596 This is an example of a recurring event with overrides. The first 1597 override removes an ATTACH property and adds an ATTACH property. The 1598 second override removes all ATTACH properties. 1600 BEGIN:VCALENDAR 1601 CALSCALE:GREGORIAN 1602 PRODID:-//example.org//EN 1603 VERSION:2.0 1604 BEGIN:VEVENT 1605 DTSTAMP:20200522T142047Z 1606 DTSTART;TZID=America/New_York:20200522T120000 1607 DURATION:PT1H 1608 RRULE:FREQ=DAILY;COUNT=8 1609 SUMMARY:recurring daily 8 times 1610 UID:6252D6C40A8308BFE25BBDErecur-1 1611 ATTACH;FMTTYPE=text/plain:http://example.org/doc1.txt 1612 ATTACH;FMTTYPE=text/plain:http://example.org/doc2.txt 1613 ATTACH;FMTTYPE=text/plain:http://example.org/doc3.txt 1614 END:VEVENT 1615 BEGIN:VEVENT 1616 DTSTAMP:20200522T142047Z 1617 DTSTART;TZID=America/New_York:20200523T120000 1618 DURATION:PT1H 1619 RECURRENCE-ID;TZID=America/New_York:20200523T120000 1620 SUMMARY:recurring daily 8 times 1621 UID:6252D6C40A8308BFE25BBDErecur-1 1622 ATTACH;FMTTYPE=text/plain:http://example.org/doc2.txt 1623 ATTACH;FMTTYPE=text/plain:http://example.org/doc3.txt 1624 ATTACH;FMTTYPE=text/plain:http://example.org/doc4.txt 1625 END:VEVENT 1626 BEGIN:VEVENT 1627 DTSTAMP:20200522T142047Z 1628 DTSTART;TZID=America/New_York:20200524T120000 1629 DURATION:PT1H 1630 RECURRENCE-ID;TZID=America/New_York:20200524T120000 1631 SUMMARY:recurring daily 8 times 1632 UID:6252D6C40A8308BFE25BBDErecur-1 1633 END:VEVENT 1634 END:VCALENDAR 1636 maps to 1638 { 1639 "prodId": "//example.org//EN", 1640 "entries": [ 1641 { 1642 "links": { 1643 "1": { 1644 "@type": "Link", 1645 "rel": "enclosure", 1646 "contentType": "text/plain", 1647 "href": "http://example.org/doc1.txt" 1648 }, 1649 "2": { 1650 "@type": "Link", 1651 "rel": "enclosure", 1652 "contentType": "text/plain", 1653 "href": "http://example.org/doc2.txt" 1654 }, 1655 "3": { 1656 "@type": "Link", 1657 "rel": "enclosure", 1658 "contentType": "text/plain", 1659 "href": "http://example.org/doc3.txt" 1660 } 1661 }, 1662 "created ": "2020-05-23T17:04:50Z", 1663 "start": "2020-05-22T12:00:00", 1664 "timeZone": "America/New_York", 1665 "duration": "PT1H", 1666 "title": "recurring daily 8 times", 1667 "uid": "6252D6C40A8308BFE25BBDErecur-1", 1668 "recurrenceRules": [ 1669 { 1670 "@type": "RecurrenceRule", 1671 "frequency": "daily", 1672 "count": 8 1673 } 1674 ], 1675 "recurrenceOverrides": { 1676 "2020-05-23T12:00:00": { 1677 "recurrenceId": "2020-05-23T12:00:00", 1678 "links/d4a618d4-929c-4c81-ae5b-322afe407a00": null, 1679 "links/fb75b76a-a159-4a86-bd3d-7ace6b39c6c3": { 1680 "@type": "Link", 1681 "rel": "enclosure", 1682 "contentType": "text/plain", 1683 "href": "http://example.org/doc4.txt" 1684 } 1685 }, 1686 "2020-05-24T12:00:00": { 1687 "recurrenceId": "2020-05-24T12:00:00", 1688 "links/d4a618d4-929c-4c81-ae5b-322afe407a00": null, 1689 "links/6c54e72e-3413-487c-ae14-fb318a90db43": null, 1690 "links/44087e9a-132c-4a5d-b25d-4ce580edb004": null 1691 } 1692 } 1693 } 1694 ] 1695 } 1697 7.2. Simple event with CONTACT 1699 This example shows the conversion of a simple event with a single 1700 CONTACT property in JSCalendar. 1702 BEGIN:VCALENDAR 1703 CALSCALE:GREGORIAN 1704 PRODID:-//Example//EN 1705 VERSION:2.0 1706 BEGIN:VEVENT 1707 DTSTAMP:20200522T142047Z 1708 DTSTART;TZID=America/New_York:20200622T120000 1709 DURATION:PT1H 1710 SUMMARY:event with contact 1711 UID:6252D6C40A8308BFE25BBEFcontact-1 1712 CONTACT;ALTREP="ldap://example.com:6666/o=ABC%20Industries\, 1713 c=US???(cn=Jim%20Dolittle)":Jim Dolittle\, ABC Industries\, 1714 +1-919-555-1234 1715 END:VEVENT 1716 END:VCALENDAR 1718 translates to 1720 { 1721 "@type": "jsgroup", 1722 "prodId": "//Example.org//Example V3.13.2//EN", 1723 "entries": [ 1724 { 1725 "@type": "jsevent", 1726 "participants": { 1727 "40288108-733187c1-0173-3188007b-00000001": { 1728 "@type": "Participant", 1729 "roles": { 1730 "contact": true 1731 }, 1732 "description": "Jim Dolittle, ABC Industries,\ 1733 +1-919-555-1234", 1734 "links": { 1735 "1": { 1736 "@type": "Link", 1737 "href": "ldap://example.com:6666/o=ABC%20Industries,\ 1738 c=US???(cn=Jim%20Dolittle)", 1739 "rel": "alternate" 1740 } 1741 } 1742 } 1743 }, 1744 "created ": "2020-07-09T03:04:23Z", 1745 "start": "2020-06-22T12:00:00", 1746 "timeZone": "America/New_York", 1747 "duration": "PT1H", 1748 "title": "event with contact", 1749 "uid": "6252D6C40A8308BFE25BBEFcontact-1" 1750 } 1751 ] 1752 } 1754 7.3. Simple event with RESOURCES 1756 TBD 1758 7.4. Recurring event. Attendees only in overrides 1760 In this more complex example there is no ORGANIZER or ATTENDEEs in 1761 the master event. There are overrides which invite one or more 1762 attendees. 1764 For one overrride the ORGANIZER is also an ATTENDEE. In the other 1765 that is not the case. This is reflected in the "roles" property for 1766 the organizer. 1768 Note that each override has its own "participants" property and the 1769 first has a links property to handle the DIR parameter on one 1770 attendee. 1772 BEGIN:VCALENDAR 1773 PRODID://Example.org//Example V3.13.2//EN 1774 VERSION:2.0 1775 BEGIN:VEVENT 1776 CREATED:20200704T035515Z 1777 DURATION:PT1H 1778 DTSTAMP:20200704T035706Z 1779 DTSTART;TZID=America/New_York:20200522T120000 1780 LAST-MODIFIED:20200704T035706Z 1781 SUMMARY:recurring daily 8 times 1782 UID:6252D6C40A8308BFE25BBEFrecur1-1 1783 RRULE:FREQ=DAILY;COUNT=8 1784 END:VEVENT 1785 BEGIN:VEVENT 1786 RECURRENCE-ID;TZID=America/New_York:20200523T120000 1787 ATTENDEE:mailto:douglm@example.org 1788 ATTENDEE;RSVP=TRUE;SCHEDULE-STATUS=1.2;DIR="http://example.org/ 1789 vcards/vbede.vcf":mailto:vbede@example.org 1790 CREATED:20200704T035515Z 1791 DURATION:PT1H 1792 DTSTAMP:20200704T035706Z 1793 DTSTART;TZID=America/New_York:20200523T120000 1794 LAST-MODIFIED:20200704T035706Z 1795 ORGANIZER:mailto:douglm@example.org 1796 SUMMARY:recurring daily 8 times 1797 UID:6252D6C40A8308BFE25BBEFrecur1-1 1798 END:VEVENT 1799 BEGIN:VEVENT 1800 RECURRENCE-ID;TZID=America/New_York:20200524T120000 1801 ATTENDEE;RSVP=TRUE;SCHEDULE-STATUS=1.2:mailto:user01@example.org 1802 ATTENDEE;RSVP=TRUE;SCHEDULE-STATUS=1.2:mailto:vbede@example.org 1803 CREATED:20200704T035515Z 1804 DURATION:PT1H 1805 DTSTAMP:20200704T035706Z 1806 DTSTART;TZID=America/New_York:20200524T120000 1807 LAST-MODIFIED:20200704T035706Z 1808 ORGANIZER:mailto:douglm@example.org 1809 SUMMARY:recurring daily 8 times 1810 UID:6252D6C40A8308BFE25BBEFrecur1-1 1811 END:VEVENT 1812 END:VCALENDAR 1814 translates to 1816 { 1817 "@type": "jsgroup", 1818 "prodId": "//Example.org//Example V3.13.2//EN", 1819 "entries": [ 1820 { 1821 "@type": "jsevent", 1822 "created ": "2020-07-04T03:57:06Z", 1823 "start": "2020-05-22T12:00:00", 1824 "timeZone": "America/New_York", 1825 "duration": "PT1H", 1826 "title": "recurring daily 8 times", 1827 "uid": "6252D6C40A8308BFE25BBEFrecur1-1", 1828 "recurrenceRules": [ 1829 { 1830 "@type": "RecurrenceRule", 1831 "frequency": "daily", 1832 "count": 8 1833 } 1834 ], 1835 "recurrenceOverrides": { 1836 "2020-05-23T12:00:00": { 1837 "participants": { 1838 "be450b70-9bf7-4f6e-8f65-971ede566ce3": { 1839 "@type": "Participant", 1840 "sendTo": { 1841 "imip": "mailto:douglm@example.org" 1842 }, 1843 "roles": { 1844 "attendee": true, 1845 "owner": true 1846 } 1847 }, 1848 "a539dfe3-4463-4f28-b9de-17d3a0e99faf": { 1849 "@type": "Participant", 1850 "sendTo": { 1851 "imip": "mailto:vbede@example.org" 1852 }, 1853 "expectReply": true, 1854 "links": { 1855 "1": { 1856 "@type": "Link", 1857 "href": "http://example.org/vcards/vbede.vcf", 1858 "rel": "alternate" 1859 } 1860 }, 1861 "roles": { 1862 "attendee": true 1863 }, 1864 "scheduleStatus": "1.2" 1865 } 1866 }, 1867 "replyTo": { 1868 "imip": "mailto:douglm@example.org" 1869 } 1870 }, 1871 "2020-05-24T12:00:00": { 1872 "participants": { 1873 "daeae4cf-6f6a-4ce3-9f4d-6bd884650d3d": { 1874 "@type": "Participant", 1875 "sendTo": { 1876 "imip": "mailto:user01@example.org" 1877 }, 1878 "expectReply": true, 1879 "roles": { 1880 "attendee": true 1881 }, 1882 "scheduleStatus": "1.2" 1883 }, 1884 "a6de6de3-271f-4679-9241-1b3bca6b602d": { 1885 "@type": "Participant", 1886 "sendTo": { 1887 "imip": "mailto:vbede@example.org" 1888 }, 1889 "expectReply": true, 1890 "roles": { 1891 "attendee": true 1892 }, 1893 "scheduleStatus": "1.2" 1894 }, 1895 "aaa8483b-b18b-4dbd-b218-77d8db027d35": { 1896 "@type": "Participant", 1897 "sendTo": { 1898 "imip": "mailto:douglm@example.org" 1899 }, 1900 "roles": { 1901 "owner": true 1902 } 1903 } 1904 }, 1905 "replyTo": { 1906 "imip": "mailto:douglm@example.org" 1907 } 1908 } 1909 } 1910 } 1911 ] 1912 } 1914 8. Security Considerations 1916 The same security considerations as for 1917 [draft-ietf-calext-jscalendar] apply. 1919 9. IANA Considerations 1921 None. 1923 10. Acknowledgments 1925 The authors would like to thank the members of CalConnect for their 1926 valuable contributions. This specification originated from the work 1927 of the API technical committee of CalConnect, the Calendaring and 1928 Scheduling Consortium. 1930 11. References 1932 11.1. Normative References 1934 [draft-ietf-calext-eventpub-extensions] 1935 "Event Publishing Extensions to iCalendar", 1936 . 1939 [draft-ietf-calext-ical-relations] 1940 "Support for iCalendar Relationships", 1941 . 1944 [draft-ietf-calext-valarm-extensions] 1945 "VALARM Extensions for iCalendar", 1946 . 1949 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1950 Requirement Levels", BCP 14, RFC 2119, 1951 DOI 10.17487/RFC2119, March 1997, 1952 . 1954 [RFC2397] Masinter, L., "The "data" URL scheme", RFC 2397, 1955 DOI 10.17487/RFC2397, August 1998, 1956 . 1958 [RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and 1959 Scheduling Core Object Specification (iCalendar)", 1960 RFC 5545, DOI 10.17487/RFC5545, September 2009, 1961 . 1963 [RFC5546] Daboo, C., Ed., "iCalendar Transport-Independent 1964 Interoperability Protocol (iTIP)", RFC 5546, 1965 DOI 10.17487/RFC5546, December 2009, 1966 . 1968 [RFC6638] Daboo, C. and B. Desruisseaux, "Scheduling Extensions to 1969 CalDAV", RFC 6638, DOI 10.17487/RFC6638, June 2012, 1970 . 1972 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1973 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 1974 2014, . 1976 [RFC7265] Kewisch, P., Daboo, C., and M. Douglass, "jCal: The JSON 1977 Format for iCalendar", RFC 7265, DOI 10.17487/RFC7265, May 1978 2014, . 1980 [RFC7986] Daboo, C., "New Properties for iCalendar", RFC 7986, 1981 DOI 10.17487/RFC7986, October 2016, 1982 . 1984 11.2. Informative References 1986 [draft-apthorp-ical-tasks] 1987 "Task Extensions to iCalendar", 1988 . 1990 [draft-ietf-calext-jscalendar] 1991 "Task Extensions to iCalendar", 1992 . 1995 Appendix A. Outdated document sections 1997 A.1. Translating JSCalendar properties to iCalendar components 1999 This section is an alphabetic list of all JSCalendar property types 2000 that map on to components. 2002 A.1.1. jsevent 2004 A JSCalendar object with a type of "jsevent" is mapped on to a 2005 [RFC5545] VEVENT component. 2007 If it is a single VEVENT then a [RFC5545] VCALENDAR component must 2008 surround it and the JSCalendar "prodid" property will be converted to 2009 a [RFC5545] PRODID. 2011 { 2012 "@type": "jsevent", 2013 "prodid": "-//ABC Corporation//NONSGML My Product//EN", 2014 ... 2015 } 2017 maps to 2019 BEGIN: VCALENDAR 2020 PRODID:-//ABC Corporation//NONSGML My Product//EN 2021 BEGIN:VEVENT 2022 ... 2023 END:VEVENT 2024 END: VCALENDAR 2026 When converting multiple JSEvent or JSTask objects the surrounding 2027 [RFC5545] VCALENDAR object must have a [RFC5545] PRODID set from 2028 either the JSGroup "prodid" or generated. 2030 A.1.2. jsgroup 2032 A JSCalendar object with a type of "jsgroup" is mapped on to a 2033 [RFC5545] VCALENDAR component. 2035 { 2036 "@type": "jsgroup", 2037 "prodid": "-//ABC Corporation//NONSGML My Product//EN", 2038 ... 2039 { 2040 "@type": "jsevent", 2041 ... 2042 } 2043 { 2044 "@type": "jsevent", 2045 ... 2046 } 2047 } 2049 maps to 2051 BEGIN: VCALENDAR 2052 PRODID:-//ABC Corporation//NONSGML My Product//EN 2053 BEGIN:VEVENT 2054 ... 2055 END:VEVENT 2056 BEGIN:VEVENT 2057 ... 2058 END:VEVENT 2059 END: VCALENDAR 2061 A.1.3. jstask 2063 A JSCalendar object with a type of "jstask" is mapped on to a 2064 [RFC5545] VTODO component. 2066 If it is a single VTODO then a [RFC5545] VCALENDAR component must 2067 surround it and the JSCalendar "prodid" property will be converted to 2068 a [RFC5545] PRODID. 2070 { 2071 "@type": "jstask", 2072 "prodid": "-//ABC Corporation//NONSGML My Product//EN", 2073 ... 2074 } 2076 maps to 2078 BEGIN: VCALENDAR 2079 PRODID:-//ABC Corporation//NONSGML My Product//EN 2080 BEGIN:VTODO 2081 ... 2082 END:VTODO 2083 END: VCALENDAR 2085 When converting multiple JSEvent or JSTask objects the surrounding 2086 [RFC5545] VCALENDAR object must have a [RFC5545] PRODID set from 2087 either the JSGroup "prodid" or generated. 2089 A.1.4. timezones 2091 The JSCalendar TimeZone objects within a "timezones" property are 2092 mapped on to [RFC5545] VTIMEZONE components within the surrounding 2093 VCALENDAR component. Each mapped TimeZone MUST only appear once. 2095 { 2096 "@type": "jsevent", 2097 ... 2098 "timezones": { 2099 "/Example/Somewhere: { 2100 "@type": "TimeZone", 2101 ... 2102 }, 2103 "/Example/Somewhere-else": { 2104 "@type": "TimeZone", 2105 ... 2106 } 2107 } 2108 } 2110 maps to 2112 BEGIN: VTIMEZONE 2113 TZID: /Example/Somewhere 2114 ... 2115 END: VTIMEZONE 2116 BEGIN: VTIMEZONE 2117 TZID: /Example/Somewhere-else 2118 ... 2119 END: VTIMEZONE 2120 BEGIN: VEVENT 2121 ... 2122 END: VEVENT 2124 When converting multiple JSEvent or JSTask objects the surrounding 2125 [RFC5545] VCALENDAR object must have a [RFC5545] PRODID set from 2126 either the JSGroup "prodid" or generated. 2128 A.1.5. locations 2130 JSCalendar locations should be mapped on to 2131 [draft-ietf-calext-eventpub-extensions]VLOCATION components. 2132 Additionally, for backwards compatibility, a location should be 2133 mapped on to a [RFC5545] LOCATION property. This property should be 2134 mapped from the only location or the one related to the start. 2136 A.1.6. participants 2138 JSCalendar participants will be mapped on to different iCalendar 2139 properties and components depending on their jsCalendar role values. 2141 A participant with a role containing "contact" MUST be mapped on to 2142 an iCalendar CONTACT property and SHOULD also be mapped on to a 2144 [draft-ietf-calext-eventpub-extensions]PARTICIPANT component which 2145 provides a better mapping. 2147 A participant with a role containing "owner" MUST be mapped on to an 2148 iCalendar ORGANIZER property and SHOULD also be mapped on to a 2149 [draft-ietf-calext-eventpub-extensions]PARTICIPANT component which 2150 provides a better mapping. 2152 A participant with a role containing any of "attendee", "optional" or 2153 "informational" MUST be mapped on to an iCalendar ATTENDEE property 2154 and SHOULD also be mapped on to a 2155 [draft-ietf-calext-eventpub-extensions]PARTICIPANT component which 2156 provides a better mapping. 2158 A more complete mapping may be achieved by creating a 2159 [draft-ietf-calext-eventpub-extensions]PARTICIPANT component. 2161 For all properties the participants jsCalendar "language" property, 2162 if present, is mapped on to the iCalendar "LANG" property parameter. 2164 For all properties if the participant contains a jsCalendar "link" 2165 with a "rel" of "alternate" then the value of the link is used for 2166 the iCalendar "ALTREP" property parameter. 2168 Where do we get the cua? 2170 A.2. Note 2172 The sections following this one are all the original ones from draft 2173 1 writen by Robert/Neil - there for reference. 2175 A.3. JSEvent 2177 A JSEvent maps to the the iCalendar VEVENT component type [RFC5545]. 2178 The following tables maps the JSEvent-specific properties to 2179 iCalendar: 2181 +----------+--------------------------------------------------------+ 2182 | Property | iCalendar counterpart | 2183 +----------+--------------------------------------------------------+ 2184 | duration | DURATION property. If the VEVENT contains a DTEND | 2185 | | property, the this maps to the duration property as | 2186 | | the time span between DTSTART and DTEND when | 2187 | | converting the respective time points to the UTC time | 2188 | | zone. Fractional seconds SHOULD be preserved with the | 2189 | | SUBSECOND parameter. | 2190 +----------+--------------------------------------------------------+ 2192 Table 1: Mapping JSEvent properties 2194 A.4. JSTask 2196 A JSTask object maps to the iCalendar VTODO component type [RFC5545]. 2197 The following tables maps the JSTask-specific properties to 2198 iCalendar: 2200 +-------------------+-----------------------------------------------+ 2201 | Property | iCalendar counterpart | 2202 +-------------------+-----------------------------------------------+ 2203 | due | Maps to the DUE property. See Appendix A.6.1. | 2204 | | | 2205 | estimatedDuration | ESTIMATED-DURATION property in the RFC draft | 2206 | | [draft-apthorp-ical-tasks], or the DURATION | 2207 | | property otherwise. Fractional seconds | 2208 | | SHOULD be preserved with the SUBSECOND | 2209 | | parameter. | 2210 | | | 2211 | statusUpdatedAt | COMPLETED property. The JSTask status | 2212 | | property MUST have value "completed". | 2213 | | Fractional seconds SHOULD be preserved with | 2214 | | the SUBSECOND parameter. | 2215 | | | 2216 | progress | PARTSTAT and COMPLETED properties, including | 2217 | | the definitions in the RFC draft | 2218 | | [draft-apthorp-ical-tasks]. | 2219 | | | 2220 | status | STATUS property, including the definitions in | 2221 | | the RFC draft [draft-apthorp-ical-tasks]. | 2222 +-------------------+-----------------------------------------------+ 2224 Table 2: Mapping JSTask properties 2226 A.5. JSGroup 2228 A JSGroup maps to a iCalendar VCALENDAR containing VEVENT or VTODO 2229 components. 2231 +----------+--------------------------------------------------------+ 2232 | Property | iCalendar counterpart | 2233 +----------+--------------------------------------------------------+ 2234 | entries | VEVENT and VTODO components embedded in a VCALENDAR | 2235 | | component. | 2236 | | | 2237 | source | SOURCE property. | 2238 +----------+--------------------------------------------------------+ 2240 Table 3: Mapping JSGroup properties 2242 A.6. Common properties 2244 This section contains recommendations how to map JSCalendar from and 2245 to iCalendar. It lists all common JSCalendar object properties in 2246 alphabetical order. 2248 +------------------------+------------------------------------------+ 2249 | Property | iCalendar counterpart | 2250 +------------------------+------------------------------------------+ 2251 | @type | Determined by the iCalendar component | 2252 | | type: "jsevent" for VEVENT, "jstask" for | 2253 | | VTODO, "jsgroup" for VCALENDAR. | 2254 | | | 2255 | alerts | Each entry maps to a VALARM component. | 2256 | | The action property maps to iCalendar | 2257 | | ACTION, where both iCalendar "DISPLAY" | 2258 | | and "AUDIO" values map to the "display" | 2259 | | action. An EMAIL value maps to a | 2260 | | JSCalendar "email" action. _relativeTo_ | 2261 | | and _offset_ map to the TRIGGER | 2262 | | property. | 2263 | | | 2264 | categories | CONCEPT property, defined in | 2265 | | [draft-ietf-calext-ical-relations]. | 2266 | | | 2267 | color | COLOR property, as specified in | 2268 | | [RFC7986]. | 2269 | | | 2270 | created | CREATED property. Fractional seconds | 2271 | | SHOULD be preserved with the SUBSECOND | 2272 | | parameter. | 2273 | | | 2274 | description | DESCRIPTION property. | 2275 | | | 2276 | descriptionContentType | Implementation-specific. | 2277 | | | 2278 | excluded | EXDATE property. Fractional seconds | 2279 | | SHOULD be preserved with the SUBSECOND | 2280 | | parameter. | 2281 | | | 2282 | freeBusyStatus | TRANSP property. | 2283 | | | 2284 | invitedBy | Implementation-specific. | 2285 | | | 2286 | keywords | CATEGORIES property, as specified in | 2287 | | [RFC7986]. | 2288 | | | 2289 | links | ATTACH ([RFC5545]), URL or IMAGE | 2290 | | ([RFC7986]) properties with URI value | 2291 | | types map to the the Link _href_. The | 2292 | | FMTTYPE parameter maps to _type_, the | 2293 | | SIZE parameter to _size_. Mapping other | 2294 | | properties is implementation-specific. | 2295 | | | 2296 | locale | LANGUAGE parameter of the SUMMARY or | 2297 | | DESCRIPTION property. | 2298 | | | 2299 | localizations | Implementation-specific. | 2300 | | | 2301 | locations | See Appendix A.6.2. | 2302 | | | 2303 | method | METHOD property of the embedding | 2304 | | VCALENDAR. | 2305 | | | 2306 | participants | See Appendix A.6.3. | 2307 | | | 2308 | priority | PRIORITY property. | 2309 | | | 2310 | privacy | CLASS property. | 2311 | | | 2312 | prodId | PRODID property. | 2313 | | | 2314 | recurrenceOverrides | RDATE and EXDATE properties, and any | 2315 | | VEVENT or VTODO instances with a | 2316 | | recurrence-id and same UID as the mapped | 2317 | | main object. If the DTSTART property | 2318 | | defines a SUBSECOND parameter, but the | 2319 | | RECURRENCE-ID of a recurrence instance | 2320 | | does not, then use the SUBSECOND | 2321 | | parameter value of DTSTART to determine | 2322 | | the recurrence override time stamp. | 2323 | | | 2324 | recurrenceRule | RRULE property. For all-day calendar | 2325 | | objects, map the _until_ property value | 2326 | | to an iCalendar DATE (effectively | 2327 | | removing the time component). To convert | 2328 | | a DATE-typed UNTIL from iCalendar, set | 2329 | | the time components of the LocalDateTime | 2330 | | value to "23:59:59". If the iCalendar | 2331 | | UNTIL value is a UTC date time, convert | 2332 | | it to the local time in the JSCalendar | 2333 | | calendar object time zone. To convert to | 2334 | | iCalendar where the DTSTART or DUE | 2335 | | property is of type DATE, omit the time | 2336 | | component of the LocalDateTime value. | 2337 | | | 2338 | relatedTo | RELATED-TO property. | 2339 | | | 2340 | replyTo | An iCalendar ORGANIZER with a mailto: | 2341 | | URI mapped to the "imip" method, or any | 2342 | | other URI mapped to the "other" method. | 2343 | | Mapping multiple methods is | 2344 | | implementation-specific. | 2345 | | | 2346 | sequence | SEQUENCE property. | 2347 | | | 2348 | showWithoutTime | Implementation-specific. | 2349 | | | 2350 | start | Maps to the DTSTART property. See | 2351 | | Appendix A.6.1. | 2352 | | | 2353 | status | STATUS property. | 2354 | | | 2355 | timeZone | Maps to the TZID parameter. See | 2356 | | Appendix A.6.1. | 2357 | | | 2358 | timeZones | Each entry in the property maps to a | 2359 | | VTIMEZONE in the embedding VCALENDAR | 2360 | | component. | 2361 | | | 2362 | title | SUMMARY property. | 2363 | | | 2364 | uid | UID property. | 2365 | | | 2366 | updated | DTSTAMP and LAST-MODIFIED properties. | 2367 | | Fractional seconds SHOULD be preserved | 2368 | | with the SUBSECOND parameter. | 2369 | | | 2370 | useDefaultAlerts | Implementation-specific. | 2371 | | | 2372 | virtualLocations | See Appendix A.6.2. | 2373 +------------------------+------------------------------------------+ 2375 Table 4: Translation between JSCalendar and iCalendar 2377 A.6.1. Time properties and types 2379 iCalendar defines two different time types, DATE and DATE-TIME, where 2380 the latter may occur in three forms (with local time, with UTC time, 2381 with local time and time zone reference). In contrast, JSCalendar 2382 does not define a distinct type for dates, and date times are defined 2383 with the LocalDateTime type only. 2385 A JSCalendar time maps to the iCalendar DATE type if all of the 2386 following criteria apply: 2388 o The "start" ("due") property value has zero time, or is not set. 2390 o The "duration" ("estimatedDuration") property value has zero time, 2391 or is a multiple of days or weeks, or is not set. 2393 o The "timeZone" property value is null, or is not set. 2395 For all other cases, the time maps to an iCalendar DATE-TIME: 2397 o With local time and time zone reference, if the "timeZone" 2398 property value is set and does not equal "Etc/UTC". 2400 o With UTC time, if the "timeZone" property value equals "Etc/UTC". 2402 o With local time, if the "timeZone" property value is null or not 2403 set. 2405 Fractional seconds SHOULD be preserved with the SUBSECOND parameter. 2407 A.6.2. Locations 2409 The iCalendar counterpart for JSCalendar Location objects is the 2410 iCalendar [RFC5545] LOCATION property, or implementation-specific. 2412 +-------------+----------------------------------+ 2413 | Property | iCalendar counterpart | 2414 +-------------+----------------------------------+ 2415 | coordinates | GEO property. | 2416 | | | 2417 | description | Implementation-specific. | 2418 | | | 2419 | name | LOCATION property value. | 2420 | | | 2421 | rel | Implementation-specific. | 2422 | | | 2423 | timeZone | Implementation-specific. | 2424 | | | 2425 | uri | The LOCATION ALTREP parameter. | 2426 +-------------+----------------------------------+ 2428 Table 5: Mapping Location properties 2430 The iCalendar counterpart for JSCalendar VirtualLocation objects is 2431 the iCalendar [RFC7986] CONFERENCE property. 2433 +-------------+------------------------------+ 2434 | Property | iCalendar counterpart | 2435 +-------------+------------------------------+ 2436 | description | Implementation-specific. | 2437 | | | 2438 | name | LABEL parameter. | 2439 | | | 2440 | uri | CONFERENCE property value. | 2441 +-------------+------------------------------+ 2443 Table 6: Mapping virtualLocation properties 2445 A.6.3. Participants 2447 The following table outlines translation of JSCalendar participants. 2448 An iCalendar ORGANIZER maps to both the replyTo property and a 2449 participant with role "owner". If an ATTENDEE with the same CAL- 2450 ADDRESS value exists, then it maps to the same participant as the 2451 ORGANIZER participant. Other participants map to ATTENDEEs. 2453 +---------------------+---------------------------------------------+ 2454 | Property | iCalendar counterpart | 2455 +---------------------+---------------------------------------------+ 2456 | attendance | ROLE parameter values REQ-PARTICIPANT, OPT- | 2457 | | PARTICIPANT and NON-PARTICIPANT. | 2458 | | | 2459 | delegatedFrom | DELEGATED-FROM parameter | 2460 | | | 2461 | delegatedTo | DELEGATED-TO parameter | 2462 | | | 2463 | email | EMAIL parameter, if defined. Otherwise the | 2464 | | CAL-ADDRESS property value, if it is a | 2465 | | mailto: URI. | 2466 | | | 2467 | expectReply | RSVP parameter | 2468 | | | 2469 | kind | CUTYPE parameter | 2470 | | | 2471 | locationId | Implementation-specific. | 2472 | | | 2473 | memberOf | MEMBER parameter | 2474 | | | 2475 | name | CN parameter | 2476 | | | 2477 | participationStatus | PARTSTAT parameter | 2478 | | | 2479 | roles | ROLE parameter. | 2480 | | | 2481 | scheduleSequence | SEQUENCE property of the participant's | 2482 | | latest iMIP message | 2483 | | | 2484 | scheduleUpdated | DTSTAMP property of the participant's | 2485 | | latest iMIP message | 2486 | | | 2487 | sendTo | A CAL-ADDRESS with a mailto: URI maps to | 2488 | | the JSCalendar "imip" method, any other URI | 2489 | | to the "other" method. Mapping multiple | 2490 | | methods is implementation-specific. | 2491 +---------------------+---------------------------------------------+ 2493 Table 7: Mapping Participant properties 2495 A.7. Custom properties 2497 Mapping custom or unknown properties between JSCalendar and iCalendar 2498 is implementation-specific. Implementations might use vendor- 2499 extension properties, which could also serve as basis for discussion 2500 for a JSCalendar standard extension. Alternatively, an 2501 implementation could preserve iCalendar properties and components in 2502 JSCalendar by use of a vendor-extension property formatted as jCal 2503 [RFC7265] data. 2505 Authors' Addresses 2507 Neil Jenkins 2508 FastMail 2509 PO Box 234 2510 Collins St West 2511 Melbourne VIC 8007 2512 Australia 2514 Email: neilj@fastmailteam.com 2515 URI: https://www.fastmail.com 2517 Robert Stepanek 2518 FastMail 2519 PO Box 234 2520 Collins St West 2521 Melbourne VIC 8007 2522 Australia 2524 Email: rsto@fastmailteam.com 2525 URI: https://www.fastmail.com 2527 Michael Douglass 2528 Bedework Commercial Services 2529 226 3rd Street 2530 Troy, NY 12180 2531 United States of America 2533 Email: mdouglass@bedework.com 2534 URI: http://bedework.com