idnits 2.17.1 draft-ietf-calext-jscalendar-icalendar-01.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 136 has weird spacing: '...sons in iCale...' -- The document date (June 29, 2019) is 1763 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- No issues found here. Summary: 0 errors (**), 0 flaws (~~), 2 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: Informational FastMail 5 Expires: December 31, 2019 June 29, 2019 7 JSCalendar: Converting from and to iCalendar 8 draft-ietf-calext-jscalendar-icalendar-01 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 December 31, 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. New iCalendar parameters . . . . . . . . . . . . . . . . . . 3 54 2.1. SUBSECOND parameter . . . . . . . . . . . . . . . . . . . 3 55 3. JSEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 56 4. JSTask . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 57 5. JSGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 58 6. Common properties . . . . . . . . . . . . . . . . . . . . . . 5 59 6.1. Time properties and types . . . . . . . . . . . . . . . . 8 60 6.2. Locations . . . . . . . . . . . . . . . . . . . . . . . . 9 61 6.3. Participants . . . . . . . . . . . . . . . . . . . . . . 10 62 7. Custom properties . . . . . . . . . . . . . . . . . . . . . . 12 63 8. Security Considerations . . . . . . . . . . . . . . . . . . . 12 64 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 65 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 12 66 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 67 11.1. Normative References . . . . . . . . . . . . . . . . . . 12 68 11.2. Informative References . . . . . . . . . . . . . . . . . 13 69 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13 71 1. Introduction 73 1.1. Motivation 75 The JSCalendar [draft-ietf-calext-jscalendar] data format is used to 76 represent calendar data, and is meant as an alternative to the widely 77 deployed iCalendar [RFC5545] data format. 79 While new calendaring services and applications might use JSCalendar 80 as their main data format to exchange calendaring data, they are 81 likely to interoperate with services and clients that just support 82 iCalendar. Similarly, existing calendaring data is stored in 83 iCalendar format in databases and other calendar stores, and 84 providers and users might want to represent this data also in 85 JSCalendar. Lastly, some implementations might want to preserve 86 custom iCalendar properties, that have no equivalent in JSCalendar 87 when converting between these formats. 89 To facilitate these use cases, this document provides an 90 informational guide how to convert JSCalendar data from and to 91 iCalendar. 93 1.2. Scope and caveats 95 JSCalendar and iCalendar have a lot of semantics in common, but they 96 are not interchangeable formats: 98 o JSCalendar contains a richer data model to express calendar 99 information such as event locations and participants; while future 100 iCalendar extensions may allow a direct mapping, for now there may 101 be no representation directly in iCalendar of some properties and 102 these have been marked as implementation specific for mapping. 104 o iCalendar may contain arbitrary, non-standardised data with custom 105 properties/attributes. Translating these into JSCalendar is 106 implementation specific. 108 o iCalendar has some obsolete features that have been removed from 109 JSCalendar due to not being useful and/or supported in the real 110 world (e.g. custom email alerts to send to random people). 111 Translating these may lose some of the original fidelity. 113 o Implementations may use a custom property to store data that could 114 not be mapped directly in either direction in the original or a 115 custom format, however this is not interoperable. 117 Accordingly, this document does not standardize a canonical 118 translation between iCalendar and JSCalendar, and implementations 119 MUST NOT make any assumptions how iCalendar data is represented in 120 JSCalendar by other systems. 122 1.3. Notational Conventions 124 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 125 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 126 document are to be interpreted as described in [RFC2119]. 128 2. New iCalendar parameters 130 2.1. SUBSECOND parameter 132 Parameter name: SUBSECOND 134 Purpose: This parameter is used to define fractional seconds for 135 time values and durations. SUBSECOND MUST NOT be used in date- 136 time calculations or comparisons in iCalendar. It is meant to 137 preserve time precision on time values and duration with sub- 138 second precision, without increasing the time value range within 139 iCalendar. 141 Description: This parameter MAY be specified on properties of type 142 DATE-TIME or DURATION. The integral part of the float value MUST 143 be zero. The value MUST NOT be negative. iCalendar 144 implementations SHOULD ignore this parameter in date time 145 arithmetic. Implementations MUST ignore presence of the SUBSECOND 146 parameter on RECURRENCE-ID properties when determining recurrence 147 overrides. If present on a RECURRENCE-ID property, its value MUST 148 match the SUBSECOND parameter value on the DATE-TIME property that 149 defines the reference point for the recurring instances. 151 Format Definition: 153 This parameter is defined by the following notation: 155 subsecond-param = float 157 Example: DTSTART;SUBSECOND=0.03:20190605T133015 159 3. JSEvent 161 A JSEvent maps to the the iCalendar VEVENT component type [RFC5545]. 162 The following tables maps the JSEvent-specific properties to 163 iCalendar: 165 +----------+--------------------------------------------------------+ 166 | Property | iCalendar counterpart | 167 +----------+--------------------------------------------------------+ 168 | duration | DURATION property. If the VEVENT contains a DTEND | 169 | | property, the this maps to the duration property as | 170 | | the time span between DTSTART and DTEND when | 171 | | converting the respective time points to the UTC time | 172 | | zone. Fractional seconds SHOULD be preserved with the | 173 | | SUBSECOND parameter. | 174 +----------+--------------------------------------------------------+ 176 Table 1: Mapping JSEvent properties 178 4. JSTask 180 A JSTask object maps to the iCalendar VTODO component type [RFC5545]. 181 The following tables maps the JSTask-specific properties to 182 iCalendar: 184 +-------------------+-----------------------------------------------+ 185 | Property | iCalendar counterpart | 186 +-------------------+-----------------------------------------------+ 187 | due | Maps to the DUE property. See Section 6.1. | 188 | | | 189 | estimatedDuration | ESTIMATED-DURATION property in the RFC draft | 190 | | [draft-apthorp-ical-tasks], or the DURATION | 191 | | property otherwise. Fractional seconds | 192 | | SHOULD be preserved with the SUBSECOND | 193 | | parameter. | 194 | | | 195 | statusUpdatedAt | COMPLETED property. The JSTask status | 196 | | property MUST have value "completed". | 197 | | Fractional seconds SHOULD be preserved with | 198 | | the SUBSECOND parameter. | 199 | | | 200 | progress | PARTSTAT and COMPLETED properties, including | 201 | | the definitions in the RFC draft | 202 | | [draft-apthorp-ical-tasks]. | 203 | | | 204 | status | STATUS property, including the definitions in | 205 | | the RFC draft [draft-apthorp-ical-tasks]. | 206 +-------------------+-----------------------------------------------+ 208 Table 2: Mapping JSTask properties 210 5. JSGroup 212 A JSGroup maps to a iCalendar VCALENDAR containing VEVENT or VTODO 213 components. 215 +----------+--------------------------------------------------------+ 216 | Property | iCalendar counterpart | 217 +----------+--------------------------------------------------------+ 218 | entries | VEVENT and VTODO components embedded in a VCALENDAR | 219 | | component. | 220 | | | 221 | source | SOURCE property. | 222 +----------+--------------------------------------------------------+ 224 Table 3: Mapping JSGroup properties 226 6. Common properties 228 This section contains recommendations how to map JSCalendar from and 229 to iCalendar. It lists all common JSCalendar object properties in 230 alphabetical order. 232 +------------------------+------------------------------------------+ 233 | Property | iCalendar counterpart | 234 +------------------------+------------------------------------------+ 235 | @type | Determined by the iCalendar component | 236 | | type: "jsevent" for VEVENT, "jstask" for | 237 | | VTODO, "jsgroup" for VCALENDAR. | 238 | | | 239 | alerts | Each entry maps to a VALARM component. | 240 | | The action property maps to iCalendar | 241 | | ACTION, where both iCalendar "DISPLAY" | 242 | | and "AUDIO" values map to the "display" | 243 | | action. An EMAIL value maps to a | 244 | | JSCalendar "email" action. _relativeTo_ | 245 | | and _offset_ map to the TRIGGER | 246 | | property. | 247 | | | 248 | categories | CONCEPT property, defined in | 249 | | [draft-ietf-calext-ical-relations]. | 250 | | | 251 | color | COLOR property, as specified in | 252 | | [RFC7986]. | 253 | | | 254 | created | CREATED property. Fractional seconds | 255 | | SHOULD be preserved with the SUBSECOND | 256 | | parameter. | 257 | | | 258 | description | DESCRIPTION property. | 259 | | | 260 | descriptionContentType | Implementation-specific. | 261 | | | 262 | excluded | EXDATE property. Fractional seconds | 263 | | SHOULD be preserved with the SUBSECOND | 264 | | parameter. | 265 | | | 266 | freeBusyStatus | TRANSP property. | 267 | | | 268 | invitedBy | Implementation-specific. | 269 | | | 270 | keywords | CATEGORIES property, as specified in | 271 | | [RFC7986]. | 272 | | | 273 | links | ATTACH ([RFC5545]), URL or IMAGE | 274 | | ([RFC7986]) properties with URI value | 275 | | types map to the the Link _href_. The | 276 | | FMTTYPE parameter maps to _type_, the | 277 | | SIZE parameter to _size_. Mapping other | 278 | | properties is implementation-specific. | 279 | | | 280 | locale | LANGUAGE parameter of the SUMMARY or | 281 | | DESCRIPTION property. | 282 | | | 283 | localizations | Implementation-specific. | 284 | | | 285 | locations | See Section 6.2. | 286 | | | 287 | method | METHOD property of the embedding | 288 | | VCALENDAR. | 289 | | | 290 | participants | See Section 6.3. | 291 | | | 292 | priority | PRIORITY property. | 293 | | | 294 | privacy | CLASS property. | 295 | | | 296 | prodId | PRODID property. | 297 | | | 298 | recurrenceOverrides | RDATE and EXDATE properties, and any | 299 | | VEVENT or VTODO instances with a | 300 | | recurrence-id and same UID as the mapped | 301 | | main object. If the DTSTART property | 302 | | defines a SUBSECOND parameter, but the | 303 | | RECURRENCE-ID of a recurrence instance | 304 | | does not, then use the SUBSECOND | 305 | | parameter value of DTSTART to determine | 306 | | the recurrence override time stamp. | 307 | | | 308 | recurrenceRule | RRULE property. For all-day calendar | 309 | | objects, map the _until_ property value | 310 | | to an iCalendar DATE (effectively | 311 | | removing the time component). To convert | 312 | | a DATE-typed UNTIL from iCalendar, set | 313 | | the time components of the LocalDateTime | 314 | | value to "23:59:59". If the iCalendar | 315 | | UNTIL value is a UTC date time, convert | 316 | | it to the local time in the JSCalendar | 317 | | calendar object time zone. To convert to | 318 | | iCalendar where the DTSTART or DUE | 319 | | property is of type DATE, omit the time | 320 | | component of the LocalDateTime value. | 321 | | | 322 | relatedTo | RELATED-TO property. | 323 | | | 324 | replyTo | An iCalendar ORGANIZER with a mailto: | 325 | | URI mapped to the "imip" method, or any | 326 | | other URI mapped to the "other" method. | 327 | | Mapping multiple methods is | 328 | | implementation-specific. | 329 | | | 330 | sequence | SEQUENCE property. | 331 | | | 332 | showWithoutTime | Implementation-specific. | 333 | | | 334 | start | Maps to the DTSTART property. See | 335 | | Section 6.1. | 336 | | | 337 | status | STATUS property. | 338 | | | 339 | timeZone | Maps to the TZID parameter. See Section | 340 | | 6.1. | 341 | | | 342 | timeZones | Each entry in the property maps to a | 343 | | VTIMEZONE in the embedding VCALENDAR | 344 | | component. | 345 | | | 346 | title | SUMMARY property. | 347 | | | 348 | uid | UID property. | 349 | | | 350 | updated | DTSTAMP and LAST-MODIFIED properties. | 351 | | Fractional seconds SHOULD be preserved | 352 | | with the SUBSECOND parameter. | 353 | | | 354 | useDefaultAlerts | Implementation-specific. | 355 | | | 356 | virtualLocations | See Section 6.2. | 357 +------------------------+------------------------------------------+ 359 Table 4: Translation between JSCalendar and iCalendar 361 6.1. Time properties and types 363 iCalendar defines two different time types, DATE and DATE-TIME, where 364 the latter may occur in three forms (with local time, with UTC time, 365 with local time and time zone reference). In contrast, JSCalendar 366 does not define a distinct type for dates, and date times are defined 367 with the LocalDateTime type only. 369 A JSCalendar time maps to the iCalendar DATE type if all of the 370 following criteria apply: 372 o The "start" ("due") property value has zero time, or is not set. 374 o The "duration" ("estimatedDuration") property value has zero time, 375 or is a multiple of days or weeks, or is not set. 377 o The "timeZone" property value is null, or is not set. 379 For all other cases, the time maps to an iCalendar DATE-TIME: 381 o With local time and time zone reference, if the "timeZone" 382 property value is set and does not equal "Etc/UTC". 384 o With UTC time, if the "timeZone" property value equals "Etc/UTC". 386 o With local time, if the "timeZone" property value is null or not 387 set. 389 Fractional seconds SHOULD be preserved with the SUBSECOND parameter. 391 6.2. Locations 393 The iCalendar counterpart for JSCalendar Location objects is the 394 iCalendar [RFC5545] LOCATION property, or implementation-specific. 396 +-------------+----------------------------------+ 397 | Property | iCalendar counterpart | 398 +-------------+----------------------------------+ 399 | coordinates | GEO property. | 400 | | | 401 | description | Implementation-specific. | 402 | | | 403 | linkIds | Implementation-specific. | 404 | | | 405 | name | LOCATION property value. | 406 | | | 407 | rel | Implementation-specific. | 408 | | | 409 | timeZone | Implementation-specific. | 410 | | | 411 | uri | The LOCATION ALTREP parameter. | 412 +-------------+----------------------------------+ 414 Table 5: Mapping Location properties 416 The iCalendar counterpart for JSCalendar VirtualLocation objects is 417 the iCalendar [RFC7986] CONFERENCE property. 419 +-------------+------------------------------+ 420 | Property | iCalendar counterpart | 421 +-------------+------------------------------+ 422 | description | Implementation-specific. | 423 | | | 424 | name | LABEL parameter. | 425 | | | 426 | uri | CONFERENCE property value. | 427 +-------------+------------------------------+ 429 Table 6: Mapping virtualLocation properties 431 6.3. Participants 433 The following table outlines translation of JSCalendar participants. 434 An iCalendar ORGANIZER maps to both the replyTo property and a 435 participant with role "owner". If an ATTENDEE with the same CAL- 436 ADDRESS value exists, then it maps to the same participant as the 437 ORGANIZER participant. Other participants map to ATTENDEEs. 439 +---------------------+---------------------------------------------+ 440 | Property | iCalendar counterpart | 441 +---------------------+---------------------------------------------+ 442 | attendance | ROLE parameter values REQ-PARTICIPANT, OPT- | 443 | | PARTICIPANT and NON-PARTICIPANT. | 444 | | | 445 | delegatedFrom | DELEGATED-FROM parameter | 446 | | | 447 | delegatedTo | DELEGATED-TO parameter | 448 | | | 449 | email | EMAIL parameter, if defined. Otherwise the | 450 | | CAL-ADDRESS property value, if it is a | 451 | | mailto: URI. | 452 | | | 453 | expectReply | RSVP parameter | 454 | | | 455 | kind | CUTYPE parameter | 456 | | | 457 | linkIds | Implementation-specific. | 458 | | | 459 | locationId | Implementation-specific. | 460 | | | 461 | memberOf | MEMBER parameter | 462 | | | 463 | name | CN parameter | 464 | | | 465 | participationStatus | PARTSTAT parameter | 466 | | | 467 | roles | ROLE parameter. | 468 | | | 469 | scheduleSequence | SEQUENCE property of the participant's | 470 | | latest iMIP message | 471 | | | 472 | scheduleUpdated | DTSTAMP property of the participant's | 473 | | latest iMIP message | 474 | | | 475 | sendTo | A CAL-ADDRESS with a mailto: URI maps to | 476 | | the JSCalendar "imip" method, any other URI | 477 | | to the "other" method. Mapping multiple | 478 | | methods is implementation-specific. | 479 +---------------------+---------------------------------------------+ 481 Table 7: Mapping Participant properties 483 7. Custom properties 485 Mapping custom or unknown properties between JSCalendar and iCalendar 486 is implementation-specific. Implementations might use vendor- 487 extension properties, which could also serve as basis for discussion 488 for a JSCalendar standard extension. Alternatively, an 489 implementation could preserve iCalendar properties and components in 490 JSCalendar by use of a vendor-extension property formatted as jCal 491 [RFC7265] data. 493 8. Security Considerations 495 The same security considerations as for 496 [draft-ietf-calext-jscalendar] apply. 498 9. IANA Considerations 500 None. 502 10. Acknowledgments 504 The authors would like to thank the members of CalConnect for their 505 valuable contributions. This specification originated from the work 506 of the API technical committee of CalConnect, the Calendaring and 507 Scheduling Consortium. 509 11. References 511 11.1. Normative References 513 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 514 Requirement Levels", BCP 14, RFC 2119, 515 DOI 10.17487/RFC2119, March 1997, 516 . 518 [RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and 519 Scheduling Core Object Specification (iCalendar)", 520 RFC 5545, DOI 10.17487/RFC5545, September 2009, 521 . 523 [RFC7265] Kewisch, P., Daboo, C., and M. Douglass, "jCal: The JSON 524 Format for iCalendar", RFC 7265, DOI 10.17487/RFC7265, May 525 2014, . 527 [RFC7986] Daboo, C., "New Properties for iCalendar", RFC 7986, 528 DOI 10.17487/RFC7986, October 2016, 529 . 531 11.2. Informative References 533 [draft-apthorp-ical-tasks] 534 "Task Extensions to iCalendar", 535 . 537 [draft-ietf-calext-ical-relations] 538 "Support for iCalendar Relationships", 539 . 542 [draft-ietf-calext-jscalendar] 543 "Task Extensions to iCalendar", 544 . 547 Authors' Addresses 549 Neil Jenkins 550 FastMail 551 PO Box 234 552 Collins St West 553 Melbourne VIC 8007 554 Australia 556 Email: neilj@fastmailteam.com 557 URI: https://www.fastmail.com 559 Robert Stepanek 560 FastMail 561 PO Box 234 562 Collins St West 563 Melbourne VIC 8007 564 Australia 566 Email: rsto@fastmailteam.com 567 URI: https://www.fastmail.com