JMAP for Calendars

1.1. Notational Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

Type signatures, examples, and property descriptions in this document follow the conventions established in Section 1.1 of [RFC8620]. The Id, UnsignedInt, Date and UTCDate data types defined in Sections 1.2, 1.3 and 1.4 of [RFC8620] are also used in this document.¶

1.2. The LocalDate Data Type

Where LocalDate is given as a type, it means a string in the same format as Date (see Section 1.4 of [RFC8620]), but with the time-offset omitted from the end. For example, 2014-10-30T14:12:00. The interpretation in absolute time depends upon the time zone for the event, which may not be a fixed offset (for example when daylight saving time occurs).¶

1.3. The Duration Data Type

Where Duration is given as a type, it means a length of time represented by a subset of the ISO 8601 duration format, as defined in Section 1.4.6 of [RFC8984].¶

1.4. Terminology

The same terminology is used in this document as in the core JMAP specification, see Section 1.6 of [RFC8620].¶

The terms ParticipantIdentity, Calendar, CalendarEvent, and CalendarEventNotification (with these specific capitalizations) are used to refer to the data types defined in this document and instances of those data types.¶

1.5. Data Model Overview

An Account (see Section 1.6.2 of [RFC8620]) with support for the calendar data model contains zero or more Calendar objects, which is a named collection of CalendarEvents. Calendars can also provide defaults, such as alerts and a color to apply to events in the calendar. Clients commonly let users toggle visibility of events belonging to a particular calendar on/off. Servers may allow an event to belong to multiple Calendars within an account.¶

A CalendarEvent is a representation of an event or recurring series of events in JSCalendar Event [RFC8984] format. Simple clients may ask the server to expand recurrences for them within a specific time period, and optionally convert times into UTC so they do not have to handle time zone conversion. More full-featured clients will want to access the full event information and handle recurrence expansion and time zone conversion locally.¶

CalendarEventNotification objects keep track of the history of changes made to a calendar by other users, allowing calendar clients to notify the user of changes to their schedule.¶

The ParticipantIdentity data type represents the identities of the current user within an Account, which determines which events the user is a participant of and possibly their permissions related to that event.¶

In servers with support for JMAP Sharing [I-D.ietf-jmap-sharing], data may be shared with other users. Sharing permissions are managed per calendar. For example, an individual may have separate calendars for personal and work activities, with both contributing to their free-busy availability, but only the work calendar shared in its entirety with colleagues. Principals may also represent schedulable entities, such as a meeting room.¶

Users can normally subscribe to any calendar to which they have access. This indicates the user wants this calendar to appear in their regular list of calendars. The separate "isVisible" property stores whether the user would currently like to view the events in a subscribed calendar.¶

1.6. Addition to the Capabilities Object

The capabilities object is returned as part of the JMAP Session object; see Section 2 of [RFC8620]. This document defines three additional capability URIs.¶

2.1. Principal Capability urn:ietf:params:jmap:calendars

A urn:ietf:params:jmap:calendars property is added to the Principal "capabilities" object, the value of which is an object with the following properties:¶

• accountId: Id|null¶

  Id of Account with the urn:ietf:params:jmap:calendars capability that contains the calendar data for this principal, or null if none (e.g. the Principal is a group just used for permissions management), or the user does not have access to any data in the account (with the exception of free/busy, which is governed by the mayGetAvailability property). The corresponding Account object can be found in the principal's "accounts" property, as per Section 2 of [I-D.ietf-jmap-sharing].¶

• mayGetAvailability: Boolean¶

  May the user call the "Principal/getAvailability" method with this Principal?¶

• mayShareWith: Boolean¶

  May the user add this principal as a calendar sharee (by adding them to the shareWith property of a calendar, see Section 4)?¶

• scheduleId: String¶

  If this principal may be added as a participant to an event, this is the scheduleId to use to represent it.¶

• sendTo: String[String]|null¶

  If this principal may be added as a participant to an event, this is the Participant#sendTo property to add (see Section 4.4.5 of [RFC8984]) for scheduling messages to reach it.¶

2.2. Principal/getAvailability

This method calculates the availability of the principal for scheduling within a requested time period. It takes the following arguments:¶

• accountId: Id¶

  The id of the account to use.¶

• id: Id¶

  The id of the Principal to calculate availability for.¶

• utcStart: UTCDate¶

  The start time (inclusive) of the period for which to return availability.¶

• utcEnd: UTCDate¶

  The end time (exclusive) of the period for which to return availability.¶

• showDetails: Boolean¶

  If true, event details will be returned if the user has permission to view them.¶

• eventProperties: String[]|null¶

  A list of properties to include in any JSCalendar Event object returned. If null, all properties of the event will be returned. Otherwise, only properties with names in the given list will be returned.¶

The server will first find all relevant events, expanding any recurring events. Relevant events are ones where all of the following is true:¶

• The principal is subscribed to the calendar.¶

• The "includeInAvailability" property of the calendar for the principal is "all" or "attending".¶

• The user has the "mayReadFreeBusy" permission for the calendar.¶

• The event finishes after the "utcStart" argument and starts before the "utcEnd" argument.¶

• The event's "privacy" property is not "secret".¶

• The "freeBusyStatus" property of the event is "busy" (or omitted, as this is the default).¶

• The "status" property of the event is not "cancelled".¶

