idnits 2.17.1 draft-ietf-calext-jscalendar-icalendar-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (May 2, 2019) is 1820 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- No issues found here. Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 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: Informational FastMail 5 Expires: November 3, 2019 May 2, 2019 7 JSCalendar: Converting from and to iCalendar 8 draft-ietf-calext-jscalendar-icalendar-00 10 Abstract 12 This document provides an informational guideline for converting 13 JSCalendar from and to iCalendar. 15 Status of This Memo 17 This Internet-Draft is submitted in full conformance with the 18 provisions of BCP 78 and BCP 79. 20 Internet-Drafts are working documents of the Internet Engineering 21 Task Force (IETF). Note that other groups may also distribute 22 working documents as Internet-Drafts. The list of current Internet- 23 Drafts is at https://datatracker.ietf.org/drafts/current/. 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet-Drafts as reference 28 material or to cite them other than as "work in progress." 30 This Internet-Draft will expire on November 3, 2019. 32 Copyright Notice 34 Copyright (c) 2019 IETF Trust and the persons identified as the 35 document authors. All rights reserved. 37 This document is subject to BCP 78 and the IETF Trust's Legal 38 Provisions Relating to IETF Documents 39 (https://trustee.ietf.org/license-info) in effect on the date of 40 publication of this document. Please review these documents 41 carefully, as they describe your rights and restrictions with respect 42 to this document. Code Components extracted from this document must 43 include Simplified BSD License text as described in Section 4.e of 44 the Trust Legal Provisions and are provided without warranty as 45 described in the Simplified BSD License. 47 Table of Contents 49 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 50 1.1. Motivation . . . . . . . . . . . . . . . . . . . . . . . 2 51 1.2. Scope and caveats . . . . . . . . . . . . . . . . . . . . 3 52 1.3. Notational Conventions . . . . . . . . . . . . . . . . . 3 53 2. JSEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 54 3. JSTask . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 55 4. JSGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 56 5. Common properties . . . . . . . . . . . . . . . . . . . . . . 5 57 5.1. Time . . . . . . . . . . . . . . . . . . . . . . . . . . 7 58 5.2. Locations . . . . . . . . . . . . . . . . . . . . . . . . 8 59 5.3. Participants . . . . . . . . . . . . . . . . . . . . . . 9 60 6. Custom properties . . . . . . . . . . . . . . . . . . . . . . 11 61 7. Security Considerations . . . . . . . . . . . . . . . . . . . 11 62 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 63 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 11 64 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 65 10.1. Normative References . . . . . . . . . . . . . . . . . . 11 66 10.2. Informative References . . . . . . . . . . . . . . . . . 12 67 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 12 69 1. Introduction 71 1.1. Motivation 73 The JSCalendar [draft-ietf-calext-jscalendar] data format is used to 74 represent calendar data, and is meant as an alternative to the widely 75 deployed iCalendar [RFC5545] data format. 77 While new calendaring services and applications might use JSCalendar 78 as their main data format to exchange calendaring data, they are 79 likely to interoperate with services and clients that just support 80 iCalendar. Similarly, existing calendaring data is stored in 81 iCalendar format in databases and other calendar stores, and 82 providers and users might want to represent this data also in 83 JSCalendar. Lastly, some implementations might want to preserve 84 custom iCalendar properties, that have no equivalent in JSCalendar 85 when converting between these formats. 87 To facilitate these use cases, this document provides an 88 informational guide how to convert JSCalendar data from and to 89 iCalendar. 91 1.2. Scope and caveats 93 JSCalendar and iCalendar have a lot of semantics in common, but they 94 are not interchangeable formats: 96 o JSCalendar contains a richer data model to express calendar 97 information such as event locations and participants; while future 98 iCalendar extensions may allow a direct mapping, for now there may 99 be no representation directly in iCalendar of some properties and 100 these have been marked as implementation specific for mapping. 102 o iCalendar may contain arbitrary, non-standardised data with custom 103 properties/attributes. Translating these into JSCalendar is 104 implementation specific. 106 o iCalendar has some obsolete features that have been removed from 107 JSCalendar due to not being useful and/or supported in the real 108 world (e.g. custom email alerts to send to random people). 109 Translating these may lose some of the original fidelity. 111 o Implementations may use a custom property to store data that could 112 not be mapped directly in either direction in the original or a 113 custom format, however this is not interoperable. 115 Accordingly, this document does not standardize a canonical 116 translation between iCalendar and JSCalendar, and implementations 117 MUST NOT make any assumptions how iCalendar data is represented in 118 JSCalendar by other systems. 120 1.3. Notational Conventions 122 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 123 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 124 document are to be interpreted as described in [RFC2119]. 126 2. JSEvent 128 A _JSEvent_ maps to the the iCalendar VEVENT component type 129 [RFC5545]. The following tables maps the JSEvent-specific properties 130 to iCalendar: 132 +----------+--------------------------------------------------------+ 133 | Property | iCalendar counterpart | 134 +----------+--------------------------------------------------------+ 135 | duration | DURATION property. If the VEVENT contains a DTEND | 136 | | property, the this maps to the _duration_ property as | 137 | | the time span between DTSTART and DTEND when | 138 | | converting the respective time points to the UTC time | 139 | | zone. | 140 +----------+--------------------------------------------------------+ 142 Table 1: Mapping JSEvent properties 144 3. JSTask 146 A _JSTask_ object maps to the iCalendar VTODO component type 147 [RFC5545]. The following tables maps the JSTask-specific properties 148 to iCalendar: 150 +-------------------+-----------------------------------------------+ 151 | Property | iCalendar counterpart | 152 +-------------------+-----------------------------------------------+ 153 | due | DUE property | 154 | | | 155 | estimatedDuration | ESTIMATED-DURATION property in the RFC draft | 156 | | [draft-apthorp-ical-tasks], or the DURATION | 157 | | property otherwise. | 158 | | | 159 | statusUpdatedAt | COMPLETED property. The JSTask status | 160 | | property MUST have value "completed". | 161 | | | 162 | progress | PARTSTAT and COMPLETED properties, including | 163 | | the definitions in the RFC draft | 164 | | [draft-apthorp-ical-tasks]. | 165 | | | 166 | status | STATUS property, including the definitions in | 167 | | the RFC draft [draft-apthorp-ical-tasks]. | 168 +-------------------+-----------------------------------------------+ 170 Table 2: Mapping JSTask properties 172 4. JSGroup 174 A JSGroup maps to a iCalendar VCALENDAR containing VEVENT or VTODO 175 components. 177 +----------+--------------------------------------------------------+ 178 | Property | iCalendar counterpart | 179 +----------+--------------------------------------------------------+ 180 | entries | VEVENT and VTODO components embedded in a VCALENDAR | 181 | | component. | 182 | | | 183 | source | SOURCE property. | 184 +----------+--------------------------------------------------------+ 186 Table 3: Mapping JSGroup properties 188 5. Common properties 190 This section contains recommendations how to map JSCalendar from and 191 to iCalendar. It lists all common JSCalendar object properties in 192 alphabetical order. 194 +------------------------+------------------------------------------+ 195 | Property | iCalendar counterpart | 196 +------------------------+------------------------------------------+ 197 | @type | Determined by the iCalendar component | 198 | | type: "jsevent" for VEVENT, "jstask" for | 199 | | VTODO, "jsgroup" for VCALENDAR. | 200 | | | 201 | alerts | Each entry maps to a VALARM component. | 202 | | The ACTION property maps to _action_, | 203 | | where both "DISPLAY" and "AUDIO" values | 204 | | map to the "display" action. An EMAIL | 205 | | value maps to a JSCalendar "email" | 206 | | action. _relativeTo_ and _offset_ map | 207 | | to the TRIGGER property. | 208 | | | 209 | categories | CONCEPT property, defined in | 210 | | [draft-ietf-calext-ical-relations]. | 211 | | | 212 | color | COLOR property, as specified in | 213 | | [RFC7986]. | 214 | | | 215 | created | CREATED property. | 216 | | | 217 | description | DESCRIPTION property. | 218 | | | 219 | descriptionContentType | Implementation-specific. | 220 | | | 221 | excluded | EXDATE property. | 222 | | | 223 | freeBusyStatus | TRANSP property. | 224 | | | 225 | isAllDay | See Section 5.1. | 226 | | | 227 | keywords | CATEGORIES property, as specified in | 228 | | [RFC7986]. | 229 | | | 230 | links | ATTACH ([RFC5545]), URL or IMAGE | 231 | | ([RFC7986]) properties with URI value | 232 | | types map to the the Link _href_. The | 233 | | FMTTYPE parameter maps to _type_, the | 234 | | SIZE parameter to _size_. Mapping other | 235 | | properties is implementation-specific. | 236 | | | 237 | locale | LANGUAGE parameter of the SUMMARY or | 238 | | DESCRIPTION property. | 239 | | | 240 | localizations | Implementation-specific. | 241 | | | 242 | locations | See Section 5.2. | 243 | | | 244 | method | METHOD property of the embedding | 245 | | VCALENDAR. | 246 | | | 247 | participants | See Section 5.3. | 248 | | | 249 | priority | PRIORITY property. | 250 | | | 251 | privacy | CLASS property. | 252 | | | 253 | prodId | PRODID property. | 254 | | | 255 | recurrenceOverrides | RDATE and EXDATE properties, and any | 256 | | VEVENT or VTODO instances with a | 257 | | recurrence-id and same UID as the mapped | 258 | | main object. | 259 | | | 260 | recurrenceRule | RRULE property. For all-day calendar | 261 | | objects, map the _until_ property value | 262 | | to an iCalendar DATE (effectively | 263 | | removing the time component). To convert | 264 | | a DATE-typed UNTIL from iCalendar, set | 265 | | the time components of the LocalDate | 266 | | value to "23:59:59". If the iCalendar | 267 | | UNTIL value is a UTC date time, convert | 268 | | it to the local time in the JSCalendar | 269 | | calendar object time zone. | 270 | | | 271 | relatedTo | RELATED-TO property. | 272 | | | 273 | replyTo | An iCalendar ORGANIZER with a mailto: | 274 | | URI mapped to the "imip" method, or any | 275 | | other URI mapped to the "other" method. | 276 | | Mapping multiple methods is | 277 | | implementation-specific. | 278 | | | 279 | sequence | SEQUENCE property. | 280 | | | 281 | start | See Section 5.1. | 282 | | | 283 | status | STATUS property. | 284 | | | 285 | timeZone | See Section 5.1. | 286 | | | 287 | timeZones | Each entry in the property maps to a | 288 | | VTIMEZONE in the embedding VCALENDAR | 289 | | component. | 290 | | | 291 | title | SUMMARY property. | 292 | | | 293 | uid | UID property. | 294 | | | 295 | updated | DTSTAMP and LAST-MODIFIED properties. | 296 | | | 297 | useDefaultAlerts | Implementation-specific. | 298 | | | 299 | virtualLocations | See Section 5.2. | 300 +------------------------+------------------------------------------+ 302 Table 4: Translation between JSCalendar and iCalendar 304 5.1. Time 306 JSEvent and JSTask objects share the _start_, _timeZone_ and 307 _isAllDay_ properties to express their occurrence in time. The 308 following table defines how to map these properties: 310 +------------+------------------------------------------------------+ 311 | Property | iCalendar counterpart | 312 +------------+------------------------------------------------------+ 313 | start and | The _start_ property value maps to an iCalendar | 314 | non-null | DTSTART of type local DATE-TIME and the _timeZone_ | 315 | timeZone | value to its TZID parameter. If the time zone is | 316 | | "Etc/UTC", then the start time may alternatively map | 317 | | to an iCalendar UTC DATE-TIME without a TZID | 318 | | parameter. | 319 | | | 320 | start and | The _start_ property value maps to an iCalendar | 321 | isAllDay | DTSTART property value of type DATE. When mapping | 322 | is true | from iCalendar, the time component of the _start_ | 323 | | property value is zero. | 324 | | | 325 | start and | The _start_ property value maps to an iCalendar | 326 | null | DTSTART of type local DATE-TIME and no TZID | 327 | timeZone | parameter. | 328 | and | | 329 | isAllDay | | 330 | is false | | 331 +------------+------------------------------------------------------+ 333 Table 5: Mapping common time properties 335 5.2. Locations 337 The iCalendar counterpart for JSCalendar Location objects is the 338 iCalendar [RFC5545] LOCATION property, or implementation-specific. 340 +-------------+----------------------------------+ 341 | Property | iCalendar counterpart | 342 +-------------+----------------------------------+ 343 | coordinates | GEO property. | 344 | | | 345 | description | Implementation-specific. | 346 | | | 347 | linkIds | Implementation-specific. | 348 | | | 349 | name | LOCATION property value. | 350 | | | 351 | rel | Implementation-specific. | 352 | | | 353 | timeZone | Implementation-specific. | 354 | | | 355 | uri | The LOCATION ALTREP parameter. | 356 +-------------+----------------------------------+ 358 Table 6: Mapping Location properties 360 The iCalendar counterpart for JSCalendar VirtualLocation objects is 361 the iCalendar [RFC7986] CONFERENCE property. 363 +-------------+------------------------------+ 364 | Property | iCalendar counterpart | 365 +-------------+------------------------------+ 366 | description | Implementation-specific. | 367 | | | 368 | name | LABEL parameter. | 369 | | | 370 | uri | CONFERENCE property value. | 371 +-------------+------------------------------+ 373 Table 7: Mapping virtualLocation properties 375 5.3. Participants 377 The following table outlines translation of JSCalendar participants. 378 An iCalendar ORGANIZER maps to _replyTo_ and a participant with role 379 "owner". If an ATTENDEE with the same CAL-ADDRESS value exists, then 380 it maps to the same participant as the ORGANIZER participant. Other 381 participants map to ATTENDEEs. 383 +---------------------+---------------------------------------------+ 384 | Property | iCalendar counterpart | 385 +---------------------+---------------------------------------------+ 386 | attendance | ROLE parameter values REQ-PARTICIPANT, OPT- | 387 | | PARTICIPANT and NON-PARTICIPANT. | 388 | | | 389 | delegatedFrom | DELEGATED-FROM parameter | 390 | | | 391 | delegatedTo | DELEGATED-TO parameter | 392 | | | 393 | email | EMAIL parameter, if defined. Otherwise the | 394 | | CAL-ADDRESS property value, if it is a | 395 | | mailto: URI. | 396 | | | 397 | expectReply | RSVP parameter | 398 | | | 399 | kind | CUTYPE parameter | 400 | | | 401 | linkIds | Implementation-specific. | 402 | | | 403 | locationId | Implementation-specific. | 404 | | | 405 | memberOf | MEMBER parameter | 406 | | | 407 | name | CN parameter | 408 | | | 409 | participationStatus | PARTSTAT parameter | 410 | | | 411 | roles | ROLE parameter. | 412 | | | 413 | scheduleSequence | SEQUENCE property of the participant's | 414 | | latest iMIP message | 415 | | | 416 | scheduleUpdated | DTSTAMP property of the participant's | 417 | | latest iMIP message | 418 | | | 419 | sendTo | A CAL-ADDRESS with a mailto: URI maps to | 420 | | the JSCalendar "imip" method, any other URI | 421 | | to the "other" method. Mapping multiple | 422 | | methods is implementation-specific. | 423 +---------------------+---------------------------------------------+ 425 Table 8: Mapping Participant properties 427 6. Custom properties 429 Mapping custom or unknown properties between JSCalendar and iCalendar 430 is implementation-specific. Implementations might use vendor- 431 extension properties, which could also serve as basis for discussion 432 for a JSCalendar standard extension. Alternatively, an 433 implementation could preserve iCalendar properties and components in 434 JSCalendar by use of a vendor-extension property formatted as jCal 435 [RFC7265] data. 437 7. Security Considerations 439 The same security considerations as for 440 [draft-ietf-calext-jscalendar] apply. 442 8. IANA Considerations 444 None. 446 9. Acknowledgments 448 The authors would like to thank the members of CalConnect for their 449 valuable contributions. This specification originated from the work 450 of the API technical committee of CalConnect, the Calendaring and 451 Scheduling Consortium. 453 10. References 455 10.1. Normative References 457 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 458 Requirement Levels", BCP 14, RFC 2119, 459 DOI 10.17487/RFC2119, March 1997, 460 . 462 [RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and 463 Scheduling Core Object Specification (iCalendar)", 464 RFC 5545, DOI 10.17487/RFC5545, September 2009, 465 . 467 [RFC7265] Kewisch, P., Daboo, C., and M. Douglass, "jCal: The JSON 468 Format for iCalendar", RFC 7265, DOI 10.17487/RFC7265, May 469 2014, . 471 [RFC7986] Daboo, C., "New Properties for iCalendar", RFC 7986, 472 DOI 10.17487/RFC7986, October 2016, 473 . 475 10.2. Informative References 477 [draft-apthorp-ical-tasks] 478 "Task Extensions to iCalendar", 479 . 481 [draft-ietf-calext-ical-relations] 482 "Support for iCalendar Relationships", 483 . 486 [draft-ietf-calext-jscalendar] 487 "Task Extensions to iCalendar", 488 . 491 Authors' Addresses 493 Neil Jenkins 494 FastMail 495 PO Box 234 496 Collins St West 497 Melbourne VIC 8007 498 Australia 500 Email: neilj@fastmailteam.com 501 URI: https://www.fastmail.com 503 Robert Stepanek 504 FastMail 505 PO Box 234 506 Collins St West 507 Melbourne VIC 8007 508 Australia 510 Email: rsto@fastmailteam.com 511 URI: https://www.fastmail.com