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
|
<pre>Independent Submission E. Wilde
Request for Comments: 7351 UC Berkeley
Category: Informational August 2014
ISSN: 2070-1721
<span class="h1">A Media Type for XML Patch Operations</span>
Abstract
The XML patch document format defines an XML document structure for
expressing a sequence of patch operations to be applied to an XML
document. The XML patch document format builds on the foundations
defined in <a href="./rfc5261">RFC 5261</a>. This specification also provides the media type
registration "application/xml-patch+xml", to allow the use of XML
patch documents in, for example, HTTP conversations.
Status of This Memo
This document is not an Internet Standards Track specification; it is
published for informational purposes.
This is a contribution to the RFC Series, independently of any other
RFC stream. The RFC Editor has chosen to publish this document at
its discretion and makes no statement about its value for
implementation or deployment. Documents approved for publication by
the RFC Editor are not a candidate for any level of Internet
Standard; see <a href="./rfc5741#section-2">Section 2 of RFC 5741</a>.
Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
<a href="http://www.rfc-editor.org/info/rfc7351">http://www.rfc-editor.org/info/rfc7351</a>.
Copyright Notice
Copyright (c) 2014 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to <a href="https://www.rfc-editor.org/bcp/bcp78">BCP 78</a> and the IETF Trust's Legal
Provisions Relating to IETF Documents
(<a href="http://trustee.ietf.org/license-info">http://trustee.ietf.org/license-info</a>) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document.
<span class="grey">Wilde Informational [Page 1]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-2" ></span>
<span class="grey"><a href="./rfc7351">RFC 7351</a> XML Patch August 2014</span>
Table of Contents
<a href="#section-1">1</a>. Introduction . . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-2">2</a>
<a href="#section-2">2</a>. Patch Documents . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-3">3</a>
<a href="#section-2.1">2.1</a>. Patch Document Format . . . . . . . . . . . . . . . . . . <a href="#page-3">3</a>
<a href="#section-2.2">2.2</a>. Patch Examples . . . . . . . . . . . . . . . . . . . . . <a href="#page-5">5</a>
<a href="#section-3">3</a>. IANA Considerations . . . . . . . . . . . . . . . . . . . . . <a href="#page-5">5</a>
<a href="#section-4">4</a>. Security Considerations . . . . . . . . . . . . . . . . . . . <a href="#page-7">7</a>
<a href="#section-5">5</a>. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . <a href="#page-7">7</a>
<a href="#section-6">6</a>. References . . . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-7">7</a>
<a href="#section-6.1">6.1</a>. Normative References . . . . . . . . . . . . . . . . . . <a href="#page-7">7</a>
<a href="#section-6.2">6.2</a>. Informative References . . . . . . . . . . . . . . . . . <a href="#page-7">7</a>
<a href="#appendix-A">Appendix A</a>. Implementation Hints . . . . . . . . . . . . . . . . <a href="#page-9">9</a>
<a href="#appendix-A.1">A.1</a>. Matching Namespaces . . . . . . . . . . . . . . . . . . . <a href="#page-9">9</a>
<a href="#appendix-A.2">A.2</a>. Patching Namespaces . . . . . . . . . . . . . . . . . . . <a href="#page-10">10</a>
<a href="#appendix-B">Appendix B</a>. ABNF for <a href="./rfc5261">RFC 5261</a> . . . . . . . . . . . . . . . . . <a href="#page-12">12</a>
<span class="h2"><a class="selflink" id="section-1" href="#section-1">1</a>. Introduction</span>
The Extensible Markup Language (XML) [<a href="./rfc7303" title=""XML Media Types"">RFC7303</a>] is a common format for
the exchange and storage of structured data. HTTP PATCH [<a href="./rfc5789" title=""PATCH Method for HTTP"">RFC5789</a>]
extends HTTP [<a href="./rfc7231" title=""Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content"">RFC7231</a>] with a method to perform partial modifications
to resources. HTTP PATCH requires that patch documents be sent along
with the request, and it is therefore useful for there to be
standardized patch document formats (identified by media types) for
popular media types.
The XML patch media type "application/xml-patch+xml" is an XML
document structure for expressing a sequence of operations to apply
to a target XML document, suitable for use with the HTTP PATCH
method. Servers can freely choose which patch formats they want to
accept, and "application/xml-patch+xml" could be a simple default
format that can be used unless a server decides to use a different
(maybe more sophisticated) patch format for XML.
The format for patch documents is based on the XML patch framework
defined in <a href="./rfc5261">RFC 5261</a> [<a href="./rfc5261" title=""An Extensible Markup Language (XML) Patch Operations Framework Utilizing XML Path Language (XPath) Selectors"">RFC5261</a>]. While <a href="./rfc5261">RFC 5261</a> does define a concrete
syntax as well as the media type "application/patch-ops-error+xml"
for error documents, it only defines XML Schema (XSD)
[<a href="#ref-W3C.REC-xmlschema-1-20041028">W3C.REC-xmlschema-1-20041028</a>] types for patch operations. The
concrete document format and the media type for patch operations are
defined in an XSD defined in this specification.
This specification relies on <a href="./rfc5261">RFC 5261</a> but also requires that errata
reported to date are taken into account. The main reason for the
errata is the problematic ways in which <a href="./rfc5261">RFC 5261</a> relies on XML Path
Language (XPath) as the expression language for selecting the
location of a patch, while at the same time XPath's data model does
<span class="grey">Wilde Informational [Page 2]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-3" ></span>
<span class="grey"><a href="./rfc7351">RFC 7351</a> XML Patch August 2014</span>
not contain sufficient information to determine whether such a
selector indeed can be used for a patch operation or should result in
an error. Specifically, the problem occurs with namespaces, where
XPath does not expose namespace declaration attributes, while the
patch model needs them to determine whether or not a namespace patch
is allowed. <a href="#appendix-A">Appendix A</a> contains more information about the general
problem and errata reports.
<span class="h2"><a class="selflink" id="section-2" href="#section-2">2</a>. Patch Documents</span>
The following sections describe and illustrate the XML patch document
format.
<span class="h3"><a class="selflink" id="section-2.1" href="#section-2.1">2.1</a>. Patch Document Format</span>
The XML patch document format is based on a simple schema that uses a
"patch" element as the document element and allows an arbitrary
sequence of "add", "remove", and "replace" elements as the children
of the document element. These children follow the semantics defined
in <a href="./rfc5261">RFC 5261</a>, which means that each element is treated as an
individual patch operation, and the result of each patch operation is
a patched XML document that is the target XML document for the next
patch operation.
The following simple example patch document contains a single patch
operation. This operation adds a new attribute called
"new-attribute" to the document element of the target XML document.
An XML patch document always uses a "patch" element in the
"urn:ietf:rfc:7351" namespace as the document element that contains
zero or more patch operation elements, which are also in the
"urn:ietf:rfc:7351" namespace.
<p:patch xmlns:p="urn:ietf:rfc:7351">
<p:add sel="*" type="@new-attribute">value</p:add>
</p:patch>
The following more complex example patch document uses the example
from <a href="./rfc5261">RFC 5261</a>, Section A.18 (but changing the example namespaces to
example.com URIs); it uses the same "patch" element and XML namespace
as shown in the simpler example. It shows the general structure of
an XML patch document with multiple operations, as well as an example
of each operation.
<span class="grey">Wilde Informational [Page 3]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-4" ></span>
<span class="grey"><a href="./rfc7351">RFC 7351</a> XML Patch August 2014</span>
<p:patch xmlns="http://example.com/ns1"
xmlns:y="http://example.com/ns2"
xmlns:p="urn:ietf:rfc:7351">
<p:add sel="doc/elem[@a='foo']">
<!-- This is a new child -->
<child id="ert4773">
<y:node/>
</child>
</p:add>
<p:replace sel="doc/note/text()">Patched doc</p:replace>
<p:remove sel="*/elem[@a='bar']/y:child" ws="both"/>
<p:add sel="*/elem[@a='bar']" type="@b">new attr</p:add>
</p:patch>
As this example demonstrates, both the document element "patch" and
the patch operation elements are in the same XML namespace. This is
the result of <a href="./rfc5261">RFC 5261</a> only defining types for the patch operation
elements, which then can be reused in schemas to define concrete
patch elements.
<a href="./rfc5261">RFC 5261</a> defines XSD [<a href="#ref-W3C.REC-xmlschema-1-20041028">W3C.REC-xmlschema-1-20041028</a>] for the patch
operation types. The following schema for the XML patch media type
is based on the types defined in <a href="./rfc5261">RFC 5261</a>, which are imported as
"<a href="./rfc5261">rfc5261</a>.xsd" in the following schema. The schema defines a "patch"
document element, and then allows an unlimited (and possibly empty)
sequence of the "add", "remove", and "replace" operation elements,
which are directly based on the respective types from the schema
defined in <a href="./rfc5261">RFC 5261</a>.
<xs:schema targetNamespace="urn:ietf:rfc:7351"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:import schemaLocation="<a href="./rfc5261">rfc5261</a>.xsd"/>
<xs:element name="patch">
<xs:complexType>
<xs:choice minOccurs="0" maxOccurs="unbounded">
<xs:element name="add" type="add"/>
<xs:element name="remove" type="remove"/>
<xs:element name="replace" type="replace"/>
</xs:choice>
</xs:complexType>
</xs:element>
</xs:schema>
<span class="grey">Wilde Informational [Page 4]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-5" ></span>
<span class="grey"><a href="./rfc7351">RFC 7351</a> XML Patch August 2014</span>
<span class="h3"><a class="selflink" id="section-2.2" href="#section-2.2">2.2</a>. Patch Examples</span>
Since the semantics of the XML patch operations are defined by <a href="./rfc5261">RFC</a>
<a href="./rfc5261">5261</a>, please refer to the numerous examples in that specification for
more XML patch document examples. All the examples in <a href="./rfc5261">RFC 5261</a> can
be taken as examples for the XML patch media type, when looking at
them with two minor changes in mind.
The two differences are that XML patch documents always use the
"patch" element as the document element and that both the "patch"
element and the individual operation elements in XML patch documents
have to be in the XML namespace with the URI "urn:ietf:rfc:7351".
For example, consider the patch example in <a href="./rfc5261#appendix-A.1">RFC 5261, Appendix A.1</a>,
"Adding an Element". In this example, the patch is applied to the
following XML document:
<?xml version="1.0" encoding="UTF-8"?>
<doc>
<note>This is a sample document</note>
</doc>
The patch example is based on the following patch document (with the
element and namespace changes described above):
<?xml version="1.0" encoding="UTF-8"?>
<p:patch xmlns:p="urn:ietf:rfc:7351">
<p:add sel="doc"><foo id="ert4773">This is a new child</foo></p:add>
</p:patch>
Applying the patch results in the following XML document:
<?xml version="1.0" encoding="UTF-8"?>
<doc>
<note>This is a sample document</note>
<foo id="ert4773">This is a new child</foo></doc>
<span class="h2"><a class="selflink" id="section-3" href="#section-3">3</a>. IANA Considerations</span>
The Internet media type [<a href="./rfc6838" title=""Media Type Specifications and Registration Procedures"">RFC6838</a>] for an XML patch document is
application/xml-patch+xml.
Type name: application
Subtype name: xml-patch+xml
Required parameters: none
<span class="grey">Wilde Informational [Page 5]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-6" ></span>
<span class="grey"><a href="./rfc7351">RFC 7351</a> XML Patch August 2014</span>
Optional parameters:
charset: Same as charset parameter for the media type
"application/xml" as specified in <a href="./rfc7303">RFC 7303</a> [<a href="./rfc7303" title=""XML Media Types"">RFC7303</a>].
Encoding considerations: Same as encoding considerations of media
type "application/xml" as specified in <a href="./rfc7303">RFC 7303</a> [<a href="./rfc7303" title=""XML Media Types"">RFC7303</a>].
Security considerations: This media type has all of the security
considerations described in <a href="./rfc7303">RFC 7303</a> [<a href="./rfc7303" title=""XML Media Types"">RFC7303</a>], <a href="./rfc5261">RFC 5261</a>
[<a href="./rfc5261" title=""An Extensible Markup Language (XML) Patch Operations Framework Utilizing XML Path Language (XPath) Selectors"">RFC5261</a>], and <a href="./rfc3470">RFC 3470</a> [<a href="./rfc3470" title=""Guidelines for the Use of Extensible Markup Language (XML) within IETF Protocols"">RFC3470</a>], plus those listed in <a href="#section-4">Section 4</a>.
Interoperability considerations: N/A
Published specification: <a href="./rfc7351">RFC 7351</a>
Applications that use this media type: Applications that
manipulate XML documents.
Additional information:
Magic number(s): N/A
File extension(s): XML documents often use ".xml" as the file
extension, and this media type does not propose a specific
extension other than this generic one.
Macintosh file type code(s): TEXT
Person & email address to contact for further information: Erik
Wilde <dret@berkeley.edu>
Intended usage: COMMON
Restrictions on usage: none
Author: Erik Wilde <dret@berkeley.edu>
Change controller: IETF
<span class="grey">Wilde Informational [Page 6]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-7" ></span>
<span class="grey"><a href="./rfc7351">RFC 7351</a> XML Patch August 2014</span>
<span class="h2"><a class="selflink" id="section-4" href="#section-4">4</a>. Security Considerations</span>
The security considerations from <a href="./rfc5261">RFC 5261</a> [<a href="./rfc5261" title=""An Extensible Markup Language (XML) Patch Operations Framework Utilizing XML Path Language (XPath) Selectors"">RFC5261</a>] apply to the
application/xml-patch+xml media type.
In addition, parsing XML may entail including information from
external sources through XML's mechanism of external entities.
Implementations, therefore, should be aware of the fact that standard
parsers may resolve external entities and thus include external
information as a result of applying patch operations to an XML
document.
<span class="h2"><a class="selflink" id="section-5" href="#section-5">5</a>. Acknowledgements</span>
Thanks for comments and suggestions provided by Bas de Bakker, Tony
Hansen, Bjoern Hoehrmann, and Julian Reschke.
<span class="h2"><a class="selflink" id="section-6" href="#section-6">6</a>. References</span>
<span class="h3"><a class="selflink" id="section-6.1" href="#section-6.1">6.1</a>. Normative References</span>
[<a id="ref-RFC3470">RFC3470</a>] Hollenbeck, S., Rose, M., and L. Masinter, "Guidelines for
the Use of Extensible Markup Language (XML)
within IETF Protocols", <a href="https://www.rfc-editor.org/bcp/bcp70">BCP 70</a>, <a href="./rfc3470">RFC 3470</a>, January 2003.
[<a id="ref-RFC5234">RFC5234</a>] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, <a href="./rfc5234">RFC 5234</a>, January 2008.
[<a id="ref-RFC5261">RFC5261</a>] Urpalainen, J., "An Extensible Markup Language (XML) Patch
Operations Framework Utilizing XML Path Language (XPath)
Selectors", <a href="./rfc5261">RFC 5261</a>, September 2008.
[<a id="ref-RFC6838">RFC6838</a>] Freed, N., Klensin, J., and T. Hansen, "Media Type
Specifications and Registration Procedures", <a href="https://www.rfc-editor.org/bcp/bcp13">BCP 13</a>, <a href="./rfc6838">RFC</a>
<a href="./rfc6838">6838</a>, January 2013.
[<a id="ref-RFC7303">RFC7303</a>] Thompson, H. and C. Lilley, "XML Media Types", <a href="./rfc7303">RFC 7303</a>,
July 2014.
<span class="h3"><a class="selflink" id="section-6.2" href="#section-6.2">6.2</a>. Informative References</span>
[<a id="ref-Err3477">Err3477</a>] RFC Errata, "Errata ID 3477", <a href="./rfc5261">RFC 5261</a>.
[<a id="ref-Err3478">Err3478</a>] RFC Errata, "Errata ID 3478", <a href="./rfc5261">RFC 5261</a>.
[<a id="ref-RFC5789">RFC5789</a>] Dusseault, L. and J. Snell, "PATCH Method for HTTP", <a href="./rfc5789">RFC</a>
<a href="./rfc5789">5789</a>, March 2010.
<span class="grey">Wilde Informational [Page 7]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-8" ></span>
<span class="grey"><a href="./rfc7351">RFC 7351</a> XML Patch August 2014</span>
[<a id="ref-RFC7231">RFC7231</a>] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
(HTTP/1.1): Semantics and Content", <a href="./rfc7231">RFC 7231</a>, June 2014.
[<a id="ref-W3C.REC-DOM-Level-3-Core-20040407">W3C.REC-DOM-Level-3-Core-20040407</a>]
Robie, J., Wood, L., Champion, M., Hegaret, P., Nicol, G.,
Le Hors, A., and S. Byrne, "Document Object Model (DOM)
Level 3 Core Specification", World Wide Web Consortium
Recommendation REC-DOM-Level-3-Core-20040407, April 2004,
<<a href="http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407">http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407</a>>.
[<a id="ref-W3C.REC-xml-20081126">W3C.REC-xml-20081126</a>]
Sperberg-McQueen, C., Yergeau, F., Paoli, J., Maler, E.,
and T. Bray, "Extensible Markup Language (XML) 1.0 (Fifth
Edition)", World Wide Web Consortium Recommendation REC-
xml-20081126, November 2008,
<<a href="http://www.w3.org/TR/2008/REC-xml-20081126">http://www.w3.org/TR/2008/REC-xml-20081126</a>>.
[<a id="ref-W3C.REC-xml-names-20091208">W3C.REC-xml-names-20091208</a>]
Hollander, D., Layman, A., Bray, T., Tobin, R., and H.
Thompson, "Namespaces in XML 1.0 (Third Edition)", World
Wide Web Consortium Recommendation REC-xml-names-20091208,
December 2009,
<<a href="http://www.w3.org/TR/2009/REC-xml-names-20091208">http://www.w3.org/TR/2009/REC-xml-names-20091208</a>>.
[<a id="ref-W3C.REC-xmlschema-1-20041028">W3C.REC-xmlschema-1-20041028</a>]
Thompson, H., Beech, D., Maloney, M., and N. Mendelsohn,
"XML Schema Part 1: Structures Second Edition", World Wide
Web Consortium Recommendation REC-xmlschema-1-20041028,
October 2004,
<<a href="http://www.w3.org/TR/2004/REC-xmlschema-1-20041028">http://www.w3.org/TR/2004/REC-xmlschema-1-20041028</a>>.
[<a id="ref-W3C.REC-xpath-19991116">W3C.REC-xpath-19991116</a>]
DeRose, S. and J. Clark, "XML Path Language (XPath)
Version 1.0", World Wide Web Consortium Recommendation
REC-xpath-19991116, November 1999,
<<a href="http://www.w3.org/TR/1999/REC-xpath-19991116">http://www.w3.org/TR/1999/REC-xpath-19991116</a>>.
[<a id="ref-W3C.REC-xpath20-20101214">W3C.REC-xpath20-20101214</a>]
Boag, S., Berglund, A., Kay, M., Simeon, J., Robie, J.,
Chamberlin, D., and M. Fernandez, "XML Path Language
(XPath) 2.0 (Second Edition)", World Wide Web Consortium
Recommendation REC-xpath20-20101214, December 2010,
<<a href="http://www.w3.org/TR/2010/REC-xpath20-20101214">http://www.w3.org/TR/2010/REC-xpath20-20101214</a>>.
<span class="grey">Wilde Informational [Page 8]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-9" ></span>
<span class="grey"><a href="./rfc7351">RFC 7351</a> XML Patch August 2014</span>
<span class="h2"><a class="selflink" id="appendix-A" href="#appendix-A">Appendix A</a>. Implementation Hints</span>
This section is informative. It describes some issues that might be
interesting for implementers, but it might also be interesting for
users of XML patch that want to understand some of the differences
between standard XPath 1.0 processing and the processing model of
selectors in <a href="./rfc5261">RFC 5261</a>.
Specifically, the issues described in the following two sections have
been identified as technical issues with <a href="./rfc5261">RFC 5261</a> and have been filed
as errata. Implementers interested in using XML patch are encouraged
to take those errata into account when implementing XML patch
documents. The issue about "Matching Namespaces" described in
<a href="#appendix-A.1">Appendix A.1</a> has been filed as RFC Errata ID 3477 [<a href="#ref-Err3477" title=""Errata ID 3477"">Err3477</a>]. The
issue about "Patching Namespaces" described in <a href="#appendix-A.2">Appendix A.2</a> has been
filed as RFC Errata ID 3478 [<a href="#ref-Err3478" title=""Errata ID 3478"">Err3478</a>].
<span class="h3"><a class="selflink" id="appendix-A.1" href="#appendix-A.1">A.1</a>. Matching Namespaces</span>
<a href="./rfc5261">RFC 5261</a> defines standard rules for matching prefixed names in
expressions: any prefixes are interpreted according to the namespace
bindings of the diff document (the document that the expression is
applied against). This means that each prefixed name can be
interpreted in the context of the diff document.
For unprefixed names in expressions, the rules depart from XPath 1.0
[<a href="#ref-W3C.REC-xpath-19991116">W3C.REC-xpath-19991116</a>]. XPath 1.0 defines that unprefixed names in
expressions match namespace-less names (i.e., there is no "default
namespace" for names used in XPath 1.0 expressions). <a href="./rfc5261">RFC 5261</a>
requires, however, that unprefixed names in expressions must use the
default namespace of the diff document (if there is one). This means
that it is not possible to simply take a selector from a patch
document and evaluate it in the context of the diff document
according to the rules of XPath 1.0 because this would interpret
unprefixed names incorrectly. As a consequence, it is not possible
to simply take an XPath 1.0 processor and evaluate XML patch
selectors in the context of the diff document.
As an extension of XPath 1.0's simple model, XPath 2.0
[<a href="#ref-W3C.REC-xpath20-20101214">W3C.REC-xpath20-20101214</a>] specifies different processing rules for
unprefixed names: they are matched against the URI of the "default
element/type namespace", which is defined as part of an expression's
static context. In some XPath 2.0 applications, this can be set; XSL
Transformations (XSLT) 2.0, for example, has the ability to define an
"xpath-default-namespace", which then will be used to match
unprefixed names in expressions. Thus, by using an XPath 2.0
implementation that allows one to set this URI, and setting it to the
default namespace of the diff document (or leaving it undefined if
<span class="grey">Wilde Informational [Page 9]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-10" ></span>
<span class="grey"><a href="./rfc7351">RFC 7351</a> XML Patch August 2014</span>
there is no such default namespace), it is possible to use an out-of-
the-box XPath 2.0 implementation for evaluating XML patch selectors.
Please keep in mind, however, that evaluating selectors is only one
part of applying patches. When it comes to applying the actual patch
operation, neither XPath 1.0 nor XPath 2.0 are sufficient because
they do not preserve some of the information from the XML syntax
(specifically namespace declarations) that is required to correctly
apply patch operations. The following section describes this issue
in more detail.
Please note that <a href="./rfc5261#section-4.2.2">[RFC5261], Section 4.2.2</a> on namespace matching
explains XPath 2.0's rules incorrectly. For this reason, RFC Errata
ID 3477 is available for <a href="./rfc5261#section-4.2.2">Section 4.2.2 of RFC 5261</a>.
<span class="h3"><a class="selflink" id="appendix-A.2" href="#appendix-A.2">A.2</a>. Patching Namespaces</span>
One of the issues when patching namespaces based on XPath is that
XPath exposes namespaces differently than the XML 1.0
[<a href="#ref-W3C.REC-xml-20081126">W3C.REC-xml-20081126</a>] syntax for XML namespaces
[<a href="#ref-W3C.REC-xml-names-20091208">W3C.REC-xml-names-20091208</a>]. In the XML syntax, a namespace is
declared with an attribute using the reserved name or prefix "xmlns",
and this results in this namespace being available recursively
through the document tree. In XPath, the namespace declaration is
not exposed as an attribute (i.e., the attribute, although
syntactically an XML attribute, is not accessible in XPath), but the
resulting namespace nodes are exposed recursively through the tree.
<a href="./rfc5261">RFC 5261</a> uses the terms "namespace declaration" and "namespace"
almost interchangeably, but it is important to keep in mind that the
namespace declaration is an XML syntax construct that is unavailable
in XPath, while the namespace itself is a logical construct that is
not visible in the XML syntax, but a result of a namespace
declaration. The intent of <a href="./rfc5261">RFC 5261</a> is to patch namespaces as if
namespace declarations were patched; thus, it only allows patching
namespace nodes on the element nodes where the namespace has been
declared.
Patching namespaces in XML patch is supposed to "emulate" the effect
of actually changing the namespace declaration (which is why a
namespace can only be patched at the element where it has been
declared). Therefore, when patching a namespace, even though XPath's
"namespace" axis is used, implementations have to make sure that not
only the single selected namespace node is being patched but that all
namespaces nodes resulting from the namespace declaration of this
namespace are also patched accordingly.
<span class="grey">Wilde Informational [Page 10]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-11" ></span>
<span class="grey"><a href="./rfc7351">RFC 7351</a> XML Patch August 2014</span>
This means that an implementation might have to descend into the
tree, matching all namespace nodes with the selected prefix/URI pair
recursively, until it encounters leaf elements or namespace
declarations with the same prefix it is patching. Determining this
requires access to the diff document beyond XPath, because, in XPath
itself, namespace declarations are not represented; thus, such a
recursive algorithm wouldn't know when to stop. Consider the
following document:
<x xmlns:a="tag:42">
<y xmlns:a="tag:42"/>
</x>
If this document is patched with a selector of /x/namespace::a, then
only the namespace node on element x should be patched, even though
the namespace node on element y has the same prefix/URI combination
as the one on element x. However, determining that the repeated
namespace declaration was present at all on element y is impossible
when using XPath alone, which means that implementations must have an
alternative way to determine the difference between the document
above, and this one:
<x xmlns:a="tag:42">
<y/>
</x>
In this second example, patching with a selector of /x/namespace::a
should indeed change the namespace nodes on elements x and y, because
they both have been derived from the same namespace declaration.
The conclusion of these considerations is that for implementing XML
patch, access closer to the XML syntax (specifically access to
namespace declarations) is necessary. As a result, implementations
attempting to exclusively use the XPath model for implementing XML
patch will fail to correctly address certain edge cases (such as the
one shown above).
Note that XPath's specific limitations do not mean that it is
impossible to use XML technologies other than XPath. The Document
Object Model (DOM) [<a href="#ref-W3C.REC-DOM-Level-3-Core-20040407">W3C.REC-DOM-Level-3-Core-20040407</a>], for example,
does expose namespace declaration attributes as regular attributes in
the document tree; thus, they could be used to differentiate between
the two variants shown above.
Please note that <a href="./rfc5261#section-4.4.3">RFC 5261, Section 4.4.3</a> (on replacing namespaces)
mixes the terms "namespace declaration" and "namespace". For this
reason, RFC Errata ID 3478 is available for Section 4.4.3 of <a href="./rfc5261">RFC</a>
<a href="./rfc5261">5261</a>.
<span class="grey">Wilde Informational [Page 11]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-12" ></span>
<span class="grey"><a href="./rfc7351">RFC 7351</a> XML Patch August 2014</span>
<span class="h2"><a class="selflink" id="appendix-B" href="#appendix-B">Appendix B</a>. ABNF for <a href="./rfc5261">RFC 5261</a></span>
<a href="./rfc5261">RFC 5261</a> [<a href="./rfc5261" title=""An Extensible Markup Language (XML) Patch Operations Framework Utilizing XML Path Language (XPath) Selectors"">RFC5261</a>] does not contain an ABNF grammar for the allowed
subset of XPath expressions but includes an XSD-based grammar in its
type definition for operation types. In order to make implementation
easier, this appendix contains an ABNF grammar that has been derived
from the XSD expressions in <a href="./rfc5261">RFC 5261</a>. In the following grammar,
"xpath" is the definition for the allowed XPath expressions for
remove and replace operations, and "xpath-add" is the definition for
the allowed XPath expressions for add operations. The names of all
grammar productions are the ones used in the XSD-based grammar of <a href="./rfc5261">RFC</a>
<a href="./rfc5261">5261</a>.
<span class="grey">Wilde Informational [Page 12]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-13" ></span>
<span class="grey"><a href="./rfc7351">RFC 7351</a> XML Patch August 2014</span>
anychar = %x00-ffffffff
ncname = 1*%x00-ffffffff
qname = [ ncname ":" ] ncname
aname = "@" qname
pos = "[" 1*DIGIT "]"
attr = ( "[" aname "='" 0*anychar "']" ) /
( "[" aname "=" DQUOTE 0*anychar DQUOTE "]" )
valueq = "[" ( qname / "." ) "=" DQUOTE 0*anychar DQUOTE "]"
value = ( "[" ( qname / "." ) "='" 0*anychar "']" ) / valueq
cond = attr / value / pos
step = ( qname / "*" ) 0*cond
piq = %x70.72.6f.63.65.73.73.69.6e.67.2d
%x69.6e.73.74.72.75.63.74.69.6f.6e
; "processing-instruction", case-sensitive
"(" [ DQUOTE ncname DQUOTE ] ")"
pi = ( %x70.72.6f.63.65.73.73.69.6e.67.2d
%x69.6e.73.74.72.75.63.74.69.6f.6e
; "processing-instruction", case-sensitive
"(" [ "'" ncname "'" ] ")" ) / piq
id = ( %x69.64 ; "id", case-sensitive
"(" [ "'" ncname "'" ] ")" ) /
( %x69.64 ; "id", case-sensitive
"(" [ DQUOTE ncname DQUOTE ] ")" )
com = %x63.6f.6d.6d.65.6e.74 ; "comment", case-sensitive
"()"
text = %x74.65.78.74 ; "text", case-sensitive
"()"
nspa = %x6e.61.6d.65.73.70.61.63.65 ; "namespace", case-sensitive
"::" ncname
cnodes = ( text / com / pi ) [ pos ]
child = cnodes / step
last = child / aname / nspa
xpath = [ "/" ] ( ( id [ 0*( "/" step ) "/" last ] ) /
( 0*( step "/" ) last ) )
xpath-add = [ "/" ] ( ( id [ 0*( "/" step ) "/" child ] ) /
( 0*( step "/" ) child ) )
Please note that the "ncname" production listed above does not fully
capture the constraints of the original XSD-based definition, where
it is defined as "\i\c*". DIGIT and DQUOTE are defined by the ABNF
specification [<a href="./rfc5234" title=""Augmented BNF for Syntax Specifications: ABNF"">RFC5234</a>].
<span class="grey">Wilde Informational [Page 13]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-14" ></span>
<span class="grey"><a href="./rfc7351">RFC 7351</a> XML Patch August 2014</span>
Author's Address
Erik Wilde
UC Berkeley
EMail: dret@berkeley.edu
URI: <a href="http://dret.net/netdret/">http://dret.net/netdret/</a>
Wilde Informational [Page 14]
</pre>
|