• If the "includeInAvailability" property of the calendar is "attending", then the principal is a participant of the event, and has a "participationStatus" of "accepted" or "tentative".¶

If an event is in more than one calendar, it is relevant if all of the above are true for any one calendar that it is in.¶

The server then generates a BusyPeriod object for each of these events. A BusyPeriod object has the following properties:¶

• utcStart: UTCDate¶

  The start time (inclusive) of the period this represents.¶

• utcEnd: UTCDate¶

  The end time (exclusive) of the period this represents.¶

• busyStatus: String (optional, default "unavailable")¶

  This MUST be one of¶

  • confirmed: The event status is "confirmed" and the principal's¶

    "participationStatus" is "attending".¶

  • tentative: The event status is "tentative" or the principal's¶

    "participationStatus" is "tentative".¶

  • unavailable: The principal is not available for scheduling at this time¶

    for any other reason.¶

• event: JSCalendar Event|null¶

  The JSCalendar Event representation of the event, or null if any of the following are true:¶

  • The "showDetails" argument is false.¶

  • The "privacy" property of the event is "private".¶

  • The user does not have the "mayReadItems" permission for any of the calendars the event is in.¶

  If an eventProperties argument was given, any properties in the JSCalendar Event that are not in the eventProperties list are removed from the returned representation.¶

The server MAY also generate BusyPeriod objects based on other information it has about the principal's availability, such as office hours.¶

Finally, the server MUST merge and split BusyPeriod objects where the "event" property is null, such that none of them overlap and either there is a gap in time between any two objects (the utcEnd of one does not equal the utcStart of another) or those objects have a different busyStatus property. If there are overlapping BusyPeriod time ranges with different "busyStatus" properties the server MUST choose the value in the following order: confirmed > unavailable > tentative.¶

The response has the following argument:¶

• list: BusyPeriod[]¶

  The list of BusyPeriod objects calculated as described above.¶

The following additional errors may be returned instead of the "Principal/getAvailability" response:¶

notFound: No principal with this id exists, or the user does not have permission to see that this principal exists.¶

forbidden: The user does not have permission to query this principal's availability.¶

tooLarge: The duration between utcStart and utcEnd is longer than the server is willing to calculate availability for.¶

rateLimit: Too many availability requests have been made recently and the user is being rate limited. It may work to try again later.¶

3.1. ParticipantIdentity/get

This is a standard "/get" method as described in Section 5.1 of [RFC8620]. The "ids" argument may be null to fetch all at once.¶

3.2. ParticipantIdentity/changes

This is a standard "/changes" method as described in Section 5.2 of [RFC8620].¶

3.3. ParticipantIdentity/set

This is a standard "/set" method as described in Section 5.3 of [RFC8620], but with the following additional request argument:¶

• onSuccessSetIsDefault: Id|null¶

  If an id is given, and all creates, updates and destroys (if any) succeed without error, the server will try to set this identity as the default. (For references to ParticipantIdentity creations, this is equivalent to a creation-reference, so the id will be the creation id prefixed with a "#".)¶

If the id is not found, or the change is not permitted by the server for policy reasons, it MUST be ignored and the currently default ParticipantIdentity (if any) will remain as such. No error is returned to the client in this case.¶

As per Section 5.3 of [RFC8620], if the default is successfully changed, any changed objects MUST be reported in either the "created" or "updated" argument in the response as appropriate, with the server-set value included.¶

The server MAY restrict the uri values the user may claim, for example only allowing mailto: URIs with email addresses that belong to the user. A standard forbidden error is returned to reject non-permissible changes.¶

4.1. Calendar/get

This is a standard "/get" method as described in Section 5.1 of [RFC8620]. 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 behave as though it did not exist. The data is just used as part of Principal/getAvailability.¶

4.2. Calendar/changes

This is a standard "/changes" method as described in Section 5.2 of [RFC8620].¶

4.3. Calendar/set

This is a standard "/set" method as described in Section 5.3 of [RFC8620] but with the following additional request arguments:¶

• onDestroyRemoveEvents: Boolean (default: false)¶

  If false, any attempt to destroy a Calendar that still has CalendarEvents in it will be rejected with a calendarHasEvent SetError. If true, any CalendarEvents that were in the Calendar will be removed from it, and if in no other Calendars they will be destroyed. This SHOULD NOT send scheduling messages to participants or create CalendarEventNotification objects.¶

• onSuccessSetIsDefault: Id|null¶

  If an id is given, and all creates, updates and destroys (if any) succeed without error, the server will try to set this calendar as the default. (For references to Calendar creations, this is equivalent to a creation-reference, so the id will be the creation id prefixed with a "#".)¶

  If the id is not found, or the change is not permitted by the server for policy reasons, it MUST be ignored and the currently default calendar (if any) will remain as such. No error is returned to the client in this case.¶

  As per Section 5.3 of [RFC8620], if the default is successfully changed, any changed objects MUST be reported in either the "created" or "updated" argument in the response as appropriate, with the server-set value included.¶

The "shareWith" property may only be set by users that have the mayAdmin right. When modifying the shareWith property, the user cannot give a right to a principal if the principal did not already have that right and the user making the change also does not have that right. Any attempt to do so must be rejected with a forbidden SetError.¶

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 following properties may be set by anyone who is subscribed to the calendar and are always stored per-user:¶

