-
Notifications
You must be signed in to change notification settings - Fork 0
/
draft-calconnect-vpatch.xml
2405 lines (2218 loc) · 79.9 KB
/
draft-calconnect-vpatch.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"?>
<!DOCTYPE rfc SYSTEM 'rfc2629.dtd' []>
<rfc ipr="trust200902" category="std" docName="draft-daboo-icalendar-vpatch" updates="5545, 6321">
<?rfc toc="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<?rfc private=""?>
<?rfc topblock="yes"?>
<?rfc comments="no"?>
<front>
<title abbrev="daboo-icalendar-vpatch">The iCalendar VPATCH Component</title>
<author initials="C." surname="Daboo" fullname="Cyrus Daboo">
<organization>Apple Inc.</organization>
<address>
<postal>
<street>1 Infinite Loop</street>
<city>Cupertino</city>
<code>95014</code>
<country>USA</country>
<region>CA</region>
</postal>
<phone></phone>
<email>[email protected]</email>
<uri>https://www.apple.com</uri>
</address>
</author>
<author initials="K." surname="Murchison" fullname="Kenneth Murchison">
<organization>Carnegie Mellon University</organization>
<address>
<postal>
<street>5000 Forbes Avenue</street>
<city>Pittsburgh</city>
<code>15213</code>
<country>USA</country>
<region>PA</region>
</postal>
<phone></phone>
<email>[email protected]</email>
<uri>https://www.cmu.edu</uri>
</address>
</author>
<date year="2016" month="October" day="28"/>
<area>Internet</area>
<workgroup>Network Working Group</workgroup>
<abstract>
<t>This document defines a new iCalendar <xref target="RFC5545"/> component that
allows small "patches" to be applied to large iCalendar data objects,
to allow for efficient data updates. It also describes how this new
component can be used with the CalDAV calendar data access protocol
<xref target="RFC4791"/>.
</t>
</abstract>
<note title="Open Issues">
<t>
<list style="symbols">
<t>Do we need/want to handle individual values in multi-valued
properties/parameters?</t>
<t>What media type do we advertise in <spanx style="verb">Accept-Patch</spanx> header? Just
<spanx style="verb">text/calendar</spanx>? Currently using <spanx style="verb">text/calendar;
component=VPATCH; optinfo=PATCH-VERSION:1</spanx></t>
</list>
</t>
</note>
</front>
<middle>
<section anchor="introduction" title="Introduction">
<t>The iCalendar <xref target="RFC5545"/> data format is in widespread use to represent
calendar data. iCalendar data can grow large (e.g., a family calendar
containing events over a period of several years). Updating large
resources over the network currently requires the entire data to be
sent - even if the change itself is minor.
</t>
<t>This specification defines a new iCalendar component that can be used
to "patch" (incrementally update) iCalendar data in an efficient
manner. When combined with the HTTP PATCH method <xref target="RFC5789"/>, it can
be used to update calendar object resources on a CalDAV <xref target="RFC4791"/>
server, or any resource on an HTTP server that contains iCalendar
data.
</t>
</section>
<section anchor="conventions-used-in-this-document" title="Conventions Used in This Document">
<t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL",
"SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",
"MAY", and "OPTIONAL" in this document are to be interpreted as
described in <xref target="RFC2119"/>.
</t>
<t>The notation used in this memo is the ABNF notation of <xref target="RFC5234"/> as
used by iCalendar <xref target="RFC5545"/>. Any syntax elements shown below that
are not explicitly defined in this specification come from iCalendar
<xref target="RFC5545"/> and Calendar Availability <xref target="RFC7953"/>.
</t>
</section>
<section anchor="overview" title="Overview">
<t>The basic design of the patch format is a "VPATCH" component (defined
in Section 10.1) containing one or more "PATCH" components (defined
in Section 10.1.1), each specifying a path (which identifies one or
more components in the iCalendar object being patched), and other
components and properties that define the set of changes to be made.
</t>
<t>When multiple "VPATCH" components are present in an iCalendar object,
the order in which they are applied is defined by the value of any
"PATCH-ORDER" properties in the "VPATCH" components. The "VPATCH"
components are sorted in order from lowest "PATCH-ORDER" integer
value to highest, with any components not containing a "PATCH-ORDER"
property placed last. The patch process is then applied in sorted
order (any components with the same "PATCH-ORDER" value can be
applied in any order).
</t>
<t>No specific processing order is defined for multiple "PATCH"
components in a "VPATCH" component.
</t>
<t>The "VPATCH" component also contains an optional "PATCH-VERSION"
property to allow future extensions to the format to be recognized.
This document only defines version number "1". The "PATCH-VERSION"
property only needs to be present if the version number is greater
than "1". If a patch processing engine is unable to handle the
indicated version it MUST reject the entire patch operation defined
by the enclosing iCalendar object, even if other "VPATCH" components
have a "PATCH-VERSION" number that is supported.
</t>
<t>After applying a patch to an iCalendar object, the basic validity of
the resulting iCalendar object SHOULD be checked by the processing
engine (e.g., if the patch added an extra "DTSTART" property to a
"VEVENT" component that would be considered a violation of
<xref target="RFC5545"/>'s cardinality rules for the "DTSTART" property in a
"VEVENT"). If this occurs, the patch operation MUST fail.
</t>
<t>Other validity constraints can be applied if needed. For example,
CalDAV <xref target="RFC4791"/> requires that the "UID" property be the same in all
components in a calendar object resource stored on the server. If a
patch operation adds a component to an iCalendar object with a
different "UID" value than the existing components, that result would
be an invalid CalDAV calendar object resource. If other validity
constraints are violated, the patch operation MUST fail.
</t>
<t>Any failure to process a "VPATCH" component, for whatever reason,
MUST result in the entire patch operation being cancelled, with the
iCalendar object being patched left in its original state.
</t>
</section>
<section anchor="patch-component" title="PATCH Component">
<t>A "PATCH" component (defined in Section 10.1.1) MUST contain one
"PATCH-TARGET" property whose value is an iCalendar path (see
Section 5) that identifies components within the iCalendar object
being patched (see Section 11.2 for special handling of components
representing recurring items). The set of components thus identified
are the "target components" for the patch operations. The set of
patch operations defined by the other components and properties
present in the "PATCH" component are then applied to each target
component (in the order specified below). If a "PATCH-TARGET"
property does not match any components in the iCalendar object being
patched, then the patch operation MUST succeed without any changes
being applied to the iCalendar object being patched.
</t>
<t>Four patch operations are supported:
</t>
<t>
<list style="symbols">
<t>Component additions or updates: any components within the "PATCH"
component are considered to be additions or updates (see
Section 6).</t>
<t>Property additions or updates: any properties (other than those
whose name starts with the "PATCH-" prefix) are considered to be
additions or updates (see Section 7).</t>
<t>Component, property, property parameter, property value, or
property parameter value deletion: indicated by the present of
one or more "PATCH-DELETE" properties (see Section 8).</t>
<t>Property parameter additions or updates: indicated by the
presence of one or more "PATCH-PARAMETER" properties (see
Section 9).</t>
</list>
</t>
<t>When processing a "PATCH" component, the processing engine MUST
follow this order:
</t>
<t>
<list style="symbols">
<t>Process all "PATCH-DELETE" properties first.</t>
<t>Process all "PATCH-PARAMETER" properties second.</t>
<t>Process all other components third.</t>
<t>Process all non "PATCH-" prefixed properties fourth.</t>
</list>
</t>
</section>
<section anchor="icalendar-path" title="iCalendar Path">
<t>The "PATCH-TARGET", "PATCH-DELETE", and "PATCH-PARAMETER" property
values are all iCalendar "paths". The path is used to match
iCalendar elements that the patch operation will be applied to. The
path is a list of "segments" (separated by the "/", "#", ";" or "="
characters) that matches an iCalendar element in the iCalendar object
model hierarchy (a component, a property, a property parameter, a
property value, or a property parameter value). A path can either be
"absolute" (referring to items within the top-level iCalendar object
being patched) or "relative" (referring to items within some other
component as determined by the scope of the operation).
</t>
<t>A path can start with a series of component segments (which always
have a "/" prefix). Those can be followed by a property segment
(which always has a "#" prefix"). A property segment can be followed
by either a parameter segment (which always has a ";" prefix), or a
value segment (which always has a "=" prefix). A parameter segment
can be followed by a value segment (which always has a "=" prefix).
</t>
<t>An absolute path always starts with a "/VCALENDAR" component segment
since an iCalendar object is always a single "VCALENDAR" component.
</t>
<t>A relative path can start with a component segment or a property
segment, with the path assumed to be relative to an enclosing
component defined by the context.
</t>
<t>To target a component inside of another component, a component
segment is appended to the path. Component segments can include an
optional match item. When present, this allows targeting of
components that match a specific "UID" property value, and/or a
"RECURRENCE-ID" value (or lack of "RECURRENCE-ID" property to target
a "master" recurrence component). See Section 11.2 for special
handling of components representing recurring items.
</t>
<t>To target a property inside of a component, a property segment is
added to the path. A property segment can include an optional match
item. When present, this allows targeting of properties by value
(matching or not matching a specific value), or which have a named
property parameter present, or by property parameter value (matching
or not matching a specific value).
</t>
<t>To target a property parameter, a parameter segment is added to the
property segment at the end of the path.
</t>
<t>To target a single value in a multi-valued property, a value segment
is added to the property segment at the end of the path.
</t>
<t>To target a single value in a multi-valued property parameter, a
value segment is added to the parameter segment at the end of the
path.
</t>
<t>Values in match items MUST use URL-style percent (%) encoding of the
characters "/", "#", ";", "=", and "]". This allows a path to be
quickly split into segments by breaking apart the text on the
relevant delimiter characters.
</t>
<t>The syntax for a path is defined by the following notation (note that
some of the syntax elements defined here are not used by this
specification, however, it is anticipated that this general path
syntax will be useful for other specifications):
</t>
<figure align="left"><artwork align="left" type="abnf">
abs-path = abs-comp-path [prop-all-path]
; Absolute path for any iCalendar element
rel-full-path = (comp-path [prop-all-path]) / prop-all-path
; Relative path for any iCalendar element at any depth
; within the enclosing component
rel-one-path = comp-path / prop-all-path
; Relative path for any iCalendar element immediately
; within the enclosing component
abs-comp-path = "/VCALENDAR" *comp-segment
; Absolute path for components only
comp-path = 1*comp-segment
; Path for components only
prop-path = prop-segment
; Relative path for properties only
prop-param-path = prop-segment [param-segment]
; Relative path for property and parameter only
prop-all-path = prop-segment [param-segment] [value-segment]
; Relative path for any element of a property
comp-segment = "/" name comp-match
comp-match = [uid-match] [rid-match]
uid-match = "[UID=" value-escaped "]"
rid-match = "[RID=" ("M" / ridval) "]"
; "M" matches "master" component
prop-segment = prop-prefix [prop-match]
prop-prefix = "#" name
prop-match = "[" ( prop-equal / prop-not-equal /
param-match ) "]"
prop-equal = "=" value-escaped
prop-not-equal = "!" value-escaped
param-match = "@" param-name [ ( param-equal /
param-not-equal ) ]
param-equal = "=" param-value-escaped
param-not-equal = "!" param-value-escaped
param-segment = ";" param-name
value-segment = "=" (value / param-value)
value-escaped = value
; % encoding for "/", "#", ";", and "]"
param-value-escaped = param-value
; % encoding for "/", "#", ";", and "]"
</artwork></figure>
<t>Some examples of "path" items follow.
</t>
<t>Targeting components (path contains exactly one or more component
segments):
</t>
<t>
<list style="symbols">
<t><spanx style="verb">/VCALENDAR</spanx></t>
</list>
</t>
<t>Targets the "VCALENDAR" component in the iCalendar object.
</t>
<t>
<list style="symbols">
<t><spanx style="verb">/VCALENDAR/VEVENT</spanx></t>
</list>
</t>
<t>Targets all "VEVENT" components in the "VCALENDAR" component in
the iCalendar object.
</t>
<t>
<list style="symbols">
<t><spanx style="verb">/VCALENDAR/VEVENT[UID=1234]</spanx></t>
</list>
</t>
<t>Targets any "VEVENT" components that have a "UID" property value
exactly equal to "1234", in the "VCALENDAR" component in the
iCalendar object.
</t>
<t>
<list style="symbols">
<t><spanx style="verb">/VCALENDAR/VEVENT[UID=1234%2F4567][RID=M]</spanx></t>
</list>
</t>
<t>Targets any "VEVENT" components that have a "UID" property value
exactly equal to "1234/4567" and do not have a "RECURRENCE-ID"
property, in the "VCALENDAR" component in the iCalendar object.
</t>
<t>
<list style="symbols">
<t>`/VCALENDAR/VEVENT[UID=1234][RID=20160902T223000Z]
Targets any "VEVENT" components that have a "UID" property value
exactly equal to "1234" and have a "RECURRENCE-ID" property whose
UTC value is "20160902T223000Z", in the "VCALENDAR" component in
the iCalendar object.</t>
</list>
</t>
<t>Targeting properties (path contains exactly zero or more component
segments, and one property segment):
</t>
<t>
<list style="symbols">
<t><spanx style="verb">/VCALENDAR/VEVENT#STATUS</spanx></t>
</list>
</t>
<t>Targets all "STATUS" properties in all "VEVENT" components in the
"VCALENDAR" component in the iCalendar object.
</t>
<t>
<list style="symbols">
<t><spanx style="verb">/VCALENDAR/VEVENT[UID=1234]#STATUS</spanx></t>
</list>
</t>
<t>Targets all "STATUS" properties in any "VEVENT" components that
have a "UID" property value exactly equal to "1234", in the
"VCALENDAR" component in the iCalendar object.
</t>
<t>
<list style="symbols">
<t><spanx style="verb">/VCALENDAR/VEVENT#ATTENDEE[=mailto:[email protected]]</spanx></t>
</list>
</t>
<t>Targets any "ATTENDEE" properties that have the value
"mailto:[email protected]" in all "VEVENT" components, in the
"VCALENDAR" component in the iCalendar object.
</t>
<t>
<list style="symbols">
<t><spanx style="verb">/VCALENDAR/VEVENT#ATTENDEE[!mailto:[email protected]]</spanx></t>
</list>
</t>
<t>Targets any "ATTENDEE" properties that do not have the value
"mailto:[email protected]" in all "VEVENT" components, in the
"VCALENDAR" component in the iCalendar object.
</t>
<t>
<list style="symbols">
<t><spanx style="verb">/VCALENDAR/VEVENT#ATTENDEE[@MEMBER]</spanx></t>
</list>
</t>
<t>Targets any "ATTENDEE" properties that have a "MEMBER" property
parameter present in all "VEVENT" components, in the "VCALENDAR"
component in the iCalendar object
</t>
<t>
<list style="symbols">
<t><spanx style="verb">/VCALENDAR/VEVENT#ATTENDEE[@CN=Cyrus Daboo]</spanx></t>
</list>
</t>
<t>Targets any "ATTENDEE" properties that have a "CN" property
parameter with the value "Cyrus Daboo" present in all "VEVENT"
components, in the "VCALENDAR" component in the iCalendar object.
</t>
<t>
<list style="symbols">
<t><spanx style="verb">/VCALENDAR/VEVENT#ATTENDEE[@CN!Cyrus Daboo]</spanx></t>
</list>
</t>
<t>Targets any "ATTENDEE" properties that have a "CN" property
parameter not equal to the value "Cyrus Daboo", or do not have a
"CN" property parameter present in all "VEVENT" components, in the
"VCALENDAR" component in the iCalendar object.
</t>
<t>
<list style="symbols">
<t><spanx style="verb">#ATTENDEE[=mailto:[email protected]]</spanx>
A relative path that targets any "ATTENDEE" properties that have
the value "mailto:[email protected]" in all components the path is
relative to.</t>
</list>
</t>
<t>Targeting property parameters (path contains exactly zero or more
component segments, one property segment, and one parameter segment):
</t>
<t>
<list style="symbols">
<t><spanx style="verb">/VCALENDAR/VEVENT#ATTENDEE;PARTSTAT</spanx>
Targets the "PARTSTAT" parameter on all "ATTENDEE" properties in
all "VEVENT" components in the "VCALENDAR" component in the
iCalendar object.</t>
<t><spanx style="verb">/VCALENDAR/VEVENT#ATTENDEE[=mailto:[email protected]];PARTSTAT</spanx>
Targets the "PARTSTAT" parameter on any "ATTENDEE" properties that
have the value "mailto:[email protected]" in all "VEVENT"
components, in the "VCALENDAR" component in the iCalendar object.</t>
</list>
</t>
<t>Targeting property values (path contains exactly zero or more
component segments, one property segment, and one value segment):
</t>
<t>
<list style="symbols">
<t><spanx style="verb">/VCALENDAR/VEVENT#EXDATE=20160905</spanx>
Targets all "EXDATE" property values with the value "20160905" in
all "VEVENT" components in the "VCALENDAR" component in the
iCalendar object.</t>
</list>
</t>
<t>Targeting property parameter values (path contains exactly zero or
more component segments, one property segment, one parameter segment,
and one value segment):
</t>
<t>
<list style="symbols">
<t><spanx style="verb">/VCALENDAR/VEVENT#ATTENDEE;MEMBER=mailto:[email protected]</spanx>
Targets all "MEMBER" property parameter values with the value
"mailto:[email protected]" in all "ATTENDEE" properties in all
"VEVENT" components in the "VCALENDAR" component in the iCalendar
object.</t>
</list>
</t>
</section>
<section anchor="adding-or-updating-components" title="Adding or Updating Components">
<t>Any iCalendar component defined in the "PATCH" component (referred to
below as the "action component") is treated as either an addition to
the target component, or as an update of an existing component in the
target component. The following rules are used to process such
components:
</t>
<t>
<list style="symbols">
<t>If the action component contains a "UID" property and a
"RECURRENCE-ID" property, then any components with the same
values for both their "UID" and "RECURRENCE-ID" properties, that
are immediate sub-components of the target component, are removed
from the target component, and the action component is added to
the target component.</t>
<t>If the action component contains a "UID" property and does not
contain a "RECURRENCE-ID" property, then any components with the
same value for their "UID" property, and containing no
"RECURRENCE-ID" property, that are immediate sub-components of
the target component, are removed from the target component, and
the action component is added to the target component.</t>
<t>If the action component does not contain a "UID" property, then
all components with the same name that do not contain a "UID"
property, that are immediate sub-components of the target
component, are removed from the target component, and the action
component is added to the target component.</t>
</list>
</t>
</section>
<section anchor="adding-or-updating-properties" title="Adding or Updating Properties">
<t>Any iCalendar property defined in the "PATCH" component (referred to
below as the "action property") is treated as either an addition to
the target component, or as an update of an existing property in the
target component. A "PATCH-ACTION" (Section 10.4) property parameter
can be defined on action properties and is used to control how the
action is processed. Any "PATCH-ACTION" property parameter MUST be
removed from the action property when it is added to the target
component. The following rules are used to process such properties:
</t>
<t>
<list style="symbols">
<t>If the action property does not contain a "PATCH-ACTION" property
parameter, or contains a "PATCH-ACTION" property parameter with
the default value "BYNAME", then all properties with the same
name in the target component are removed, and the action property
is added to the target component.</t>
<t>If the action property contains a "PATCH-ACTION" property
parameter with the value "CREATE", then the action property is
added to the target component.</t>
<t>If the action property contains a "PATCH-ACTION" property
parameter with the value "BYVALUE", then all properties with the
same name and same value in the target component are removed, and
the action property is added to the target component.</t>
<t>If the action property contains a "PATCH-ACTION" property
parameter with the value starting with "BYPARAM", then all
properties with the same name and a property parameter that
matches the one that is part of the "PATCH-ACTION" property
value, in the target component are removed, and the action
property is added to the target component.</t>
</list>
</t>
<t>The "PATCH-ACTION=BYNAME" operation is used for adding or updating
"singleton" properties - properties that only appear once in a given
iCalendar component (e.g., "DTSTART", "DTEND", "LOCATION", etc).
</t>
<t>The "PATCH-ACTION=CREATE" operation is used for adding "multi-
occurring" properties - properties that can appear more than once in
a given iCalendar component (e.g., "ATTENDEE", "ATTACH", "EXDATE",
etc).
</t>
<t>The "PATCH-ACTION=BYVALUE" operation is used for updating a specific
"multi-occurring" property that can be uniquely identified by its
value (e.g., the "ATTENDEE" property can appear multiple times in a
"VEVENT" component, but each property will have a unique value in
that component). This operation cannot be used when the value of the
property is being changed. Instead, the "PATCH-ACTION=BYPARAM"
operation can be used to identify the target property.
</t>
<t>The "PATCH-ACTION=BYPARAM" operation is used for updating a specific
"multi-occurring" property that can be uniquely identified by a
parameter value that is the same in the action and target properties.
</t>
<t>There may be some situations where a multi-occurring property cannot
be uniquely identified. In such cases, the solution to updating one
or more of them is to use a "PATCH-ACTION=BYNAME" to replace all the
existing properties with one new one, then use "PATCH-ACTION=CREATE"
to add back others that are unchanged or also being updated. Whilst
this is not ideal, it is anticipated that these situations can be
avoided by adding appropriate property parameters with unique values
to help disambiguate the multi-occurring properties.
</t>
</section>
<section anchor="deleting-components-properties-or-property-parameters" title="Deleting Components, Properties, or Property Parameters">
<t>The "PATCH-DELETE" property (defined in Section 10.3.2) is used to
indicate deletion of iCalendar elements from the component identified by
the "PATCH-TARGET" property in the same "PATCH" component as the
"PATCH-DELETE" property. As such, the value of the "PATCH-DELETE"
property is always a relative path (see Section 5) that refers to an
element that is an immediate "child" of the target component.
</t>
<t>The following operations are supported:
</t>
<t>Delete components
:
The "PATCH-DELETE" path value targets components only. The matching
components are removed from the "parent" target component.
</t>
<t>Properties
:
The "PATCH-DELETE" path value targets properties only. The matching
properties are removed from the "parent" target component.
</t>
<t>Property parameters
:
The "PATCH-DELETE" path value targets property parameters on specific
properties only. The matching property parameters are removed from
the corresponding property.
</t>
<t>Property values
:
The "PATCH-DELETE" path value targets a property value on specific
multi-valued properties only. The matching property value is removed
from the the corresponding property. If that results in a property
with no value, that property is also removed from its "parent" target
component.
</t>
<t>Property parameter values
:
The "PATCH-DELETE" path value targets a property parameter value on a
specific multi-valued property parameter on specific properties only.
The matching property parameter value is removed from the
corresponding property parameter. If that results in a property
parameter with no value, that property parameter is also removed from
from the corresponding property.
</t>
</section>
<section anchor="adding-or-updating-property-parameters" title="Adding or Updating Property Parameters">
<t>The "PATCH-PARAMETER" property (defined in Section 10.3.3) is used to
indicate addition or update of property parameters and property
parameter values to properties contained in the components identified by
the "PATCH-TARGET" property in the same "PATCH" component as the
"PATCH-PARAMETER" property. As such, the value of the "PATCH-
PARAMETER" property is always a relative path (see Section 5) that
refers to a property that is an immediate "child" of the target
component.
</t>
<t>The following operations are supported:
</t>
<t>Add or update property parameters
:
The "PATCH-PARAMETER" path value targets a property only. Any
property parameters defined on the "PATCH-PARAMETER" replace the
matching parameters on the target property, or are added to the target
property if no matching parameters exist.
</t>
<t>Add a property parameter value
:
The "PATCH-PARAMETER" path value targets a multi-valued parameter
only. The values in any property parameters defined on the
"PATCH-PARAMETER" property are added to the corresponding property
parameters of the target properties. If no corresponding property
parameter is defined on the target properties, then property
parameters are created with the corresponding values.
</t>
</section>
<section anchor="icalendar-extensions" title="iCalendar Extensions">
<t>This specification adds a new "VPATCH" calendar component to
iCalendar. The "VPATCH" component is itself a container for a new
"PATCH" sub-component.
</t>
<section anchor="vpatch-component" title="VPATCH Component">
<t>Component Name: VPATCH
</t>
<t>
<list style="hanging">
<t hangText="Purpose:">
<vspace />
Provide a grouping of "PATCH" sub-components that describe
the patch actions to be performed.</t>
<t hangText="Description:">
<vspace />
This component serves as a container for a series of
"PATCH" sub-components, each specifying patch actions to be
performed on a certain target element in an iCalendar object.</t>
<t hangText="Format Definition:
:
A "VPATCH" calendar component is defined by the following notation:">
<vspace />
</t>
</list>
</t>
<figure align="left"><artwork align="left" type="abnf">
vpatchc = "BEGIN" ":" "VPATCH" CRLF
vpatchprop action
"END" ":" "VPATCH" CRLF
vpatchprop = *(
;
; The following are REQUIRED,
; but MUST NOT occur more than once.
;
dtstamp / uid /
;
;
; The following are OPTIONAL,
; but MUST NOT occur more than once.
;
patch-version / patch-order /
;
; The following are OPTIONAL,
; and MAY occur more than once.
;
other-prop
;
)
other-prop = ( iana-prop / x-prop )
action = *( patchc / iana-comp / x-comp )
</artwork></figure>
<section anchor="patch-component-1" title="PATCH Component">
<t>
<list style="hanging">
<t hangText="Component Name:">
<vspace />
PATCH</t>
<t hangText="Purpose
:
Provide a set of components, properties, and property parameters to be
added to, deleted from, or updated in the iCalendar object.">
<vspace />
</t>
<t hangText="Description:
:
This component provides a grouping of patch actions to be performed
within the scope of a set of components. If the "PATCH-TARGET"
property matches one or more iCalendar components, then the target
components are patched using the remaining properties and components.
If there is no iCalendar component that matches the "PATCH-TARGET"
property in the iCalendar object, the "PATCH" action MUST succeed
without any changes being applied to the iCalendar object being
patched.">
<vspace />
</t>
<t hangText="Format Definition:
:
A "PATCH" calendar component is defined by the following notation:">
<vspace />
</t>
</list>
</t>
<figure align="left"><artwork align="left" type="abnf">
patchc = "BEGIN" ":" "PATCH" CRLF
patchprop subcomp
"END" ":" "PATCH" CRLF
patchprop = *(
;
; The following is REQUIRED,
; but MUST NOT occur more than once.
;
patchtarget /
;
; The following are OPTIONAL,
; and MAY occur more than once.
;
patchdelete / patchparam / other-prop
;
)
subcomp = *(
;
; The following are OPTIONAL,
; and MAY occur more than once.
;
eventc / todoc / journalc / freebusyc /
timezonec / alarmc / standard / daylight /
availabilityc / availablec /
iana-comp / x-comp
;
)
</artwork></figure>
</section>
</section>
<section anchor="vpatch-properties" title="VPATCH Properties">
<t>The "VPATCH" properties are attributes that apply to the "VPATCH"
component, as a whole. These properties do not appear within "VPATCH"
sub-components. They SHOULD be specified after the "BEGIN:VPATCH"
delimiter string and prior to any sub-component.
</t>
<section anchor="patchversion-property" title="PATCH-VERSION Property">
<t>Property Name: PATCH-VERSION
</t>
<t>Purpose: This property specifies the identifier corresponding to the
highest version number of the "VPATCH" specification that is
required in order to interpret the "VPATCH" component.
</t>
<t>Value Type: INTEGER
</t>
<t>Property Parameters: IANA and nonstandard property parameters can be
specified on this property.
</t>
<t>Conformance: This property can be specified once in an "VPATCH"
component. The default value is "1". This property MUST be
specified if its value is greater than "1". Otherwise, this
property is OPTIONAL.
</t>
<t>Description: A value of "1" corresponds to this memo. See Section 3
for a description of how this property is used.
</t>
<t>Format Definition: This property is defined by the following
notation:
</t>
<figure align="left"><artwork align="left" type="abnf">
patch-version = "PATCH-VERSION pverparam ":" pvervalue CRLF
pverparam = *(";" other-param)
pvervalue = "1" / pmaxver
; "1" signifies compliance with this memo
pmaxver = <A IANA-registered VPATCH version>
; Maximum VPATCH version needed to process the VPATCH
; component.
</artwork></figure>
<t>Example: The following is an example of this property:
</t>
<figure align="left"><artwork align="left">
PATCH-VERSION:1
</artwork></figure>
</section>
<section anchor="patchorder-property" title="PATCH-ORDER Property">
<t>Property Name: PATCH-ORDER
</t>
<t>Purpose: This property specifies the ordering of the associated
"VPATCH" component.
</t>
<t>Value Type: INTEGER
</t>
<t>Property Parameters: IANA and nonstandard property parameters can be
specified on this property.
</t>
<t>Conformance: This property can be specified once in a "VPATCH"
component.
</t>
<t>Description: This property is OPTIONAL and is used to indicate the
relative ordering of the associated "VPATCH" component amongst its
siblings. See Section 3 for a description of how this property is
used.
</t>
<t>Format Definition: This property is defined by the following
notation:
</t>
<figure align="left"><artwork align="left" type="abnf">
patch-order = "PATCH-ORDER porderparam ":" integer CRLF
porderparam = *(";" other-param)
</artwork></figure>
<t>Example: The following is an example of this property:
</t>
<figure align="left"><artwork align="left">
PATCH-ORDER:1
</artwork></figure>
</section>
</section>
<section anchor="patch-component-properties" title="PATCH Component Properties">
<t>The following properties can appear within PATCH components.
</t>
<section anchor="patchtarget-property" title="PATCH-TARGET Property">
<t>Property Name: PATCH-TARGET
</t>
<t>Purpose: This property specifies a path targeting one or more
components within an iCalendar object.
</t>
<t>Value Type: TEXT
</t>
<t>Property Parameters: IANA and nonstandard property parameters can be
specified on this property.
</t>
<t>Conformance: This property MUST be specified within any "PATCH" sub-
component.
</t>
<t>Description: This property is used to match iCalendar components
that the patch operations will be applied to. The path value is
always an absolute path, and interpreted as described in
Section 5.
</t>
<t>Format Definition: This property is defined by the following
notation:
</t>
<figure align="left"><artwork align="left" type="abnf">
patchtarget = "PATCH-TARGET ptargetparam ":" ptargetpath CRLF
ptargetparam = *(";" other-param)
ptargetpath = abs-comp-path / comp-path
; This specification only defines how abs-comp-path
; is used. Use of the comp-path element will be
; defined by other specifications wishing to make use
; of "relative" patches.
</artwork></figure>
<t>Example: The following is an example of this property:
</t>
<figure align="left"><artwork align="left">
PATCH-TARGET:/VCALENDAR/VEVENT[UID=1234]
</artwork></figure>
</section>
<section anchor="patchdelete-property" title="PATCH-DELETE Property">
<t>Property Name: PATCH-DELETE
</t>
<t>Purpose: This property specifies a path (relative to "PATCH-TARGET")
targeting one or more components, properties, or parameters to be
removed from the target components identified by "PATCH-TARGET".
</t>
<t>Value Type: TEXT
</t>
<t>Property Parameters: IANA and nonstandard property parameters can be
specified on this property.
</t>
<t>Conformance: This property can be specified within a "PATCH" sub-
component.
</t>
<t>Description: This property is used to match iCalendar elements that
will be deleted. The path value is always a relative path for
only immediate components and properties within the target
component, and interpreted as described in Section 8.
</t>
<t>Format Definition: This property is defined by the following
notation:
</t>
<figure align="left"><artwork align="left" type="abnf">
patchdelete = "PATCH-DELETE pdeleteparam ":" pdeletepath CRLF
pdeleteparam = *(";" other-param)
pdeletepath = rel-one-path
; PATCH-DELETE path is relative to PATCH-TARGET path
</artwork></figure>
<t>Example: The following are examples of this property:
</t>
<t>PATCH-DELETE:/VEVENT[UID=1234]
PATCH-DELETE:#ATTENDEE[=mailto:[email protected]]
</t>
</section>
<section anchor="patchparameter-property" title="PATCH-PARAMETER Property">
<t>Property Name: PATCH-PARAMETER
</t>
<t>Purpose: This property specifies a set of parameters to be set on
the target property.
</t>
<t>Value Type: TEXT
</t>
<t>Property Parameters: IANA and nonstandard property parameters can be
specified on this property.
</t>
<t>Conformance: This property can be specified within a "PATCH" sub-
component.
</t>
<t>Description: This property specifies parameters to be set on the
target property. The path value is always a relative path to a
property within the target component, and interpreted as described
in Section 9.
</t>
<t>Format Definition: This property is defined by the following
notation:
</t>
<figure align="left"><artwork align="left" type="abnf">
patchparam = "PATCH-PARAMETER pparamparam ":" pparampath CRLF
pparamparam = *(";" other-param)
pparampath = prop-param-path
</artwork></figure>
<t>Example: The following are examples of this property:
</t>
<figure align="left"><artwork align="left">
PATCH-PARAMETER;PARTSTAT=NEEDS-ACTION:
#ATTENDEE[=mailto:[email protected]]
PATCH-PARAMETER;PARTSTAT=NEEDS-ACTION:#ATTENDEE[@CN=Cyrus Daboo]
PATCH-PARAMETER;MEMBER=mailto:[email protected]:#ATTENDEE;MEMBER
</artwork></figure>
</section>
</section>
<section anchor="patchaction-property-parameter" title="PATCH-ACTION Property Parameter">
<t>Parameter Name: PATCH-ACTION
</t>
<t>Purpose: To specify whether the property should be added or
replaced.
</t>
<t>Format Definition: This parameter is defined by the following
notation:
</t>
<figure align="left"><artwork align="left" type="abnf">
pactionparam = "PATCH-ACTION" "="