[JMAP] Re: JMAP for Calendars comments

[Neil Jenkins <[e-mail]>]

Hi Mauro,

Thanks for all the great feedback!

> First, a few typos and editorial things I spotted:
> - Section 4: “initally” should be “initially”.
> - Section 1.5.1: “can be can assigned” -> “can be assigned”.
> - Section 5.1: it says “four new JSCalendar properties” but only three are defined (mayInviteSelf, mayInviteOthers, hideAttendees).

Thanks, fixed.

> - Section 5.6.1: the sentence “Splitting an event however is problematic…” may read better as “However, splitting an event is problematic…”.

I had some other feedback about the clarity of this, so I've rewritten it to hopefully be easier to follow.

> - Section 2.2 (Principal/getAvailability): Returning the full/partial event in the availability response could make responses unnecessarily large (even when using ranges). In addition to this, clients may already have the event cached. It might be better to return only the synthetic ids of the events and let clients fetch the details with a CalendarEvent/get call using a result reference to list/*/eventIds in the Principal/getAvailability response.

I think this would considerably complicate things, and I'm not convinced the saving is that necessary. The user may only have permission to call Principal/getAvailability and no other access to the data in the account, so this method wouldn't always work, so we'd still need everything we currently have in the spec. Generally the time period involved will be short (e.g. no more than a week), so the volume of data is unlikely to be that high, and the client requests which properties it wants (the `eventProperties` argument) and even whether it wants the details at all (the `showDetails` argument), so has a lot of control in ensuring the volume of data is reasonable.

> - Section 3 (ParticipantIdentity): It’s not clear whether participant identities are associated with each calendar or if they’re account-level objects like email identities. If they are calendar-specific, which permissions apply when viewing or modifying them?

To confirm, as you later clarified, these are account-level objects, like email identities.

> What I was trying to ask is how this works when a user has access to shared accounts. For example, let’s say a user with accountId A1 has access to a shared account A2, and that shared account contains a calendar. Are the ParticipantIdentity objects defined in the user’s account (A1), or in the account where the calendar lives (A2)?

They are defined where the calendar lives (A2). Note though, different sharees of A2 may have access to the same calendars but get different ParticipantIdentity objects. Consider:
 • If A2 is the account of Ms Boss, and it's shared with Mr Secretary, then the ParticipantIdentities will be the same as the owner of A2 (the sharee is acting as the owner, aka secretary mode).
 • But if A2 is an account representing Team Alpha, the calendar may represent the team but each sharee acts as themselves on it, so the ParticipantIdentities will be the same as in A1 (the sharee is acting as themself).
The server doesn't have to implement both modes of course, but the flexibility is there in the API.

> After re-reading Section 3, I now understand that ParticipantIdentity objects are per-account. If that’s the case, would it perhaps be clearer to expose them by extending the Principal object with a new property, similar to how CalDAV handles this with the calendar-user-address-set property?

I don't think putting this as a property on the Principal object makes sense. The user might fetch the Principal object for everyone in their company, but they only need the participant identities for the accounts that are shared with them. Furthermore, some people consider their list of alternate email addresses to be private information. The current approach also is more consistent with mail, and allows individual identities to be created/updated/destroyed rather than having to update a single compound property on an object.

> For example, in Stalwart, calendar addresses are derived from the account’s email address(es) and cannot be modified by users. If we allow users to add other participant identities that are not their email addresses, how should the server validate that they are authorized to use those identities?

Just to confirm, as you later realised this yourself, the sever can always reject any create with a standard `forbidden` SetError, just like with email identities. What you choose to allow is up to you and your policies.

> As for permissions, my understanding is that ParticipantIdentity objects can only be retrieved and modified by the account owner (otherwise the spec would need to define how to set permissions for them).

Not quite. They can be retrieved by the sharee as well (see above). In theory you could allow them to `/set` as well, but I imagine most servers would forbid this, as the ParticipantIdentity objects seen by the user would be determined by a combination of server policy, configuration (e.g. are calendars shared in secretary or team mode), and what calendars have been shared with the user.

> My confusion mainly comes from how calendar addresses are handled in CalDAV. So let me ask a related question: how can one calendar user discover the principal ID or account ID associated with a given (local) calendar address? If the calendar address is simply an email listed under a Principal object, that’s straightforward. But consider this example:
> 
> - John’s Principal lists [e-mail] as the email address.
> - John also has two ParticipantIdentity objects: mailto:[e-mail] and mailto:[e-mail].
> 
> Now, suppose Jane sees mailto:[e-mail] listed as a participant in an event and wants to query John’s availability using Principal/getAvailability. How can Jane determine which principal ID is associated with that address, given that it’s defined as a ParticipantIdentity under John’s account? The Principal/query method does not currently allow querying by calendar address and Principal objects can contain just one email, so how should a client resolve that mapping?

Interesting, I see where you're coming from now with all this. A few thoughts:
 • It would have to be a policy decision for the server over whether users are allowed to resolve the owner of the alias; as mentioned earlier, some people consider them private.
 • The most common scenario (by far) is for the *organiser* to be checking availability, and they would not have this problem (because you go the other way → find the principals you want to schedule with, check their availability, then get the address to invite from the Principal).
 • If we did want to support this, my feeling is the best way would be to add an optional `principalId` property to the Participant <https://www.ietf.org/archive/id/draft-ietf-calext-jscalendarbis-09.html#name-participants> object, which the server would automatically add if it could resolve which Principal this participant corresponded to, and its policy gave user permission to see this. Do others think this is worth adding?

> - Default Alerts: It might be worth clarifying that only OffsetTrigger alerts should be used in set requests. AbsoluteTrigger does not make sense for a default alert.

Yeah, you'd have thought this would be obvious but doesn't hurt to add a MUST NOT on this I think. I'll do that.

> - Permissions (Section 4): I think mayRSVP should be renamed to mayUpdateRSVP, since it refers to the permission to update an RSVP status rather than the permission to RSVP.

Disagree, I think `mayRSVP` is more accurate. RSVP is also a verb, and the permission is about the ability to RSVP, which depending on the event permissions may involve adding yourself as a participant to the event object, not just setting the RSVP property.

> - Section 5.11.1 (Filtering): Some filters accept null as an argument. In some cases this makes sense (to indicate absence of a value), but for others like text, before, or after it doesn’t really make sense.

Yeah, this is inconsistent with JMAP Mail + JMAP Contacts. I've updated it to be consistent with those. Instead of being nullable, I've noted each property is optional.

> - iCalComponent: Since the iCalComponent property may include unnecessary converted data (like VTIMEZONE components) that most JMAP Calendar clients won’t care about, maybe it’s worth suggesting that such components and properties should not be returned by default unless explicitly requested.

Yeah, agreed; I've added this.

> - Calendar deletion: I think the spec should specify whether scheduling messages are sent when an entire calendar is deleted.

This is already covered in the description of Calendar/set <https://www.ietf.org/archive/id/draft-ietf-jmap-calendars-24.html#section-4.3> (emphasis added below):

*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 MUST NOT send scheduling messages to participants.*

> Personally, I don’t think sending them is necessary, but it might be useful to have an option similar to sendSchedulingMessages in Calendar/set, just for consistency.

I don't think it's necessary either:
 • Sending a huge batch of cancellations is almost never what you want to do.
 • It's likely to hit rate limits due to the number being sent at once with a large calendar, and so some may fail, and if that happens do you still continue with the calendar deletion?
 • Clients that really want to do this can always manually destroy the events first with `CalendarEvent/set` to send the scheduling messages.

> - Section 5.3 – Attachments: The blobId property mentioned there is not currently registered with IANA.

Good spot, I've added a registration.

I've uploaded a v25 draft with the changes.

Cheers,
Neil.