• name¶

• color¶

• sortOrder¶

• isVisible¶

• timeZone¶

• includeInAvailability¶

• defaultAlertsWithoutTime¶

• defaultAlertsWithTime¶

The "name", "color", and "timeZone" properties are initially inherited from the owner's copy of the calendar, but if set by a sharee then they get 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 "sortOrder", "isVisible", "includeInAvailability", "defaultAlertsWithTime", and "defaultAlertsWithoutTime" properties are initally the default value for each sharee; they are not inherited from the owner.¶

The following extra SetError types are defined:¶

For "destroy":¶

• calendarHasEvent: The Calendar has at least one CalendarEvent assigned to it, and the "onDestroyRemoveEvents" argument was false.¶

5.1. Additional JSCalendar properties

This document defines four new JSCalendar properties for common use.¶

5.2. Attachments

The Link object, as defined in Section 4.2.7 of [RFC8984], 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 Section 6 of [RFC8620].¶

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.3. Per-user properties

In shared calendars, any top-level property registered in the IANA registry as "Is Per-User: yes" (see Section 10.3) MUST be stored per-user. This includes:¶

• keywords¶

• color¶

• freeBusyStatus¶

• useDefaultAlerts¶

• alerts¶

If the user modifies any such properties on a per-occurrence basis for recurring events then again, these MUST also be stored per-user. Sharees initially receive the default value for each of these properties, not whatever value another user may have set.¶

When writing only per-user properties, the "updated" property MUST also be stored just for that user if set. 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 base event.¶

5.4. Recurring events

Events may recur, in which case they represent multiple occurrences or instances. The data store will either contain a single base 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 base 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 base event, "CalendarEvent/changes" will show the ids of all the individual instances being destroyed and the id for the base event being created.¶

5.5. Updating for "this-and-future"

When editing a recurring event, you can either update the base 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 base event and override all occurrences before the split point back to their original values.¶

5.6. CalendarEvent/get

This is a standard "/get" method as described in Section 5.1 of [RFC8620], with three extra arguments:¶

• recurrenceOverridesBefore: UTCDate|null¶

  If given, only recurrence overrides with a recurrence id before this date (when translated into UTC) will be returned.¶

• recurrenceOverridesAfter: UTCDate|null¶

  If given, only recurrence overrides with a recurrence id on or after this date (when translated into UTC) will be returned.¶

• 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 base event and any recurrence overrides. If false, all participants will be returned.¶

• timeZone: String (default "Etc/UTC")¶

  The time zone to use when calculating the utcStart/utcEnd property of floating events. This argument has no effect if those properties are not requested.¶

A CalendarEvent object is a JSCalendar Event object so may have arbitrary properties. If the client makes a "CalendarEvent/get" call with a null or omitted "properties" argument, all properties defined on the JSCalendar Event object in the store are returned, along with the "id", "calendarIds", "isDraft", and "isOrigin" 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 JSCalendar Event 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 server-expanded 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 "recurrenceRules" 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 "hideAttendees" property of a JSCalendar Event object allows the event owner(s) to reduce the visibility of sharees into the set of participants. If this is true, when a non-owner sharee fetches the event, the server MUST only return participants with the "owner" role or corresponding to the user's participant identities.¶

The "privacy" property of a JSCalendar Event object allows the principal that owns the calendar to override how sharees of the calendar see the event. If set to "private", then when a sharee fetches the event the server MUST only return properties that are:¶

• the basic time and metadata properties of the JSCalendar Event object as specified in Section 4.4.3 of [RFC8984]; or¶

• properties that are wholly derived from these permitted properties (i.e., utcStart, utcEnd); or¶

• Additional CalendarEvent properties not derived from the JSCalendar Event data (i.e., id, baseEventId, calendarIds, isDraft, isOrigin).¶

If "privacy" is set to "secret", the server MUST behave as though the event does not exist for all users other than the principal that owns the calendar.¶

5.7. CalendarEvent/changes

This is a standard "/changes" method as described in Section 5.2 of [RFC8620].¶

Synthetic ids generated by the server expanding recurrences in "CalendarEvent/query" do not appear in "CalendarEvent/changes" responses; only the ids of events as actually stored on the server.¶

5.8. CalendarEvent/set

This is a standard "/set" method as described in Section 5.3 of [RFC8620], with the following extra argument:¶

• sendSchedulingMessages: Boolean (default: false)¶

  If true then any changes to scheduled events will be sent to all the participants (if the server is the origin of the event) or back to the origin (otherwise). If false, the changes only affect this account and no scheduling messages will be sent.¶

An id may represent a server-expanded single instance of a recurring event if the client asked the server to expand recurrences in "CalendarEvent/query". When the synthetic id for such an instance is given, the server MUST process an update as an update to the recurrence override for that instance on the base event, and a destroy as removing just that instance.¶

Clients MUST NOT send an update/destroy to both the base event and a synthetic instance in a single "/set" request; the result of this is undefined. Note however, a client may replace a series of explicit instances (each with the same uid but a different recurrenceId property) with the base event (same uid, no recurrenceId) in a single "/set" call. (So the /set will destroy the existing instances and create the new base event.) This will happen when someone is initially invited to a specific instance or instances of a recurring event, then later invited to the whole series.¶

