An Extensible Markup Language (XML) Patch Operations Framework Utilizing XML Path Language (XPath) Selectors
Extracted elements (28)
Positional selectors like '*/*[3]/*[2]' produce the shortest selector strings but are fragile: when sibling elements are removed or inserted, positional indexes shift for subsequent operations. Named selectors with attribute predicates like 'doc[@sel="foo"]' are safer for auto-diff tools despite producing larger diff documents.
The schema defined in this document declares no target namespace, so type definitions inherit the target namespace of the including schema. This avoids the need for additional namespace declarations within XML diff documents that embed these types.
The XPath id() function MAY be used in selectors to identify unique elements, but requires either a schema-declared ID-typed attribute or an xml:id attribute. Implementations that do not support id() report <unsupported-id-function> or <unsupported-xml-id> errors rather than silently failing.
This specification's namespace prefix matching in selectors differs from XPath 1.0 and 2.0. In XPath 1.0, 'bar' always locates an unqualified element; here, a prefixless selector matches only if the element's namespace (or lack thereof) is an exact match. The namespace-uri() and local-name() functions are not allowed.
It is an error condition if the 'sel' selector locates multiple nodes. The 'sel' value MUST identify a single unique target node from the target XML document.
Patch operations MUST be applied sequentially in document order. After each patch is applied, the patched document becomes the new target for the next patch. If any patch operation fails, it is an error condition and further processing is not sensible.
Per XPath 1.0, a text node MUST NOT have another text node as an immediate sibling. When adding content adjacent to an existing text node, the text node contents MUST be combined together rather than creating sibling text nodes.
Specifications referencing this framework's schema types MUST define the full XML diff format with an appropriate MIME type and character set (e.g., UTF-8). Instance document elements based on these schema type definitions MUST be well-formed and SHOULD be valid.
The agent parsing the diff document MUST resolve namespace prefixes separately in both the diff and target documents in order to match the resulting QNames. The XML diff document MUST contain declarations for all namespaces used within it.
The canonical form with comments (W3C XML c14n) of an XML document determines logical equivalence in this framework. White space text nodes MUST be processed properly because white space is by default significant in canonical XML.
The resulting patched document MUST NOT be 'cleaned up' by removing unused or superfluous namespace declarations that arise from the namespace mangling procedure.
When a diff document element selector uses a prefix, the agent MUST look up that prefix in the diff document's namespace declarations and locate the corresponding element by namespace URI, regardless of what prefix the target document uses for the same namespace.
When adding attributes or namespaces via <add>, the child node of the <add> element MUST be a single text node. The located target node MUST be an element. For other additions, <add> MAY contain any mixture of element, text, comment, or processing instruction nodes.
When adding namespace-qualified content to the target document, the agent MUST ensure the target document contains the same namespace declaration (same URI, prefix MAY differ). The namespace prefix in the patched document is resolved by priority rules based on the evaluation context node's in-scope prefixes.
When removing an element, comment, or processing instruction without the 'ws' directive, if immediate preceding and following sibling text nodes both exist, their content MUST be combined together and the latter text node removed from the document.
When replacing an attribute with an empty <replace> element, the attribute MUST remain in the patched document with an empty value. When replacing a text node with an empty <replace>, the text node MUST be removed because a text node must always have at least one character of data.
An XML diff document contains patch operation elements: <add>, <replace>, and <remove>. These operations are applied sequentially in document order to transform a target XML document into a patched XML document.
Defined error elements include: <invalid-attribute-value>, <invalid-character-set>, <invalid-diff-format>, <invalid-entity-declaration>, <invalid-namespace-prefix>, <invalid-namespace-uri>, <invalid-node-types>, <invalid-patch-directive>, <invalid-root-element-operation>, <invalid-xml-prolog-operation>, <invalid-whitespace-directive>, <unlocated-node>, <unsupported-id-function>, <unsupported-xml-id>.
Each patch operation element contains a 'sel' attribute whose value is a restricted XPath 1.0 selector. The selector locates a single unique target node in the target XML document; locating zero or multiple nodes is an error.
The <add> element has three attributes: required 'sel' (xpath-add type XPath selector), optional 'type' (used only for attributes '@attr' or namespaces 'namespace::pref'), and optional 'pos' (before/after/prepend, used for non-attribute/namespace insertions). Children of <add> are copied into the target document.
The error document root element is <patch-ops-error> in namespace 'urn:ietf:params:xml:ns:patch-ops-error'. It contains a specific error condition element, each carrying a 'phrase' attribute for human-readable text and an optional 'xml:lang'. Most error elements include the offending patch operation element.
The <remove> element has a required 'sel' attribute and an optional 'ws' attribute with values 'before', 'after', or 'both'. The 'ws' attribute removes immediate sibling white space text nodes and is only permitted when removing element, comment, or processing instruction nodes (not text, attribute, or namespace nodes).
The <replace> element has only a required 'sel' attribute (xpath type). If the located target is an element, comment, or processing instruction, the single child of <replace> MUST be of the same node type. For attribute and text node replacement, <replace> contains text content or MAY be empty.
IANA registered the MIME type 'application/patch-ops-error+xml' (file extension .xer) for transporting XML patch operation error documents, per RFC 4288 and RFC 3023 procedures.
IANA registered the XML namespace URN 'urn:ietf:params:xml:ns:patch-ops-error' for the patch operations error namespace, per RFC 3688 procedures.
IANA registered two XML Schemas: 'urn:ietf:params:xml:schema:patch-ops' (Section 8, patch operation type definitions for add/replace/remove) and 'urn:ietf:params:xml:schema:patch-ops-error' (Section 9, error document definitions), per RFC 3688 procedures.
This framework uses a restricted subset of XPath 1.0, making applications potentially vulnerable to XPath injection attacks that could reveal non-allowable content of an XML document. This risk is greatest with shared resources where per-user access is restricted. Implementors MUST sanitize input, for example by validating diff formats against the restrictive schemas defined in this document.
The 'xpath-add' simple type restricts XPath selectors for <add> to allow child node targets (text(), comment(), processing-instruction(), element steps). The 'xpath' type for <replace> and <remove> additionally allows attribute axis (@qname) and namespace axis (namespace::ncname) as final steps. The 'pos' type enumerates 'before', 'after', 'prepend'. The 'ws' type enumerates 'before', 'after', 'both'.