SIMPLE WG J. Urpalainen Internet-Draft Nokia Research Center Expires: August 18, 2005 February 14, 2005 The Extensible Markup Language (XML) Configuration Access Protocol (XCAP) Patch Operations draft-urpalainen-simple-xcap-patch-ops-00 Status of this Memo This document is an Internet-Draft and is subject to all provisions of Section 3 of RFC 3667. By submitting this Internet-Draft, each author represents that any 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 become aware will be disclosed, in accordance with RFC 3668. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on August 18, 2005. Copyright Notice Copyright (C) The Internet Society (2005). Abstract Many prevailing systems nowadays utilize XML documents. Sometimes there's need to do some minor changes to the documents and therefore it is useful to transport only the changes e.g. over the network. This document describes XML patch operations which can be used to achieve this goal by defining XML elements which can be embedded within a transported XML change document. Urpalainen Expires August 18, 2005 [Page 1]
Internet-Draft Patch Operations February 2005 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . 3 3. Patch operations . . . . . . . . . . . . . . . . . . . . . . 3 3.1 <add> element . . . . . . . . . . . . . . . . . . . . . . 5 3.2 <replace> element . . . . . . . . . . . . . . . . . . . . 5 3.3 <remove> element . . . . . . . . . . . . . . . . . . . . . 5 4. Error handling . . . . . . . . . . . . . . . . . . . . . . . 5 5. Usage of patch operations . . . . . . . . . . . . . . . . . 5 6. Node Selector . . . . . . . . . . . . . . . . . . . . . . . 6 7. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 6 8. XML Schema . . . . . . . . . . . . . . . . . . . . . . . . . 8 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . 9 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 10.1 Normative references . . . . . . . . . . . . . . . . . . 9 10.2 Informative references . . . . . . . . . . . . . . . . . 9 Author's Address . . . . . . . . . . . . . . . . . . . . . . 10 Intellectual Property and Copyright Statements . . . . . . . 11 Urpalainen Expires August 18, 2005 [Page 2]
Internet-Draft Patch Operations February 2005 1. Introduction Many prevailing systems nowadays utilize XML documents. Sometimes there's need to do some minor changes to the documents and therefore it is useful to transport only the changes e.g. over the network. The XCAP [4] protocol defines a model where HTTP transport with methods: PUT and DELETE can be used to apply changes to a single XML document by doing one update at a time. The patch operations will complement that model by allowing several modifications to be applied to the document during one transaction. This document describes XML patch operations by defining XML elements which can be embedded within a transported XML change document. This requires however, a more flexible transport e.g. SIP [7] or a new HTTP PATCH method [8]. 2. Conventions In this document, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in RFC 2119 [1] and indicate requirement levels for compliant implementations. The following terms are used in this demo: XML change document: This is the document that will carry all the patch operations, namepace definitions and all the data content changes. Patched document: This is the local copy of the document onto which all the patch operations in the XML change document are being applied. 3. Patch operations The XML change document contains a collection of add, replace or remove operations which will be applied one-by-one in the given order. Each of the operations contains at least one XPath [2] compatible selector which is used to select a unique specific part within the patched document. Furthermore, also the changed or added data content is given. For example, when an add operation is being requested, the element onto which new data is going to be appended is searched first from the document to be patched and then the new data content is added. OPEN ISSUE: do we want to have <add before> and <add after>. OPEN ISSUE: do we want to have http put semantics ? i.e. if replace fails continue with add. Urpalainen Expires August 18, 2005 [Page 3]
Internet-Draft Patch Operations February 2005 OPEN ISSUE: do we want to have operations for xml Processing Instructions, comments or namespace definitions ? All of these seem to call for a new operation. Adding namespace definitions could be almost automatic, however. When evaluating XPath location steps, namespace expansion follows XPath 1.0 [2] semantics, i.e. if the QName does not have a prefix then the namespace URI in the expanded name is null. When the patched document is using namespace definitions, QName expansion in the location steps is done according to the definitions in the XML change document. Thus the namespace URIs for the prefixes in the evaluation steps are easily found from the XML change document. It should be emphasized that the client MAY use any prefix value, i.e. it does not have to be the same than that of the patched document. Also when the patched document uses default namespaces an equivalent namespace URI with some prefix has to be defined within the XML change document and the defined prefix MUST be used in selectors. As all the namespace definitions relevant to the patch operations are within the XML change document the element names within the optional data content are also fully namespace qualified. This means that the content of the XML change document is independent of the prefixes of the patched document. The process that performs all these patch operations does not add new or change the namespace definitions based on the prefixes and definitions in the root node of the XML change document. Instead it keeps the definitions that already exist within the patched document. If the intention is to add new namespace definitions to the patched document their definition MUST be within the added or changed data content. When doing these XPath evaluations with a fully XPath 1.0 compatible library it means that if e.g. "pref:node" location step has to be evaluated and <xmlns:pref="urn:ietf:params:xml:ns"/> is thus defined within the XML change document the location step "pref:node" has to be changed to e.g. "*[namespace-uri()="urn:ietf:params:xml:ns"][local-name()="node"]". However, XPath libraries usually support some sort of "namespace registering" APIs so that location step parsing can be done properly without any changes in the location step string once the prefixes versus URIs has been "registered". The XML Schema defines element types for different patch operations. The XML Schema is supposed to be included into the other XML Schemas that utilize these operations: e.g. XCAP package [5] and partial PIDF [6]. They will provide a relevant XML change document context. Furthermore, it is anticipated that they will define <add>, <replace> and <remove> elements from the corresponding types defined in this XML Schema. The XML document fragments defined in this draft MUST be Urpalainen Expires August 18, 2005 [Page 4]
Internet-Draft Patch Operations February 2005 well formed and valid. 3.1 <add> element The <add> element type has two selection attributes: 'parent' and 'sel'. The value of the 'parent' attribute is used to select a single element from the document onto which new data content will be appended. The second selector 'sel' is a relative location step that will uniquely point after the append to the created element, text-node content or attribute within the 'parent' selection context. If there are several sibling elements in the new document the 'sel' selector MUST include a positional constraint to fulfill an unambiguous request. The content of the <add> element is plain text for attributes and elements which have only text-content i.e. XPath text() function is being used in the 'sel' selector. Once the 'sel' selector identifies a single element, the content of the <add> element inludes all the attributes and child elements and e.g. possible namespace definitions, comment nodes and processing instructions. 3.2 <replace> element The <replace> element type has only one attribute: 'sel' the value of which is used to select an element, a text-node content or an attribute that is going to be replaced with the new content. The content of the <replace> element is similar as with <add> operation. 3.3 <remove> element The <remove> element type has only one attribute: 'sel' the content of which is used to select an element, text-node content or an attribute that is going to be removed. 4. Error handling It is an error condition if any of the given operations can not be unambiguously fulfilled. However, it is beyond the scope of this document to describe a generic error response. OPEN ISSUE: <xcap-error> format could be extended as it could be trivial to respond that e.g. operation add[2] failed combined with some text description. HTTP patch seems to favor multi-status responses (WebDAV style). 5. Usage of patch operations The XML change document SHOULD contain only those elements or attributes that have been updated. However, when there are a lot of Urpalainen Expires August 18, 2005 [Page 5]
Internet-Draft Patch Operations February 2005 queued changes it MAY be desirable to send the full document content instead. How this will be done in practice is beyond the scope of this document. 6. Node Selector The ABNF [3] is used to describe the syntax for the node selector expressions. The node selector syntax is defined to be XPath [2] compatible, but has a more restricted set of capabilities. Each element selection has to point to a single node. As the document root is always the starting point for selections relative location paths can be used. XPath text() function can be used to select the text node content. It can't be used in this context e.g. when the element has mixed content or the element has child elements. XPath last() function can be used in predicates if e.g. the added new element should be the last sibling. node-sel = element-sel ["/" (attribute-sel / "text()")] element-sel = element-step *("/" element-step) element-step = ("*" / node-name) [conditions] conditions = *("[" condition "]") condition = 1*DIGIT / ; positional cond-name "=" <"> value <"> / ; value comparison "last()" ; XPath last() function cond-name = "@" node-name / ; attribute selection node-name / ; element selection "." ; current node selection node-name = [prefix ":"] string prefix = <any sequence of data supported by XML for namespace prefixes> string = <any sequence of data supported by XML for element or attribute names> value = <any sequence of data supported by XML for element or attribute values> attribute-sel = "@" node-name 7. Examples The document to be patched: Urpalainen Expires August 18, 2005 [Page 6]
Internet-Draft Patch Operations February 2005 <?xml version="1.0" encoding="UTF-8"?> <root xmlns="urn:ietf:params:xml:ns:xxx" xmlns:z="urn:ietf:params:xml:ns:yyy" > <note>This is a sample document</note> <node a="foo"/> <child/> <node a="bar"/> <z:child/> </root> The following namespace definitions have been added to the XML change document which uses default namespaces itself: xmlns:x="urn:ietf:params:xml:ns:xxx" xmlns:y="urn:ietf:params:xml:ns:yyy" The four example patch operations are shown as XML fragments: <add parent="x:root/x:node[@a="foo"]" sel="*[last()]"> <x:child id="ert4773"> <y:node/> </x:child> </add> <replace sel="x:root/x:note/text()">Patched doc</replace> <remove sel="*/x:node[@a="bar"]/y:child"/> <add parent="*/x:node[@a="bar"]" sel="@b">new attr</add> The resulting document after applying the patches: <?xml version="1.0" encoding="UTF-8"?> <root xmlns="urn:ietf:params:xml:ns:xxx" xmlns:z="urn:ietf:params:xml:ns:yyy" > <note>Patched doc</note> <node a="foo"/> <child/> <child id="ert4773"> <z:node/> <node a="bar" b="new attr"/> </root> Urpalainen Expires August 18, 2005 [Page 7]
Internet-Draft Patch Operations February 2005 8. XML Schema The XML schema types for the patch operations. <?xml version="1.0" encoding="UTF-8"?> <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified"> <xsd:complexType name="addType"> <xsd:complexContent mixed="true"> <xsd:restriction base="xsd:anyType"> <xsd:sequence> <xsd:any processContents="lax" namespace="##any" minOccurs="0" maxOccurs="1"/> </xsd:sequence> <xsd:attribute name="parent" type="xsd:string" use="required"/> <xsd:attribute name="sel" type="xsd:string" use="required"/> </xsd:restriction> </xsd:complexContent> </xsd:complexType> <xsd:complexType name="replaceType"> <xsd:complexContent mixed="true"> <xsd:restriction base="xsd:anyType"> <xsd:sequence> <xsd:any processContents="lax" namespace="##any" minOccurs="0" maxOccurs="1"/> </xsd:sequence> <xsd:attribute name="sel" type="xsd:string" use="required"/> </xsd:restriction> </xsd:complexContent> </xsd:complexType> <xsd:complexType name="removeType"> <xsd:attribute name="sel" type="xsd:string" use="required"/> </xsd:complexType> </xsd:schema> Urpalainen Expires August 18, 2005 [Page 8]
Internet-Draft Patch Operations February 2005 9. Acknowledgments The author would like to thank Eva Leppanen, Mikko Lonnfors, Aki Niemi and Jonathan Rosenberg for their valuable comments. 10. References 10.1 Normative references [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [2] "XML Path Language (XPath) Version 1.0", W3C REC REC-xpath-19991116 , November 1999. [3] Crocker, D., "Augmented BNF for Syntax Specifications: ABNF", RFC 2234, November 1997. 10.2 Informative references [4] Rosenberg, J., "The Extensible Markup Language (XML) Configuration Access Protoco (XCAP)", draft-ietf-simple-xcap-06, February 2005. [5] Rosenberg, J., "An Extensible Markup Language (XML) Document Format For Indicating Changes in XML Configuration Access Protocol (XCAP) Resources", draft-ietf-simple-xcap-diff-00 (work in progress), February 2005. [6] Lonnfors, M., Leppanen, E., Khartabil, H. and J. Urpalainen, "Presence Information Data format (PIDF) Extension for Partial Presence", draft-ietf-simple-partial-pidf-format-03 (work in progress), February 2005. [7] Niemi, A., "Session Initiation Protocol (SIP) Extension for Event State Publication", RFC 3903, October 2004. [8] Dusseault, L., "Partial Document Changes (PATCH Method) for HTTP", draft-dusseault-http-patch-06 (work in progress), October 2004. Urpalainen Expires August 18, 2005 [Page 9]
Internet-Draft Patch Operations February 2005 Author's Address Jari Urpalainen Nokia Research Center Itamerenkatu 11-13 00180 Helsinki Finland Phone: +358 7180 37686 Email: jari.urpalainen@nokia.com Urpalainen Expires August 18, 2005 [Page 10]
Internet-Draft Patch Operations February 2005 Intellectual Property Statement The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79. Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org. Disclaimer of Validity This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Copyright Statement Copyright (C) The Internet Society (2005). This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights. Acknowledgment Funding for the RFC Editor function is currently provided by the Internet Society. Urpalainen Expires August 18, 2005 [Page 11]