If a property is set to null in a create/update, this is equivalent to omitting/removing the property from the JSCalendar Event object.¶

Servers MUST enforce the user's permissions as returned in the "myRights" property of the Calendar objects and reject changes with a forbidden SetError if not allowed.¶

The "privacy" property of a JSCalendar Event object allows the principal to override how sharees of the calendar see the event. If this is set to "private", a sharee may not delete or update the event (even if only modifying per-user properties); any attempt to modify such an event MUST be rejected with a forbidden SetError. If set to "secret", the server MUST behave as though the event does not exist for all users other than the principal that owns the calendar.¶

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, or a calendar shared by another user). The server MUST reject this with an invalidProperties SetError.¶

If omitted on create, the server MUST set the following properties to an appropriate value:¶

• @type¶

• uid¶

• created¶

If (and only if) the server is the origin of the event (i.e., the event's "isOrigin" property is true), the "updated" property MUST be set to the current time by the server whenever an event is created or updated. If the client tries to set a value for this property it is not an error, but it MUST be overridden and replaced with the server's time. If the event is being created and the overridden "updated" time is now earlier than a client-supplied "created" time, the "created" time MUST also be overridden to the server's time. If the server is not the origin of the event it MUST NOT automatically set an "updated" time, as this can break correct processing of iTIP messages.¶

Clients SHOULD NOT allow users to manually edit anything other than per-user properties when the "isOrigin" property is false, even if the calendar "myRights" allows them to do so. All other properties may be overwritten when a future update arrives to this event from the origin (i.e., via another iTIP REQUEST). Such updates may be directly applied by the server, or applied at the user's request by a client if it has access to the data through some other means (e.g., the client also has access to the user's email and can parse an iMIP message).¶

When updating an event, if all of:¶

• a property has been changed other than "calendarIds", "isDraft", "updated" or a per-user property (see Section 5.3); and¶

• the server is the origin of the event (the "isOrigin" property is true); and¶

• the "sequence" property is not explicitly set in the update, or the given value is less than or equal to the current "sequence" value on the server;¶

then the server MUST increment the "sequence" value by one.¶

The "method" property MUST NOT be set. Any attempt to do so is rejected with a standard invalidProperties SetError.¶

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 when changing other event details. Clients should either be intelligent about whether the change invalidates previous RSVPs, or ask the user whether to reset 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 (see Section 3).¶

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.¶

{
  "id": "123",
  "title": "FooBar team meeting",
  "start": "2018-01-08T09:00:00",
  "recurrenceRules": [{
   "@type": "RecurrenceRule",
   "frequency": "weekly"
  }],
  "replyTo": {
   "imip": "mailto:6489-4f14-a57f-c1@schedule.example.com"
  },
  "participants": {
   "dG9tQGZvb2Jhci5xlLmNvbQ": {
     "@type": "Participant",
     "name": "Tom",
     "email": "tom@foobar.example.com",
     "scheduleId": "mailto:6489-4f14-a57f-c1@calendar.example.com",
     "sendTo": {
       "imip": "mailto:6489-4f14-a57f-c1@calendar.example.com"
     },
     "participationStatus": "accepted",
     "roles": {
       "attendee": true
     }
   },
   "em9lQGZvb2GFtcGxlLmNvbQ": {
     "@type": "Participant",
     "name": "Zoe",
     "email": "zoe@foobar.example.com",
     "scheduleId": "mailto:zoe@foobar.example.com"
     "sendTo": {
       "imip": "mailto:zoe@foobar.example.com",
       "other": "https://foobar.example.com/zoe/itip"
     },
     "participationStatus": "accepted",
     "roles": {
       "owner": true,
       "attendee": true,
       "chair": true
     }
   },
   "recurrenceOverrides": {
     "2018-03-08T09:00:00": {
       "start": "2018-03-08T10:00:00",
       "participants/dG9tQGZvb2Jhci5xlLmNvbQ/participationStatus":
                                                           "declined"
     }
   }
  }
}

[[ "CalendarEvent/set", {
  "accountId": "ue150411c",
  "update": {
    "123": {
      "recurrenceOverrides/2018-03-08T09:00:00/
          participants~1em9lQGZvb2GFtcGxlLmNvbQ~1participationStatus":
              "declined"
    }
  }
}, "0" ]]

"recurrenceOverrides": {
  "2018-03-08T09:00:00": {
    "start": "2018-03-08T10:00:00",
    "participants/dG9tQGZvb2Jhci5xlLmNvbQ/participationStatus":
                                                       "declined",
    "participants/em9lQGZvb2GFtcGxlLmNvbQ/participationStatus":
                                                       "declined"
  }
}

[[ "CalendarEvent/set", {
  "accountId": "ue150411c",
  "update": {
    "123": {
      "recurrenceOverrides/2018-03-08T09:00:00/
          participants~1dG9tQGZvb2Jhci5xlLmNvbQ~1participationStatus": null
    }
  }
}, "0" ]]

[[ "CalendarEvent/set", {
  "accountId": "ue150411c",
  "update": {
    "123": {
      "recurrenceOverrides/2018-03-08T09:00:00/
          participants~1dG9tQGZvb2Jhci5xlLmNvbQ": null
    }
  }
}, "0" ]]

