One document matched: draft-urpalainen-simple-xcap-patch-ops-00.txt
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]
| PAFTECH AB 2003-2026 | 2026-04-22 21:43:50 |