idnits 2.17.1 draft-jenkins-jmapcalendars-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 -- The document date (March 26, 2019) is 1829 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) == Outdated reference: A later version (-32) exists of draft-ietf-calext-jscalendar-12 == Outdated reference: A later version (-17) exists of draft-ietf-jmap-core-16 Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 JMAP N. Jenkins 3 Internet-Draft FastMail 4 Intended status: Standards Track March 26, 2019 5 Expires: September 27, 2019 7 JMAP for Calendars 8 draft-jenkins-jmapcalendars-01 10 Abstract 12 This document specifies a data model for synchronising calendar data 13 with a server using JMAP. 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 September 27, 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. Notational conventions . . . . . . . . . . . . . . . . . 2 51 1.2. The Date datatypes . . . . . . . . . . . . . . . . . . . 3 52 1.3. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 53 1.4. Addition to the capabilities object . . . . . . . . . . . 3 54 2. Calendars . . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 2.1. Calendar/get . . . . . . . . . . . . . . . . . . . . . . 5 56 2.2. Calendar/changes . . . . . . . . . . . . . . . . . . . . 5 57 2.3. Calendar/set . . . . . . . . . . . . . . . . . . . . . . 5 58 3. Calendar events . . . . . . . . . . . . . . . . . . . . . . . 5 59 3.1. CalendarEvent/get . . . . . . . . . . . . . . . . . . . . 6 60 3.2. CalendarEvent/changes . . . . . . . . . . . . . . . . . . 6 61 3.3. CalendarEvent/set . . . . . . . . . . . . . . . . . . . . 6 62 3.4. CalendarEvent/copy . . . . . . . . . . . . . . . . . . . 6 63 3.5. CalendarEvent/query . . . . . . . . . . . . . . . . . . . 7 64 3.5.1. Filtering . . . . . . . . . . . . . . . . . . . . . . 7 65 3.5.2. Sorting . . . . . . . . . . . . . . . . . . . . . . . 8 66 3.6. CalendarEvent/queryChanges . . . . . . . . . . . . . . . 8 67 4. Security considerations . . . . . . . . . . . . . . . . . . . 8 68 5. IANA considerations . . . . . . . . . . . . . . . . . . . . . 9 69 5.1. JMAP capability registration for "calendars" . . . . . . 9 70 6. Normative References . . . . . . . . . . . . . . . . . . . . 9 71 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9 73 1. Introduction 75 JMAP ([I-D.ietf-jmap-core] - JSON Meta Application Protocol) is a 76 generic protocol for synchronising data, such as mail, calendars or 77 contacts, between a client and a server. It is optimised for mobile 78 and web environments, and aims to provide a consistent interface to 79 different data types. 81 This specification defines a data model for synchronising calendar 82 data between a client and a server using JMAP. 84 1.1. Notational conventions 86 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 87 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 88 "OPTIONAL" in this document are to be interpreted as described in BCP 89 14 [RFC2119] [RFC8174] when, and only when, they appear in all 90 capitals, as shown here. 92 Type signatures, examples and property descriptions in this document 93 follow the conventions established in section 1.1 of 94 [I-D.ietf-jmap-core]. 96 Object properties may also have a set of attributes defined along 97 with the type signature. These have the following meanings: 99 o *server-set*: Only the server can set the value for this property. 100 The client MUST NOT send this property when creating a new object 101 of this type. 103 o *immutable*: The value MUST NOT change after the object is 104 created. 106 o *default*: (This is followed by a JSON value). The value that 107 will be used for this property if it is omitted in an argument, or 108 when creating a new object of this type. 110 Data types defined in the core specification are used in this 111 document. 113 1.2. The Date datatypes 115 Where "LocalDate" is given as a type, it means a string in the same 116 format as "Date", but with the _time-offset_ omitted from the end. 117 The interpretation in absolute time depends upon the time zone for 118 the event, which may not be a fixed offset (for example when daylight 119 saving time occurs). For example, ""2014-10-30T14:12:00"". 121 1.3. Terminology 123 The same terminology is used in this document as in the core JMAP 124 specification. 126 1.4. Addition to the capabilities object 128 The capabilities object is returned as part of the standard JMAP 129 Session object; see the JMAP spec. Servers supporting _this_ 130 specification MUST add a property called 131 "urn:ietf:params:jmap:calendars" to the capabilities object. 133 The value of this property is an empty object in both the JMAP 134 session _capabilities_ property and an account's 135 _accountCapabilities_ property. 137 2. Calendars 139 A Calendar is a named collection of events. All events are 140 associated with one, and only one, calendar. 142 A *Calendar* object has the following properties: 144 o *id*: "Id" (immutable; server-set) The id of the calendar. 146 o *name*: "String" The user-visible name of the calendar. This may 147 be any UTF-8 string of at least 1 character in length and maximum 148 255 octets in size. 150 o *color*: "String" Any valid CSS color value. The color to be used 151 when displaying events associated with the calendar. The color 152 SHOULD have sufficient contrast to be used as text on a white 153 background. 155 o *sortOrder*: "UnsignedInt" (default: 0) Defines the sort order of 156 calendars when presented in the client's UI, so it is consistent 157 between devices. The number MUST be an integer in the range 0 <= 158 sortOrder < 2^31. A calendar with a lower order should be 159 displayed before a calendar with a higher order in any list of 160 calendars in the client's UI. Calendars with equal order should 161 be sorted in alphabetical order by name. The sorting should take 162 into locale-specific character order convention. 164 o *isVisible*: "Boolean" (default: true) Should the calendar's 165 events be displayed to the user at the moment? 167 o *mayReadFreeBusy*: "Boolean" (server-set) The user may read the 168 free-busy information for this calendar. In JMAP terms, this 169 means the user may use this calendar as part of a filter in a 170 _CalendarEvent/query_ call, however unless "mayRead == true", the 171 events returned for this calendar will only contain free-busy 172 information, and be stripped of any other data. This property 173 MUST be "true" if _mayRead_ is "true". 175 o *mayReadItems*: "Boolean" (server-set) The user may fetch the 176 events in this calendar. In JMAP terms, this means the user may 177 use this calendar as part of a filter in a _CalendarEvent/query_ 178 call 180 o *mayAddItems*: "Boolean" (server-set) The user may add events to 181 this calendar. In JMAP terms, this means the user may call 182 _CalendarEvent/set_ to create new events in this calendar or move 183 existing events into this calendar from another calendar. This 184 property MUST be "false" if the account to which this calendar 185 belongs has the _isReadOnly_ property set to "true". 187 o *mayModifyItems*: "Boolean" (server-set) The user may edit events 188 in this calendar by calling _CalendarEvent/set_ with the _update_ 189 argument referencing events in this collection. This property 190 MUST be "false" if the account to which this calendar belongs has 191 the _isReadOnly_ property set to "true". 193 o *mayRemoveItems*: "Boolean" (server-set) The user may remove 194 events from this calendar by calling _CalendarEvent/set_ with the 195 _destroy_ argument referencing events in this collection, or by 196 updating their _calendarId_ property to a different calendar. 197 This property MUST be "false" if the account to which this 198 calendar belongs has the _isReadOnly_ property set to "true". 200 o *mayRename*: "Boolean" (server-set) The user may rename the 201 calendar. This property MUST be "false" if the account to which 202 this calendar belongs has the _isReadOnly_ property set to "true". 204 o *mayDelete*: "Boolean" (server-set) The user may delete the 205 calendar itself. This property MUST be "false" if the account to 206 which this calendar belongs has the _isReadOnly_ property set to 207 "true". 209 2.1. Calendar/get 211 Standard "/get" method as described in [I-D.ietf-jmap-core] section 212 5.1. The _ids_ argument may be "null" to fetch all at once. 214 2.2. Calendar/changes 216 Standard "/changes" method as described in [I-D.ietf-jmap-core] 217 section 5.2. 219 2.3. Calendar/set 221 Standard "/set" method as described in [I-D.ietf-jmap-core] section 222 5.3. 224 A calendar MAY be deleted that is currently associated with one or 225 more events. In this case, the events belonging to this calendar 226 MUST also be deleted. Conceptually, this MUST happen prior to the 227 calendar itself being deleted, and MUST generate a *push* event that 228 modifies the state of the _CalendarEvent_ type for the account. 230 3. Calendar events 232 A *CalendarEvent* object contains information about an event, or 233 recurring series of events, that takes place at a particular time. 234 It is a JSEvent object, as defined in [I-D.ietf-calext-jscalendar], 235 with the following additional properties: 237 o *id*: "Id" The id of the event. This property is immutable. 239 o *calendarId*: "Id" The id of the calendar this event belongs to. 241 o *participantId*: "Id|null" The id of the participant in the 242 _participants_ object which corresponds to the account this event 243 is in. 245 3.1. CalendarEvent/get 247 Standard "/get" method as described in [I-D.ietf-jmap-core] section 248 5.1. 250 3.2. CalendarEvent/changes 252 Standard "/changes" method as described in [I-D.ietf-jmap-core] 253 section 5.2 255 3.3. CalendarEvent/set 257 Standard "/set" method as described in [I-D.ietf-jmap-core] section 258 5.3. 260 When an event is created, updated or destroyed, the server MUST also 261 ensure the following: 263 o Any alerts are scheduled/cancelled correctly. 265 o If there is a _participantId_, and the corresponding participant 266 has a _role_ of "owner": 268 * If an event is created/updated: send a REQUEST iMIP email with 269 the event as an ICS attachment to all participants that are not 270 "you". 272 * When an event is destroyed, if it is in the future, then email 273 all participants other than you the appropriate iMIP email to 274 inform them that the event has been cancelled. If it is in the 275 past, the server SHOULD NOT send a message. 277 o If there is a _participantId_, and the corresponding participant 278 does not have a _role_ of "owner", and the _scheduleStatus_ is 279 updated for this participant, send the appropriate iMIP email to 280 the _replyTo_ address. 282 3.4. CalendarEvent/copy 284 Standard "/copy" method as described in [I-D.ietf-jmap-core] section 285 5.4. 287 3.5. CalendarEvent/query 289 Standard "/query" method as described in [I-D.ietf-jmap-core] section 290 5.5. 292 3.5.1. Filtering 294 A *FilterCondition* object has the following properties: 296 o *inCalendars*: "Id[]|null" A list of calendar ids. An event must 297 be in ANY of these calendars to match the condition. 299 o *after*: "UTCDate|null" The end of the event, or any recurrence of 300 the event, in UTC time must be after this date to match the 301 condition. 303 o *before*: "UTCDate|null" The start of the event, or any recurrence 304 of the event, in UTC time must be before this date to match the 305 condition. 307 o *text*: "String|null" Looks for the text in the _title_, 308 _description_, _locations_ (matching name/description), or 309 _participants_ (matching name/email) properties of the event or 310 any recurrence of the event. 312 o *title*: "String|null" Looks for the text in the _title_ property 313 of the event, or the overridden _title_ property of a recurrence. 315 o *description*: "String|null" Looks for the text in the 316 _description_ property of the event, or the overridden 317 _description_ property of a recurrence. 319 o *location*: "String|null" Looks for the text in the _locations_ 320 property of the event (matching name/description of a location), 321 or the overridden _locations_ property of a recurrence. 323 o *owner*: "String|null" Looks for the text in the name or email 324 fields of a participant in the _participants_ property of the 325 event, or the overridden _participants_ property of a recurrence, 326 where the participant has a role of "owner". 328 o *attendee*: "String|null" Looks for the text in the name or email 329 fields of a participant in the _participants_ property of the 330 event, or the overridden _participants_ property of a recurrence, 331 where the participant has a role of "attendee". 333 If zero properties are specified on the FilterCondition, the 334 condition MUST always evaluate to "true". If multiple properties are 335 specified, ALL must apply for the condition to be "true" (it is 336 equivalent to splitting the object into one-property conditions and 337 making them all the child of an AND filter operator). 339 The exact semantics for matching "String" fields is *deliberately not 340 defined* to allow for flexibility in indexing implementation, subject 341 to the following: 343 o Text SHOULD be matched in a case-insensitive manner. 345 o Text contained in either (but matched) single or double quotes 346 SHOULD be treated as a *phrase search*, that is a match is 347 required for that exact sequence of words, excluding the 348 surrounding quotation marks. Use "\"", "\'" and "\\" to match a 349 literal """, "'" and "\" respectively in a phrase. 351 o Outside of a phrase, white-space SHOULD be treated as dividing 352 separate tokens that may be searched for separately in the event, 353 but MUST all be present for the event to match the filter. 355 o Tokens MAY be matched on a whole-word basis using stemming (so for 356 example a text search for "bus" would match "buses" but not 357 "business"). 359 3.5.2. Sorting 361 The following properties MUST be supported for sorting: 363 o start 365 o uid 367 3.6. CalendarEvent/queryChanges 369 Standard "/queryChanges" method as described in [I-D.ietf-jmap-core] 370 section 5.6. 372 4. Security considerations 374 All security considerations of JMAP ([I-D.ietf-jmap-core]) apply to 375 this specification. Additional considerations specific to the data 376 types and functionality introduced by this document are described in 377 the following subsections. 379 TODO 381 5. IANA considerations 383 5.1. JMAP capability registration for "calendars" 385 IANA will register the "calendars" JMAP Capability as follows: 387 Capability Name: "urn:ietf:params:jmap:calendars" 389 Specification document: this document 391 Intended use: common 393 Change Controller: IETF 395 Security and privacy considerations: this document, section TODO 397 6. Normative References 399 [I-D.ietf-calext-jscalendar] 400 Jenkins, N. and R. Stepanek, "JSCalendar: A JSON 401 representation of calendar data", draft-ietf-calext- 402 jscalendar-12 (work in progress), March 2019. 404 [I-D.ietf-jmap-core] 405 Jenkins, N. and C. Newman, "JSON Meta Application 406 Protocol", draft-ietf-jmap-core-16 (work in progress), 407 March 2019. 409 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 410 Requirement Levels", BCP 14, RFC 2119, 411 DOI 10.17487/RFC2119, March 1997, 412 . 414 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 415 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 416 May 2017, . 418 Author's Address 420 Neil Jenkins 421 FastMail 422 PO Box 234, Collins St West 423 Melbourne VIC 8007 424 Australia 426 Email: neilj@fastmailteam.com 427 URI: https://www.fastmail.com