JMAP for Calendars
draft-ietf-jmap-calendars-02
The information below is for an old version of the document.
Document | Type |
This is an older version of an Internet-Draft whose latest revision state is "Active".
|
|
---|---|---|---|
Authors | Neil Jenkins , Michael Douglass | ||
Last updated | 2020-03-09 (Latest revision 2019-10-28) | ||
Replaces | draft-jenkins-jmapcalendars | ||
RFC stream | Internet Engineering Task Force (IETF) | ||
Formats | |||
Additional resources | Mailing list discussion | ||
Stream | WG state | WG Document | |
Associated WG milestone |
|
||
Document shepherd | (None) | ||
IESG | IESG state | I-D Exists | |
Consensus boilerplate | Yes | ||
Telechat date | (None) | ||
Responsible AD | (None) | ||
Send notices to | (None) |
draft-ietf-jmap-calendars-02
o *description*: "String|null" An optional longer-form description of the calendar, to provide context in shared environments where users need more than just the name. o *color*: "String" The color to be used when displaying events associated with the calendar. The value MUST be a case- insensitive color name taken from the CSS3 set of names, defined in Section 4.3 of W3C.REC-css3-color-20110607, or a CSS3 RGB color hex value. The color SHOULD have sufficient contrast to be used as text on a white background. o *sortOrder*: "UnsignedInt" (default: 0) Defines the sort order of calendars when presented in the client's UI, so it is consistent between devices. The number MUST be an integer in the range 0 <= sortOrder < 2^31. A calendar with a lower order should be displayed before a calendar with a higher order in any list of calendars in the client's UI. Calendars with equal order SHOULD be sorted in alphabetical order by name. The sorting should take into account locale-specific character order convention. o *isSubscribed*: "Boolean" Has the user indicated they wish to see this Calendar in their client? This SHOULD default to false for Calendars in shared accounts the user has access to and true for any new Calendars created by the user themself. If false, the calendar should only be displayed when the user explicitly requests it or to offer it for the user to subscribe to. o *isVisible*: "Boolean" (default: true) Should the calendar's events be displayed to the user at the moment? Clients MUST ignore this property if isSubscribed is false. o *includeInAvailability*: "String" (default: all) Should the calendar's events be used as part of availability calculation? This MUST be one of: * "all": all events are considered. * "attending": events the user is a confirmed or tentative participant of are considered. * "none": all events are ignored. o *defaultAlertsWithTime*: "Alert[]" The alerts to apply for events where showWithoutTime is false that have "useDefaultAlerts" set. See [I-D.ietf-calext-jscalendar], Section 4.5.2 for the definition of an Alert object. Jenkins & Douglass Expires September 11, 2020 [Page 13] Internet-Draft JMAP Calendars March 2020 o *defaultAlertsWithoutTime*: "Alert[]" The alerts to apply for events where showWithoutTime is true that have "useDefaultAlerts" set. See [I-D.ietf-calext-jscalendar], Section 4.5.2 for the definition of an Alert object. o *timeZone*: "String|null" The time zone to use for events without a time zone when the server needs to resolve them into absolute time, e.g., for reminders, queries, or availability calculation. The value MUST be a time zone id from the IANA Time Zone Database. If "null", the timeZone of the account's associated CalendarPrincipal will be used. Clients SHOULD use this as the default for new events in this calendar if set. o *participantIdentities*: "ParticipantIdentity[]|null" (server-set) The identities that represent the user in this calendar. The first item in the array is the default. A *ParticipantIdentity* object has the following properties: * *name*: "String" The display name of the participant to use when adding this participant to an event, e.g. "Joe Bloggs". * *type*: "String" The method for sending scheduling messages to this identity, e.g. "imip" * *uri*: "String" The URI for sending scheduling messages to this identity, e.g. "mailto:foo@example.com" The user is an *owner* for an event if the CalendarEvent object has a "participants" property, and one of the Participant objects has both: a) The "owner" role. b) A "sendTo" property that has "type" and "uri" equal to one of the ParticipantIdentity objects returned with the calendar. o *shareWith*: "Id[CalendarRights]|null" A map of CalendarPrincipal id to rights for principals this calendar is shared with. The pricincipal to which this calendar belongs MUST NOT be in this set. This is null if the user requesting the object does not have the mayAdmin right, or if the calendar is not shared with anyone. May be modified only if the user has the mayAdmin right. o *shareesActAs*: "String" (immutable; default server-dependent) This MUST be one of: * "secretary" * "self" Jenkins & Douglass Expires September 11, 2020 [Page 14] Internet-Draft JMAP Calendars March 2020 If "self", sharees act as themselves when using this calendar. If "secretary", they act as the pricincipal to which this calendar belongs (secretary mode). If omitted, the default is server dependent. For example, it may be "self" if creating a calendar in a CalendarPrincipal representing a group, and "secretary" if creating a calendar for an individual. Users may attempt to set this on creation, but the server may reject with an "invalidProperties" error if the value is not permissible. o *myRights*: "CalendarRights" (server-set) The set of access rights the user has in relation to this Calendar. A *CalendarRights* object has the following properties: o *mayReadFreeBusy*: "Boolean" The user may read the free-busy information for this calendar as part of a call to CalendarPrincipal/getAvailability (see Section XXX). o *mayReadItems*: "Boolean" The user may fetch the events in this calendar. o *mayAddItems*: "Boolean" The user may create new events on this calendar or move events to this calendar. For recurring events, they may add an override to add an occurrence, or remove an existing override that is excluding an occurrence. o *mayUpdatePrivate*: "Boolean" The user may modify the following properties on all events in the calendar. If shareesActAs is "self", these properties MUST all be stored per-user, and changes do not affect any other user of the calendar. If shareesActAs is "secretary", the values are shared between all users. * keywords * color * freeBusyStatus * useDefaultAlerts * alerts The user may also modify the above on a per-occurrence basis for recurring events. o *mayRSVP*: "Boolean" The user may modify the "participationStatus", "participationComment", "expectReply" and "scheduleAgent" properties of any Participant object that is Jenkins & Douglass Expires September 11, 2020 [Page 15] Internet-Draft JMAP Calendars March 2020 represented in the "participantIdentities" property of the calendar. The user may also modify the above on a per-occurrence basis for recurring events. o *mayUpdateOwn*: "Boolean" The user may modify an existing event on this calendar if either they are the owner of the event or the event has no owner. o *mayUpdateAll*: "Boolean" The user may modify all existing events on this calendar. o *mayRemoveOwn*: "Boolean" The user may delete an event or move it to a different calendar if either they are the owner of the event or the event has no owner. For recurring events, they may add an override to remove an occurrence. o *mayRemoveAll*: "Boolean" The user may delete any event or move it to a different calendar. For recurring events, they may add an override to remove an occurrence. o *mayAdmin*: "Boolean" The user may modify sharing for this calendar. o *mayDelete*: "Boolean" (server-set) The user may delete the calendar itself. This property MUST be false if the account to which this calendar belongs has the _isReadOnly_ property set to true. 3.1. Per-user properties The following properties MUST be stored per-user: o name o color o sortOrder o isVisible 3.2. Calendar/get This is a standard "/get" method as described in [RFC8620], Section 5.1. The _ids_ argument may be "null" to fetch all at once. If mayReadFreeBusy is the only permission the user has, the calendar MUST NOT be returned in Calendar/get and Calendar/query; it must Jenkins & Douglass Expires September 11, 2020 [Page 16] Internet-Draft JMAP Calendars March 2020 behave as though it did not exist. The data is just used as part of CalendarPrincipal/getAvailability. 3.3. Calendar/changes This is a standard "/changes" method as described in [RFC8620], Section 5.2. 3.4. Calendar/set This is a standard "/set" method as described in [RFC8620], Section 5.3 but with the following additional request argument: o *onDestroyRemoveEvents*: "Boolean" (default: false) If false, any attempt to destroy a Calendar that still has CalendarEvents in it will be rejected with a "calendarHasEvents" SetError. If true, any CalendarEvents that were in the Calendar will be destroyed. This SHOULD NOT send scheduling messages to participants or create CalendarEventNotification objects. The "role" and "shareWith" properties may only be set by users that have the mayAdmin right. The value is shared across all users, although users without the mayAdmin right cannot see the value. Users can subscribe or unsubscribe to a calendar by setting the "isSubscribed" property. The server MAY forbid users from subscribing to certain calendars even though they have permission to see them, rejecting the update with a "forbidden" SetError. The "timeZone", "includeInAvailability", "defaultAlertsWithoutTime" and "defaultAlertsWithTime" properties are stored per-user if the calendar "shareesActAs" value is "self", and may be set by any user who is subscribed to the calendar. Otherwise, these properties are shared, and may only be set by users that have the mayAdmin right. The following properties may be set by anyone who is subscribed to the calendar and are all stored per-user: o name o color o sortOrder o isVisible Jenkins & Douglass Expires September 11, 2020 [Page 17] Internet-Draft JMAP Calendars March 2020 These properties are initially inherited from the owner's copy of the calendar, but if set by a sharee that user gets their own copy of the property; it does not change for any other principals. If the value of the property in the owner's calendar changes after this, it does not overwrite the sharee's value. The following extra SetError types are defined: For "destroy": o *calendarHasEvent*: The Calendar has at least one CalendarEvent assigned to it, and the "onDestroyRemoveEvents" argument was false. 4. Calendar Share Notifications The CalendarShareNotification data type records when the user's permissions to access a shared calendar changes. CalendarShareNotification are only created by the server; users cannot create them explicitly. Notifications are stored in the same Account as the CalendarPrincipals. Clients SHOULD present the list of notifications to the user and allow them to dismiss them. To dismiss a notification you use a standard "/set" call to destroy it. The server SHOULD create a CalendarShareNotification whenever the user's permissions change on a calendar. It SHOULD NOT create a notification for permission changes to a group principal, even if the user is in the group. 4.1. Auto-deletion of Notifications The server MAY limit the maximum number of notifications it will store for a user. When the limit is reached, any new notification will cause the previously oldest notification to be automatically deleted. The server MAY coalesce events if appropriate, or remove events that it deems are no longer relevant or after a certain period of time. The server SHOULD automatically destroy a notification about a calendar if the user subscribes to that calendar. 4.2. Object Properties The *CalendarShareNotification* object has the following properties: o *id*: "String" The id of the CalendarShareNotification. Jenkins & Douglass Expires September 11, 2020 [Page 18] Internet-Draft JMAP Calendars March 2020 o *created*: "UTCDate" The time this notification was created. o *changedBy*: "Person" Who made the change. * *name*: "String" The name of the person who made the change. * *email*: "String|null" The email of the person who made the change, or null if no email is available. * *calendarPrincipalId*: "String|null" The id of the CalendarPrincipal corresponding to the person who made the change, or null if no associated princiapal. o *calendarAccountId*: "String" The id of the account where this Calendar exists. o *calendarId*: "String" The id of the Calendar that this notification is about. o *calendarName*: "String" The name of the Calendar at the time the notification was made. o *oldRights*: "CalendarRights|null" The rights the user had before the change. o *newRights*: "CalendarRights|null" The rights the user has after the change. 4.3. CalendarShareNotification/get This is a standard "/get" method as described in [RFC8620], Section 5.1. 4.4. CalendarShareNotification/changes This is a standard "/changes" method as described in [RFC8620], Section 5.2. 4.5. CalendarShareNotification/set This is a standard "/changes" method as described in [RFC8620], Section 5.3. Only destroy is supported; any attempt to create/update MUST be rejected with a "forbidden" SetError. Jenkins & Douglass Expires September 11, 2020 [Page 19] Internet-Draft JMAP Calendars March 2020 4.6. CalendarShareNotification/query This is a standard "/query" method as described in [RFC8620], Section 5.5. 4.6.1. Filtering A *FilterCondition* object has the following properties: o *after*: "UTCDate|null" The creation date must be on or after this date to match the condition. o *before*: "UTCDate|null" The creation date must be before this date to match the condition. 4.6.2. Sorting The "created" property MUST be supported for sorting. 4.7. CalendarShareNotification/queryChanges This is a standard "/queryChanges" method as described in [RFC8620], Section 5.6. 5. Calendar Events A *CalendarEvent* object contains information about an event, or recurring series of events, that takes place at a particular time. It is a JSEvent object, as defined in [I-D.ietf-calext-jscalendar], with the following additional properties: o *id*: "Id" The id of the CalendarEvent. This property is immutable. The id uniquely identifies a JSEvent with a particular "uid" and "recurrenceId" within a particular account. o *calendarId*: "Id" The id of the Calendar this event belongs to. o *isDraft*: "Boolean" If true, this event is to be considered a draft. The server will not send any scheduling messages to participants or send push notifications for alerts. This may only be set to true upon creation. Once set to false, the value cannot be updated to true. This property MUST NOT appear in "recurrenceOverrides". o *utcStart*: "UTCDate" For simple clients that do not or cannot implement time zone support. Clients should only use this if also asking the server to expand recurrences, as you cannot accurately expand a recurrence without the original time zone. This property Jenkins & Douglass Expires September 11, 2020 [Page 20] Internet-Draft JMAP Calendars March 2020 is calculated at fetch time by the server. Time zones are political and they can and do change at any time. Fetching exactly the same property again may return a different results if the time zone data has been updated on the server. Time zone data changes are not considered "updates" to the event. If set, server will convert to the event's current time zone using its current time zone data and store the local time. This is not included by default and must be requested explicitly. Floating events will be interpreted as per calendar's time zone property; or if not set, the the principal's time zone property. Note that it is not possible to accurately calculate the expansion of recurrence rules or recurrence overrides with the utcStart property rather than the local start time. Even simple recurrences such as "repeat weekly" may cross a daylight-savings boundary and end up at a different UTC time. Clients that wish to use "utcStart" are RECOMMENDED to request the server expand recurrences (see Section XXX). o *utcEnd*: "UTCDate" The server calculates the end time in UTC from the start/timeZone/duration properties of the event. This is not included by default and must be requested explicitly. Like utcStart, this is calculated at fetch time if requested and may change due to time zone data changes. CalendarEvent objects MUST NOT have a "method" property as this is only used when representing iTIP [RFC5546] scheduling messages, not events in a data store. 5.1. Attachments The Link object, as defined in [I-D.ietf-calext-jscalendar] Section 4.2.7, with a "rel" property equal to "enclosure" is used to represent attachments. Instead of mandating an "href" property, clients may set a "blobId" property instead to reference a blob of binary data in the account, as per [RFC8620] Section 6. The server MUST translate this to an embedded "data:" URL [RFC2397] when sending the event to a system that cannot access the blob. Servers that support CalDAV access to the same data are recommended to expose these files as managed attachments [?@RFC8607]. 5.2. Per-user properties In shared calendars where "shareesActAs" is "self", the following properties MUST be stored per-user: o keywords o color Jenkins & Douglass Expires September 11, 2020 [Page 21] Internet-Draft JMAP Calendars March 2020 o freeBusyStatus o useDefaultAlerts o alerts The user may also modify these properties on a per-occurrence basis for recurring events; again, these MUST be stored per-user. When writing per-user properties, the "updated" property MUST also be stored just for that user. When fetching the "updated" property, the value to return is whichever is later of the per-user updated time or the updated time of the master event. 5.3. Recurring events Events may recur, in which case they represent multiple occurrences or instances. The data store will either contain a single master event, containing a recurrence rule and/or recurrence overrides; or, a set of individual instances (when invited to specific occurrences only). The client may ask the server to expand recurrences within a specific time range in "CalendarEvent/query". This will generate synthetic ids representing individual instances in the requested time range. The client can fetch and update the objects using these ids and the server will make the appropriate changes to the master event. Synthetic ids do not appear in "CalendarEvent/changes" responses; only the ids of events as actually stored on the server. If the user is invited to specific instances then later added to the master event, "CalendarEvent/changes" will show the ids of all the individual instances being destroyed and the id for the master event being created. 5.4. Updating for "this-and-future" When editing a recurring event, you can either update the master event (affecting all instances unless overriden) or update an override for a specific occurrence. To update all occurrences from a specific point onwards, there are therefore two options: split the event, or update the master and override all occurrences before the split point back to their original values. Jenkins & Douglass Expires September 11, 2020 [Page 22] Internet-Draft JMAP Calendars March 2020 5.4.1. Splitting an event If the event is not scheduled (has no participants), the simplest thing to do is to duplicate the event, modifying the recurrence rules of the original so it finishes before the split point, and the duplicate so it starts at the split point. As per JSCalendar {TODO:ref} Section 4.1.3, a "next" and "first" relation MUST be set on the new objects respectively. Splitting an event however is problematic in the case of a scheduled event, because the iTIP messages generated make it appear like two unrelated changes, which can be confusing. 5.4.2. Updating the master and overriding previous For scheduled events, a better approach is to avoid splitting and instead update the master event with the new property value for "this and future", then create overrides for all occurrences before the split point to restore the property to its previous value. Indeed, this may be the only option the user has permission to do if not an owner of the event. Clients may choose to skip creating the overrides if the old data is not important, for example if the "alerts" property is being updated, it is probably not important to create overrides for events in the past with the alerts that have already fired. 5.5. CalendarEvent/get This is a standard "/get" method as described in [RFC8620], Section 5.1, with three extra arguments: o *recurrenceOverridesBefore*: "UTCDate|null" If given, only recurrence overrides with a recurrence id on or after this date (when translated into UTC) will be returned. o *recurrenceOverridesAfter*: "UTCDate|null" If given, only recurrence overrides with a recurrence id before this date (when translated into UTC) will be returned. o *reduceParticipants*: "Boolean" (default: false) If true, only participants with the "owner" role or corresponding to the user's participant identities will be returned in the "participants" property of the master event and any recurrence overrides. If false, all participants will be returned. A CalendarEvent object is a JSEvent object so may have arbitrary properties. If the client makes a "CalendarEvent/get" call with a Jenkins & Douglass Expires September 11, 2020 [Page 23] Internet-Draft JMAP Calendars March 2020 null or omitted "properties" argument, all properties defined on the JSEvent object in the store are returned, along with the "id", "calendarId", and "isDraft" properties. The "utcStart" and "utcEnd" computed properties are only returned if explicitly requested. If either are requested, the "recurrenceOverrides" property MUST NOT be requested (recurrence overrides cannot be interpreted accurately with just the UTC times). If specific properties are requested from the JSEvent and the property is not present on the object in the server's store, the server SHOULD return the default value if known for that property. A requested id may represent a single instance of a recurring event if the client asked the server to expand recurrences in "CalendarEvent/query". In such a case, the server will resolve any overrides and set the appropriate "start" and "recurrenceId" properties on the CalendarEvent object returned to the client. The "recurrenceRule" and "recurrenceOverrides" properties MUST be returned as null if requested for such an event. An event with the same uid/recurrenceId may appear in different accounts. Clients may coalesce the view of such events, but must be aware that the data may be different in the different accounts due to per-user properties, difference in permissions etc. The "privacy" property of a JSEvent object allows the owner to override how sharees of the calendar see the event. If this is set to "private", when a sharee fetches the event the server MUST only return the basic time and metadata properties of the JSEvent object as specified in [I-D.ietf-calext-jscalendar], Section 4.4.3. If set to "secret", the server MUST behave as though the event does not exist for all users other than the owner. 5.6. CalendarEvent/changes This is a standard "/changes" method as described in [RFC8620], Section 5.2. 5.7. CalendarEvent/set This is a standard "/set" method as described in [RFC8620], Section 5.3, with the following extra argument: o *sendSchedulingMessages*: "Boolean" (default: true) If true then any changes to scheduled events will be sent to all the participants (if the user is an owner of the event) or back to the owners (otherwise). If false, the changes only affect this calendar and no scheduling messages will be sent. Jenkins & Douglass Expires September 11, 2020 [Page 24] Internet-Draft JMAP Calendars March 2020 For recurring events, an id may represent the master event or a specific instance. When the id for a specific instance is given, the server MUST process an update as an update to the recurrence override for that instance on the master event, and a destroy as removing just that instance. Clients MUST NOT send an update/destroy to both the master event and a specific instance in a single "/set" request; the result of this is undefined. Servers MUST enforce the user's permissions as returned in the "myRights" property of the Calendar object and reject changes with a "forbidden" SetError if not allowed. The "privacy" property MUST NOT be set to anything other than "public" (the default) for events in a calendar that does not belong to the user (e.g. a shared team calendar). The server MUST reject this with an "invalidProperties" SetError. The server MUST reject attempts to add events with a "participants" property where none of the participants correspond to one of the calendar's participant identities with a "forbidden" SetError. If omitted on create, the server MUST set the following properties to an appropriate value: o @type o uid o created o updated When modifying the event, the server MUST set the following properties if the server is the source of the event and the property is not explicitly set in the update: o updated: set to the current time. o sequence: increment by one, unless only per-user properties (see Section XXX) were changed. The "created" property MUST NOT be updated after creation. The "sequence" property MUST NOT be set to a lower number than its current value. The "method" property MUST NOT be set. Any attempt to do these is rejected with a standard "invalidProperties" SetError. Jenkins & Douglass Expires September 11, 2020 [Page 25] Internet-Draft JMAP Calendars March 2020 If "utcStart" is set, this is translated into a "start" property using the server's current time zone information. It MUST NOT be set in addition to a "start" property and it cannot be set inside "recurrenceOverrides"; this MUST be rejected with an "invalidProperties" SetError. Similarly, the "utcEnd" property is translated into a "duration" property if set. It MUST NOT be set in addition to a "duration" property and it cannot be set inside "recurrenceOverrides"; this MUST be rejected with an "invalidProperties" SetError. The server does not automatically reset the "partipationStatus" or "expectReply" properties of a Participant if the event details change. Clients should either be intelligent about whether the change necessitates resending RSVP requests, or ask the user whether to send them. The server MAY enforce that all events have an owner, for example in team calendars. If the user tries to create an event without participants in such a calendar, the server MUST automatically add a participant with the "owner" role corresponding to one of the user's "participantIdentities" for the calendar. When creating an event with participants, or adding participants to an event that previously did not have participants, the server MUST set the "replyTo" property of the event if not present. Clients SHOULD NOT set the replyTo property for events when the user adds participants; the server is better positioned to add all the methods it supports to receive replies. 5.7.1. Sending invitations and responses Unless "sendSchedulingMessages" is false, the server MUST send appropriate iTIP [RFC5546] scheduling messages after successfuly creating, updating or destroying a calendar event. When determining which scheduling messages to send, the server must first establish whether it is the _source_ of the event. The server is the source if it will receive messages sent to any of the methods specified in the "replyTo" property of the event. Messages are only sent to participants with a "scheduleAgent" property set to "server" or omitted. If the effective "scheduleAgent" property is changed: o to "server" from something else: send messages to this participant as though the event had just been created. Jenkins & Douglass Expires September 11, 2020 [Page 26] Internet-Draft JMAP Calendars March 2020 o from "server" to something else: send messages to this participant as though the event had just been destroyed. o any other change: do not send any messages to this participant. The server may send the scheduling message via any of the methods defined on the sendTo property of a participant (if the server is the source) or the replyTo property of the event (otherwise) that it supports. If no supported methods are available, the server MUST reject the change with a "noSupportedScheduleMethods" SetError. If the server is the source of the event it MUST NOT send messages to any participant corresponding to the participantIdentities of the calendar it is in. If sending via iMIP [RFC6047], the server MAY choose to only send updates it deems "essential" to avoid flooding the recipient's email with changes they do not care about. For example, changes to the participationStatus of another participant, or changes to events solely in the past may be omitted. 5.7.1.1. REQUEST When the server is the source for the event, a REQUEST message ([RFC5546], Section 3.2.2) is sent to all current participants if: o The event is being created. o Any non per-user property (see Section XXX) is updated on the event (including adding/removing participants), except if just modifying the recurrenceOverrides such that CANCEL messages are generated (see the next section). Note, if the only change is adding an additional instance (not generated by the event's recurrence rule) to the recurrenceOverrides, this MAY be handled via sending an ADD message ([RFC5546], Section 3.2.4) for the single instance rather than a REQUEST message for the master. However, for interoperability reasons this is not recommended due to poor support in the wild for this type of message. The server MUST ensure participants are only sent information about recurrence instances they are added to when sending scheduling messages for recurring events. If the participant is not invited to the master recurring event but only individual instances, scheduling messages MUST be sent for just those expanded occurrences individually. If a participant is invited to a recurring event, but removed via a recurrence override from a particular instance, any scheduling messages to this participant MUST return the instance as Jenkins & Douglass Expires September 11, 2020 [Page 27] Internet-Draft JMAP Calendars March 2020 "excluded" (if it matches a recurrence rule for the event) or omit the instance entirely (otherwise). 5.7.1.2. CANCEL When the server is the source for the event, a CANCEL message ([RFC5546], Section 3.2.5) is sent if: o A participant is removed from either the master event or a single instance (the message is only sent to this participant; remaining participants will get a REQUEST, as described above). o The event is destroyed. o An exclusion is added to recurrenceOverrides to remove an instance generated by the event's recurrence rule. o An additional instance (not generated by the event's recurrence rule) is removed from the recurrenceOverrides. In each of the latter 3 cases, the message is sent to all participants. 5.7.1.3. REPLY When the server is _not_ the source for the event, a REPLY message ([RFC5546], Section 3.2.3) is sent for any participant corresponding to the participantIdentities of the calendar it is in if: o The "participationStatus" property of the participant is changed. o The event is destroyed and the participationStatus was not "needs- action". o The event is created and the participationStatus is not "needs- action". o An exclusion is added to recurrenceOverrides to remove an instance generated by the event's recurrence rule. o An exclusion is removed from recurrenceOverrides (this is presumed to be the client undoing the deletion of a single instance). o An instance not generated by the event's recurrence rule is removed from the recurrenceOverrides. Jenkins & Douglass Expires September 11, 2020 [Page 28] Internet-Draft JMAP Calendars March 2020 o An instance not generated by the event's recurrence rule is added to the recurrenceOverrides (this is presumed to be the client undoing the deletion of a single instance). A reply is not sent when deleting an event where the current status is "needs-action" as if a junk calendar event gets added by an automated system, the user MUST be able to delete the event without sending a reply. 5.8. CalendarEvent/copy This is a standard "/copy" method as described in [RFC8620], Section 5.4. 5.9. CalendarEvent/query This is a standard "/query" method as described in [RFC8620], Section 5.5, with two extra arguments: o *expandRecurrences*: "Boolean" (default: false) If true, the server will expand any recurring event. If true, the filter MUST be just a FilterCondition (not a FilterOperator) and MUST include both a before and after property. This ensures the server is not asked to return an infinite number of results. o *timeZone*: "String" The time zone for before/after filter conditions (default: "Etc/UTC") If expandRecurrences is true, a separate id will be returned for each instance of a recurring event that matches the query. This synthetic id is opaque to the client, but allows the server to resolve the id + recurrence id for "/get" and "/set" operations. Otherwise, a single id will be returned for matching recurring events that represents the entire event. There is no necessary correspondence between the ids of different instances of the same expanded event. The following additional error may be returned instead of the "CalendarEvent/query" response: "cannotCalculateOccurrences": the server cannot expand a recurrence required to return the results for this query. Jenkins & Douglass Expires September 11, 2020 [Page 29] Internet-Draft JMAP Calendars March 2020 5.9.1. Filtering A *FilterCondition* object has the following properties: o *inCalendars*: "Id[]|null" A list of calendar ids. An event must be in ANY of these calendars to match the condition. o *after*: "LocalDate|null" The end of the event, or any recurrence of the event, in the time zone given as the timeZone argument, must be after this date to match the condition. o *before*: "LocalDate|null" The start of the event, or any recurrence of the event, in the time zone given as the timeZone argument, must be before this date to match the condition. o *text*: "String|null" Looks for the text in the _title_, _description_, _locations_ (matching name/description), _participants_ (matching name/email) and any other textual properties of the event or any recurrence of the event. o *title*: "String|null" Looks for the text in the _title_ property of the event, or the overridden _title_ property of a recurrence. o *description*: "String|null" Looks for the text in the _description_ property of the event, or the overridden _description_ property of a recurrence. o *location*: "String|null" Looks for the text in the _locations_ property of the event (matching name/description of a location), or the overridden _locations_ property of a recurrence. o *owner*: "String|null" Looks for the text in the name or email fields of a participant in the _participants_ property of the event, or the overridden _participants_ property of a recurrence, where the participant has a role of "owner". o *attendee*: "String|null" Looks for the text in the name or email fields of a participant in the _participants_ property of the event, or the overridden _participants_ property of a recurrence, where the participant has a role of "attendee". o *participationStatus*: Must match. If owner/attendee condition, status must be of that participant. Otherwise any. o *uid*: "String" The uid of the event is exactly the given string. If expandRecurrences is true, all conditions must match against the same instance of a recurring event for the instance to match. If Jenkins & Douglass Expires September 11, 2020 [Page 30] Internet-Draft JMAP Calendars March 2020 expandRecurrences is false, all conditions must match, but they may each match any instance of the event. If zero properties are specified on the FilterCondition, the condition MUST always evaluate to "true". If multiple properties are specified, ALL must apply for the condition to be "true" (it is equivalent to splitting the object into one-property conditions and making them all the child of an AND filter operator). The exact semantics for matching "String" fields is *deliberately not defined* to allow for flexibility in indexing implementation, subject to the following: o Text SHOULD be matched in a case-insensitive manner. o Text contained in either (but matched) single or double quotes SHOULD be treated as a *phrase search*, that is a match is required for that exact sequence of words, excluding the surrounding quotation marks. Use "\"", "\'" and "\\" to match a literal """, "'" and "\" respectively in a phrase. o Outside of a phrase, white-space SHOULD be treated as dividing separate tokens that may be searched for separately in the event, but MUST all be present for the event to match the filter. o Tokens MAY be matched on a whole-word basis using stemming (so for example a text search for "bus" would match "buses" but not "business"). 5.9.2. Sorting The following properties MUST be supported for sorting: o start o uid o recurrenceId The following properties SHOULD be supported for sorting: o created o updated Jenkins & Douglass Expires September 11, 2020 [Page 31] Internet-Draft JMAP Calendars March 2020 5.10. CalendarEvent/queryChanges This is a standard "/queryChanges" method as described in [RFC8620], Section 5.6. 5.11. Examples TODO: Add example of how to get event by uid: query uid=foo and backref. Return multiple with recurrenceId set (user invited to specific instances of recurring event). 6. Alerts Alerts may be specified on events as described in [I-D.ietf-calext-jscalendar], Section 4.5. If the "useDefaultAlerts" property is true, the alerts are taken from the Calendar "defaultAlertsWithTime" or "defaultAlertsWithoutTime" property, as described in Section XXX. Otherwise, the alerts are taken from the "alerts" property of the CalendarEvent. Alerts MUST only be triggered for events in calendars where the user is subscribed and either the user owns the calendar or the calendar's "shareesActAs" property is "self". When an alert with an "email" action is triggered, the server MUST send an email to the user to notify them of the event. The contents of the email is implementation specific. Clients MUST NOT perform an action for these alerts. When an alert with a "display" action is triggered, clients SHOULD display an alert in a platform-appropriate manner to the user to remind them of the event. Clients with a full offline cache of events may choose to calculate when alerts should trigger locally. Alternatively, they can subscribe to push events from the server. 6.1. Push events Servers that support the "urn:ietf:params:jmap:calendars" capability MUST support registering for the pseudo-type "CalendarAlert" in push subscriptions and event source connections, as described in [RFC8620], Sections 7.2 and 7.3. If requested, a CalendarAlert notification will be pushed whenever an alert is triggered for the user. For Event Source connections, this notification is pushed as an event called "calendaralert". A *CalendarAlert* object has the following properties: Jenkins & Douglass Expires September 11, 2020 [Page 32] Internet-Draft JMAP Calendars March 2020 o *@type*: "String" This MUST be the string "CalendarAlert". o *accountId*: "String" The account id for the calendar in which the alert triggered. o *calendarEventId*: "String" The CalendarEvent id for the alert that triggered. o *uid*: "String" The uid property of the CalendarEvent for the alert that triggered. o *recurrenceId*: "String|null" The recurrenceId for the instance of the event for which this alert is being triggered, or "null" if the event is not recurring. o *alertId*: "String" The id for the alert that triggered. 6.2. Acknowledging an alert To dismiss an alert, clients set the "acknowledged" property of the Alert object to the current date-time. When other clients fetch the CalendarEvent with the updated Alert they SHOULD automatically dismiss or suppress duplicate alerts (alerts with the same alert id that triggered on or before this date-time). Setting the "acknowledged" property MUST NOT create a new recurrence override. For a recurring calendar object, the "acknowledged" property of the parent object MUST be updated, unless the alert is already overridden in the "recurrenceOverrides" property. 6.3. Snoozing an alert Users may wish to dismiss an alert temporarily and have it come back after a specific period of time. To do this, clients MUST: 1. Acknowledge the alert as described in Section XXX. 2. Add a new alert with an "AbsoluteTrigger" for the date-time the alert has been snoozed until. Add a "relatedTo" property to the new alert, setting the "parent" relation to point to the original alert. This MUST NOT create a new recurrence override; it is added to the same "alerts" property that contains the alert being snoozed. When acknowledging a snoozed alert (i.e. one with a parent relatedTo pointing to the original alert), the client SHOULD delete the alert rather than setting the "acknowledged" property. Jenkins & Douglass Expires September 11, 2020 [Page 33] Internet-Draft JMAP Calendars March 2020 7. Calendar Event Notifications The CalendarEventNotification data type records changes made by external entities to events in calendars the user is subscribed to. Notifications are stored in the same Account as the CalendarEvent that was changed. Notifications are only created by the server; users cannot create them directly. Clients SHOULD present the list of notifications to the user and allow them to dismiss them. To dismiss a notification you use a standard "/set" call to destroy it. The server SHOULD create a CalendarEventNotification whenever an event is added, updated or destroyed by another user or due to receiving an iTIP [RFC5546] or other scheduling message in a calendar this user is subscribed to. The server SHOULD NOT create notifications for events implicitly deleted due to the containing calendar being deleted. 7.1. Auto-deletion of Notifications The server MAY limit the maximum number of notifications it will store for a user. When the limit is reached, any new notification will cause the previously oldest notification to be automatically deleted. The server MAY coalesce events if appropriate, or remove events that it deems are no longer relevant or after a certain period of time. The server SHOULD automatically destroy a notification about an event if the user updates or destroys that event (e.g. if the user sends an RSVP for the event). 7.2. Object Properties The *CalendarEventNotification* object has the following properties: o *id*: "String" The id of the CalendarEventNotification. o *created*: "UTCDate" The time this notification was created. o *changedBy*: "Person" Who made the change. * *name*: "String" The name of the person who made the change. * *email*: "String" The email of the person who made the change, or null if no email is available. Jenkins & Douglass Expires September 11, 2020 [Page 34] Internet-Draft JMAP Calendars March 2020 * *calendarPrincipalId*: "String|null" The id of the calendar principal corresponding to the person who made the change, if any. This will be null if the change was due to receving an iTIP message. o *comment*: "String|null" Comment sent along with the change by the user that made it. (e.g. COMMENT property in an iTIP message). o *type*: "String" This MUST be one of * created * updated * destroyed o *calendarEventId*: "String" The id of the CalendarEvent that this notification is about. o *isDraft*: "Boolean" (created/updated only) Is this event a draft? o *event*: "JSEvent" The data before the change (if updated or destroyed), or the data after creation (if created). o *eventPatch*: "PatchObject" (updated only) A patch encoding the change between the data in the event property, and the data after the update. To reduce data, if the change only affects a single instance of a recurring event, the server MAY set the event and eventPatch properties for the instance; the calendarEventId MUST still be for the master event. 7.3. CalendarEventNotification/get This is a standard "/get" method as described in [RFC8620], Section 5.1. 7.4. CalendarEventNotification/changes This is a standard "/changes" method as described in [RFC8620], Section 5.2. 7.5. CalendarEventNotification/set This is a standard "/changes" method as described in [RFC8620], Section 5.3. Jenkins & Douglass Expires September 11, 2020 [Page 35] Internet-Draft JMAP Calendars March 2020 Only destroy is supported; any attempt to create/update MUST be rejected with a "forbidden" SetError. 7.6. CalendarEventNotification/query This is a standard "/query" method as described in [RFC8620], Section 5.5. 7.6.1. Filtering A *FilterCondition* object has the following properties: o *after*: "UTCDate|null" The creation date must be on or after this date to match the condition. o *before*: "UTCDate|null" The creation date must be before this date to match the condition. o *type*: "String" The type property must be the same to match the condition. o *calendarEventIds*: "Id[]|null" A list of event ids. The calendarEventId property of the notification must be in this list to match the condition. 7.6.2. Sorting The "created" property MUST be supported for sorting. 7.7. CalendarEventNotification/queryChanges This is a standard "/queryChanges" method as described in [RFC8620], Section 5.6. 8. Security Considerations All security considerations of JMAP [RFC8620] and JSCalendar [I-D.ietf-calext-jscalendar] apply to this specification. Additional considerations specific to the data types and functionality introduced by this document are described in the following subsections. 8.1. Denial-of-service Expanding Recurrences Recurrence rules can be crafted to occur as frequently as every second. Servers MUST be careful to not allow resources to be exhausted when expanding. Equally, rules can be generated that never Jenkins & Douglass Expires September 11, 2020 [Page 36] Internet-Draft JMAP Calendars March 2020 create any occurrences at all. Servers MUST be careful to limit the work spent iterating in search of the next occurrence. 8.2. Privacy TODO. 9. IANA Considerations 9.1. JMAP Capability Registration for "calendars" IANA will register the "calendars" JMAP Capability as follows: Capability Name: "urn:ietf:params:jmap:calendars" Specification document: this document Intended use: common Change Controller: IETF Security and privacy considerations: this document, Section XXX 9.2. Reservation of JMAP attributes in JSCalendar Property registry TODO. 10. References 10.1. Normative References [I-D.ietf-calext-jscalendar] Jenkins, N. and R. Stepanek, "JSCalendar: A JSON representation of calendar data", draft-ietf-calext- jscalendar-26 (work in progress), March 2020. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/info/rfc2119>. [RFC2397] Masinter, L., "The "data" URL scheme", RFC 2397, DOI 10.17487/RFC2397, August 1998, <https://www.rfc-editor.org/info/rfc2397>. Jenkins & Douglass Expires September 11, 2020 [Page 37] Internet-Draft JMAP Calendars March 2020 [RFC5546] Daboo, C., Ed., "iCalendar Transport-Independent Interoperability Protocol (iTIP)", RFC 5546, DOI 10.17487/RFC5546, December 2009, <https://www.rfc-editor.org/info/rfc5546>. [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/info/rfc8174>. [RFC8620] Jenkins, N. and C. Newman, "The JSON Meta Application Protocol (JMAP)", RFC 8620, DOI 10.17487/RFC8620, July 2019, <https://www.rfc-editor.org/info/rfc8620>. 10.2. Informative References [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, DOI 10.17487/RFC4791, March 2007, <https://www.rfc-editor.org/info/rfc4791>. [RFC6047] Melnikov, A., Ed., "iCalendar Message-Based Interoperability Protocol (iMIP)", RFC 6047, DOI 10.17487/RFC6047, December 2010, <https://www.rfc-editor.org/info/rfc6047>. Authors' Addresses Neil Jenkins Fastmail PO Box 234, Collins St West Melbourne VIC 8007 Australia Email: neilj@fastmailteam.com URI: https://www.fastmail.com Michael Douglass Spherical Cow Group 226 3rd Street Troy NY 12180 United States of America Email: mdouglass@sphericalcowgroup.com URI: http://sphericalcowgroup.com Jenkins & Douglass Expires September 11, 2020 [Page 38]