[[ "CalendarEvent/set", {
  "accountId": "ue150411c",
  "update": {
    "123": {
      "recurrenceOverrides/2018-03-08T09:00:00": {
        "start": "2018-03-08T10:00:00",
        "participants/em9lQGZvb2GFtcGxlLmNvbQ/participationStatus":
                                                       "declined"
        "participants/dG9tQGZvb2Jhci5xlLmNvbQ": null
      }
    }
  }
}, "0" ]]

5.9. CalendarEvent/copy

This is a standard "/copy" method as described in Section 5.4 of [RFC8620].¶

5.10. CalendarEvent/query

This is a standard "/query" method as described in Section 5.5 of [RFC8620], with two extra arguments:¶

• 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.¶

• 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.¶

5.11. CalendarEvent/queryChanges

This is a standard "/queryChanges" method as described in Section 5.6 of [RFC8620].¶

5.12. CalendarEvent/parse

This method allows the client to parse blobs as iCalendar files [RFC5545] to get CalendarEvent objects. This can be used to parse, display, and import information from iCalendar files without having to implement iCalendar parsing in the client. Server support for this is optional, and indicated via the urn:ietf:params:jmap:calendars:parse capability, as per Section 1.6.3.¶

The following metadata properties on the CalendarEvent objects will be null if requested:¶

• id¶

• baseEventId¶

• calendarIds¶

• isDraft¶

• isOrigin¶

The "CalendarEvent/parse" method takes the following arguments:¶

• accountId: Id¶

  The id of the account to use.¶

• blobIds: Id[]¶

  The ids of the blobs to parse.¶

• properties: String[]¶

  If supplied, only the properties listed in the array are returned for each CalendarEvent object. If omitted, defaults to all the properties.¶

The response object contains the following arguments:¶

• accountId: Id¶

  The id of the account used for the call.¶

• parsed: Id[CalendarEvent[]]|null¶

  A map of blob ids to parsed CalendarEvent objects representations for each successfully parsed blob, or null if none.¶

• notFound: Id[]|null¶

  A list of blob ids given that could not be found, or null if none.¶

• notParsable: Id[]|null¶

  A list of blob ids given that corresponded to blobs that could not be parsed as CalendarEvents, or null if none.¶

Parsed iCalendars are to be converted into CalendarEvent objects following the process defined in the JSCalendar: Converting from and to iCalendar document.¶

6.1. Default alerts

If the "useDefaultAlerts" property of an event is true, the alerts are taken from the "defaultAlertsWithTime" or "defaultAlertsWithoutTime" property of all Calendars (see Section 4) the event is in, rather than the "alerts" property of the CalendarEvent.¶

When using default alerts, the "alerts" property of the event is ignored except for the following:¶

• The "acknowledged" time for an alert is stored here when a default alert for the event is dismissed. The id of the alert MUST be the same as the id of the default alert in the calendar. See Section 6.2 on acknowledging alerts.¶

• If an alert has a relatedTo property where the parent is the id of one of the calendar default alerts, it is processed as normal and not ignored. This is to support snoozing default alerts; see Section 6.3.¶

6.2. Acknowledging an alert

To dismiss an alert, clients set the "acknowledged" property of the Alert object to the current date-time. If the alert was a calendar default, it may need to be added to the event at this point in order to acknowledge it. When other clients fetch the updated CalendarEvent they SHOULD automatically dismiss or suppress duplicate alerts (alerts with the same alert id that triggered on or before the "acknowledged" date-time) and alerts that have been removed from the event.¶

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 6.2.¶

2. Add a new alert to the event 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 that was acknowledged in step 1.¶

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.¶

6.4. 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:¶

• @type: String¶

  This MUST be the string "CalendarAlert".¶

• accountId: Id¶

  The account id for the calendar in which the alert triggered.¶

• calendarEventId: Id¶

  The CalendarEvent id for the alert that triggered. Note, for a recurring event this is the id of the base event, never a synthetic id for a particular instance.¶

• uid: String¶

  The uid property of the CalendarEvent for the alert that triggered.¶

• recurrenceId: LocalDate|null¶

  The recurrenceId for the instance of the event for which this alert is being triggered, or null if the event is not recurring.¶

• alertId: String¶

  The id for the alert that triggered.¶

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:¶

• id: Id¶

  The id of the CalendarEventNotification.¶

• created: UTCDate¶

  The time this notification was created.¶

• changedBy: Person¶

  Who made the change. The Person object has the following properties:¶

  • 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.¶

  • principalId: Id|null¶

    The id of the 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.¶

  • scheduleId: String|null¶

    The scheduleId URI of the person who made the change, if any. This will normally be set if the change was made due to receving an iTIP message.¶

• comment: String|null¶

  Comment sent along with the change by the user that made it. (e.g. COMMENT property in an iTIP message), if any.¶

• type: String¶

  This MUST be one of¶

  • created¶

  • updated¶

  • destroyed¶

• calendarEventId: Id¶

  The id of the CalendarEvent that this notification is about.¶

• isDraft: Boolean (created/updated only)¶

  Is this event a draft?¶

• event: JSCalendar Event¶

  The data before the change (if updated or destroyed), or the data after creation (if created).¶

• eventPatch: PatchObject (updated only)¶

  A patch encoding the change between the data in the event property, and the data after the update.¶

