Internet DRAFT - draft-rosenberg-simple-xcap-change-log
draft-rosenberg-simple-xcap-change-log
SIMPLE J. Rosenberg
Internet-Draft Cisco Systems
Expires: April 20, 2006 October 17, 2005
An XML Format for Representing XML Configuration Access Protocol (XCAP)
Change Logs
draft-rosenberg-simple-xcap-change-log-00
Status of this Memo
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 becomes
aware will be disclosed, in accordance with Section 6 of BCP 79.
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 April 20, 2006.
Copyright Notice
Copyright (C) The Internet Society (2005).
Abstract
The XML Configuration Access Protocol (XCAP) Diff Format defines a
simple XML format for indicating that an XML document has changed.
This format does not indicate the actual change in the document; just
that it changed. However, the XCAP Diff Format is extensible, to
allow inclusion of the actual document changes. This specification
defines an XML schema that can be used to represent a set of changes
in an XCAP document.
Rosenberg Expires April 20, 2006 [Page 1]
Internet-Draft XCAP Diff Format October 2005
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Structure of an XCAP Change Log . . . . . . . . . . . . . . 3
4. Inclusion Within and XCAP Diff Document . . . . . . . . . . 4
5. Constructing a Document from the Change Log . . . . . . . . 5
6. Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
7. Example Document . . . . . . . . . . . . . . . . . . . . . . 7
8. Security Considerations . . . . . . . . . . . . . . . . . . 8
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . 8
9.1 URN Sub-Namespace Registration for
urn:ietf:params:xml:ns:xcap-log . . . . . . . . . . . . . 9
9.2 Schema Registration . . . . . . . . . . . . . . . . . . . 9
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 10
10.1 Normative References . . . . . . . . . . . . . . . . . . 10
10.2 Informative References . . . . . . . . . . . . . . . . . 10
Author's Address . . . . . . . . . . . . . . . . . . . . . . 11
Intellectual Property and Copyright Statements . . . . . . . 12
Rosenberg Expires April 20, 2006 [Page 2]
Internet-Draft XCAP Diff Format October 2005
1. Introduction
The XML Configuration Access Protocol (XCAP) [1] Diff format [2]
defines a simple XML-based format for describing the fact that a
document has changed. However, it does not actually describe the
changes to the document. When an XCAP Diff document is delivered in
a notification from the Session Initiation Protocol (SIP) [8]
configuration profile [3], the agent receiving the notification must
go to the XCAP server and fetch the entire document. For large
documents, this can be inefficient, especially over wireless
networks.
This document defines an XML format for an XCAP change log, meant for
inclusion within the <document> element in an XCAP Diff document.
This log represents the series of XCAP operations that took place on
the server. An XCAP client can use these logs to reconstruct the
document held by the server, and optionally use the document hash
defined in the XCAP Diff format to validate its current version.
2. Terminology
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 [5] and
indicate requirement levels for compliant implementations.
3. Structure of an XCAP Change Log
The namespace URI for elements defined by this specification is a URN
[6], using the namespace identifier 'ietf' defined by [7] and
extended by [4]. This URN is:
urn:ietf:params:xml:ns:xcap-log
The <change-log> element tells the client the specific set of XCAP
operations that can be applied to transform the document from the
version whose etag was "previous-etag" to the version whose etag is
"new-etag". The values of "previous-etag" and "new-etag" are
obtained from the context in which the <change-log> element appears.
When used within an XCAP Diff document, they are included as
attributes of the <document> element that contains the <change-log>.
If the "previous-etag" is not present, the <change-log> element tells
the client the specific set of XCAP operations that can be applied to
create a document from nothing, and result in the document whose etag
is "new-etag". The series of operations in the <change-log> do not
have to be the same exact series of operations that occurred at the
server. The only requirement is that, if the server includes the
<change-log> element, the sequence of events, when executed serially,
Rosenberg Expires April 20, 2006 [Page 3]
Internet-Draft XCAP Diff Format October 2005
will result in the transformation of the document with the etag
"previous-etag" to the one whose etag is "new-etag".
Each <change-log> element contains zero or more <put-event> or
<delete-event> elements. It can also contain elements from other
namespaces, which allows for extensibility to other transformations
in the future. A client MUST ignore any such elements it does not
understand. Each <delete-event> element reports an HTTP DELETE
operation, and each <put-event> element reports an HTTP PUT
operation. Both <put-event> and <delete-event> have a single
optional attribute, "node-selector", which contains the node selector
in the Request URI of the HTTP PUT or DELETE request. The node
selector present in the "node-selector" attribute MUST be escape
coded. This is because the double quote is not an allowed character
in an attribute value. Rather than use the XML escaping rules, URI
escaping is used. The server MUST include the "node-selector" when
the PUT or DELETE operation was against an XML element or attribute.
The "node-selector" attribute MUST NOT be present if the PUT or
DELETE operation was against the document itself. The <put-event>
element also has the mandatory attribute "content-type", which
indicates the Content-Type of the HTTP PUT request. The content of
the <put-event> element is either an <element> element or <attribute>
element, depending on whether an element or attribute was inserted or
modified through the PUT. If an attribute was inserted or modified,
the <attribute> element is used. It has text content, equal to the
value of the application/xcap-att+xml body that was present in the
request. Similarly, if an element was inserted or modified, the
<element> element is used. It has a single element as its child,
equal to the element that was in the application/xcap-el+xml body in
the request. In addition, both the the <attribute> and <element>
elements MUST include namespace declarations for all of the
namespaces in scope at the parent of the element or attribute that
was inserted, including the default, which MUST be declared as the
default namespace. Doing this has two benefits. Firstly, it allows
the resulting XCAP Diff document to be valid itself, since all
namespace prefixes used within the XCAP Diff document would be
defined. Secondly, it informs the client of the namespaces in scope
when the element or attribute was added. This allows xcap change
notifications to be used by clients that don't even cache the
document, but rather, alert the user to what change has just occurred
in the document.
4. Inclusion Within and XCAP Diff Document
Each <document> element of an XCAP Diff document MUST contain zero or
one <change-log> elements. More than one are not permitted. When an
XCAP Diff document is serving as a reference XCAP Diff (used to
establish the current etag for the document, as described in [2]),
Rosenberg Expires April 20, 2006 [Page 4]
Internet-Draft XCAP Diff Format October 2005
the <change-log> for each of the <document> elements MUST be absent.
It is important to note that a <document> element with no <change-
log> child is not equivalent to a <document> element with a <change-
log> child that is itself empty. The latter means that the document
has been assigned a new etag but its content is unchanged. The
former means that it has been assigned a new etag as a result of a
change, but the specific changes are not being reported in the XCAP
diff document.
5. Constructing a Document from the Change Log
If a client has the XML document whose etag matches the "previous-
etag" associated with the change log, the client can follow the
procedures defined here to obtain the document with the etag value of
"new-etag". This procedure is relatively straightforward, and is
done by having the client emulate XCAP server behavior as defined in
[1]
The client starts with the its version of the document whose etag is
"previous-etag" as the current document. If there was no "previous-
etag", the client starts with no document. The client MUST iterate
through each child of <change-log>, in order. For each element, it
MUST apply processing depending on the name of the element.
If the element is <delete-event>, the client takes the current
document. If the "node-selector" attribute was absent, it deletes
the entire document. If the "node-selector" attribute was present,
it selects the element or attribute using that node selector, as
described in Section 6.3 of [1]. The selected element or attribute
is deleted from the document, and the result becomes the current
document. There is no need for the client to run the validity checks
or idempotency checks normally performed by the server; a client will
always be provided with <delete-event> operations that succeeded at
the server.
If the element is <put-event>, the client takes the current document.
It then computes the Request URI that was seen by the server, by
concatenating the XCAP root with the "doc-selector" attribute of the
<document> element, appending the path separator, and then adding the
"node-selector" attribute of the <put-event> element, if present. If
the content of the <document> element is an <attribute> element, the
client "acts" as if it were the server, having receive an HTTP PUT
request with the Request URI equal to this value prior to escape
coding, with a body of Content-Type equal to the value of the
"content-type" attribute, and whose body equals the value of the
<attribute> element. If the content of the <document> element is an
<element> element, the client "acts" as if it were the server, having
Rosenberg Expires April 20, 2006 [Page 5]
Internet-Draft XCAP Diff Format October 2005
received an HTTP PUT request with the Request URI equal to this
value, with a body of Content-Type equal to the value of the
"content-type" attribute, and whose body equals the value of the
<element> element.
The client then follows the logic of Section 8.2 of [1] to apply the
PUT, ignorning all validity checks, resource interdependency
computations, error processing and verification of document content.
The resulting document becomes the current document. An actual
implementation need not literally act as a server; the behavior is
defined in these terms to specify what the correct output of the
processing has to be.
Once each child element of <change-log> has been processed, the
current document is equal to the document on the server whose etag
equals "new-etag".
Rosenberg Expires April 20, 2006 [Page 6]
Internet-Draft XCAP Diff Format October 2005
6. Schema
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema targetNamespace="urn:ietf:params:xml:ns:xcap-log"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns="urn:ietf:params:xml:ns:xcap-log"
elementFormDefault="qualified" attributeFormDefault="unqualified">
<xs:element name="change-log">
<xs:complexType>
<xs:sequence minOccurs="0" maxOccurs="unbounded">
<xs:choice>
<xs:element ref="delete-event"/>
<xs:element ref="put-event"/>
<xs:any namespace="##other" minOccurs="0" maxOccurs="unbounded"/>
</xs:choice>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="put-event">
<xs:complexType>
<xs:choice>
<xs:element name="element">
<xs:complexType>
<xs:sequence>
<xs:any namespace="##other"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="attribute" type="xs:string"/>
<xs:any namespace="##other"/>
</xs:choice>
<xs:attribute name="node-selector" type="xs:anyURI" use="optional"/>
</xs:complexType>
</xs:element>
<xs:element name="delete-event">
<xs:complexType>
<xs:attribute name="node-selector" type="xs:anyURI" use="optional"/>
</xs:complexType>
</xs:element>
</xs:schema>
7. Example Document
The following is an example of an XCAP Diff document that includes a
change log. The <delete-event> and <put-event> lines are folded for
Rosenberg Expires April 20, 2006 [Page 7]
Internet-Draft XCAP Diff Format October 2005
readability purposes only.
<?xml version="1.0" encoding="UTF-8"?>
<xcap-diff xmlns="urn:ietf:params:xml:ns:xcap-diff"
xmlns:log="urn:ietf:params:xml:ns:xcap-log"
xcap-root="http://xcap.example.com/root" >
<document new-etag="7ahggs"
doc-selector="resource-lists/users/joe/coworkers"
previous-etag="8a77f8d">
<log:delete-event node-selector="resouce-lists/list[@name=%22fr
iends%22]/entry[@uri=%22bill@example.com%22]"/>
<log:put-event node-selector="resouce-lists/list[@name=%22friend
s%22]/entry[@uri=%22jane@example.com%22]">
<log:element xmlns="urn:ietf:params:xml:ns:resource-lists">
<entry uri="sip:jane@example.com">
<display-name>Bill Doe</display-name>
</entry>
</log:element>
</log:put-event>
</document>
</xcap-diff>
This example XCAP diff document will indicate a transformation of the
example document in Section 3.3 of [9] by removing the entry for Bill
Smith and adding one for Jane Doe. Note how the <log:element> element
redefines the default namespace to
urn:ietf:params:xml:ns:resource-lists. This is the default namespace
in scope for the <entry> element in the actual document.
8. Security Considerations
XCAP diff documents without a change-log are not very sensitive; they
only contain entity tags and the URI for documents. However, with
the addition of a change-log, the documents can be used to
reconstruct the document held on the server. As a consequence,
message integrity and confidentiality may be important, depending on
the application usage. As a consequence, protocols for transporting
XCAP Diff documents with a change log MUST provide integrity and
confidentiality services.
9. IANA Considerations
There are several IANA considerations associated with this
specification.
Rosenberg Expires April 20, 2006 [Page 8]
Internet-Draft XCAP Diff Format October 2005
9.1 URN Sub-Namespace Registration for urn:ietf:params:xml:ns:xcap-log
This section registers a new XML namespace, as per the guidelines in
[4]
URI: The URI for this namespace is
urn:ietf:params:xml:ns:xcap-log.
Registrant Contact: IETF, SIMPLE working group, (simple@ietf.org),
Jonathan Rosenberg (jdrosen@jdrosen.net).
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>XCAP Diff Namespace</title>
</head>
<body>
<h1>Namespace for XCAP Change Logs</h1>
<h2>urn:ietf:params:xml:ns:xcap-log</h2>
<p>See <a href="[URL of published RFC]">RFCXXXX[[NOTE
TO IANA/RFC-EDITOR: Please replace XXXX with the RFC number of this
specification.]]</a>.</p>
</body>
</html>
END
9.2 Schema Registration
This section registers a new XML schema per the procedures in [4].
URI: urn:ietf:params:xml:schema:xcap-log
Registrant Contact: IETF, SIMPLE working group, (simple@ietf.org),
Jonathan Rosenberg (jdrosen@jdrosen.net).
The XML for this schema can be found as the sole content of
Section 6.
Rosenberg Expires April 20, 2006 [Page 9]
Internet-Draft XCAP Diff Format October 2005
10. References
10.1 Normative References
[1] Rosenberg, J., "The Extensible Markup Language (XML)
Configuration Access Protocol (XCAP)", draft-ietf-simple-xcap-07
(work in progress), June 2005.
[2] Rosenberg, J., "An Extensible Markup Language (XML) Document
Format for Indicating Changes in XML Configuration Access
Protocol (XCAP) Resources", draft-ietf-simple-xcap-diff-01 (work
in progress), July 2005.
[3] Petrie, D., "A Framework for Session Initiation Protocol User
Agent Profile Delivery", draft-ietf-sipping-config-framework-07
(work in progress), July 2005.
[4] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
January 2004.
[5] Bradner, S., "Key words for use in RFCs to Indicate Requirement
Levels", BCP 14, RFC 2119, March 1997.
[6] Moats, R., "URN Syntax", RFC 2141, May 1997.
[7] Moats, R., "A URN Namespace for IETF Documents", RFC 2648,
August 1999.
10.2 Informative References
[8] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A.,
Peterson, J., Sparks, R., Handley, M., and E. Schooler, "SIP:
Session Initiation Protocol", RFC 3261, June 2002.
[9] Rosenberg, J., "Extensible Markup Language (XML) Formats for
Representing Resource Lists",
draft-ietf-simple-xcap-list-usage-05 (work in progress),
February 2005.
Rosenberg Expires April 20, 2006 [Page 10]
Internet-Draft XCAP Diff Format October 2005
Author's Address
Jonathan Rosenberg
Cisco Systems
600 Lanidex Plaza
Parsippany, NJ 07054
US
Phone: +1 973 952-5000
Email: jdrosen@cisco.com
URI: http://www.jdrosen.net
Rosenberg Expires April 20, 2006 [Page 11]
Internet-Draft XCAP Diff Format October 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.
Rosenberg Expires April 20, 2006 [Page 12]
