-
Notifications
You must be signed in to change notification settings - Fork 81
/
calendars.xml
1633 lines (1459 loc) · 107 KB
/
calendars.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version="1.0" encoding="utf-8"?>
<rfc version="3" ipr="trust200902" docName="draft-ietf-jmap-calendars-14" submissionType="IETF" category="std" xml:lang="en" xmlns:xi="http://www.w3.org/2001/XInclude" indexInclude="true" consensus="true">
<front>
<title abbrev="JMAP Calendars">JMAP for Calendars</title><seriesInfo value="draft-ietf-jmap-calendars-14" stream="IETF" status="standard" name="Internet-Draft"></seriesInfo>
<author role="editor" initials="N.M." surname="Jenkins" fullname="Neil Jenkins">
<organization>Fastmail</organization>
<address>
<postal>
<street>PO Box 234, Collins St West</street>
<city>Melbourne</city>
<code>VIC 8007</code>
<country>Australia</country>
</postal>
<email>neilj@fastmailteam.com</email>
<uri>https://www.fastmail.com</uri>
</address>
</author>
<author role="editor" initials="M." surname="Douglass" fullname="Michael Douglass">
<organization>Spherical Cow Group</organization>
<address>
<postal>
<street>226 3rd Street</street>
<city>Troy</city>
<code>NY 12180</code>
<country>United States of America</country>
</postal>
<email>mdouglass@sphericalcowgroup.com</email>
<uri>http://sphericalcowgroup.com</uri>
</address>
</author>
<date year="2024" month="February" day="29"></date>
<area>Applications</area>
<workgroup>JMAP</workgroup>
<keyword>JMAP</keyword>
<keyword>JSON</keyword>
<keyword>calendars</keyword>
<abstract>
<t>This document specifies a data model for synchronizing calendar data with a server using JMAP.</t>
</abstract>
</front>
<middle>
<section anchor="introduction"><name>Introduction</name>
<t>JMAP (<xref target="RFC8620"></xref> — JSON Meta Application Protocol) is a generic protocol for synchronizing data, such as mail, calendars or contacts, between a client and a server. It is optimized for mobile and web environments, and aims to provide a consistent interface to different data types.</t>
<t>This specification defines a data model for synchronizing calendar data between a client and a server using JMAP. The data model is designed to allow a server to provide consistent access to the same data via CalDAV <xref target="RFC4791"></xref> as well as JMAP, however the functionality offered over the two protocols may differ. Unlike CalDAV, this specification does not define access to tasks or journal entries (VTODO or VJOURNAL iCalendar components in CalDAV).</t>
<section anchor="notational-conventions"><name>Notational Conventions</name>
<t>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 <xref target="RFC2119"></xref> <xref target="RFC8174"></xref> when, and only when, they appear in all capitals, as shown here.</t>
<t>Type signatures, examples, and property descriptions in this document follow the conventions established in <xref target="RFC8620" section="1.1" sectionFormat="of" />.</t>
</section>
<section anchor="the-localdate-data-type"><name>Data Types</name>
<t>The Id data type defined in <xref target="RFC8620" section="1.2" /> is used in this document. So too are the UnsignedInt, UTCDateTime, LocalDateTime, Duration, and TimeZoneId data types defined in Sections <xref target="RFC8984" section="1.4.3" sectionFormat="bare" />, <xref target="RFC8984" section="1.4.4" sectionFormat="bare" />, <xref target="RFC8984" section="1.4.5" sectionFormat="bare" />, <xref target="RFC8984" section="1.4.6" sectionFormat="bare" />, and <xref target="RFC8984" section="1.4.8" sectionFormat="bare" /> of <xref target="RFC8984" /> respectively.</t>
</section>
<section anchor="terminology"><name>Terminology</name>
<t>The same terminology is used in this document as in the core JMAP specification, see <xref target="RFC8620" section="1.6"></xref>.</t>
<t>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.</t>
</section>
<section anchor="data-model-overview"><name>Data Model Overview</name>
<t>An Account (see <xref target="RFC8620" section="1.6.2"></xref>) 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.</t>
<t>A CalendarEvent is a representation of an event or recurring series of events in JSCalendar Event <xref target="RFC8984"></xref> 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.</t>
<t>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.</t>
<t>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.</t>
<t>In servers with support for JMAP Sharing <xref target="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.</t>
<t>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.</t>
<section anchor="uids-and-calendarevent-ids"><name>UIDs and CalendarEvent Ids</name>
<t>Each CalendarEvent has a <tt>uid</tt> property (<xref target="RFC8984" section="4.1.2" />), which is a globally unique identifier that identifies the same event in different Accounts, or different instances of the same recurring event within an Account.</t>
<t>An Account MUST NOT contain more than one CalendarEvent with the same uid unless all of the CalendarEvent objects have distinct, non-null values for their <tt>recurrenceId</tt> property. (This situation occurs if the principal is added to one or more specific instances of a recurring event without being invited to the whole series.)</t>
<t>Each CalendarEvent also has an id, which is scoped to the JMAP Account and used for referencing it in JMAP methods. There is no necessary link between the uid property and the CalendarEvent's id. CalendarEvents with the same uid in different Accounts MAY have different ids.</t>
</section>
</section>
<section anchor="addition-to-the-capabilities-object"><name>Addition to the Capabilities Object</name>
<t>The capabilities object is returned as part of the JMAP Session object; see <xref target="RFC8620" section="2" />. This document defines three additional capability URIs.</t>
<section anchor="urn-ietf-params-jmap-calendars"><name>urn:ietf:params:jmap:calendars</name>
<t>This represents support for the Calendar, CalendarEvent, CalendarEventNotification, and ParticipantIdentity data types and associated API methods, except for "CalendarEvent/parse". The value of this property in the JMAP Session capabilities property is an empty object.</t>
<t>The value of this property in an account's accountCapabilities property is an object that MUST contain the following information on server capabilities and permissions for that account:</t>
<ul spacing="compact">
<li><t><strong>maxCalendarsPerEvent</strong>: <tt>UnsignedInt|null</tt></t>
<t>The maximum number of Calendars (see <xref target="calendars" />) that can be can assigned to a single CalendarEvent object (see <xref target="calendar-events" />). This MUST be an integer >= 1, or null for no limit (or rather, the limit is always the number of Calendars in the account).</t></li>
<li><t><strong>minDateTime</strong>: <tt>LocalDateTime</tt></t>
<t>The earliest date-time the server is willing to accept for any date stored in a CalendarEvent.</t></li>
<li><t><strong>maxDateTime</strong>: <tt>LocalDateTime</tt></t>
<t>The latest date-time the server is willing to accept for any date stored in a CalendarEvent.</t></li>
<li><t><strong>maxExpandedQueryDuration</strong>: <tt>Duration</tt></t>
<t>The maximum duration the user may query over when asking the server to expand recurrences.</t></li>
<li><t><strong>maxParticipantsPerEvent</strong>: <tt>UnsignedInt|null</tt></t>
<t>The maximum number of participants a single event may have, or null for no limit.</t></li>
<li><t><strong>mayCreateCalendar</strong>: <tt>Boolean</tt></t>
<t>If true, the user may create a calendar in this account.</t></li>
</ul>
</section>
<section anchor="urn-ietf-params-jmap-principals-availability"><name>urn:ietf:params:jmap:principals:availability</name>
<t>Represents support for the Principal/getAvailability method. Any account with this capability MUST also have the <tt>urn:ietf:params:jmap:principals</tt> capability (see <xref target="I-D.ietf-jmap-sharing" section="1.5.1" />).</t>
<t>The value of this property in the JMAP Session capabilities property is an empty object.</t>
<t>The value of this property in an account's accountCapabilities property is an object that MUST contain the following information on server capabilities and permissions for that account:</t>
<ul spacing="compact">
<li><t><strong>maxAvailabilityDuration</strong>: <tt>Duration</tt></t>
<t>The maximum duration over which the server is prepared to calculate availability in a single call (see <xref target="principal-getavailability" />).</t></li>
</ul>
</section>
<section anchor="urn-ietf-params-jmap-calendars-parse"><name>urn:ietf:params:jmap:calendars:parse</name>
<t>This represents support for the CalendarEvent/parse method (see <xref target="calendarevent-parse" />). The value of this property is an empty object in both the JMAP session capabilities property and an account's accountCapabilities property.</t>
</section>
</section>
</section>
<section anchor="principals-and-sharing"><name>Principals and Sharing</name>
<t>For systems that also support JMAP Sharing <xref target="I-D.ietf-jmap-sharing" />, the <tt>urn:ietf:params:jmap:calendars</tt> capability is used to indicate that this principal may be used with calendaring. A new method is defined to allow users to query availability when scheduling events.</t>
<section anchor="principal-capability-urn-ietf-params-jmap-calendars"><name>Principal Capability urn:ietf:params:jmap:calendars</name>
<t>A <tt>urn:ietf:params:jmap:calendars</tt> property is added to the Principal "capabilities" object, the value of which is an object with the following properties:</t>
<ul spacing="compact">
<li><t><strong>accountId</strong>: <tt>Id|null</tt></t>
<t>Id of Account with the <tt>urn:ietf:params:jmap:calendars</tt> 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 <xref target="I-D.ietf-jmap-sharing" section="2" />.</t></li>
<li><t><strong>mayGetAvailability</strong>: <tt>Boolean</tt></t>
<t>May the user call the "Principal/getAvailability" method with this Principal?</t></li>
<li><t><strong>mayShareWith</strong>: <tt>Boolean</tt></t>
<t>May the user add this principal as a calendar sharee (by adding them to the
shareWith property of a calendar, see <xref target="calendars" />)?</t></li>
<li><t><strong>calendarUserAddress</strong>: <tt>String</tt></t>
<t>If this principal may be added as a participant to an event, this is the calendarUserAddress to use to represent it.</t></li>
<li><t><strong>sendTo</strong>: <tt>String[String]|null</tt></t>
<t>If this principal may be added as a participant to an event, this is the Participant#sendTo property to add (see <xref target="RFC8984" section="4.4.5" />) for scheduling messages to reach it.</t></li>
</ul>
</section>
<section anchor="principal-getavailability"><name>Principal/getAvailability</name>
<t>This method calculates the availability of the principal for scheduling within a requested time period. It takes the following arguments:</t>
<ul spacing="compact">
<li><t><strong>accountId</strong>: <tt>Id</tt></t>
<t>The id of the account to use.</t></li>
<li><t><strong>id</strong>: <tt>Id</tt></t>
<t>The id of the Principal to calculate availability for.</t></li>
<li><t><strong>utcStart</strong>: <tt>UTCDateTime</tt></t>
<t>The start time (inclusive) of the period for which to return availability.</t></li>
<li><t><strong>utcEnd</strong>: <tt>UTCDateTime</tt></t>
<t>The end time (exclusive) of the period for which to return availability.</t></li>
<li><t><strong>showDetails</strong>: <tt>Boolean</tt></t>
<t>If true, event details will be returned if the user has permission to view them.</t></li>
<li><t><strong>eventProperties</strong>: <tt>String[]|null</tt></t>
<t>A list of properties to include in any JSCalendar Event object returned. If <tt>null</tt>, all properties of the event will be returned. Otherwise, only properties with names in the given list will be returned.</t></li>
</ul>
<t>The server will first find all relevant events, expanding any recurring events. Relevant events are ones where all of the following is true:</t>
<ul spacing="compact">
<li><t>The principal is subscribed to the calendar.</t></li>
<li><t>The "includeInAvailability" property of the calendar for the principal is "all" or "attending".</t></li>
<li><t>The user has the "mayReadFreeBusy" permission for the calendar.</t></li>
<li><t>The event finishes after the "utcStart" argument and starts before the "utcEnd" argument.</t></li>
<li><t>The event's "privacy" property is not "secret".</t></li>
<li><t>The "freeBusyStatus" property of the event is "busy" (or omitted, as this is the default).</t></li>
<li><t>The "status" property of the event is not "cancelled".</t></li>
<li><t>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".</t></li>
</ul>
<t>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.</t>
<t>The server then generates a BusyPeriod object for each of these events. A <strong>BusyPeriod</strong> object has the following properties:</t>
<ul>
<li><t><strong>utcStart</strong>: <tt>UTCDateTime</tt></t>
<t>The start time (inclusive) of the period this represents.</t></li>
<li><t><strong>utcEnd</strong>: <tt>UTCDateTime</tt></t>
<t>The end time (exclusive) of the period this represents.</t></li>
<li><t><strong>busyStatus</strong>: <tt>String</tt> (optional, default "unavailable")</t>
<t>This MUST be one of</t>
<ul spacing="compact">
<li><t><tt>confirmed</tt>: The event status is "confirmed" and the principal's</t>
<t>"participationStatus" is "attending".</t></li>
<li><t><tt>tentative</tt>: The event status is "tentative" or the principal's</t>
<t>"participationStatus" is "tentative".</t></li>
<li><t><tt>unavailable</tt>: The principal is not available for scheduling at this time</t>
<t>for any other reason.</t></li>
</ul></li>
<li><t><strong>event</strong>: <tt>JSCalendar Event|null</tt></t>
<t>The JSCalendar Event representation of the event, or null if any of the following are true:</t>
<ul spacing="compact">
<li><t>The "showDetails" argument is false.</t></li>
<li><t>The "privacy" property of the event is "private".</t></li>
<li><t>The user does not have the "mayReadItems" permission for any of the calendars the event is in.</t></li>
</ul>
<t>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.</t>
</li>
</ul>
<t>The server MAY also generate BusyPeriod objects based on other information it has about the principal's availability, such as office hours.</t>
<t>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.</t>
<t>The response has the following argument:</t>
<ul spacing="compact">
<li><t><strong>list</strong>: <tt>BusyPeriod[]</tt></t>
<t>The list of BusyPeriod objects calculated as described above.</t></li>
</ul>
<t>The following additional errors may be returned instead of the
"Principal/getAvailability" response:</t>
<t><tt>notFound</tt>: No principal with this id exists, or the user does not have
permission to see that this principal exists.</t>
<t><tt>forbidden</tt>: The user does not have permission to query this principal's availability.</t>
<t><tt>tooLarge</tt>: The duration between utcStart and utcEnd is longer than the server is willing to calculate availability for.</t>
<t><tt>rateLimit</tt>: Too many availability requests have been made recently and the user is being rate limited. It may work to try again later.</t>
</section>
</section>
<section anchor="participant-identities"><name>Participant Identities</name>
<t>A ParticipantIdentity stores information about a URI that represents the user within that account in an event's participants. It has the following properties:</t>
<ul>
<li><t><strong>id</strong>: <tt>Id</tt> (immutable; server-set)</t>
<t>The id of the ParticipantIdentity.</t></li>
<li><t><strong>name</strong>: <tt>String</tt> (default: ")</t>
<t>The display name of the participant to use when adding this participant to an event, e.g. "Joe Bloggs".</t></li>
<li><t><strong>calendarUserAddress</strong>: <tt>String</tt></t>
<t>The URI that represents this participant for scheduling. This URI may also be the URI for one of the sendTo methods.</t></li>
<li><t><strong>sendTo</strong>: <tt>String[String]</tt></t>
<t>Represents methods by which the participant may receive invitations and updates to an event.</t>
<t>The keys in the property value are the available methods and MUST only contain ASCII alphanumeric characters (A-Za-z0-9). The value is a URI for the method specified in the key.</t>
</li>
<li><t><strong>isDefault</strong>: <tt>Boolean</tt> (server-set)</t>
<t>This SHOULD be true for exactly one participant identity in any account, and
MUST NOT be true for more than one participant identity within an account.
The default identity should be used by clients whenever they need to choose
an identity for the user within this account, and they do not have any other
information on which to make a choice. For example, if creating a scheduled
event in this account, the default identity may be automatically added as
an owner. (But the client may ignore this if, for example, it has its own
feature to allow users to choose which identity to use based on the
invitees.)</t></li>
</ul>
<t>A participant in an event corresponds to a ParticipantIdentity if the calendarUserAddress property of the participant is equivalent to the calendarUserAddress property of the identity after syntax-based normalisation, as per <xref target="RFC3986" section="6.2.2" />.</t>
<t>The following JMAP methods are supported.</t>
<section anchor="participantidentity-get"><name>ParticipantIdentity/get</name>
<t>This is a standard "/get" method as described in <xref target="RFC8620" section="5.1" />. The "ids" argument may be <tt>null</tt> to fetch all at once.</t>
</section>
<section anchor="participantidentity-changes"><name>ParticipantIdentity/changes</name>
<t>This is a standard "/changes" method as described in <xref target="RFC8620" section="5.2" />.</t>
</section>
<section anchor="participantidentity-set"><name>ParticipantIdentity/set</name>
<t>This is a standard "/set" method as described in <xref target="RFC8620" section="5.3" />, but with the following additional request argument:</t>
<ul spacing="compact">
<li><t><strong>onSuccessSetIsDefault</strong>: <tt>Id|null</tt></t>
<t>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 "#".)</t></li>
</ul>
<t>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.</t>
<t>As per <xref target="RFC8620" section="5.3" />, 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.</t>
<t>The server MAY restrict the uri values the user may claim, for example only allowing <tt>mailto:</tt> URIs with email addresses that belong to the user. A standard <tt>forbidden</tt> error is returned to reject non-permissible changes.</t>
</section>
</section>
<section anchor="calendars"><name>Calendars</name>
<t>A Calendar is a named collection of events. All events are associated with at least one calendar.</t>
<t>A <strong>Calendar</strong> object has the following properties:</t>
<ul spacing="compact">
<li><t><strong>id</strong>: <tt>Id</tt> (immutable; server-set)</t>
<t>The id of the calendar.</t></li>
<li><t><strong>name</strong>: <tt>String</tt></t>
<t>The user-visible name of the calendar. This may be any UTF-8 string of at least 1 character in length and maximum 255 octets in size.</t></li>
<li><t><strong>description</strong>: <tt>String|null</tt> (default: null)</t>
<t>An optional longer-form description of the calendar, to provide context in shared environments where users need more than just the name.</t></li>
<li><t><strong>color</strong>: <tt>String|null</tt> (default: null)</t>
<t>A color to be used when displaying events associated with the calendar.</t>
<t>If not null, the value MUST be a case-insensitive color name taken from the set of names defined in Section 4.3 of CSS Color Module Level 3 <eref target="https://www.w3.org/TR/css-color-3/">COLORS</eref>, or an RGB value in hexadecimal notation, as defined in Section 4.2.1 of CSS Color Module Level 3.</t>
<t>The color SHOULD have sufficient contrast to be used as text on a white background.</t></li>
</ul>
<ul>
<li><t><strong>sortOrder</strong>: <tt>UnsignedInt</tt> (default: 0)</t>
<t>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<sup>31.</sup></t>
<t>A calendar with a lower order is to 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.</t></li>
<li><t><strong>isSubscribed</strong>: <tt>Boolean</tt></t>
<t>True if the user has 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.</t>
<t>If false, the calendar should only be displayed when the user explicitly
requests it or to offer it for the user to subscribe to. For example, a company may have a large number of shared calendars which all employees have permission to access, but you would only subscribe to the ones you care about and want to be able to have normally accessible.</t></li>
<li><t><strong>isVisible</strong>: <tt>Boolean</tt> (default: true)</t>
<t>Should the calendar's events be displayed to the user at the moment? Clients MUST ignore this property if isSubscribed is false. If an event is in multiple calendars, it should be displayed if isVisible is true for any of those calendars.</t></li>
<li><t><strong>isDefault</strong>: <tt>Boolean</tt> (server-set)</t>
<t>This SHOULD be true for exactly one calendar in any account, and MUST NOT be
true for more than one calendar within an account. The default calendar
should be used by clients whenever they need to choose a calendar for the
user within this account, and they do not have any other information on
which to make a choice. For example, if the user creates a new event, the
client may automatically set the event as belonging to the default calendar
from the user's primary account.</t></li>
<li><t><strong>includeInAvailability</strong>: <tt>String</tt></t>
<t>Should the calendar's events be used as part of availability calculation?
This MUST be one of:</t>
<ul spacing="compact">
<li><t><tt>all</tt>: all events are considered.</t></li>
<li><t><tt>attending</tt>: events the user is a confirmed or tentative participant of are considered.</t></li>
<li><t><tt>none</tt>: all events are ignored (but may be considered if also in another calendar).</t></li>
</ul>
<t>This should default to "all" for the calendars in the user's own account,
and "none" for calendars shared with the user.</t></li>
<li><t><strong>defaultAlertsWithTime</strong>: <tt>Id[Alert]|null</tt></t>
<t>A map of alert ids to Alert objects (see <xref target="RFC8984" section="4.5.2" />) to apply for events where "showWithoutTime" is false and "useDefaultAlerts" is true. Ids MUST be unique across all default alerts in the account, including those in other calendars; a UUID is recommended.</t>
<t>If omitted on creation, the default is server dependent. For example, servers may choose to always default to <tt>null</tt>, or may copy the alerts from the default calendar.</t></li>
<li><t><strong>defaultAlertsWithoutTime</strong>: <tt>Id[Alert]|null</tt></t>
<t>A map of alert ids to Alert objects (see <xref target="RFC8984" section="4.5.2" />) to apply for events where "showWithoutTime" is true and "useDefaultAlerts" is true. Ids MUST be unique across all default alerts in the account, including those in other calendars; a UUID is recommended.</t>
<t>If omitted on creation, the default is server dependent. For example, servers may choose to always default to <tt>null</tt>, or may copy the alerts from the default calendar.</t></li>
<li><t><strong>timeZone</strong>: <tt>TimeZoneId|null</tt> (default: null)</t>
<t>The time zone to use for events without a time zone when the server needs to resolve them into absolute time, e.g., for alerts or availability calculation. The value MUST be a time zone id from the IANA Time Zone Database <eref target="https://www.iana.org/time-zones">TZDB</eref>. If <tt>null</tt>, the timeZone of the account's associated Principal will be used. Clients SHOULD use this as the default for new events in this calendar if set.</t></li>
<li><t><strong>shareWith</strong>: <tt>Id[CalendarRights]|null</tt> (default: null)</t>
<t>A map of Principal id to rights for principals this calendar is shared with. The principal to which this calendar belongs MUST NOT be in this set. This is null if the calendar is not shared with anyone. May be modified only if the user has the mayAdmin right. The account id for the principals may be found in the <tt>urn:ietf:params:jmap:principals:owner</tt> capability of the Account to which the calendar belongs.</t></li>
<li><t><strong>myRights</strong>: <tt>CalendarRights</tt> (server-set)</t>
<t>The set of access rights the user has in relation to this Calendar. If any event is in multiple calendars, the user has the following rights:</t>
<ul spacing="compact">
<li><t>The user may fetch the event if they have the mayReadItems right on any calendar the event is in.</t></li>
<li><t>The user may remove an event from a calendar (by modifying the event's "calendarIds" property) if the user has the appropriate permission for that
calendar.</t></li>
<li><t>The user may make other changes to the event if they have the right to do so in <strong>all</strong> calendars to which the event belongs.</t></li>
</ul></li>
</ul>
<t>A <strong>CalendarRights</strong> object has the following properties:</t>
<ul>
<li><t><strong>mayReadFreeBusy</strong>: <tt>Boolean</tt></t>
<t>The user may read the free-busy information for this calendar as part of a call to Principal/getAvailability (see <xref target="principal-getavailability" />).</t></li>
<li><t><strong>mayReadItems</strong>: <tt>Boolean</tt></t>
<t>The user may fetch the events in this calendar.</t></li>
<li><t><strong>mayWriteAll</strong>: <tt>Boolean</tt></t>
<t>The user may create, modify or destroy all events in this calendar, or move events to or from this calendar. If this is true, the mayWriteOwn, mayUpdatePrivate and mayRSVP properties MUST all also be true.</t></li>
<li><t><strong>mayWriteOwn</strong>: <tt>Boolean</tt></t>
<t>The user may create, modify or destroy an event on this calendar if either they are the owner of the event (see below) or the event has no owner. This means the user may also transfer ownership by updating an event so they are no longer an owner.</t></li>
<li><t><strong>mayUpdatePrivate</strong>: <tt>Boolean</tt></t>
<t>The user may modify per-user properties (see <xref target="per-user-properties" />) on all events in the calendar, even if they would not otherwise have permission to modify that event. These properties MUST all be stored per-user, and changes do not affect any other user of the calendar.</t>
<t>The user may also modify these properties on a per-occurrence basis for recurring events (updating the "recurrenceOverrides" property of the event to do so).</t></li>
<li><t><strong>mayRSVP</strong>: <tt>Boolean</tt></t>
<t>The user may modify the following properties of any Participant object that corresponds to one of the user's ParticipantIdentity objects in the account, even if they would not otherwise have permission to modify that event:</t>
<ul spacing="compact">
<li><t>participationStatus</t></li>
<li><t>participationComment</t></li>
<li><t>expectReply</t></li>
<li><t>scheduleAgent</t></li>
<li><t>scheduleSequence</t></li>
<li><t>scheduleUpdated</t></li>
</ul>
<t>If the event has its "mayInviteSelf" property set to true (see <xref target="mayinviteself" />), then the user may also add a new Participant to the event with calendarUserAddress/sendTo properties that are the same as the calendarUserAddress/sendTo properties of one of the user's ParticipantIdentity objects in the account. The roles property of the participant MUST only contain "attendee".</t>
<t>If the event has its "mayInviteOthers" property set to true (see <xref target="mayinviteothers" />) and there is an existing Participant in the event corresponding to one of the user's ParticipantIdentity objects in the account, then the user may also add new participants. The roles property of any new participant MUST only contain "attendee".</t>
<t>The user may also do all of the above on a per-occurrence basis for recurring events (updating the recurrenceOverrides property of the event to do so).</t></li>
<li><t><strong>mayAdmin</strong>: <tt>Boolean</tt></t>
<t>The user may modify the "shareWith" property for this calendar.</t></li>
<li><t><strong>mayDelete</strong>: <tt>Boolean</tt></t>
<t>The user may delete the calendar itself.</t></li>
</ul>
<t>The user is an <strong>owner</strong> for an event if the CalendarEvent object has a "participants" property, and one of the Participant objects both:</t>
<ol type="a">
<li><t>Has the "owner" role.</t></li>
<li><t>Corresponds to one of the user's ParticipantIdentity objects in the account (as per <xref target="participant-identities" />).</t></li>
</ol>
<t>An event has no owner if its participants property is null or omitted, or if none of the Participant objects have the "owner" role.</t>
<section anchor="calendar-get"><name>Calendar/get</name>
<t>This is a standard "/get" method as described in <xref target="RFC8620" section="5.1" />. The "ids" argument may be <tt>null</tt> to fetch all at once.</t>
<t>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.</t>
</section>
<section anchor="calendar-changes"><name>Calendar/changes</name>
<t>This is a standard "/changes" method as described in <xref target="RFC8620" section="5.2" />.</t>
</section>
<section anchor="calendar-set"><name>Calendar/set</name>
<t>This is a standard "/set" method as described in <xref target="RFC8620" section="5.3" /> but with the following additional request arguments:</t>
<ul spacing="compact">
<li><t><strong>onDestroyRemoveEvents</strong>: <tt>Boolean</tt> (default: false)</t>
<t>If false, any attempt to destroy a Calendar that still has CalendarEvents in it will be rejected with a <tt>calendarHasEvent</tt> 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.</t>
</li>
<li><t><strong>onSuccessSetIsDefault</strong>: <tt>Id|null</tt></t>
<t>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 "#".)</t>
<t>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.</t>
<t>As per <xref target="RFC8620" section="5.3" />, 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.</t>
</li>
</ul>
<t>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 <tt>forbidden</tt> SetError.</t>
<t>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 <tt>forbidden</tt> SetError.</t>
<t>The following properties may be set by anyone who is subscribed to the calendar and are always stored per-user:</t>
<ul spacing="compact">
<li><t>name</t></li>
<li><t>color</t></li>
<li><t>sortOrder</t></li>
<li><t>isVisible</t></li>
<li><t>timeZone</t></li>
<li><t>includeInAvailability</t></li>
<li><t>defaultAlertsWithoutTime</t></li>
<li><t>defaultAlertsWithTime</t></li>
</ul>
<t>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.</t>
<t>The "sortOrder", "isVisible", "includeInAvailability", "defaultAlertsWithTime", and "defaultAlertsWithoutTime" properties are initally the default value for each sharee; they are not inherited from the owner.</t>
<t>The following extra SetError type is defined:</t>
<t>For "destroy":</t>
<ul spacing="compact">
<li><t><strong>calendarHasEvent</strong>: The Calendar has at least one CalendarEvent assigned to it, and the "onDestroyRemoveEvents" argument was false.</t></li>
</ul>
</section>
</section>
<section anchor="calendar-events"><name>Calendar Events</name>
<t>A <strong>CalendarEvent</strong> object contains information about an event, or recurring series of events, that takes place at a particular time. It is a JSCalendar Event object, as defined in <xref target="RFC8984"></xref>, with the following additional properties:</t>
<ul>
<li><t><strong>id</strong>: <tt>Id</tt> (immutable; server-set)</t>
<t>The id of the CalendarEvent. The id uniquely identifies a JSCalendar Event with a particular "uid" and "recurrenceId" within a particular account.</t></li>
<li><t><strong>baseEventId</strong>: <tt>Id|null</tt> (immutable; server-set)</t>
<t>This is only defined if the "id" property is a synthetic id, generated by the server to represent a particular instance of a recurring event (see <xref target="calendarevent-query" />). This property gives the id of the "real" CalendarEvent this was generated from.</t></li>
<li><t><strong>calendarIds</strong>: <tt>Id[Boolean]</tt></t>
<t>The set of Calendar ids this event belongs to. An event MUST belong to one or more Calendars at all times (until it is destroyed). The set is represented as an object, with each key being a Calendar id. The value for each key in the object MUST be true.</t></li>
<li><t><strong>isDraft</strong>: <tt>Boolean</tt> (default: false)</t>
<t>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".</t></li>
<li><t><strong>isOrigin</strong>: <tt>Boolean</tt> (server-set)</t>
<t>Is this the authoritative source for this event (i.e., does it control
scheduling for this event; the event has not been added as a result of an
invitation from another calendar system)? This is true if, and only if:</t>
<ul spacing="compact">
<li><t>the event's "replyTo" property is <tt>null</tt>; or</t></li>
<li><t>the account will receive messages sent to at least one of the methods specified in the "replyTo" property of the event.</t></li>
</ul></li>
<li><t><strong>utcStart</strong>: <tt>UTCDateTime</tt></t>
<t>For simple clients that do not 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.</t>
<t>This property 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.</t>
<t>If set, the server will convert the UTC date to the event's current time zone and store the local time.</t>
<t>This property is not included in CalendarEvent/get responses by default and must be requested explicitly.</t>
<t>Floating events (events without a time zone) will be interpreted as per the time zone given as a CalendarEvent/get argument.</t>
<t>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 <xref target="calendarevent-query" />).</t></li>
<li><t><strong>utcEnd</strong>: <tt>UTCDateTime</tt></t>
<t>The server calculates the end time in UTC from the start/timeZone/duration properties of the event. This property is not included by default and must be requested explicitly. Like utcStart, it is calculated at fetch time if requested and may change due to time zone data changes. Floating events will be interpreted as per the time zone given as a CalendarEvent/get argument.</t></li>
</ul>
<t>CalendarEvent objects MUST NOT have a "method" property as this is only used when representing iTIP <xref target="RFC5546"></xref> scheduling messages, not events in a data store.</t>
<section anchor="additional-jscalendar-properties"><name>Additional JSCalendar properties</name>
<t>This document defines four new JSCalendar properties for common use.</t>
<section anchor="calendar-user-address"><name>calendarUserAddress</name>
<t>Type: <tt>String</tt></t>
<t>Context: Participant</t>
<t>This is a URI as defined by <xref target="RFC3986"></xref> or any other IANA-registered form for a URI. It is the same as the CAL-ADDRESS value of an ATTENDEE or ORGANIZER in iCalendar (<xref target="RFC5545"></xref>) — it globally identifies a particular participant, even across different events.</t>
</section>
<section anchor="mayinviteself"><name>mayInviteSelf</name>
<t>Type: <tt>Boolean</tt> (default: false)</t>
<t>Context: Event, Task</t>
<t>If true, anyone may add themselves to the event as a participant with the "attendee" role. This property MUST NOT be altered in the recurrenceOverrides; it may only be set on the base object.</t>
</section>
<section anchor="mayinviteothers"><name>mayInviteOthers</name>
<t>Type: <tt>Boolean</tt> (default: false)</t>
<t>Context: Event, Task</t>
<t>If true, any current participant with the "attendee" role may add new participants with the "attendee" role to the event. This property MUST NOT be altered in the recurrenceOverrides; it may only be set on the base object.</t>
</section>
<section anchor="hideattendees"><name>hideAttendees</name>
<t>Type: <tt>Boolean</tt> (default: false)</t>
<t>Context: Event, Task</t>
<t>If true, only the owners of the event may see the full set of participants. Other sharees of the event may only see the owners and themselves. This property MUST NOT be altered in the recurrenceOverrides; it may only be set on the base object.</t>
</section>
</section>
<section anchor="attachments"><name>Attachments</name>
<t>The Link object, as defined in <xref target="RFC8984" 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 <xref target="RFC8620" section="6" />.</t>
<t>The server MUST translate this to an embedded <tt>data:</tt> URL <xref target="RFC2397"></xref> 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].</t>
</section>
<section anchor="per-user-properties"><name>Per-user properties</name>
<t>In shared calendars, any top-level property registered in the IANA registry as "Is Per-User: yes" (see <xref target="update-to-the-jscalendar-properties-registry" />) MUST be stored per-user. This includes:</t>
<ul spacing="compact">
<li><t>keywords</t></li>
<li><t>color</t></li>
<li><t>freeBusyStatus</t></li>
<li><t>useDefaultAlerts</t></li>
<li><t>alerts</t></li>
</ul>
<t>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.</t>
<t>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.</t>
</section>
<section anchor="recurring-events"><name>Recurring events</name>
<t>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).</t>
<t>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.</t>
<t>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.</t>
</section>
<section anchor="updating-for-this-and-future"><name>Updating for "this-and-future"</name>
<t>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.</t>
<section anchor="splitting-an-event"><name>Splitting an event</name>
<t>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 <xref target="RFC8984" section="4.1.3" />, a "next" and "first" relation MUST be set on the new objects respectively.</t>
<t>Splitting an event however is problematic in the case of a scheduled event, because the participants will see it as two separate changes, and may not understand the connection between the two.</t>
</section>
<section anchor="updating-the-base-event-and-overriding-previous"><name>Updating the base event and overriding previous</name>
<t>For scheduled events, a better approach is to avoid splitting and instead update the base 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.</t>
<t>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.</t>
</section>
</section>
<section anchor="calendarevent-get"><name>CalendarEvent/get</name>
<t>This is a standard "/get" method as described in <xref target="RFC8620" section="5.1" />, with three extra arguments:</t>
<ul spacing="compact">
<li><t><strong>recurrenceOverridesBefore</strong>: <tt>UTCDateTime|null</tt></t>
<t>If given, only recurrence overrides with a recurrence id before this date (when translated into UTC) will be returned.</t></li>
<li><t><strong>recurrenceOverridesAfter</strong>: <tt>UTCDateTime|null</tt></t>
<t>If given, only recurrence overrides with a recurrence id on or after this date (when translated into UTC) will be returned.</t></li>
<li><t><strong>reduceParticipants</strong>: <tt>Boolean</tt> (default: false)</t>
<t>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.</t></li>
<li><t><strong>timeZone</strong>: <tt>TimeZoneId</tt> (default "Etc/UTC")</t>
<t>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.</t></li>
</ul>
<t>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).</t>
<t>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 MUST return the default value if known for that property.</t>
<t>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.</t>
<t>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.</t>
<t>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.</t>
<t>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:</t>
<ul spacing="compact">
<li><t>the basic time and metadata properties of the JSCalendar Event object as specified in <xref target="RFC8984" section="4.4.3" />; or</t></li>
<li><t>properties that are wholly derived from these permitted properties (i.e., utcStart, utcEnd); or</t></li>
<li><t>Additional CalendarEvent properties not derived from the JSCalendar Event data (i.e., id, baseEventId, calendarIds, isDraft, isOrigin).</t></li>
</ul>
<t>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.</t>
</section>
<section anchor="calendarevent-changes"><name>CalendarEvent/changes</name>
<t>This is a standard "/changes" method as described in <xref target="RFC8620" section="5.2" />.</t>
<t>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.</t>
</section>
<section anchor="calendarevent-set"><name>CalendarEvent/set</name>
<t>This is a standard "/set" method as described in <xref target="RFC8620" section="5.3" />, with the following extra argument:</t>
<ul spacing="compact">
<li><t><strong>sendSchedulingMessages</strong>: <tt>Boolean</tt> (default: false)</t>
<t>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.</t>
<t>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 origin) 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 <tt>noSupportedScheduleMethods</tt> SetError.</t>
<t>At time of writing, the most common interoperable protocol for sending scheduling methods between participants on different servers is iMIP <xref target="RFC5546" />. A future document will provide recommendations of what iMIP messages to send based on the change for best compatibility.</t></li>
</ul>
<t>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.</t>
<t>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 <tt>recurrenceId</tt> property) with the base event (same uid, no <tt>recurrenceId</tt>) 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.</t>
<t>If a property is set to null in a create/update, this is equivalent to
omitting/removing the property from the JSCalendar Event object.</t>
<t>Servers MUST enforce the user's permissions as returned in the "myRights" property of the Calendar objects and reject changes with a <tt>forbidden</tt> SetError if not allowed.</t>
<t>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 <tt>forbidden</tt> 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.</t>
<t>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 <tt>invalidProperties</tt> SetError.</t>
<t>If omitted on create, the server MUST set the following properties to an appropriate value:</t>
<ul spacing="compact">
<li><t>@type</t></li>
<li><t>uid</t></li>
<li><t>created</t></li>
</ul>
<t>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 scheduling messages.</t>
<t>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 (e.g., via an iTIP REQUEST message). 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).</t>
<t>When updating an event, if all of:</t>
<ul spacing="compact">
<li><t>a property has been changed other than "calendarIds", "isDraft", "updated" or a per-user property (see <xref target="per-user-properties" />); and</t></li>
<li><t>the server is the origin of the event (the "isOrigin" property is true); and</t></li>
<li><t>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;</t></li>
</ul>
<t>then the server MUST increment the "sequence" value by one.</t>
<t>The "method" property MUST NOT be set. Any attempt to do so is rejected with a standard <tt>invalidProperties</tt> SetError.</t>
<t>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 <tt>invalidProperties</tt> SetError.</t>
<t>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 <tt>invalidProperties</tt> SetError.</t>
<t>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.</t>
<t>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 <xref target="participant-identities" />).</t>
<t>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.</t>
<t>The following extra SetError type is defined:</t>
<ul spacing="compact">
<li><t><strong>noSupportedScheduleMethods</strong>: The server was requested to send scheduling messages, but does not support any of the methods available for at least one of the recipients.</t></li>
</ul>
<section anchor="patching"><name>Patching</name>
<t>The JMAP "/set" method allows you to update an object by sending a patch, rather than having to supply the whole object. When doing so, care must be taken if updating a property of a CalendarEvent where the value is itself a PatchObject, e.g. inside "localizations" or "recurrenceOverrides". In particular, you cannot add a property with value <tt>null</tt> to the CalendarEvent using a direct patch on that property, as this is interpreted instead as a patch to remove the property.</t>
<t>This is more easily understood with an example. Suppose you have a CalendarEvent object like so:</t>
<artwork>{
"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",
"calendarUserAddress": "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",
"calendarUserAddress": "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"
}
}
}
}
</artwork>
<t>In this example, Tom is normally going to the weekly meeting but has declined
the occurrence on 2018-03-08, which starts an hour later than normal. Now, if Zoe too were to decline that meeting, she could update the event by just sending a patch like so:</t>
<artwork>[[ "CalendarEvent/set", {
"accountId": "ue150411c",
"update": {
"123": {
"recurrenceOverrides/2018-03-08T09:00:00/
participants~1em9lQGZvb2GFtcGxlLmNvbQ~1participationStatus":
"declined"
}
}
}, "0" ]]
</artwork>
<t>This patches the "2018-03-08T09:00:00" PatchObject in recurrenceOverrides so that it ends up like this:</t>
<artwork>"recurrenceOverrides": {
"2018-03-08T09:00:00": {
"start": "2018-03-08T10:00:00",
"participants/dG9tQGZvb2Jhci5xlLmNvbQ/participationStatus":
"declined",
"participants/em9lQGZvb2GFtcGxlLmNvbQ/participationStatus":
"declined"
}
}
</artwork>
<t>Now if Tom were to change his mind and remove his declined status override (thus meaning he is attending, as inherited from the top-level event), he might remove his patch from the overrides like so:</t>
<artwork>[[ "CalendarEvent/set", {
"accountId": "ue150411c",
"update": {
"123": {
"recurrenceOverrides/2018-03-08T09:00:00/
participants~1dG9tQGZvb2Jhci5xlLmNvbQ~1participationStatus": null
}
}
}, "0" ]]
</artwork>
<t>However, if you instead want to remove Tom from this instance altogether, you could not send this patch:</t>
<artwork>[[ "CalendarEvent/set", {
"accountId": "ue150411c",
"update": {
"123": {
"recurrenceOverrides/2018-03-08T09:00:00/
participants~1dG9tQGZvb2Jhci5xlLmNvbQ": null
}
}
}, "0" ]]
</artwork>
<t>This would mean remove the "participants/dG9tQGZvb2Jhci5xlLmNvbQ" property at path "recurrenceOverrides" -> "2018-03-08T09:00:00" inside the object; but this doesn't exist. We actually want to add this property and make it map to <tt>null</tt>. The client must instead send the full object that contains the property mapping to <tt>null</tt>, like so:</t>
<artwork>[[ "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" ]]
</artwork>
</section>
</section>
<section anchor="calendarevent-copy"><name>CalendarEvent/copy</name>
<t>This is a standard "/copy" method as described in <xref target="RFC8620" section="5.4" />.</t>
</section>
<section anchor="calendarevent-query"><name>CalendarEvent/query</name>
<t>This is a standard "/query" method as described in <xref target="RFC8620" section="5.5" />, with two extra arguments:</t>
<ul spacing="compact">
<li><t><strong>expandRecurrences</strong>: <tt>Boolean</tt> (default: false)</t>
<t>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.</t></li>
<li><t><strong>timeZone</strong>: <tt>TimeZoneId</tt></t>
<t>The time zone for before/after filter conditions (default: "Etc/UTC")</t></li>
</ul>
<t>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.</t>
<t>There is no necessary correspondence between the ids of different instances of the same expanded event.</t>
<t>The following additional error may be returned instead of the "CalendarEvent/query" response:</t>
<t><tt>cannotCalculateOccurrences</tt>: The server cannot expand a recurrence required to return the results for this query.</t>
<section anchor="filtering"><name>Filtering</name>
<t>A <strong>FilterCondition</strong> object has the following properties:</t>
<ul spacing="compact">
<li><t><strong>inCalendars</strong>: <tt>Id[]|null</tt></t>
<t>A list of calendar ids. An event must be in ANY of these calendars to match the condition.</t></li>
<li><t><strong>after</strong>: <tt>LocalDateTime|null</tt></t>
<t>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.</t></li>
<li><t><strong>before</strong>: <tt>LocalDateTime|null</tt></t>
<t>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.</t></li>
<li><t><strong>text</strong>: <tt>String|null</tt></t>
<t>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.</t></li>
<li><t><strong>title</strong>: <tt>String|null</tt></t>
<t>Looks for the text in the "title" property of the event, or the overridden "title" property of a recurrence.</t></li>
<li><t><strong>description</strong>: <tt>String|null</tt></t>
<t>Looks for the text in the "description" property of the event, or the overridden "description" property of a recurrence.</t></li>
<li><t><strong>location</strong>: <tt>String|null</tt></t>
<t>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.</t></li>
<li><t><strong>owner</strong>: <tt>String|null</tt></t>
<t>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".</t></li>
<li><t><strong>attendee</strong>: <tt>String|null</tt></t>
<t>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".</t></li>
<li><t><strong>uid</strong>: <tt>String</tt></t>
<t>The uid of the event is exactly the given string.</t></li>
</ul>
<t>If expandRecurrences is true, all conditions must match against the same instance of a recurring event for the instance to match. If expandRecurrences is false, all conditions must match, but they may each match any instance of the event.</t>
<t>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).</t>
<t>The exact semantics for matching <tt>String</tt> fields is <strong>deliberately not defined</strong> to allow for flexibility in indexing implementation, subject to the following:</t>
<ul spacing="compact">
<li><t>Text SHOULD be matched in a case-insensitive manner.</t></li>
<li><t>Text contained in either (but matched) single or double quotes SHOULD be treated as a <strong>phrase search</strong>, that is a match is required for that exact sequence of words, excluding the surrounding quotation marks. Use <tt>\"</tt>, <tt>\'</tt> and <tt>\\</tt> to match a literal <tt>"</tt>, <tt>'</tt> and <tt>\</tt> respectively in a phrase.</t></li>
<li><t>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.</t></li>
<li><t>Tokens MAY be matched on a whole-word basis using stemming (so for example a text search for <tt>bus</tt> would match "buses" but not "business").</t></li>
</ul>
</section>
<section anchor="sorting"><name>Sorting</name>
<t>The following properties MUST be supported for sorting:</t>
<ul spacing="compact">
<li><t>start</t></li>
<li><t>uid</t></li>
<li><t>recurrenceId</t></li>
</ul>
<t>The following properties SHOULD be supported for sorting:</t>
<ul spacing="compact">
<li><t>created</t></li>
<li><t>updated</t></li>
</ul>
</section>
</section>
<section anchor="calendarevent-querychanges"><name>CalendarEvent/queryChanges</name>
<t>This is a standard "/queryChanges" method as described in <xref target="RFC8620" section="5.6" />.</t>
</section>
<section anchor="calendarevent-parse"><name>CalendarEvent/parse</name>
<t>This method allows the client to parse blobs as <tt>iCalendar</tt> files <xref target="RFC5545"></xref> to get <tt>CalendarEvent</tt> 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 <tt>urn:ietf:params:jmap:calendars:parse</tt> capability, as per <xref target="urn-ietf-params-jmap-calendars-parse" />.</t>
<t>The following metadata properties on the CalendarEvent objects will be <tt>null</tt> if requested:</t>
<ul spacing="compact">
<li><t>id</t></li>
<li><t>baseEventId</t></li>
<li><t>calendarIds</t></li>
<li><t>isDraft</t></li>
<li><t>isOrigin</t></li>
</ul>
<t>The "CalendarEvent/parse" method takes the following arguments:</t>
<ul spacing="compact">
<li><t><strong>accountId</strong>: <tt>Id</tt></t>
<t>The id of the account to use.</t></li>
<li><t><strong>blobIds</strong>: <tt>Id[]</tt></t>
<t>The ids of the blobs to parse.</t></li>
<li><t><strong>properties</strong>: <tt>String[]</tt></t>
<t>If supplied, only the properties listed in the array are returned for each <tt>CalendarEvent</tt> object. If omitted, defaults to all the properties.</t></li>
</ul>
<t>The response object contains the following arguments:</t>
<ul spacing="compact">
<li><t><strong>accountId</strong>: <tt>Id</tt></t>
<t>The id of the account used for the call.</t></li>
<li><t><strong>parsed</strong>: <tt>Id[CalendarEvent[]]|null</tt></t>
<t>A map of blob ids to parsed <tt>CalendarEvent</tt> objects representations for each successfully parsed blob, or <tt>null</tt> if none.</t></li>
<li><t><strong>notFound</strong>: <tt>Id[]|null</tt></t>
<t>A list of blob ids given that could not be found, or <tt>null</tt> if none.</t></li>
<li><t><strong>notParsable</strong>: <tt>Id[]|null</tt></t>
<t>A list of blob ids given that corresponded to blobs that could not be parsed as CalendarEvents, or <tt>null</tt> if none.</t></li>
</ul>
<t>Parsed <tt>iCalendars</tt> are to be converted into <tt>CalendarEvent</tt> objects following the process defined in the <eref target="https://datatracker.ietf.org/doc/draft-ietf-calext-jscalendar-icalendar">JSCalendar: Converting from and to iCalendar</eref> document.</t>
</section>
</section>
<section anchor="alerts"><name>Alerts</name>
<t>Alerts may be specified on events as described in <xref target="RFC8984" section="4.5" />.</t>
<t>Alerts MUST only be triggered for events in calendars where the user is subscribed.</t>
<t>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.</t>
<t>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.</t>
<section anchor="default-alerts"><name>Default alerts</name>
<t>If the "useDefaultAlerts" property of an event is true, the alerts are taken from the "defaultAlertsWithTime" or "defaultAlertsWithoutTime" property of all Calendars (see <xref target="calendars" />) the event is in, rather than the "alerts" property of the CalendarEvent.</t>
<t>When using default alerts, the "alerts" property of the event is ignored except for the following:</t>
<ul spacing="compact">
<li><t>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 <xref target="acknowledging-an-alert" /> on acknowledging alerts.</t></li>
<li><t>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 <xref target="snoozing-an-alert" />.</t></li>
</ul>
</section>
<section anchor="acknowledging-an-alert"><name>Acknowledging an alert</name>
<t>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.</t>
<t>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.</t>
</section>
<section anchor="snoozing-an-alert"><name>Snoozing an alert</name>
<t>Users may wish to dismiss an alert temporarily and have it come back after a specific period of time. To do this, clients MUST:</t>
<ol spacing="compact">
<li><t>Acknowledge the alert as described in <xref target="acknowledging-an-alert" />.</t></li>
<li><t>Add a new alert to the event with an <tt>AbsoluteTrigger</tt> 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.</t></li>
</ol>
<t>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.</t>
</section>
<section anchor="push-events"><name>Push events</name>
<t>Servers that support the <tt>urn:ietf:params:jmap:calendars</tt> capability MUST support registering for the pseudo-type "CalendarAlert" in push subscriptions and event source connections, as described in <xref target="RFC8620"></xref>, Sections <xref target="RFC8620" section="7.2" sectionFormat="bare" /> and <xref target="RFC8620" section="7.3" sectionFormat="bare" />.</t>
<t>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".</t>
<t>A <strong>CalendarAlert</strong> object has the following properties:</t>
<ul spacing="compact">
<li><t><strong>@type</strong>: <tt>String</tt></t>
<t>This MUST be the string "CalendarAlert".</t></li>
<li><t><strong>accountId</strong>: <tt>Id</tt></t>
<t>The account id for the calendar in which the alert triggered.</t></li>
<li><t><strong>calendarEventId</strong>: <tt>Id</tt></t>
<t>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.</t></li>
<li><t><strong>uid</strong>: <tt>String</tt></t>
<t>The uid property of the CalendarEvent for the alert that triggered.</t></li>
<li><t><strong>recurrenceId</strong>: <tt>LocalDateTime|null</tt></t>
<t>The recurrenceId for the instance of the event for which this alert is being
triggered, or <tt>null</tt> if the event is not recurring.</t></li>
<li><t><strong>alertId</strong>: <tt>String</tt></t>
<t>The id for the alert that triggered.</t></li>
</ul>
</section>
</section>
<section anchor="calendar-event-notifications"><name>Calendar Event Notifications</name>
<t>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.</t>
<t>Notifications are only created by the server; users cannot create them directly. Clients may 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.</t>
<t>The server SHOULD create a CalendarEventNotification whenever an event is added, updated or destroyed by another user or due to receiving an iTIP <xref target="RFC5546"></xref> 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.</t>
<t>The CalendarEventNotification does not have any per-user data. A single instance may therefore be maintained on the server for all sharees of the notification. The server need only keep track of which users have yet to destroy the notification.</t>
<section anchor="auto-deletion-of-notifications"><name>Auto-deletion of Notifications</name>
<t>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.</t>
<t>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).</t>
</section>
<section anchor="object-properties"><name>Object Properties</name>
<t>The <strong>CalendarEventNotification</strong> object has the following properties:</t>
<ul spacing="compact">
<li><t><strong>id</strong>: <tt>Id</tt></t>
<t>The id of the CalendarEventNotification.</t></li>
<li><t><strong>created</strong>: <tt>UTCDateTime</tt></t>
<t>The time this notification was created.</t></li>
<li><t><strong>changedBy</strong>: <tt>Person</tt></t>
<t>Who made the change. The Person object has the following properties:</t>
<ul spacing="compact">
<li><t><strong>name</strong>: <tt>String</tt></t>
<t>The name of the person who made the change.</t></li>
<li><t><strong>email</strong>: <tt>String|null</tt></t>
<t>The email of the person who made the change, or null if no email is available.</t></li>
<li><t><strong>principalId</strong>: <tt>Id|null</tt></t>
<t>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 an entity outside of this user's organisation, e.g. an iTIP invitation from an external person.</t></li>
<li><t><strong>calendarUserAddress</strong>: <tt>String|null</tt></t>
<t>The calendarUserAddress URI of the person who made the change, if any. This may be set if the change was made due to receving a scheduling message, such as an iTIP message, in addition to changes made by internal users.</t></li>
</ul></li>
<li><t><strong>comment</strong>: <tt>String|null</tt></t>
<t>Comment sent along with the change by the user that made it. (e.g. COMMENT
property in an iTIP message), if any.</t></li>
<li><t><strong>type</strong>: <tt>String</tt></t>
<t>This MUST be one of</t>
<ul spacing="compact">
<li><t>created</t></li>
<li><t>updated</t></li>
<li><t>destroyed</t></li>
</ul></li>
<li><t><strong>calendarEventId</strong>: <tt>Id</tt></t>
<t>The id of the CalendarEvent that this notification is about.</t></li>
<li><t><strong>isDraft</strong>: <tt>Boolean</tt> (created/updated only)</t>
<t>Is this event a draft?</t></li>
<li><t><strong>event</strong>: <tt>JSCalendar Event</tt></t>
<t>The data before the change (if updated or destroyed), or the data
after creation (if created).</t></li>
<li><t><strong>eventPatch</strong>: <tt>PatchObject</tt> (updated only)</t>
<t>A patch encoding the change between the data in the event property, and the
data after the update.</t></li>
</ul>
<t>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.</t>
</section>
<section anchor="calendareventnotification-get"><name>CalendarEventNotification/get</name>
<t>This is a standard "/get" method as described in <xref target="RFC8620" section="5.1" />.</t>
</section>
<section anchor="calendareventnotification-changes"><name>CalendarEventNotification/changes</name>
<t>This is a standard "/changes" method as described in <xref target="RFC8620" section="5.2" />.</t>
</section>
<section anchor="calendareventnotification-set"><name>CalendarEventNotification/set</name>
<t>This is a standard "/set" method as described in <xref target="RFC8620" section="5.3" />.</t>
<t>Only destroy is supported; any attempt to create/update MUST be rejected with a
<tt>forbidden</tt> SetError.</t>
</section>
<section anchor="calendareventnotification-query"><name>CalendarEventNotification/query</name>
<t>This is a standard "/query" method as described in <xref target="RFC8620" section="5.5" />.</t>
<section anchor="filtering-1"><name>Filtering</name>
<t>A <strong>FilterCondition</strong> object has the following properties:</t>
<ul spacing="compact">
<li><t><strong>after</strong>: <tt>UTCDateTime|null</tt></t>
<t>The creation date must be on or after this date to match the condition.</t></li>
<li><t><strong>before</strong>: <tt>UTCDateTime|null</tt></t>
<t>The creation date must be before this date to match the condition.</t></li>