If the change only affects a single instance of a recurring event, the server MAY set the event and eventPatch properties for just that instance; the calendarEventId MUST still be for the base event.¶

7.3. CalendarEventNotification/get

This is a standard "/get" method as described in Section 5.1 of [RFC8620].¶

7.4. CalendarEventNotification/changes

This is a standard "/changes" method as described in Section 5.2 of [RFC8620].¶

7.5. CalendarEventNotification/set

This is a standard "/set" method as described in Section 5.3 of [RFC8620].¶

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 Section 5.5 of [RFC8620].¶

7.7. CalendarEventNotification/queryChanges

This is a standard "/queryChanges" method as described in Section 5.6 of [RFC8620].¶

8.1. Fetching initial data

A user has authenticated and the client has fetched the JMAP Session object. It finds a single Account with the urn:ietf:params:jmap:calendars capability, with id "a0x9", and wants to display all the calendar information for January 2023 in the Australia/Melbourne time zone. It might make the following request:¶

[
  ["Calendar/get", {
    "accountId": "a0x9"
  }, "0"],
  ["ParticipantIdentity/get", {
    "accountId": "a0x9"
  }, "1"],
  ["CalendarEvent/query", {
    "accountId": "a0x9",
    "timeZone": "Australia/Melbourne",
    "filter": {
      "after": "2023-01-01T00:00:00",
      "before": "2023-02-01T00:00:00"
    }
  }, "2"],
  ["CalendarEvent/get", {
        "accountId": "a0x9",
        "#ids":{
          "resultOf":"3",
          "name":"CalendarEvent/query",
          "path":"/ids"
        }
  }, "3"]
]

The server might respond with something like:¶

[
  ["Calendar/get", {
    "accountId": "a0x9",
    "list": [{
       "id": "062adcfa-105d-455c-bc60-6db68b69c3f3",
       "name": "Private",
       "sortOrder": 12
       "isDefault": false,
       "defaultAlertsWithTime": null,
       ...
     }, {
       "id": "3ddf2ad7-0e0c-4fb5-852d-f0ff56f3c662",
       "name": "Work",
       "sortOrder": 4
       "isDefault": true,
       "defaultAlertsWithTime": {
         "631BE24C-A3B6-11EC-BF4C-B027680D752E": {
           "@type": "Alert",
           "action": "display",
           "trigger": {
             "@type": "OffsetTrigger",
             "offset": "-PT1H",
             "relativeTo": "start"
           }
         }
       },
       ...
     }],
     "notFound": [],
     "state": "~506"
  }, "0"],
  ["ParticipantIdentity/get", {
        "accountId": "a0x9",
    "list": [{
       "id": "3",
       "name": "Jane Doe"
       "scheduleId": "mailto:jane@example.com",
       "sendTo": {
         "imip": "mailto:jane@example.com",
         "other":
                "https://example.com/uri/for/internal/scheduling"
       },
       "isDefault": true
     }],
     "notFound": [],
     "state": "lgkf:98144:aae"
  }, "1"],
  ["CalendarEvent/query", {
    "accountId": "a0x9",
    "canCalculateChanges": false,
    "position": 0,
    "queryState": "~206",
    "ids": [
      "E-01c9626e-1490-43df-a34f-457021256281",
      "E-07a2b89d-96b6-4920-982a-54fdf0a386ce",
      ...
    ]
  }, "2"],
  ["CalendarEvent/get", {
        "accountId": "a0x9",
        "list": [{
       "id": "E-01c9626e-1490-43df-a34f-457021256281",
       "calendarIds": {
          "3ddf2ad7-0e0c-4fb5-852d-f0ff56f3c662": true,
       },
       "title": "Q1 All hands"
       "start": "20230109T10:00:00",
       "duration": "PT1H",
       "timeZone": "Australia/Sydney",
       ...
     }, ...],
     "notFound": [],
     "state": "$$/413/206"
  }, "3"]
]

The client now has everything it needs to display that month in full.¶

8.2. Creating an event

Suppose the user asks the client to create a new event. The client should default to adding it to the "Work" calendar, as this is the default calendar for the user, unless it has information to make a more informed decision. (e.g. The client may have a feature to automatically choose the calendar based on the time of day, and the user indicates the event is at 7pm, so it knows to default to "Private".)¶

[
  ["CalendarEvent/set", {
    "accountId":"a0x9",
    "create":{
      "k559":{
        "uid":"5d5776f6-ff8e-4bfd-ab3e-fe2fe5d4fa91",
        "calendarIds":{
          "3ddf2ad7-0e0c-4fb5-852d-f0ff56f3c662":true
        },
        "title":"Party at Pete’s",
        "start":"2023-02-03T19:00:00",
        "duration":"PT3H0M0S",
        "timeZone":"Australia/Melbourne",
        "showWithoutTime":false,
        "participants":{
          "1":{
            "@type":"Participant",
            "name": "Jane Doe"
            "scheduleId": "mailto:jane@example.com",
            "sendTo": {
              "imip": "mailto:jane@example.com",
              "other":
                 "https://example.com/uri/for/internal/scheduling"
            }
            "kind":"individual",
            "roles":{
              "attendee":true,
              "owner":true
            },
            "participationStatus":"accepted",
            "expectReply":false
          },
          "2":{
            "@type":"Participant",
            "name":"Joe Bloggs",
            "sendTo":{
              "imip":"mailto:joe@example.com"
            },
            "kind":"individual",
            "roles":{
              "attendee":true
            },
            "participationStatus":"needs-action",
            "expectReply":true
          }
        },
        "mayInviteSelf":false,
        "mayInviteOthers":false,
        "useDefaultAlerts":false,
        "alerts":null
      }
    },
    "sendSchedulingMessages":true
  }, "0"]
]

