< draft-ietf-simple-xml-patch-ops-03.txt   draft-ietf-simple-xml-patch-ops-04.txt >
SIMPLE WG J. Urpalainen SIMPLE WG J. Urpalainen
Internet-Draft Nokia Internet-Draft Nokia
Intended status: Standards Track August 9, 2007 Intended status: Standards Track November 16, 2007
Expires: February 10, 2008 Expires: May 19, 2008
An Extensible Markup Language (XML) Patch Operations Framework Utilizing An Extensible Markup Language (XML) Patch Operations Framework Utilizing
XML Path Language (XPath) Selectors XML Path Language (XPath) Selectors
draft-ietf-simple-xml-patch-ops-03 draft-ietf-simple-xml-patch-ops-04
Status of this Memo Status of this Memo
By submitting this Internet-Draft, each author represents that any By submitting this Internet-Draft, each author represents that any
applicable patent or other IPR claims of which he or she is aware applicable patent or other IPR claims of which he or she is aware
have been or will be disclosed, and any of which he or she becomes have been or will be disclosed, and any of which he or she becomes
aware will be disclosed, in accordance with Section 6 of BCP 79. aware will be disclosed, in accordance with Section 6 of BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that Task Force (IETF), its areas, and its working groups. Note that
skipping to change at page 1, line 35 skipping to change at page 1, line 35
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt. http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
This Internet-Draft will expire on February 10, 2008. This Internet-Draft will expire on May 19, 2008.
Copyright Notice Copyright Notice
Copyright (C) The IETF Trust (2007). Copyright (C) The IETF Trust (2007).
Abstract Abstract
Extensible Markup Language (XML) documents are widely used as Extensible Markup Language (XML) documents are widely used as
containers for the exchange and storage of arbitrary data in today's containers for the exchange and storage of arbitrary data in today's
systems. In order to send changes to an XML document, an entire copy systems. In order to send changes to an XML document, an entire copy
skipping to change at page 2, line 17 skipping to change at page 2, line 17
XML document. XML document.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 4
3. Basic Features and Requirements . . . . . . . . . . . . . . . 5 3. Basic Features and Requirements . . . . . . . . . . . . . . . 5
4. Patch Operations . . . . . . . . . . . . . . . . . . . . . . . 6 4. Patch Operations . . . . . . . . . . . . . . . . . . . . . . . 6
4.1. Locating the Target of a Patch . . . . . . . . . . . . . . 7 4.1. Locating the Target of a Patch . . . . . . . . . . . . . . 7
4.2. Namespace Mangling . . . . . . . . . . . . . . . . . . . . 7 4.2. Namespace Mangling . . . . . . . . . . . . . . . . . . . . 7
4.3. <add> Element . . . . . . . . . . . . . . . . . . . . . . 9 4.2.1. Namespaces used in selectors . . . . . . . . . . . . . 8
4.3.1. Adding an Element . . . . . . . . . . . . . . . . . . 10 4.2.2. Departures from XPath Requirements . . . . . . . . . . 8
4.3.2. Adding an Attribute . . . . . . . . . . . . . . . . . 10 4.2.3. Namespaces and added/changed content . . . . . . . . . 9
4.3.3. Adding a Prefixed Namespace Declaration . . . . . . . 11 4.3. <add> Element . . . . . . . . . . . . . . . . . . . . . . 11
4.3.4. Adding Node(s) with the 'pos' Attribute . . . . . . . 11 4.3.1. Adding an Element . . . . . . . . . . . . . . . . . . 12
4.3.5. Adding Multiple Nodes . . . . . . . . . . . . . . . . 11 4.3.2. Adding an Attribute . . . . . . . . . . . . . . . . . 12
4.4. <replace> Element . . . . . . . . . . . . . . . . . . . . 12 4.3.3. Adding a Prefixed Namespace Declaration . . . . . . . 13
4.4.1. Replacing an Element . . . . . . . . . . . . . . . . . 12 4.3.4. Adding Node(s) with the 'pos' Attribute . . . . . . . 13
4.4.2. Replacing an Attribute Value . . . . . . . . . . . . . 13 4.3.5. Adding Multiple Nodes . . . . . . . . . . . . . . . . 13
4.4.3. Replacing a Namespace Declaration URI . . . . . . . . 13 4.4. <replace> Element . . . . . . . . . . . . . . . . . . . . 14
4.4.4. Replacing a Comment Node . . . . . . . . . . . . . . . 13 4.4.1. Replacing an Element . . . . . . . . . . . . . . . . . 15
4.4.5. Replacing a Processing Instruction Node . . . . . . . 13 4.4.2. Replacing an Attribute Value . . . . . . . . . . . . . 15
4.4.6. Replacing a Text Node . . . . . . . . . . . . . . . . 13 4.4.3. Replacing a Namespace Declaration URI . . . . . . . . 15
4.5. <remove> Element . . . . . . . . . . . . . . . . . . . . . 14 4.4.4. Replacing a Comment Node . . . . . . . . . . . . . . . 15
4.5.1. Removing an Element . . . . . . . . . . . . . . . . . 14 4.4.5. Replacing a Processing Instruction Node . . . . . . . 16
4.5.2. Removing an Attribute . . . . . . . . . . . . . . . . 14 4.4.6. Replacing a Text Node . . . . . . . . . . . . . . . . 16
4.5.3. Removing a Prefixed Namespace Declaration . . . . . . 15 4.5. <remove> Element . . . . . . . . . . . . . . . . . . . . . 16
4.5.4. Removing a Comment Node . . . . . . . . . . . . . . . 15 4.5.1. Removing an Element . . . . . . . . . . . . . . . . . 16
4.5.5. Removing a Processing Instruction Node . . . . . . . . 15 4.5.2. Removing an Attribute . . . . . . . . . . . . . . . . 17
4.5.6. Removing a Text Node . . . . . . . . . . . . . . . . . 15 4.5.3. Removing a Prefixed Namespace Declaration . . . . . . 17
5. Error Handling . . . . . . . . . . . . . . . . . . . . . . . . 15 4.5.4. Removing a Comment Node . . . . . . . . . . . . . . . 17
6. Usage of Patch Operations . . . . . . . . . . . . . . . . . . 16 4.5.5. Removing a Processing Instruction Node . . . . . . . . 17
7. Usage of Selector Values . . . . . . . . . . . . . . . . . . . 16 4.5.6. Removing a Text Node . . . . . . . . . . . . . . . . . 17
8. XML Schema . . . . . . . . . . . . . . . . . . . . . . . . . . 16 5. Error Handling . . . . . . . . . . . . . . . . . . . . . . . . 18
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 5.1. Error Elements . . . . . . . . . . . . . . . . . . . . . . 18
9.1. XML Schema Registration . . . . . . . . . . . . . . . . . 18 6. Usage of Patch Operations . . . . . . . . . . . . . . . . . . 20
10. Security Considerations . . . . . . . . . . . . . . . . . . . 19 7. Usage of Selector Values . . . . . . . . . . . . . . . . . . . 20
11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 19 8. XML Schema Types of Patch Operation Elements . . . . . . . . . 20
12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 19 9. XML Schema of Patch Operation Errors . . . . . . . . . . . . . 23
12.1. Normative References . . . . . . . . . . . . . . . . . . . 19 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24
12.2. Informative References . . . . . . . . . . . . . . . . . . 20 10.1. URN Sub-Namespace Registration . . . . . . . . . . . . . . 25
Appendix A. Informative Examples . . . . . . . . . . . . . . . . 20 10.2. application/patch-ops-error+xml MIME Type . . . . . . . . 25
A.1. Adding an Element . . . . . . . . . . . . . . . . . . . . 20 10.3. Patch-Ops-Types XML Schema Registration . . . . . . . . . 26
A.2. Adding an Attribute . . . . . . . . . . . . . . . . . . . 21 10.4. Patch-Ops-Error XML Schema Registration . . . . . . . . . 26
A.3. Adding a Prefixed Namespace Declaration . . . . . . . . . 21
A.4. Adding a Comment Node with the 'pos' Attribute . . . . . . 22 11. Security Considerations . . . . . . . . . . . . . . . . . . . 27
A.5. Adding Multiple Nodes . . . . . . . . . . . . . . . . . . 22 12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 27
A.6. Replacing an Element . . . . . . . . . . . . . . . . . . . 23 13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 27
A.7. Replacing an Attribute Value . . . . . . . . . . . . . . . 24 13.1. Normative References . . . . . . . . . . . . . . . . . . . 27
A.8. Replacing a Namespace Declaration URI . . . . . . . . . . 24 13.2. Informative References . . . . . . . . . . . . . . . . . . 29
A.9. Replacing a Comment Node . . . . . . . . . . . . . . . . . 25 Appendix A. Informative Examples . . . . . . . . . . . . . . . . 29
A.10. Replacing a Processing Instruction Node . . . . . . . . . 25 A.1. Adding an Element . . . . . . . . . . . . . . . . . . . . 29
A.11. Replacing a Text Node . . . . . . . . . . . . . . . . . . 26 A.2. Adding an Attribute . . . . . . . . . . . . . . . . . . . 30
A.12. Removing an Element . . . . . . . . . . . . . . . . . . . 26 A.3. Adding a Prefixed Namespace Declaration . . . . . . . . . 30
A.13. Removing an Attribute . . . . . . . . . . . . . . . . . . 27 A.4. Adding a Comment Node with the 'pos' Attribute . . . . . . 31
A.14. Removing a Prefixed Namespace Declaration . . . . . . . . 28 A.5. Adding Multiple Nodes . . . . . . . . . . . . . . . . . . 32
A.15. Removing a Comment Node . . . . . . . . . . . . . . . . . 28 A.6. Replacing an Element . . . . . . . . . . . . . . . . . . . 32
A.16. Removing a Processing Instruction Node . . . . . . . . . . 29 A.7. Replacing an Attribute Value . . . . . . . . . . . . . . . 33
A.17. Removing a Text Node . . . . . . . . . . . . . . . . . . . 29 A.8. Replacing a Namespace Declaration URI . . . . . . . . . . 33
A.18. Several Patches With Namespace Mangling . . . . . . . . . 30 A.9. Replacing a Comment Node . . . . . . . . . . . . . . . . . 34
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 32 A.10. Replacing a Processing Instruction Node . . . . . . . . . 34
Intellectual Property and Copyright Statements . . . . . . . . . . 33 A.11. Replacing a Text Node . . . . . . . . . . . . . . . . . . 35
A.12. Removing an Element . . . . . . . . . . . . . . . . . . . 36
A.13. Removing an Attribute . . . . . . . . . . . . . . . . . . 36
A.14. Removing a Prefixed Namespace Declaration . . . . . . . . 37
A.15. Removing a Comment Node . . . . . . . . . . . . . . . . . 37
A.16. Removing a Processing Instruction Node . . . . . . . . . . 38
A.17. Removing a Text Node . . . . . . . . . . . . . . . . . . . 38
A.18. Several Patches With Namespace Mangling . . . . . . . . . 39
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 40
Intellectual Property and Copyright Statements . . . . . . . . . . 42
1. Introduction 1. Introduction
Extensible Markup Language (XML) [2] documents are widely used as Extensible Markup Language (XML) [W3C.REC-xml-20060816] documents are
containers for the exchange and storage of arbitrary data in today's widely used as containers for the exchange and storage of arbitrary
systems. In order to send changes to an XML document, an entire copy data in today's systems. In order to send changes to an XML
of the new version must be sent, unless there is a means of document, an entire copy of the new version must be sent, unless
indicating only the portions that have changed (patches). there is a means of indicating only the portions that have changed
(patches).
This document describes an XML patch framework which utilizes XML This document describes an XML patch framework which utilizes XML
Path language (XPath) [3] selectors. An XPath selector is used to Path language (XPath) [W3C.REC-xpath-19991116] selectors. An XPath
pinpoint the specific portion of the XML that is the target for the selector is used to pinpoint the specific portion of the XML that is
change. These selector values and updated new data content the target for the change. These selector values and updated new
constitute the basis of patch operations described in this document. data content constitute the basis of patch operations described in
In addition to them, with basic <add>, <replace> and <remove> this document. In addition to them, with basic <add>, <replace> and
directives a set of patches can be applied to update an existing <remove> directives a set of patches can be applied to update an
initial XML document. With these patch operations, a simple existing target XML document. With these patch operations, a simple
semantics for data oriented XML documents [7] is achieved, that is, semantics for data oriented XML documents
modifications like additions, removals or substitutions of elements [W3C.REC-xmlschema-2-20041028] is achieved, that is, modifications
and attributes can easily be performed. This document does not like additions, removals or substitutions of elements and attributes
describe a full XML diff format, only basic patch operation elements can easily be performed. This document does not describe a full XML
which can be embedded within a full format which typically has diff format, only basic patch operation elements which can be
additional semantics. embedded within a full format which typically has additional
semantics.
As a one concrete example, in the Session Initiation Protocol (SIP) As a one concrete example, in the Session Initiation Protocol (SIP)
[16] based presence system a partial PIDF XML document format [14] [RFC3903] based presence system a partial PIDF XML document format
consists of the existing PIDF document format combined with the patch [I-D.ietf-simple-partial-pidf-format] consists of the existing PIDF
operations elements described in this document. In general, patch document format combined with the patch operations elements described
operations can be used in any application that exchanges XML in this document. In general, patch operations can be used in any
documents, for example within the SIP Events framework [13]. Yet application that exchanges XML documents, for example within the SIP
another example is XCAP-diff [15] which uses this framework for Events framework [RFC3265]. Yet another example is XCAP-diff
sending partial updates of changes to XCAP [12] resources. [I-D.ietf-simple-xcap-diff] which uses this framework for sending
partial updates of changes to XCAP [RFC4825] resources.
2. Conventions 2. Conventions
In this document, the key words "MUST", "MUST NOT", "REQUIRED", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
and "OPTIONAL" are to be interpreted as described in RFC 2119, BCP 14 document are to be interpreted as described in RFC 2119, BCP 14
[1] and indicate requirement levels for compliant implementations. [RFC2119] and indicate requirement levels for compliant
implementations.
The following terms are used in this document: The following terms are used in this document:
Initial XML document: An initial XML document that is going to be Target XML document: A target XML document that is going to be
updated with a set of patches. updated with a set of patches.
XML diff document: An XML document that contains patch operation XML diff document: An XML document that contains patch operation
elements, namespace declarations and all the document content elements, namespace declarations and all the document content
changes that are needed in order to transform an initial XML changes that are needed in order to transform a target XML
document into a new patched XML document. document into a new patched XML document.
Patched XML document: An XML document that results after applying Patched XML document: An XML document that results after applying
one or more patch operations defined in the XML diff document to one or more patch operations defined in the XML diff document to
the initial XML document. the target XML document.
Patch operation: A single change, i.e. a patch that is being applied Patch operation: A single change, i.e. a patch that is being applied
to update an initial XML document. to update a target XML document.
Patch operation element: An XML element that represents a single Patch operation element: An XML element that represents a single
patch operation. patch operation.
Type definition for an element: A W3C Schema type definition for an Type definition for an element: A W3C Schema type definition for an
element that describes a patch operation content. element that describes a patch operation content.
In-scope namespace declaration: A list of all in-scope namespace In-scope namespace declaration: A list of all in-scope namespace
declarations within a context node. The QName expansion of a declarations within a context node. The QName (qualified name)
context node is based on mapping a prefix with one of these expansion of a context node is based on mapping a prefix with one
declarations. For an element, one namespace binding may have an of these declarations. For an element, one namespace binding may
empty prefix. have an empty prefix.
Positional constraint: A number enclosed with square brackets. It Positional constraint: A number enclosed with square brackets. It
can be used as a location step predicate. can be used as a location step predicate.
Located target node: A node which was found from the initial XML Located target node: A node which was found from the target XML
document with the aid of an XPath selector value. document with the aid of an XPath selector value.
White space text node: A text node which contains only white space. White space text node: A text node which contains only white space.
3. Basic Features and Requirements 3. Basic Features and Requirements
In this framework, XPath selector values and new data content are In this framework, XPath selector values and new data content are
embedded within XML elements, the names of which specify the embedded within XML elements, the names of which specify the
modification to be performed: <add>, <replace> or <remove>. These modification to be performed: <add>, <replace> or <remove>. These
elements (patch operations) are defined by schema types with the W3C elements (patch operations) are defined by schema types with the W3C
Schema language [5]. XPath selectors pinpoint the target for a Schema language [W3C.REC-xmlschema-1-20041028]. XPath selectors
change and they are expressed as attributes of these elements. The pinpoint the target for a change and they are expressed as attributes
child node(s) of patch operation elements contain the new data of these elements. The child node(s) of patch operation elements
content. In general when applicable, the new content SHOULD be moved contain the new data content. In general when applicable, the new
unaltered to the patched XML document. content SHOULD be moved unaltered to the patched XML document.
XML documents which are equivalent for the purposes of many XML documents which are equivalent for the purposes of many
applications MAY differ in their physical representation. The aim of applications MAY differ in their physical representation. The aim of
this document is to describe a deterministic framework where the this document is to describe a deterministic framework where the
canonical form with comments [6] of an XML document determines canonical form with comments [W3C.REC-xml-c14n-20010315] of an XML
logical equivalence. For example, white space text nodes MUST be document determines logical equivalence. For example, white space
processed properly in order to fulfil this requirement as white space text nodes MUST be processed properly in order to fulfil this
is by default significant [6]. requirement as white space is by default significant
[W3C.REC-xml-c14n-20010315].
The specifications referencing these element schema types MUST define The specifications referencing these element schema types MUST define
the full XML diff format with an appropriate MIME type [11] and a the full XML diff format with an appropriate MIME type [RFC3023] and
character set, e.g. UTF-8 [9]. For example, the partial PIDF format a character set, e.g. UTF-8 [RFC3629]. For example, the partial
[14] includes this schema and describes additional definitions to PIDF format [I-D.ietf-simple-partial-pidf-format] includes this
produce a complete XML diff format for partial presence information schema and describes additional definitions to produce a complete XML
updates. diff format for partial presence information updates.
As the schema defined in this document does not declare any target As the schema defined in this document does not declare any target
namespace, the type definitions inherit the target namespace of the namespace, the type definitions inherit the target namespace of the
including schema. Therefore, additional namespace declarations including schema. Therefore, additional namespace declarations
within the XML diff documents can be avoided. within the XML diff documents can be avoided.
It is anticipated that applications using these types will define It is anticipated that applications using these types will define
<add>, <replace> and <remove> elements based on the corresponding <add>, <replace> and <remove> elements based on the corresponding
type definitions in this schema. In addition, an application may type definitions in this schema. In addition, an application may
reference only a subset of these type definitions. A future reference only a subset of these type definitions. A future
extension can introduce other operations, e.g. with document oriented extension can introduce other operations, e.g. with document oriented
models [7] a <move> operation and a text node patching algorithm models [W3C.REC-xmlschema-2-20041028] a <move> operation and a text
combined with <move> would undoubtedly produce smaller XML diff node patching algorithm combined with <move> would undoubtedly
documents. produce smaller XML diff documents.
The instance document elements based on these schema type definitions The instance document elements based on these schema type definitions
MUST be well formed and SHOULD be valid. MUST be well formed and SHOULD be valid.
The following XPath 1.0 data model node types can be added, replaced The following XPath 1.0 data model node types can be added, replaced
or removed with this framework: elements, attributes, namespaces, or removed with this framework: elements, attributes, namespaces,
comments, texts and processing instructions. The full XML prolog comments, texts and processing instructions. The full XML prolog
including e.g. XML entities [2] and the root node of an XML document including e.g. XML entities [W3C.REC-xml-20060816] and the root node
cannot be patched according to this framework. However, patching of of an XML document cannot be patched according to this framework.
comments and processing instructions of the root node is allowed. However, patching of comments and processing instructions of the root
Naturally the removal or addition of a document root element is not node is allowed. Naturally the removal or addition of a document
allowed as any valid XML document MUST always contain a single root root element is not allowed as any valid XML document MUST always
element. Also note that support for external entities is beyond the contain a single root element. Also note that support for external
scope of this framework. entities is beyond the scope of this framework.
4. Patch Operations 4. Patch Operations
An XML diff document contains a collection of patch operation An XML diff document contains a collection of patch operation
elements, including one or more <add>, <replace> and <remove> elements, including one or more <add>, <replace> and <remove>
elements. These patch operations will be applied sequentially in the elements. These patch operations will be applied sequentially in the
document order. After the first patch has been applied to update an document order. After the first patch has been applied to update a
initial XML document, the patched XML document becomes a new target XML document, the patched XML document becomes a new
independent XML document against which the next patch will be independent XML document against which the next patch will be
applied. This procedure repeats until all patches have successfully applied. This procedure repeats until all patches have successfully
been processed. been processed.
4.1. Locating the Target of a Patch 4.1. Locating the Target of a Patch
Each patch operation element contains a 'sel' attribute. The value Each patch operation element contains a 'sel' attribute. The value
of this attribute is an XPath selector with a restricted subset of of this attribute is an XPath selector with a restricted subset of
the full XPath 1.0 recommendation. The 'sel' value is used to locate the full XPath 1.0 recommendation. The 'sel' value is used to locate
a single unique target node from the initial XML document. This a single unique target node from the target XML document. This
located node pinpoints the target for a change and usually it is an located node pinpoints the target for a change and usually it is an
element, which is e.g. either updated itself or some child node(s) element, which is e.g. either updated itself or some child node(s)
are added into it. It MAY also be for instance a comment node, after are added into it. It MAY also be for instance a comment node, after
which some other sibling node(s) are inserted. In any case, it is an which some other sibling node(s) are inserted. In any case, it is an
error condition if multiple nodes are found during the evaluation of error condition if multiple nodes are found during the evaluation of
this selector value. this selector value.
The XPath selections of the 'sel' attribute always start from the The XPath selections of the 'sel' attribute always start from the
root node of a document. Thus relative location paths SHOULD be used root node of a document. Thus relative location paths SHOULD be used
so that the starting root node selection "/" can be omitted. When so that the starting root node selection "/" can be omitted. When
locating elements in a document tree, a node test can either be a "*" locating elements in a document tree, a node test can either be a "*"
character or a QName. A "*" character selects all element children character or a QName [W3C.REC-xml-names-20060816]. A "*" character
of the context node. Right after the node test, a location step can selects all element children of the context node. Right after the
contain one or more predicates in any order. An attribute value node test, a location step can contain one or more predicates in any
comparison is one of the most typical predicates. The string value order. An attribute value comparison is one of the most typical
of the current context node or a child element may alternatively be predicates. The string value of the current context node or a child
used to identify elements in the tree. The character ".", which element may alternatively be used to identify elements in the tree.
denotes a current context node selection, is an abbreviated form of The character ".", which denotes a current context node selection, is
"self::node()". Lastly, positional constraints like "[2]" can also an abbreviated form of "self::node()". Lastly, positional
be used as an additional predicate. constraints like "[2]" can also be used as an additional predicate.
An XPath 1.0 "id()" node-set function MAY also be used to identify An XPath 1.0 "id()" node-set function MAY also be used to identify
unique elements from the document tree. The schema that describes unique elements from the document tree. The schema that describes
the content model of the document MUST then use an attribute with the the content model of the document MUST then use an attribute with the
type ID [7] or with non-validating XML parsers, an "xml:id" [8] type ID [W3C.REC-xmlschema-2-20041028] or with non-validating XML
attribute MUST have been used within an instance document. parsers, an "xml:id" [W3C.WD-xml-id-20041109] attribute MUST have
been used within an instance document.
4.2. Namespace Mangling 4.2. Namespace Mangling
While the XPath recommendation specifies that prefixes can be used in The normal model for namespace prefixes is that they are local in
location steps, it does not specify how associated namespace URIs are scope. Thus, an XML diff document MAY have different prefixes for
discovered during these evaluations. In the patch operation the namespaces used in the target document. The agent parsing the
framework QName [4] expansion within a location step is evaluated diff document MUST resolve prefixes separately in both documents in
according to the namespace declarations of the XML diff document. order to match the resulting QNames (qualified name) from each.
Thus the namespace URIs for these prefixes are found from the in-
scope namespaces of the patch operation element. In other words, the The XML diff document MUST contain declarations for all namespaces
XML diff document contains all needed information for QName used in the diff document. The diff document declarations are always
expansions in order to perform XPath searches from the initial XML used to determine what namespaces apply within the diff document.
4.2.1. Namespaces used in selectors
A selector in a diff document may use prefixes when naming elements.
If it does use a prefix, the prefix must be looked up in the diff
document namespace declarations.
For example, the patch operation element of a diff document has an
in-scope namespace declaration "xmlns:a='foo:'" with a selector
"sel='a:bar'". The agent processing this patch MUST then look for
a 'bar' element qualified with the 'foo:' namespace regardless of
whether the 'foo:' namespace has a prefix assigned in the target
document or what that prefix is.
Default namespaces make this model a little more complicated. When
the diff document has a default namespace declaration, any element
selector without a prefix MUST be evaluated using that namespace.
For example, the patch operation element of a diff document has an
in-scope namespace declaration "xmlns='foo:'" with a selector
"sel='bar'". The agent processing this patch MUST then look for a
'bar' element qualified with the 'foo:' namespace, regardless of
whether the 'foo:' namespace has a prefix assigned in the target
document or what that prefix is.
Unqualified names are also possible. If there is no default
namespace declared, and an element name appears without a prefix,
then it is an unqualified element name. If this appears in a
selector, it MUST match an unqualified element in the target
document. document.
Note: It should be emphasized that prefixes within the XPath For example, the patch operation element of a diff document has
selectors MAY be different than those of the initial XML document only one in-scope namespace declaration "xmlns:a='foo:'" with a
because the matching of nodes is based on expanded names, i.e. a selector "sel='bar'". Since the 'bar' element has no prefix, and
prefix maps to a namespace URI and these URIs and local names MUST there is no default namespace declaration in scope, the agent
be identical. For example, with a selector "p:foo", "p" maps to a processing this patch can only match the selector against a 'bar'
namespace URI and "foo" is the local name. element that has no prefix and also no default namespace in scope.
In this framework, when a node test is "foo" and the patch operation 4.2.2. Departures from XPath Requirements
element has an in-scope default namespace declaration, a qualified
<foo> element from the initial XML document is being searched. That
is, the namespace URI of the expanded name of the located <foo>
element MUST then be identical compared to this default namespace
declaration. If there's not an in-scope default namespace
declaration within the evaluation context, an unqualified <foo>
element is located.
Note: By contrast, in XPath 1.0 a "foo" selector always locates an The prefix matching rules described previously in this section are
unqualified <foo> element but in XPath 2.0 [10] also a qualified different from those required in XPath 1.0 and 2.0
one which is attached with the default namespace declaration. [W3C.REC-xpath20-20070123]. In XPath 1.0 a "bar" selector always
locates an unqualified <bar> element. In XPath 2.0 a "bar" selector
not only matches an unqualified <bar> element, but also matches a
qualified <bar> element which is in scope of a default namespace
declaration. In contrast, in this specification, a selector without
a prefix only matches one element, and it may match an element with
or without a prefix but only if the namespace it's qualified with (or
none) is an exact match.
Note: The XPath 1.0 recommendation specifies "namespace-uri()" and The XPath 1.0 recommendation specifies "namespace-uri()" and
"local-name()" node-set functions which can be used within "local-name()" node-set functions which can be used within
predicates. These functions may be utilized during XPath predicates. These functions may be utilized during XPath
evaluations if there are no other means to "register" prefixes evaluations if there are no other means to "register" prefixes
with associated namespace URIs. They can also be used when with associated namespace URIs. They can also be used when
handling selections where default namespaces are attached to handling selections where default namespaces are attached to
elements. However, the schema type definitions for these patch elements. However, this specification does not allow the usage of
operation elements do not allow the usage of these functions. these functions.
Also elements within the changed data content are usually namespace 4.2.3. Namespaces and added/changed content
qualified. For example, when adding a new namespace qualified
element to the initial XML document, the namespace declaration
reference of this new element belongs first to the XML diff document.
Naturally after copying or moving this element, the attached
namespace MUST refer to a declaration within the patched XML
document. If this namespace is declared in the patch operation
element or within its ascendants, these references MUST thus be
changed. Like in XPath, the mapping of these references is based on
identical namespace URIs, not prefixes. The namespace with an
identical URI from the in-scope namespaces of a context node of the
initial XML document MUST be chosen. However, if overlapping in-
scope namespaces exist, i.e., there are several in-scope namespaces
with an identical namespace URI, then the namespace with the same
prefix MUST be chosen. If an equivalent prefix is not then found, an
error occurs. For instance, this kind of overlapping can happen when
a namespace qualified attribute is added while elements are attached
with an identical default namespace declaration.
When the new added or updated elements contain namespace Elements within the changed data content are also in scope of
declarations, the namespace nodes move unaltered from the XML diff namespace declarations. For example, when adding a new namespace
document to the patched XML document. Default namespace declarations qualified element to the target XML document, the diff document MUST
can only be added by this way but prefixed namespace declarations MAY contain a namespace declaration that applies to the element. The
be added or removed with XPath namespace axis semantics shown later agent processing the diff document MUST ensure that the target
in this document. document also contains the same namespace declaration. Similar to
XPath, the same namespace declaration in this context means that the
namespace URIs MUST be equal but the prefixes MAY be different in the
diff and target documents.
Note: In practice, this namespace mangling means that an XML diff For example, if a new added <a:bar> element has a namespace
document MUST only know the namespace URIs of qualified nodes, the declaration reference to "xmlns:a='foo:'" in the diff document and
prefixes of the initial XML document are not significant unless the target document has only a single in-scope namespace
there are those overlapping namespace declarations. In other declaration "xmlns:b='foo:'" at the insertion point, the namespace
words, regardless whether the prefixes of qualified elements of reference MUST be changed so that a <b:bar> element will then
the initial XML document are empty (default namespace attached) or exist in the patched document. The same rule applies although
not, the XML diff document may remain the same. default namespaces were used in either or both of the documents,
the namespace URIs determine what will be the correct references
(prefixes) in the patched document.
When the new or changed content has elements which declare new
namespaces (locally scoped), these declarations are copied unaltered
(prefix and everything) from the XML diff document to the target XML
document. Default namespace declarations can only be added by this
way but prefixed namespace declarations MAY be added or removed with
XPath namespace axis semantics shown later in this document (look
Section 4.3.3).
A fairly difficult use case for these rules is found when the target
document has several namespace declarations in scope for the same
namespace. A target document might declare several different
prefixes for the same namespace. Normally, the agent applying the
diff document chooses *the* appropriate prefix for adding new
elements to the target document, but in this special case there's
more than one. These requirements create deterministic behavior for
this special and in practice rare case:
- If the diff document happens to use a prefix which is one of the
prefixes declared for the same namespace in the evaluation context
node of the target document, this prefix MUST be used in the
resulting patched document. An empty evaluable prefix and an
existing in-scope default namespace declaration means that the
default namespace MUST be chosen. In other words, the expanded names
are then equal within the diff and patched documents.
In an <add> operation, the evaluation context node is the parent
element of the inserted node, for example with a selector "sel='*/
bar'" and without a 'pos' attribute directive (look Section 4.3),
it is the <bar> element of the root document element. With
modifications of elements, the evaluation context node is the
parent element of the modified element, and in the previous
example thus the root document element.
- Secondly, the prefix (also empty) of the evaluation context node
MUST be chosen if the namespace URIs are equal.
- Lastly if the above two rules still don't apply, first all in-scope
namespace prefixes of the evaluation context node are arranged
alphabetically in an ascending order. If a default namespace
declaration exists, it is interpreted as the first entry in this
list. The prefix from the list is then chosen which appear as the
closest and just before the compared prefix if it were inserted into
the list. If the compared prefix were to exist before the first
prefix, the first prefix in the list MUST be selected (i.e. there's
no default namespace).
For example, if the list of in-scope prefixes in the target
document is "x", "y" and the compared prefix in the diff document
is "xx", then the "x" prefix MUST be chosen. If an "a" prefix
were evaluated, the "x" prefix, the first entry MUST be chosen.
If there were also an in-scope default namespace declaration, an
evaluable "a" prefix would then select the default declaration.
Note that unprefixed attributes don't inherit the default
namespace declaration. When adding qualified attributes, the
default namespace declaration is then not on this matching list of
prefixes (look Section 4.3.2).
Note that these requirements might mean that a resulting patched
document could contain unused and/or superfluous namespace
declarations. The resulting patched document MUST NOT be "cleaned
up" such that these namespace declarations are removed.
Note: In practice, the agent constructing a diff document can
usually freely select the appropriate prefixes for the namespace
declarations and it doesn't need to know or care about the actual
prefixes in the target document unless there are overlapping
declarations. In other words, the diff format content is
typically independent of the target documents usage of namespace
prefixes. However, it may be very useful to know where namespaces
are declared in the target document. The most typical use-case is
such though, that the agent generating a diff has both the
previous (target) and new (patched) documents available and
namespace declarations are thus exactly known. Note also, that in
a case where the target document is not exactly known, it is
allowed to use locally scoped namespace declarations, the
consequences of which are larger and less human-readable patched
documents.
4.3. <add> Element 4.3. <add> Element
The <add> element represents the addition of some new content to the The <add> element represents the addition of some new content to the
initial XML document: e.g. a new element can be appended into an target XML document: e.g. a new element can be appended into an
existing element. existing element.
The new data content exists as the child node(s) of the <add> The new data content exists as the child node(s) of the <add>
element. When adding attributes and namespaces the child node of the element. When adding attributes and namespaces the child node of the
<add> element MUST be a single text node. Otherwise, the <add> <add> element MUST be a single text node. Otherwise, the <add>
element MAY contain any mixture of element, text, comment or element MAY contain any mixture of element, text, comment or
processing instruction nodes in any order. All children of the <add> processing instruction nodes in any order. All children of the <add>
element are then copied into an initial XML document. The described element are then copied into a target XML document. The described
namespace mangling procedure applies to added elements, which include namespace mangling procedure applies to added elements, which include
all of their attribute, namespace and descendant nodes. all of their attribute, namespace and descendant nodes.
The <add> element type has three attributes: 'sel', 'type' and 'pos'. The <add> element type has three attributes: 'sel', 'type' and 'pos'.
The value of the optional 'type' attribute is only used when adding The value of the optional 'type' attribute is only used when adding
attributes and namespaces. Then the located target node MUST be an attributes and namespaces. Then the located target node MUST be an
element into which new attributes and namespace declarations are element into which new attributes and namespace declarations are
inserted. When the value of this 'type' attribute equals "@attr" the inserted. When the value of this 'type' attribute equals "@attr",
purpose is to add a new attribute node with the name 'attr'. The the string "attr" is the name of the actual attribute being added.
value of this new 'attr' attribute is the text node content of the The value of this new 'attr' attribute is the text node content of
<add> element. The less frequently used, prefixed, i.e. namespace the <add> element. The less frequently used prefixed (i.e.
qualified attributes can also be added. If the value of the 'type' namespace-qualified) attributes can also be added. If the value of
attribute equals "namespace::pref" the aim is to add a new "pref" the 'type' attribute equals "namespace::pref", "pref" is the actual
prefixed namespace declaration and the text node content of the <add> prefix string to be used for the namespace declaration in the patched
element contains the corresponding namespace URI. document and the text node content of the <add> element contains the
corresponding namespace URI.
Note: The 'type' attribute is thus also an XPath selector, but it Note: The 'type' attribute is thus also an XPath selector, but it
only locates attributes and namespaces. Attribute axis only locates attributes and namespaces. Attribute axis
"attribute" has an abbreviated form "@" unlike the "namespace" "attribute" has an abbreviated form "@" unlike the "namespace"
axis which doesn't have an abbreviated form. Double colons "::" axis which doesn't have an abbreviated form. Double colons "::"
are used as an axis separator in XPath. are used as an axis separator in XPath.
The value of the optional 'pos' attribute indicates the positioning The value of the optional 'pos' attribute indicates the positioning
of new data content. It is not used when adding attributes or of new data content. It is not used when adding attributes or
namespaces. When neither 'type' nor 'pos' attribute exist, the namespaces. When neither 'type' nor 'pos' attribute exist, the
skipping to change at page 10, line 34 skipping to change at page 12, line 36
prefixes are therefore not used and the whole XML diff content is not prefixes are therefore not used and the whole XML diff content is not
shown in these examples, only patch operation elements. Full shown in these examples, only patch operation elements. Full
examples are given in an Appendix A. examples are given in an Appendix A.
4.3.1. Adding an Element 4.3.1. Adding an Element
An example for an addition of an element: An example for an addition of an element:
<add sel="doc"><foo id="ert4773">This is a new child</foo></add> <add sel="doc"><foo id="ert4773">This is a new child</foo></add>
Once the <doc> element has been found from the initial XML document, Once the <doc> element has been found from the target XML document, a
a new <foo> element is appended as the last child node of the <doc> new <foo> element is appended as the last child node of the <doc>
element. The located target node: the <doc> element is naturally the element. The located target node: the <doc> element is naturally the
root element of the initial XML document. The new <foo> element root element of the target XML document. The new <foo> element
contains an 'id' attribute and a child text node. contains an 'id' attribute and a child text node.
4.3.2. Adding an Attribute 4.3.2. Adding an Attribute
An example for an addition of an attribute: An example for an addition of an attribute:
<add sel="doc/foo[@id='ert4773']" type="@user">Bob</add> <add sel="doc/foo[@id='ert4773']" type="@user">Bob</add>
This operation adds a new 'user' attribute to the <foo> element which This operation adds a new 'user' attribute to the <foo> element which
was located by using an 'id' attribute value predicate. The value of was located by using an 'id' attribute value predicate. The value of
this new 'user' attribute is "Bob". this new 'user' attribute is "Bob".
A similar patched XML document is achieved when using a validating A similar patched XML document is achieved when using a validating
XML parser, if the 'sel' selector value had been 'id("ert4773")' and XML parser, if the 'sel' selector value had been 'id("ert4773")' and
if the data type of the 'id' attribute is "ID" [7]. if the data type of the 'id' attribute is "ID"
[W3C.REC-xmlschema-2-20041028].
Note that with namespace qualified attributes, the prefix matching
rules within the 'type' attribute are evaluated with similar rules
described before in Section 4.2.3. Also note that then the possible
default namespace declaration of the context element isn't
applicable.
Note: As the 'sel' selector value MAY contain quotation marks, Note: As the 'sel' selector value MAY contain quotation marks,
escaped forms: "&quot;" or "&apos;" can be used within attribute escaped forms: "&quot;" or "&apos;" can be used within attribute
values. However, it is often more appropriate to use the values. However, it is often more appropriate to use the
apostrophe (') character as shown in these examples. An apostrophe (') character as shown in these examples. An
alternative is also to interchange the apostrophes and quotation alternative is also to interchange the apostrophes and quotation
marks. marks.
4.3.3. Adding a Prefixed Namespace Declaration 4.3.3. Adding a Prefixed Namespace Declaration
skipping to change at page 11, line 35 skipping to change at page 13, line 46
<add sel="doc/foo[@id='ert4773']" pos="before"><!-- comment --></add> <add sel="doc/foo[@id='ert4773']" pos="before"><!-- comment --></add>
This operation adds a new comment node just before the <foo> element This operation adds a new comment node just before the <foo> element
as an immediate preceding sibling node. This is also an example how as an immediate preceding sibling node. This is also an example how
a 'pos' attribute directive can be used. a 'pos' attribute directive can be used.
4.3.5. Adding Multiple Nodes 4.3.5. Adding Multiple Nodes
Some complexity arises when so called white space text nodes exist Some complexity arises when so called white space text nodes exist
within an initial XML document. The XPath 1.0 data model requires within a target XML document. The XPath 1.0 data model requires that
that a text node MUST not have another text node as an immediate a text node MUST NOT have another text node as an immediate sibling
sibling node. For instance, if an add operation is like this: node. For instance, if an add operation is like this:
<add sel="doc"> <add sel="doc">
<foo id="ert4773">This is a new child</foo></add> <foo id="ert4773">This is a new child</foo></add>
The <add> element has then two child nodes: a white space text node The <add> element has then two child nodes: a white space text node
(a linefeed and two spaces) and a <foo> element. If the existing (a linefeed and two spaces) and a <foo> element. If the existing
last child of the <doc> element is a text node, its content and the last child of the <doc> element is a text node, its content and the
white space text node content MUST then be combined together. white space text node content MUST then be combined together.
Otherwise (white space) text nodes can be added just like elements Otherwise (white space) text nodes can be added just like elements
and thus, the canonical form of the patched XML document easily and thus, the canonical form of the patched XML document easily
skipping to change at page 12, line 21 skipping to change at page 14, line 33
text node content and the first new text node content MUST be text node content and the first new text node content MUST be
combined together. In essence, if the 'pos' value had been "before", combined together. In essence, if the 'pos' value had been "before",
the second new text node content would effectively have been the second new text node content would effectively have been
prepended to the located target text node. prepended to the located target text node.
Note: It is still worth noting that text nodes MAY contain CDATA Note: It is still worth noting that text nodes MAY contain CDATA
sections, the latter of which are not treated as separate nodes. sections, the latter of which are not treated as separate nodes.
Once these CDATA sections exist within the new text nodes, they Once these CDATA sections exist within the new text nodes, they
SHOULD be moved unaltered to the patched XML document. SHOULD be moved unaltered to the patched XML document.
While XML entities [2] cannot be patched with this framework, the While XML entities [W3C.REC-xml-20060816] cannot be patched with this
references to other than predefined internal entities can exist framework, the references to other than predefined internal entities
within text nodes or attributes when the XML prolog contains those can exist within text nodes or attributes when the XML prolog
declarations. These references may then be preserved if both the XML contains those declarations. These references may then be preserved
diff and the initial XML document have identical declarations within if both the XML diff and the target XML document have identical
their prologs. Otherwise, references may be replaced with identical declarations within their prologs. Otherwise, references may be
text as long as the "canonically equivalent" rule is obeyed. replaced with identical text as long as the "canonically equivalent"
rule is obeyed.
4.4. <replace> Element 4.4. <replace> Element
The <replace> element represents a replacement operation: e.g. an The <replace> element represents a replacement operation: e.g. an
existing element is updated with a new element or an attribute value existing element is updated with a new element or an attribute value
is replaced with a new value. This <replace> operation always is replaced with a new value. This <replace> operation always
updates a single node or node content at a time. updates a single node or node content at a time.
The <replace> element type has only a 'sel' attribute. If the The <replace> element type has only a 'sel' attribute. If the
located target node is an element, a comment or a processing located target node is an element, a comment or a processing
skipping to change at page 14, line 10 skipping to change at page 16, line 24
4.4.6. Replacing a Text Node 4.4.6. Replacing a Text Node
An example for a replacement of a text node: An example for a replacement of a text node:
<replace sel="doc/foo/text()[1]">This is the new text content</ <replace sel="doc/foo/text()[1]">This is the new text content</
replace> replace>
This will replace the first text node child of the <foo> element. This will replace the first text node child of the <foo> element.
The positional constraint "[1]" is not usually needed as the element The positional constraint "[1]" is not usually needed as the element
content is rarely of mixed type [5] where several text node siblings content is rarely of mixed type [W3C.REC-xmlschema-1-20041028] where
typically exist. several text node siblings typically exist.
If a text node is updated and the <replace> element is empty, the If a text node is updated and the <replace> element is empty, the
text node MUST thus be removed as a text node MUST always have at text node MUST thus be removed as a text node MUST always have at
least one character of data. least one character of data.
4.5. <remove> Element 4.5. <remove> Element
The <remove> element represents a removal operation of e.g. an The <remove> element represents a removal operation of e.g. an
existing element or an attribute. existing element or an attribute.
skipping to change at page 14, line 39 skipping to change at page 17, line 4
be a white space text node and if the value is "after", the be a white space text node and if the value is "after", the
corresponding following node. If the 'ws' value is "both", both the corresponding following node. If the 'ws' value is "both", both the
preceding and following white space text nodes MUST be removed. preceding and following white space text nodes MUST be removed.
4.5.1. Removing an Element 4.5.1. Removing an Element
An example for a removal of an element including all of its An example for a removal of an element including all of its
descendant, attribute and namespace nodes: descendant, attribute and namespace nodes:
<remove sel="doc/foo[@a='1']" ws="after"/> <remove sel="doc/foo[@a='1']" ws="after"/>
This will remove the <foo> element as well as the immediate following This will remove the <foo> element as well as the immediate following
sibling white space text node of the <foo> element. If the immediate sibling white space text node of the <foo> element. If the immediate
following sibling node is not a white space text node, an error following sibling node is not a white space text node, an error
occurs. occurs.
4.5.2. Removing an Attribute 4.5.2. Removing an Attribute
An example for a removal of an attribute node: An example for a removal of an attribute node:
<remove sel="doc/@a"/> <remove sel="doc/@a"/>
This will remove the 'a' attribute node from the <doc> element. This will remove the 'a' attribute node from the <doc> element.
4.5.3. Removing a Prefixed Namespace Declaration 4.5.3. Removing a Prefixed Namespace Declaration
An example for a removal of a prefixed namespace node: An example for a removal of a prefixed namespace node:
<remove sel="doc/foo/namespace::pref"/> <remove sel="doc/foo/namespace::pref"/>
This will remove the 'pref' prefixed namespace node from the <foo> This will remove the 'pref' prefixed namespace node from the <foo>
element. Naturally this prefix MUST not be associated with any node element. Naturally this prefix MUST NOT be associated with any node
prior to the removal of this namespace node. Also the parent node of prior to the removal of this namespace node. Also the parent node of
this namespace declaration MUST be the <foo> element. this namespace declaration MUST be the <foo> element.
4.5.4. Removing a Comment Node 4.5.4. Removing a Comment Node
An example for a removal of a comment node: An example for a removal of a comment node:
<remove sel="doc/comment()[1]"/> <remove sel="doc/comment()[1]"/>
This will remove the first comment node child of the <doc> element. This will remove the first comment node child of the <doc> element.
skipping to change at page 16, line 4 skipping to change at page 18, line 16
which has immediate preceding and following sibling text nodes which has immediate preceding and following sibling text nodes
without the 'ws' directive, the content of these two text nodes MUST without the 'ws' directive, the content of these two text nodes MUST
be combined together. The latter text node thus disappears from the be combined together. The latter text node thus disappears from the
document. document.
5. Error Handling 5. Error Handling
It is an error condition if any of the patch operations can not be It is an error condition if any of the patch operations can not be
unambiguously fulfilled. In other words, once a particular patch unambiguously fulfilled. In other words, once a particular patch
operation fails, it is an error condition and processing of further operation fails, it is an error condition and processing of further
patch operations is hardly sensible. Also it is beyond the scope of patch operations is hardly sensible.
this document to describe a generic error response.
A new MIME error format is defined for applications which require
deterministic error handling when patching can not be applied. It is
anticipated that these error elements can be used within other MIME
types which allow extension elements.
5.1. Error Elements
The root element of the error document is <patch-ops-error>. The
content of this element is a specific error condition. Each error
condition is represented by a different element. This allows for
different error conditions to provide different data about the nature
of the error. All error elements support a "phrase" attribute, which
can contain text meant for rendering to a human user. The optional
"xml:lang" MAY be used to describe the language of the "phrase"
attribute. Most of the error condition elements are supposed to
contain the patch operation element which caused the patch to fail.
The following error elements are defined by this specification:
<invalid-attribute-value>: The validity constraints of 'sel',
'type', 'ws' or 'pos' attribute values MAY be indicated with this
error, i.e. non-allowable content has been used. Also this error
can be used to indicate if an added or a modified attribute
content is not valid, for example CDATA sections were used when a
new attribute was intended to be added.
<invalid-character-set>: The patch could not be applied because the
diff and the patched document use different character sets.
<invalid-diff-format>: This indicates that the diff body of the
request was not a well-formed XML document or a valid XML document
according to its schema.
<invalid-entity-declaration>: An entity reference was found but
corresponding declaration could not be located or resolved.
<invalid-namespace-prefix>: The namespace URI for the given prefix
could not be located or resolved, e.g. within the 'sel' attribute
a prefix was used but its declaration is missing from the target
document.
<invalid-namespace-uri>: The namespace URI value is not valid or the
target document did not have this declaration.
<invalid-node-types>: The node types of a <replace> operation did
not match, i.e. for example the 'sel' selector locates an element
but the replaceable content is of text type. Also a <replace>
operation may locate a unique element, but replaceable content had
multiple nodes.
<invalid-patch-directive>: A patch directive could not be fulfilled
because the given directives were not understood.
<invalid-root-element-operation>: The root element of the document
cannot be removed or another sibling element for the document root
element cannot be added.
<invalid-xml-prolog-operation>: Patch failure related to XML prolog
nodes.
<invalid-whitespace-directive>: A <remove> operation requires a
removal of a whitespace node which doesn't exist in the target
document.
<unlocated-node>: A single unique node (typically an element) could
not be located with the 'sel' attribute value. Also the location
of multiple nodes can lead to this error.
<unsupported-id-function>: The nodeset function id() is not
supported and thus attributes with the ID type are not known.
<unsupported-xml-id>: The attribute xml:id as an ID attribute in XML
documents is not supported.
Additional error elements can be indicated within the root <patch-
ops-error> element from any namespace. However, the IETF MAY specify
additional error elements in the
"urn:ietf:params:xml:ns:patch-ops-error" namespace.
As an example, the following document indicates that it was attempted
to add a new <note> element with whitespace into a document, but the
parent element could not be located:
<?xml version="1.0" encoding="UTF-8"?>
<patch-ops-error
xmlns:p="urn:ietf:params:xml:ns:pidf-diff"
xmlns="urn:ietf:params:xml:ns:patch-ops-error">
<unlocated-node
phrase="a unique node could not be located with the id() function."
><p:add sel='id("ert4773")'>
<p:note>some text added</p:note>
</p:add></unlocated-node>
</patch-ops-error>
6. Usage of Patch Operations 6. Usage of Patch Operations
An XML diff document SHOULD contain only the nodes which have been An XML diff document SHOULD contain only the nodes which have been
modified. However, when there's a large collection of changes it modified as the intention is to try to reduce bandwidth/storage
could be desirable to exchange the full document content instead. requirements. However, when there's a large collection of changes it
How this will be done in practice is beyond the scope of this can be desirable to exchange the full document content instead. How
document. this will be done in practice is beyond the scope of this document.
Some applications MAY require that the full versioning history MUST
be indicated although the history had superfluous changes. This
framework doesn't mandate any specific behavior, applications MAY
decide the appropriate semantics themselves. Also in practice,
applications are free to select the proper algorithms when generating
diff document content.
7. Usage of Selector Values 7. Usage of Selector Values
It is up to the application to decide what kind of selector values to It is up to the application to decide what kind of selector values to
use. Positional element selectors like "*/*[3]/*[2]" provide the use. Positional element selectors like "*/*[3]/*[2]" provide the
shortest selectors, but care must to taken when using them. When shortest selectors, but care must to taken when using them. When
there are several removals of sibling elements, the positional there are several removals of sibling elements, the positional
element indexes change after each update. Likewise these indexes element indexes change after each update. Likewise these indexes
change when new elements are inserted into the tree. Using names change when new elements are inserted into the tree. Using names
with possible attribute predicates like "doc[@sel='foo']" is usually with possible attribute predicates like "doc[@sel='foo']" is usually
easier for an application, be it e.g. an auto diff tool but it leads easier for an application, be it e.g. an auto diff tool but it leads
to larger diff documents. to larger diff documents.
8. XML Schema 8. XML Schema Types of Patch Operation Elements
The schema types for the patch operation elements. The schema types for the patch operation elements.
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE schema [ <!DOCTYPE schema [
<!ENTITY ncname "\i\c*"> <!ENTITY ncname "\i\c*">
<!ENTITY qname "(&ncname;:)?&ncname;"> <!ENTITY qname "(&ncname;:)?&ncname;">
<!ENTITY aname "@&qname;"> <!ENTITY aname "@&qname;">
<!ENTITY pos "\[\d+\]"> <!ENTITY pos "\[\d+\]">
<!ENTITY attr "\[&aname;='(.)*'\]|\[&aname;=&quot;(.)*&quot;\]"> <!ENTITY attr "\[&aname;='(.)*'\]|\[&aname;=&quot;(.)*&quot;\]">
<!ENTITY valueq "\[(&qname;|\.)=&quot;(.)*&quot;\]"> <!ENTITY valueq "\[(&qname;|\.)=&quot;(.)*&quot;\]">
<!ENTITY value "\[(&qname;|\.)='(.)*'\]|&valueq;"> <!ENTITY value "\[(&qname;|\.)='(.)*'\]|&valueq;">
<!ENTITY cond "&attr;|&value;|&pos;"> <!ENTITY cond "&attr;|&value;|&pos;">
<!ENTITY step "(&qname;|\*)(&cond;)*"> <!ENTITY step "(&qname;|\*)(&cond;)*">
<!ENTITY piq "processing-instruction\((&quot;&ncname;&quot;)?\)"> <!ENTITY piq "processing-instruction\((&quot;&ncname;&quot;)\)">
<!ENTITY pi "processing-instruction\(('&ncname;')?\)|&piq;"> <!ENTITY pi "processing-instruction\(('&ncname;')?\)|&piq;">
<!ENTITY id "id\(('&ncname;')?\)|id\((&quot;&ncname;&quot;)?\)"> <!ENTITY id "id\(('&ncname;')?\)|id\((&quot;&ncname;&quot;)?\)">
<!ENTITY com "comment\(\)"> <!ENTITY com "comment\(\)">
<!ENTITY text "text\(\)"> <!ENTITY text "text\(\)">
<!ENTITY nspa "namespace::&ncname;"> <!ENTITY nspa "namespace::&ncname;">
<!ENTITY cnodes "(&text;(&pos;)?)|(&com;(&pos;)?)|(&pi;(&pos;)?)"> <!ENTITY cnodes "(&text;(&pos;)?)|(&com;(&pos;)?)|((&pi;)(&pos;)?)">
<!ENTITY child "&cnodes;|&step;"> <!ENTITY child "&cnodes;|&step;">
<!ENTITY last "&child;|&aname;|&nspa;"> <!ENTITY last "(&child;|&aname;|&nspa;)">
]> ]>
<xsd:schema <xsd:schema
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified"> elementFormDefault="qualified">
<xsd:simpleType name="xpath"> <xsd:simpleType name="xpath">
<xsd:restriction base="xsd:string"> <xsd:restriction base="xsd:string">
<xsd:pattern value="(/)?(&step;/)*(&last;)"/> <xsd:pattern
<xsd:pattern value="(/)?&id;((/&step;)*(/&last;))?"/> value="(/)?((&id;)((/&step;)*(/&last;))?|(&step;/)*(&last;))"/>
</xsd:restriction> </xsd:restriction>
</xsd:simpleType> </xsd:simpleType>
<xsd:simpleType name="xpath-add"> <xsd:simpleType name="xpath-add">
<xsd:restriction base="xsd:string"> <xsd:restriction base="xsd:string">
<xsd:pattern value="(/)?(&step;/)*(&child;)"/> <xsd:pattern
<xsd:pattern value="(/)?&id;((/&step;)*(/&child;))?"/> value="(/)?((&id;)((/&step;)*(/&child;))?|(&step;/)*(&child;))"/>
</xsd:restriction> </xsd:restriction>
</xsd:simpleType> </xsd:simpleType>
<xsd:simpleType name="pos"> <xsd:simpleType name="pos">
<xsd:restriction base="xsd:string"> <xsd:restriction base="xsd:string">
<xsd:enumeration value="before"/> <xsd:enumeration value="before"/>
<xsd:enumeration value="after"/> <xsd:enumeration value="after"/>
<xsd:enumeration value="prepend"/> <xsd:enumeration value="prepend"/>
</xsd:restriction> </xsd:restriction>
</xsd:simpleType> </xsd:simpleType>
<xsd:simpleType name="type"> <xsd:simpleType name="type">
<xsd:restriction base="xsd:string"> <xsd:restriction base="xsd:string">
<xsd:pattern value="&aname;"/> <xsd:pattern value="&aname;|&nspa;"/>
<xsd:pattern value="&nspa;"/> </xsd:restriction>
</xsd:restriction> </xsd:simpleType>
</xsd:simpleType>
<xsd:complexType name="add"> <xsd:complexType name="add">
<xsd:complexContent mixed="true"> <xsd:complexContent mixed="true">
<xsd:restriction base="xsd:anyType"> <xsd:restriction base="xsd:anyType">
<xsd:sequence> <xsd:sequence>
<xsd:any processContents="lax" namespace="##any" <xsd:any processContents="lax" namespace="##any"
minOccurs="0" maxOccurs="unbounded"/> minOccurs="0" maxOccurs="unbounded"/>
</xsd:sequence> </xsd:sequence>
<xsd:attribute name="sel" type="xpath-add"
use="required"/>
<xsd:attribute name="pos" type="pos"/>
<xsd:attribute name="type" type="type"/>
</xsd:restriction>
</xsd:complexContent>
</xsd:complexType>
<xsd:attribute name="sel" type="xpath-add" <xsd:complexType name="replace">
use="required"/> <xsd:complexContent mixed="true">
<xsd:attribute name="pos" type="pos"/> <xsd:restriction base="xsd:anyType">
<xsd:attribute name="type" type="type"/> <xsd:sequence>
<xsd:any processContents="lax" namespace="##any"
minOccurs="0" maxOccurs="1"/>
</xsd:sequence>
<xsd:attribute name="sel" type="xpath" use="required"/>
</xsd:restriction>
</xsd:complexContent>
</xsd:complexType>
</xsd:restriction> <xsd:simpleType name="ws">
</xsd:complexContent> <xsd:restriction base="xsd:string">
</xsd:complexType> <xsd:enumeration value="before"/>
<xsd:enumeration value="after"/>
<xsd:enumeration value="both"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:complexType name="replace"> <xsd:complexType name="remove">
<xsd:complexContent mixed="true"> <xsd:attribute name="sel" type="xpath" use="required"/>
<xsd:restriction base="xsd:anyType"> <xsd:attribute name="ws" type="ws"/>
<xsd:sequence> </xsd:complexType>
<xsd:any processContents="lax" namespace="##any"
minOccurs="0" maxOccurs="1"/>
</xsd:sequence>
<xsd:attribute name="sel" type="xpath" use="required"/> </xsd:schema>
</xsd:restriction>
</xsd:complexContent>
</xsd:complexType>
<xsd:simpleType name="ws"> 9. XML Schema of Patch Operation Errors
<xsd:restriction base="xsd:string">
<xsd:enumeration value="before"/>
<xsd:enumeration value="after"/>
<xsd:enumeration value="both"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:complexType name="remove"> The patch operation errors definitions.
<xsd:attribute name="sel" type="xpath" use="required"/>
<xsd:attribute name="ws" type="ws"/> <?xml version="1.0" encoding="UTF-8"?>
<xsd:schema
targetNamespace="urn:ietf:params:xml:ns:patch-ops-error"
xmlns:tns="urn:ietf:params:xml:ns:patch-ops-error"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified"
attributeFormDefault="unqualified">
<!-- This import brings in the XML language attribute xml:lang-->
<xsd:import namespace="http://www.w3.org/XML/1998/namespace"
schemaLocation="http://www.w3.org/2001/xml.xsd"/>
<!-- ROOT document element for signaling patch-ops errors -->
<xsd:element name="patch-ops-error">
<xsd:complexType>
<xsd:sequence>
<xsd:any namespace="##any" processContents="lax"
minOccurs="0" maxOccurs="unbounded"/>
</xsd:sequence>
<xsd:anyAttribute processContents="lax"/>
</xsd:complexType> </xsd:complexType>
</xsd:element>
<!-- patch-ops error elements:
not intended to be used as root documnet elements -->
<xsd:element name="invalid-attribute-value"
type="tns:patch-error"/>
<xsd:element name="invalid-character-set"
type="tns:patch-error-simple"/>
<xsd:element name="invalid-diff-format"
type="tns:patch-error-simple"/>
<xsd:element name="invalid-entity-declaration"
type="tns:patch-error"/>
<xsd:element name="invalid-namespace-prefix"
type="tns:patch-error"/>
<xsd:element name="invalid-namespace-uri"
type="tns:patch-error"/>
<xsd:element name="invalid-node-types"
type="tns:patch-error"/>
<xsd:element name="invalid-patch-directive"
type="tns:patch-error"/>
<xsd:element name="invalid-root-element-operation"
type="tns:patch-error"/>
<xsd:element name="invalid-xml-prolog-operation"
type="tns:patch-error"/>
<xsd:element name="invalid-whitespace-directive"
type="tns:patch-error"/>
<xsd:element name="unlocated-node"
type="tns:patch-error"/>
<xsd:element name="unsupported-id-function"
type="tns:patch-error"/>
<xsd:element name="unsupported-xml-id"
type="tns:patch-error"/>
<!-- simple patch-ops error type -->
<xsd:complexType name="patch-error-simple">
<xsd:attribute name="phrase" type="xsd:string"/>
<xsd:attribute ref="xml:lang"/>
<xsd:anyAttribute processContents="lax"/>
</xsd:complexType>
<!-- error type which includes patch operation -->
<xsd:complexType name="patch-error">
<xsd:sequence>
<xsd:any namespace="##any" processContents="lax"/>
</xsd:sequence>
<xsd:attribute name="phrase" type="xsd:string"/>
<xsd:attribute ref="xml:lang"/>
<xsd:anyAttribute processContents="lax"/>
</xsd:complexType>
</xsd:schema> </xsd:schema>
9. IANA Considerations 10. IANA Considerations
9.1. XML Schema Registration This memo calls for IANA to:
This section registers a new XML Schema. o register a new XML namespace URN according to the procedures of
RFC 3688 [RFC3688].
o register a new MIME type 'application/patch-ops-error+xml'
according to the procedures of RFC 4288 [RFC4288] and guidelines
in RFC 3023 [RFC3023].
o register two XML Schemas according to the procedures of RFC 3688
[RFC3688].
10.1. URN Sub-Namespace Registration
This specification registers a new XML namespace, as per the
guidelines in RFC 3688 [RFC3688].
URI: The URI for this namespace is
urn:ietf:params:xml:ns:patch-ops-error
Registrant Contact: IETF, SIMPLE working group, (simple@ietf.org),
Jari Urpalainen (jari.urpalainen@nokia.com).
XML:
BEGIN
<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.0//EN"
"http://www.w3.org/TR/xhtml-basic/xhtml-basic10.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type"
content="text/html;charset=iso-8859-1"/>
<title>Patch-Ops Error Namespace</title>
</head>
<body>
<h1>Namespace for Patch-Ops Error Documents</h1>
<h2>urn:ietf:params:xml:ns:patch-ops-error</h2>
<p>See <a href="[URL of published RFC]">RFCXXXX [[NOTE
TO RFC-EDITOR/IANA: Please replace XXXX with the RFC Number of
this specification]]</a>.</p>
</body>
</html>
END
10.2. application/patch-ops-error+xml MIME Type
MIME media type name: application
MIME subtype name: patch-ops-error+xml
Mandatory parameters: none
Optional parameters: Same as charset parameter application/xml as
specified in RFC 3023 [RFC3023].
Encoding considerations: Same as encoding considerations of
application/xml as specified in RFC 3023 [RFC3023].
Security considerations: See Section 10 of RFC 3023 [RFC3023].
Interoperability considerations: none.
Published specification: RFC XXXX [[NOTE TO RFC EDITOR: Please
replace XXXX with the published RFC number of this
specification.]].
Applications which use this media type: This document type has been
used to support transport of Patch-Ops errors in RFC XXXX [[NOTE
TO RFC EDITOR: Please replace XXXX with the published RFC number
of this specification.]].
Additional Information:
Magic Number: None
File Extension: .xer
Macintosh file type code: "TEXT"
Personal and email address for further information: Jari
Urpalainen, jari.urpalainen@nokia.com
Intended usage: COMMON
Author/Change controller: The IETF.
10.3. Patch-Ops-Types XML Schema Registration
This section registers a new XML Schema, the sole content of which is
shown in Section 8.
URI: URI:
urn:ietf:params:xml:schema:xml-patch-ops urn:ietf:params:xml:schema:patch-ops
Registrant Contact: Registrant Contact:
IETF, SIMPLE working group, <simple@ietf.org> IETF, SIMPLE working group, <simple@ietf.org>
Jari Urpalainen, <jari.urpalainen@nokia.com> Jari Urpalainen, <jari.urpalainen@nokia.com>
10. Security Considerations 10.4. Patch-Ops-Error XML Schema Registration
Information exchanged within these patch operations can be highly This section registers a new XML Schema, the sole content of which is
sensitive. Thus systems need to protect the integrity and shown in Section 9.
confidentiality of this data. Especially, the transport protocol
once it is used SHOULD have capabilities to protect from possible
threats. For example, a malicious man-in-the-middle attack could
easily give misinformation. However, all the security considerations
depend very much on the application which utilizes this framework.
11. Acknowledgments URI:
urn:ietf:params:xml:schema:patch-ops-error
The author would like to thank Eva Leppanen, Mikko Lonnfors, Aki Registrant Contact:
IETF, SIMPLE working group, <simple@ietf.org>
Jari Urpalainen, <jari.urpalainen@nokia.com>
11. Security Considerations
Security considerations depend very much on the application which
utilizes this framework. Since each application will have different
needs, threat models, and security features, it will be necessary to
consider these on an application-by-application basis.
However, this framework utilizes a limited subset of XPath 1.0.
Applications may thus be vulnerable to XPath injection attacks which
can reveal some non-allowable content of an XML document. Injection
attacks are most likely with shareable resources where access to a
resource is limited to only some specific parts for a user, contrary
to a typical use-case of this framework. To defend against those
attacks the input MUST be sanitized which can be done for example by
validating the diff-formats with these restrictive schemas.
12. Acknowledgments
The author would like to thank Lisa Dusseault for her efforts
including BoF arrangements, comments and editing assistance. The
author would also like to thank Eva Leppanen, Mikko Lonnfors, Aki
Niemi, Jonathan Rosenberg, Miguel A. Garcia, Anat Angel, Stephane Niemi, Jonathan Rosenberg, Miguel A. Garcia, Anat Angel, Stephane
Bortzmeyer and Dave Crocker for their valuable comments and Ted Bortzmeyer, Dave Crocker, Joel Halpern, Jeffrey Hutzelman, David Ward
Hardie for his input and support. and Chris Newman for their valuable comments and Ted Hardie for his
input and support.
12. References 13. References
12.1. Normative References 13.1. Normative References
[1] Bradner, S., "Key words for use in RFCs to Indicate Requirement [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[2] "Extensible Markup Language (XML) 1.0 (Fourth Edition)", W3C [W3C.REC-xml-20060816]
Recommendation REC-xml-20060816 , August 2006. Maler, E., Paoli, J., Bray, T., Yergeau, F., and C.
Sperberg-McQueen, "Extensible Markup Language (XML) 1.0
(Fourth Edition)", World Wide Web Consortium
Recommendation REC-xml-20060816, August 2006,
<http://www.w3.org/TR/2006/REC-xml-20060816>.
[3] "XML Path Language (XPath) Version 1.0", W3C Recommendation [W3C.REC-xpath-19991116]
REC-xpath-19991116 , November 1999. DeRose, S. and J. Clark, "XML Path Language (XPath)
Version 1.0", World Wide Web Consortium
Recommendation REC-xpath-19991116, November 1999,
<http://www.w3.org/TR/1999/REC-xpath-19991116>.
[4] "Namespaces in XML (Second Edition)", W3C Recommendation REC- [W3C.REC-xml-names-20060816]
xml-names-20060816 , August 2006. Hollander, D., Bray, T., Layman, A., and R. Tobin,
"Namespaces in XML 1.0 (Second Edition)", World Wide Web
Consortium Recommendation REC-xml-names-20060816,
August 2006,
<http://www.w3.org/TR/2006/REC-xml-names-20060816>.
[5] "XML Schema Part 1: Structures Second Edition", W3C [W3C.REC-xmlschema-1-20041028]
Recommendation REC-xmlschema-1-20041028 , October 2004. Beech, D., Thompson, H., Maloney, M., and N. Mendelsohn,
"XML Schema Part 1: Structures Second Edition", World Wide
Web Consortium Recommendation REC-xmlschema-1-20041028,
October 2004,
<http://www.w3.org/TR/2004/REC-xmlschema-1-20041028>.
[6] "Canonical XML 1.0", W3C Recommendation REC-xml-c14n-20010315 , [W3C.REC-xml-c14n-20010315]
March 2001. Boyer, J., "Canonical XML Version 1.0", World Wide Web
Consortium Recommendation REC-xml-c14n-20010315,
March 2001,
<http://www.w3.org/TR/2001/REC-xml-c14n-20010315>.
[7] "XML Schema Part 2: Datatypes Second Edition", W3C [W3C.REC-xmlschema-2-20041028]
Recommendation PER-xmlschema-2-20040318 , October 2004. Malhotra, A. and P. Biron, "XML Schema Part 2: Datatypes
Second Edition", World Wide Web Consortium
Recommendation REC-xmlschema-2-20041028, October 2004,
<http://www.w3.org/TR/2004/REC-xmlschema-2-20041028>.
[8] "xml:id Version 1.0 W3C Recommendation 9 September 2005", W3C [W3C.WD-xml-id-20041109]
Recommendation PR-xml-id-20050712 , September 2005. Veillard, D., Walsh, N., and J. Marsh, "xml:id Version
1.0", W3C LastCall WD-xml-id-20041109, November 2004.
[9] Yergeau, F., "UTF-8, a transformation format of ISO 10646", [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
RFC 2279, January 1998. 10646", STD 63, RFC 3629, November 2003.
12.2. Informative References [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media
Types", RFC 3023, January 2001.
[10] "XML Path Language (XPath) Version 2.0", W3C Recommendation [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
23 , January 2007. January 2004.
[11] Murata, M., "XML media types", RFC 3023, January 2001. [RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and
Registration Procedures", BCP 13, RFC 4288, December 2005.
[12] Rosenberg, J., "The Extensible Markup Language (XML) 13.2. Informative References
Configuration Access Protocol (XCAP)", RFC 4825, May 2007.
[13] Roach, A., "Session Initiation Protocol (SIP)-Specific Event [W3C.REC-xpath20-20070123]
Notification", RFC 3265, June 2002. Berglund, A., Fernandez, M., Chamberlin, D., Boag, S.,
Robie, J., Kay, M., and J. Simeon, "XML Path Language
(XPath) 2.0", World Wide Web Consortium
Recommendation REC-xpath20-20070123, January 2007,
<http://www.w3.org/TR/2007/REC-xpath20-20070123>.
[14] Lonnfors, M., Leppanen, E., Khartabil, H., and J. Urpalainen, [RFC4825] Rosenberg, J., "The Extensible Markup Language (XML)
"Presence Information Data format (PIDF) Extension for Partial Configuration Access Protocol (XCAP)", RFC 4825, May 2007.
Presence", draft-ietf-simple-partial-pidf-format-08 (work in
progress), November 2006.
[15] Rosenberg, J., "An Extensible Markup Language (XML) Document [RFC3265] Roach, A., "Session Initiation Protocol (SIP)-Specific
Format For Indicating Changes in XML Configuration Access Event Notification", RFC 3265, June 2002.
Protocol (XCAP) Resources", draft-ietf-simple-xcap-diff-05,
March 2007.
[16] Niemi, A., "Session Initiation Protocol (SIP) Extension for [I-D.ietf-simple-partial-pidf-format]
Event State Publication", RFC 3903, October 2004. Lonnfors, M., "Presence Information Data format (PIDF)
Extension for Partial Presence",
draft-ietf-simple-partial-pidf-format-08 (work in
progress), November 2006.
[I-D.ietf-simple-xcap-diff]
Urpalainen, J. and J. Rosenberg, "An Extensible Markup
Language (XML) Document Format for Indicating A Change in
XML Configuration Access Protocol (XCAP) Resources",
draft-ietf-simple-xcap-diff-06 (work in progress),
August 2007.
[RFC3903] Niemi, A., "Session Initiation Protocol (SIP) Extension
for Event State Publication", RFC 3903, October 2004.
Appendix A. Informative Examples Appendix A. Informative Examples
All following examples assume an imaginary XML diff document All following examples assume an imaginary XML diff document
including these patch operation elements. including these patch operation elements.
A.1. Adding an Element A.1. Adding an Element
An example initial XML document: An example target XML document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<doc> <doc>
<note>This is a sample document</note> <note>This is a sample document</note>
</doc> </doc>
An XML diff document: An XML diff document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<diff> <diff>
<add sel="doc"><foo id="ert4773">This is a new child</foo></add> <add sel="doc"><foo id="ert4773">This is a new child</foo></add>
</diff> </diff>
A result XML document: A result XML document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<doc> <doc>
<note>This is a sample document</note> <note>This is a sample document</note>
<foo id="ert4773">This is a new child</foo></doc> <foo id="ert4773">This is a new child</foo></doc>
A.2. Adding an Attribute A.2. Adding an Attribute
An example initial XML document: An example target XML document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<doc> <doc>
<note>This is a sample document</note> <note>This is a sample document</note>
<foo id="ert4773">This is a new child</foo></doc> <foo id="ert4773">This is a new child</foo></doc>
An XML diff document: An XML diff document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<diff> <diff>
skipping to change at page 21, line 42 skipping to change at page 30, line 43
A result XML document: A result XML document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<doc> <doc>
<note>This is a sample document</note> <note>This is a sample document</note>
<foo id="ert4773" user="Bob">This is a new child</foo></doc> <foo id="ert4773" user="Bob">This is a new child</foo></doc>
A.3. Adding a Prefixed Namespace Declaration A.3. Adding a Prefixed Namespace Declaration
An example initial XML document: An example target XML document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<doc> <doc>
<note>This is a sample document</note> <note>This is a sample document</note>
<foo id="ert4773">This is a new child</foo></doc> <foo id="ert4773">This is a new child</foo></doc>
An XML diff document: An XML diff document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<diff> <diff>
<add sel="doc" type="namespace::pref">urn:ns:xxx</add> <add sel="doc" type="namespace::pref">urn:ns:xxx</add>
</diff> </diff>
A result XML document: A result XML document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<doc xmlns:pref="urn:ns:xxx"> <doc xmlns:pref="urn:ns:xxx">
<note>This is a sample document</note> <note>This is a sample document</note>
<foo id="ert4773">This is a new child</foo></doc> <foo id="ert4773">This is a new child</foo></doc>
A.4. Adding a Comment Node with the 'pos' Attribute A.4. Adding a Comment Node with the 'pos' Attribute
An example initial XML document: An example target XML document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<doc> <doc>
<note>This is a sample document</note> <note>This is a sample document</note>
<foo id="ert4773">This is a new child</foo></doc> <foo id="ert4773">This is a new child</foo></doc>
An XML diff document: An XML diff document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<diff> <diff>
skipping to change at page 22, line 43 skipping to change at page 32, line 7
A result XML document: A result XML document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<doc> <doc>
<note>This is a sample document</note> <note>This is a sample document</note>
<!-- comment --><foo id="ert4773">This is a new child</foo></doc> <!-- comment --><foo id="ert4773">This is a new child</foo></doc>
A.5. Adding Multiple Nodes A.5. Adding Multiple Nodes
An example initial XML document: An example target XML document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<doc> <doc>
<note>This is a sample document</note> <note>This is a sample document</note>
</doc> </doc>
An XML diff document: An XML diff document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<diff> <diff>
skipping to change at page 23, line 28 skipping to change at page 32, line 32
A result XML document: A result XML document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<doc> <doc>
<note>This is a sample document</note> <note>This is a sample document</note>
<foo id="ert4773">This is a new child</foo></doc> <foo id="ert4773">This is a new child</foo></doc>
A.6. Replacing an Element A.6. Replacing an Element
An example initial XML document: An example target XML document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<doc> <doc>
<foo a="1">This is a sample document</foo> <foo a="1">This is a sample document</foo>
</doc> </doc>
An XML diff document: An XML diff document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<diff> <diff>
skipping to change at page 24, line 7 skipping to change at page 33, line 12
A result XML document: A result XML document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<doc> <doc>
<bar a="2"/> <bar a="2"/>
</doc> </doc>
A.7. Replacing an Attribute Value A.7. Replacing an Attribute Value
An example initial XML document: An example target XML document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<doc a="test"> <doc a="test">
<foo a="1">This is a sample document</foo> <foo a="1">This is a sample document</foo>
</doc> </doc>
An XML diff document: An XML diff document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<diff> <diff>
skipping to change at page 24, line 30 skipping to change at page 33, line 35
A result XML document: A result XML document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<doc a="new value"> <doc a="new value">
<foo a="1">This is a sample document</foo> <foo a="1">This is a sample document</foo>
</doc> </doc>
A.8. Replacing a Namespace Declaration URI A.8. Replacing a Namespace Declaration URI
An example initial XML document: An example target XML document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<doc xmlns:pref="urn:test"> <doc xmlns:pref="urn:test">
<foo a="1">This is a sample document</foo> <foo a="1">This is a sample document</foo>
</doc> </doc>
An XML diff document: An XML diff document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<diff> <diff>
skipping to change at page 24, line 43 skipping to change at page 34, line 4
<doc xmlns:pref="urn:test"> <doc xmlns:pref="urn:test">
<foo a="1">This is a sample document</foo> <foo a="1">This is a sample document</foo>
</doc> </doc>
An XML diff document: An XML diff document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<diff> <diff>
<replace sel="doc/namespace::pref">urn:new:xxx</replace> <replace sel="doc/namespace::pref">urn:new:xxx</replace>
</diff> </diff>
A result XML document: A result XML document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<doc xmlns:pref="urn:new:xxx"> <doc xmlns:pref="urn:new:xxx">
<foo a="1">This is a sample document</foo> <foo a="1">This is a sample document</foo>
</doc> </doc>
A.9. Replacing a Comment Node A.9. Replacing a Comment Node
An example initial XML document: An example target XML document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<doc xmlns:pref="urn:test"> <doc xmlns:pref="urn:test">
<foo a="1">This is a sample document</foo> <foo a="1">This is a sample document</foo>
<!-- comment --> <!-- comment -->
</doc> </doc>
An XML diff document: An XML diff document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
skipping to change at page 25, line 39 skipping to change at page 34, line 40
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<doc xmlns:pref="urn:test"> <doc xmlns:pref="urn:test">
<foo a="1">This is a sample document</foo> <foo a="1">This is a sample document</foo>
<!-- This is the new content <!-- This is the new content
--> -->
</doc> </doc>
A.10. Replacing a Processing Instruction Node A.10. Replacing a Processing Instruction Node
An example initial XML document: An example target XML document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<doc> <doc>
<foo a="1">This is a sample document</foo> <foo a="1">This is a sample document</foo>
<?test foo="bar"?> <?test foo="bar"?>
</doc> </doc>
An XML diff document: An XML diff document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<diff> <diff>
<replace sel='doc/processing-instruction("test")' <replace sel='doc/processing-instruction("test")'
><?test bar="foobar"?></replace> ><?test bar="foobar"?></replace>
</diff> </diff>
A result XML document: A result XML document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<doc> <doc>
<foo a="1">This is a sample document</foo> <foo a="1">This is a sample document</foo>
<?test bar="foobar"?> <?test bar="foobar"?>
</doc> </doc>
A.11. Replacing a Text Node A.11. Replacing a Text Node
An example initial XML document: An example target XML document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<doc> <doc>
<foo a="1">This is a sample document</foo> <foo a="1">This is a sample document</foo>
</doc> </doc>
An XML diff document: An XML diff document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<diff> <diff>
skipping to change at page 26, line 44 skipping to change at page 36, line 7
A result XML document: A result XML document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<doc> <doc>
<foo a="1">This is the new text content</foo> <foo a="1">This is the new text content</foo>
</doc> </doc>
A.12. Removing an Element A.12. Removing an Element
An example initial XML document: An example target XML document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<doc> <doc>
<foo a="1">This is a sample document</foo> <foo a="1">This is a sample document</foo>
</doc> </doc>
An XML diff document: An XML diff document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<diff> <diff>
skipping to change at page 27, line 25 skipping to change at page 36, line 29
</diff> </diff>
A result XML document: A result XML document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<doc> <doc>
</doc> </doc>
A.13. Removing an Attribute A.13. Removing an Attribute
An example initial XML document: An example target XML document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<doc a="foo"> <doc a="foo">
<foo a="1">This is a sample document</foo> <foo a="1">This is a sample document</foo>
</doc> </doc>
An XML diff document: An XML diff document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<diff> <diff>
skipping to change at page 27, line 44 skipping to change at page 37, line 4
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<diff> <diff>
<remove sel="doc/@a"/> <remove sel="doc/@a"/>
</diff> </diff>
A result XML document: A result XML document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<doc> <doc>
<foo a="1">This is a sample document</foo> <foo a="1">This is a sample document</foo>
</doc> </doc>
A.14. Removing a Prefixed Namespace Declaration A.14. Removing a Prefixed Namespace Declaration
An example initial XML document: An example target XML document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<doc> <doc>
<foo a="1" xmlns:pref="urn:test" <foo a="1" xmlns:pref="urn:test"
>This is a sample document</foo> >This is a sample document</foo>
<!-- comment --> <!-- comment -->
</doc> </doc>
An XML diff document: An XML diff document:
skipping to change at page 28, line 33 skipping to change at page 37, line 35
A result XML document: A result XML document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<doc> <doc>
<foo a="1">This is a sample document</foo> <foo a="1">This is a sample document</foo>
<!-- comment --> <!-- comment -->
</doc> </doc>
A.15. Removing a Comment Node A.15. Removing a Comment Node
An example initial XML document: An example target XML document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<doc> <doc>
<foo a="1">This is a sample document</foo> <foo a="1">This is a sample document</foo>
<!-- comment --> <!-- comment -->
</doc> </doc>
An XML diff document: An XML diff document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
skipping to change at page 28, line 46 skipping to change at page 38, line 4
<doc> <doc>
<foo a="1">This is a sample document</foo> <foo a="1">This is a sample document</foo>
<!-- comment --> <!-- comment -->
</doc> </doc>
An XML diff document: An XML diff document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<diff> <diff>
<remove sel="doc/comment()[1]" ws="after"/> <remove sel="doc/comment()[1]" ws="after"/>
</diff> </diff>
A result XML document: A result XML document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<doc> <doc>
<foo a="1">This is a sample document</foo> <foo a="1">This is a sample document</foo>
</doc> </doc>
A.16. Removing a Processing Instruction Node A.16. Removing a Processing Instruction Node
An example initial XML document: An example target XML document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<doc> <doc>
<foo a="1">This is a sample document</foo> <foo a="1">This is a sample document</foo>
<?test?> <?test?>
</doc> </doc>
An XML diff document: An XML diff document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
skipping to change at page 29, line 38 skipping to change at page 38, line 41
A result XML document: A result XML document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<doc> <doc>
<foo a="1">This is a sample document</foo> <foo a="1">This is a sample document</foo>
</doc> </doc>
A.17. Removing a Text Node A.17. Removing a Text Node
An example initial XML document: An example target XML document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<doc> <doc>
<foo a="1">This is a sample document</foo> <foo a="1">This is a sample document</foo>
</doc> </doc>
An XML diff document: An XML diff document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<diff> <diff>
<remove sel="doc/foo/text()[1]"/> <remove sel="doc/foo/text()[1]"/>
</diff> </diff>
A result XML document: A result XML document:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<doc> <doc>
<foo a="1"/> <foo a="1"/>
</doc> </doc>
A.18. Several Patches With Namespace Mangling A.18. Several Patches With Namespace Mangling
An example initial XML document where namespace qualified elements An example target XML document where namespace qualified elements
exist: exist:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<doc xmlns="urn:ietf:params:xml:ns:xxx" <doc xmlns="urn:ietf:params:xml:ns:xxx"
xmlns:z="urn:ietf:params:xml:ns:yyy"> xmlns:z="urn:ietf:params:xml:ns:yyy">
<note>This is a sample document</note> <note>This is a sample document</note>
<elem a="foo"> <elem a="foo">
<child/> <child/>
</elem> </elem>
<elem a="bar"> <elem a="bar">
skipping to change at page 31, line 43 skipping to change at page 40, line 43
<!-- This is a new child --> <!-- This is a new child -->
<child id="ert4773"> <child id="ert4773">
<z:node/> <z:node/>
</child> </child>
</elem> </elem>
<elem a="bar" b="new attr"/> <elem a="bar" b="new attr"/>
</doc> </doc>
The <node> and removed <child> element prefixes within the XML diff The <node> and removed <child> element prefixes within the XML diff
document are different than what are the "identical" namespace document are different than what are the "identical" namespace
declarations in the initial XML document. If the initial XML declarations in the target XML document. If the target XML document
document had used a prefixed namespace declaration instead of the had used a prefixed namespace declaration instead of the default one,
default one, the XML diff document could still have been the same. the XML diff document could still have been the same. The added new
The added new qualified elements would just have inherited that qualified elements would just have inherited that prefix.
prefix.
Author's Address Author's Address
Jari Urpalainen Jari Urpalainen
Nokia Nokia
Itamerenkatu 11-13 Itamerenkatu 11-13
Helsinki 00180 Helsinki 00180
Finland Finland
Phone: +358 7180 37686 Phone: +358 7180 37686
 End of changes. 116 change blocks. 
371 lines changed or deleted 806 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/