As the event has participants, the server sets a "replyTo" property. This server uses a special email address for receiving iTIP RSVPs rather than just receiving them at the owner's regular email address, and also provides a web page for people that don't have calendar clients supporting iTIP. The response may look something like this:¶

[
  ["CalendarEvent/set", {
    "accountId":"a0x9",
    "created":{
      "k559":{
        "id":"E-5d5776f6-ff8e-4bfd-ab3e-fe2fe5d4fa91",
        "isOrigin": true,
        "@type": "Event",
        "created": "20221005T20:42:13Z",
        "updated": "20221005T20:42:13Z",
        "sequence": 1,
        "replyTo": {
          "imip": "3e87-1b18bb5e6b4@itip.example.com",
          "web": https://cal.example.com/
                5d5776f6-ff8e-4bfd-ab3e-fe2fe5d4fa91/?
                auth=bfc0-4ba3-9e44"
        }
      }
    },
    ...
  }, "0"]
]

8.3. Snoozing an alert

The client is connected to the event source and receives a push:¶

{
        "@type": "CalendarAlert",
        "accountId": "a0x9",
        "calendarEventId": "E-7e93e3ee-4e6e-408a-9adc-cbaf1dbd0a3f",
        "uid": "b6f7e27b-5872-4b52-b457-0242541bb01c",
        "recurrenceId": null,
        "alertId": "7519a951-1e6f-4a6c-b08b-20dd2e5a89cd"
}

Not finding this event in its local cache, the client fetches the information for this event that it needs to show the alert by making the following request:¶

[
  ["CalendarEvent/get", {
        "accountId": "a0x9",
        "ids":["E-7e93e3ee-4e6e-408a-9adc-cbaf1dbd0a3f"],
        "properties": ["calendarIds", title", "start",
          "timeZone", "useDefaultAlerts", "alerts"]
  }, "0"]
]

In response it receives:¶

[
  ["CalendarEvent/get", {
        "accountId": "a0x9",
        "list": [{
       "id": "E-01c9626e-1490-43df-a34f-457021256281",
       "calendarIds": {
          "3ddf2ad7-0e0c-4fb5-852d-f0ff56f3c662": true,
       },
       "title": "Team catchup"
       "start": "20230210T17:00:00",
       "timeZone": "America/New_York",
       "useDefaultAlerts": false,
       "alerts": {
         "7519a951-1e6f-4a6c-b08b-20dd2e5a89cd": {
           "@type": "Alert",
           "action": "display",
           "trigger": {
             "@type": "OffsetTrigger",
             "relativeTo": "start",
             "offset": "-PT1H"
           }
         }
       }
     }],
     "notFound": [],
     "state": "$$/414/208"
  }, "0"]
]

The client displays an alert in a platform-appropriate manner. Presuming the user here is in the Australia/Melbourne time zone, this might look something like:¶

+----------------------------------------+
|                                        |
|  Reminder: Team catchup                |
|  Today at 10am (in 1 hour)             |
|                             [Snooze\/] |
+----------------------------------------+

The user snoozes the notification for 30 minutes. The client dismisses the current notification and sends an update to the event to the server:¶

[
  ["CalendarEvent/set", {
        "accountId": "a0x9",
        "update": {
      "E-01c9626e-1490-43df-a34f-457021256281": {
        "alerts/7519a951-1e6f-4a6c-b08b-20dd2e5a89cd
                /acknowledged": "20230110T23:00:31Z",
        "alerts/86b0-318b8291045f": {
          "@type": "Alert",
          "action": "display",
          "trigger": {
            "@type": "AbsoluteTrigger",
            "when": "20230210T23:30:00Z",
            "relatedTo": {
              "7519a951-1e6f-4a6c-b08b-20dd2e5a89cd": {
                "@type": "Relation",
                "relation": {
                  "parent": true,
                }
              }
                }
          }
        }
      }
        }
  }, "0"]
]

Any other connected client will receive a push, sync the change and dismiss any duplicate alert. After the snooze time has elapsed, the new alert will trigger.¶

8.4. Changing the default calendar

The client tries to change the default calendar from "Work" to "Private" (and makes no other change):¶

[
  ["Calendar/set", {
    "accountId": "a0x9",
    "onSuccessSetIsDefault": "062adcfa-105d-455c-bc60-6db68b69c3f3"
  }, "0"]
]

The server allows the change, returning the following response:¶

[
  ["Calendar/set", {
    "accountId": "a0x9",
    "updated": {
      "062adcfa-105d-455c-bc60-6db68b69c3f3": {
        "isDefault": true,
      },
      "3ddf2ad7-0e0c-4fb5-852d-f0ff56f3c662": {
        "isDefault": false,
      }
  }, "0"]
]

8.5. Parsing an iCalendar file

The client makes a request to parse the calendar event from a blob id representing an icalendar file:¶

[
  [ "CalendarEvent/parse", {
    "accountId": "a0x9",
    "blobIds": ["0f9f65ab-dc7b-4146-850f-6e4881093965"]
  }, "c1"]
]

The server responds:¶

[[ "CalendarEvent/parse",
{
  "accountId": "a0x9",
  "parsed": {
    "0f9f65ab-dc7b-4146-850f-6e4881093965": [
      {
        "uid": "ea127690-0440-404b-af98-9823c855a283",
        "title": "Gatling: break LemonLDAP!",
        "description": "Let's write some basic OIDC benchmarks",
        "start": "2023-02-09T10:00:00",
        "duration": "PT2H0M0S",
        "end": "2023-02-09T12:00:00",
        "timeZone": "Asia/Ho_Chi_Minh",
        "location": "10 Thai Ha, Ha Noi",
        "method": "REQUEST",
        "sequence": 0,
        "priority": 5,
        "freeBusyStatus": "busy",
        "privacy": "public",
        "organizer": {
          "name": "Bob SMITH",
          "mailto": "bsmith@example.com"
        },
        "participants": [{
            "name": "Bob SMITH",
            "mailto": "bsmith@example.com",
            "kind": "individual",
            "role": "chair",
            "participationStatus": "accepted",
            "expectReply": false
          },
          {
            "name": "Alice DOE",
            "mailto": "adoe@example.com",
            "kind": "individual",
            "role": "requested-participant",
            "participationStatus": "needs-action",
            "expectReply": true
          }
        ],
        "extensionFields": {
          "X-VIDEOCONFERENCE": ["https://jitsi.linagora.com/abcd"],
          "X-CUSTOM-HEADER1": ["whatever1", "whatever2"]
        },
        "recurrenceRules":[
          {
            "frequency": "yearly",
            "byDay": [ "mo" ],
            "byMonth": [ "10" ],
            "bySetPosition": [ 1, 2 ],
            "until":"2024-01-11T09:00:00Z"
          }
        ]
      },
      ...
    ]
  }
}, "c1" ]]

If the blob id had not been found, the server would have responded:¶

[[ "CalendarEvent/parse",
{
  "accountId": "a0x9",
  "notFound": [ "0f9f65ab-dc7b-4146-850f-6e4881093965" ]
}, "c1" ]]

If the blob id had been found but was not parsable, the server would have responded:¶

[[ "CalendarEvent/parse",
{
  "accountId": "a0x9",
  "notParsable": [ "0f9f65ab-dc7b-4146-850f-6e4881093965" ]
}, "c1" ]]

9.1. Privacy

Calendars often contain the precise movements, activities, and contacts of people; all intensely private data. Privacy leaks can have real world consequences, and calendar servers and clients MUST be mindful of the need to keep all data secure.¶

Servers MUST enforce the ACLs set on calendars to ensure only authorised data is shared. The additional restrictions specified by the "privacy" property of a JSCalendar Event object (see Section 4.4.3 of [RFC8984]) MUST also be enforced.¶

Users may have multiple Participant Identities that they use for areas of their life kept private from one another. Using one identity with an event MUST NOT leak the existence of any other identity. For example, sending an RSVP from identity worklife@example.com MUST NOT reveal anything about another identity present in the account such as privatelife@example.org.¶

Severs SHOULD enforce that invitations sent to external systems are only transmitted via secure encrypted and signed connections to protect against eavesdropping and modification of data.¶

9.2. Spoofing

When receiving events and updates from external systems, it can be hard to verify that the identity of the author is who they claim to be. When receiving events via email, DKIM [RFC6376] and S/MIME [RFC8551] are two mechanisms that may be used to verify certain properties about the email data, which can be correlated with the event information.¶

9.3. Denial-of-service

There are many ways in which a calendar user can make a request liable to cause a calendar server to spend an inordinate amount of processing time. Care must be taken to limit resources allocated to any one user to ensure the system does not become unresponsive. The following subsections list particularly hazardous areas.¶

9.4. Spam

Invitations received from an untrusted source may be spam. If this is added to the user's calendar automatically it can be very obtrusive, especially if it is a recurring event that now appears every day. Incoming invitations to events should be subject to spam scanning, and suspicious events should not be added to the calendar automatically.¶

Servers should strip any alerts on invitations when adding to the user's calendar; the useDefaultAlerts property should be set instead to apply the user's preferences.¶

Similarly, a malicious user may use a calendar system to send spam by inviting people to an event. Outbound iTIP should be subject to all the same controls used on outbound email systems, and rate limited as appropriate. A rate limit on the number of distinct recipients as well as overall messages is recommended.¶

10.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 1.6.1¶

10.2. JMAP Capability Registration for "principals:availability"

IANA will register the "principals:availability" JMAP Capability as follows:¶

Capability Name: urn:ietf:params:jmap:principals:availability¶

Specification document: this document¶

Intended use: common¶

Change Controller: IETF¶

Security and privacy considerations: this document, Section 1.6.2¶

10.3. Update to the JSCalendar Properties Registry

IANA will update the "JSCalendar Properties" registry to add a new column called "Is Per-User". The value in this column for each entry MUST be either "yes" or "no", indicating whether each sharee of the object should be able to set their own value for this property without affecting the value for other sharees.¶

10.4. JSCalendar Property Registrations

IANA will register the following additional properties in the JSCalendar Properties Registry.¶