< draft-ietf-simple-xcap-diff-13.txt   draft-ietf-simple-xcap-diff-14.txt >
SIMPLE J. Rosenberg SIMPLE J. Rosenberg
Internet-Draft Cisco Internet-Draft Cisco
Intended status: Standards Track J. Urpalainen Intended status: Standards Track J. Urpalainen
Expires: December 31, 2009 Nokia Expires: August 5, 2010 Nokia
June 29, 2009 February 1, 2010
An Extensible Markup Language (XML) Document Format for Indicating A An Extensible Markup Language (XML) Document Format for Indicating A
Change in XML Configuration Access Protocol (XCAP) Resources Change in XML Configuration Access Protocol (XCAP) Resources
draft-ietf-simple-xcap-diff-13 draft-ietf-simple-xcap-diff-14
Abstract
This specification defines a document format that can be used to
indicate that a change has occurred in a document managed by the
Extensible Markup Language (XML) Configuration Access Protocol
(XCAP). This format reports which document has changed and its
former and new entity tags. It can report the differences between
versions of the document, using an XML patch format. It can report
existing element and attribute content when versions of an XCAP
server document change. XCAP diff documents can be delivered to diff
clients using a number of means, including a Session Initiation
Protocol (SIP) event package.
Status of this Memo Status of this Memo
This Internet-Draft is submitted to IETF in full conformance with the This Internet-Draft is submitted to IETF in full conformance with the
provisions of BCP 78 and BCP 79. This document may contain material provisions of BCP 78 and BCP 79.
from IETF Documents or IETF Contributions published or made publicly
available before November 10, 2008. The person(s) controlling the
copyright in some of this material may not have granted the IETF
Trust the right to allow modifications of such material outside the
IETF Standards Process. Without obtaining an adequate license from
the person(s) controlling the copyright in such materials, this
document may not be modified outside the IETF Standards Process, and
derivative works of it may not be created outside the IETF Standards
Process, except to format it for publication as an RFC or to
translate it into languages other than English.
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
other groups may also distribute working documents as Internet- other groups may also distribute working documents as Internet-
Drafts. Drafts.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
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 December 31, 2009. This Internet-Draft will expire on August 5, 2010.
Copyright Notice Copyright Notice
Copyright (c) 2010 IETF Trust and the persons identified as the
Copyright (c) 2009 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents in effect on the date of Provisions Relating to IETF Documents
publication of this document (http://trustee.ietf.org/license-info). (http://trustee.ietf.org/license-info) in effect on the date of
Please review these documents carefully, as they describe your rights publication of this document. Please review these documents
and restrictions with respect to this document. carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
Abstract include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the BSD License.
This specification defines a document format that can be used to This document may contain material from IETF Documents or IETF
indicate that a change has occurred in a document managed by the Contributions published or made publicly available before November
Extensible Markup Language (XML) Configuration Access Protocol 10, 2008. The person(s) controlling the copyright in some of this
(XCAP). This format indicates the document that has changed and its material may not have granted the IETF Trust the right to allow
former and new entity tags. It also can indicate the specific change modifications of such material outside the IETF Standards Process.
that was made in the document, using an XML patch format. This Without obtaining an adequate license from the person(s) controlling
format allows also indications of element and attribute content of an the copyright in such materials, this document may not be modified
XML document. XCAP diff documents can be delivered to clients using outside the IETF Standards Process, and derivative works of it may
a number of means, including a Session Initiation Protocol (SIP) not be created outside the IETF Standards Process, except to format
event package. it for publication as an RFC or to translate it into languages other
than English.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5
3. Structure of an XCAP Diff Document . . . . . . . . . . . . . . 5 3. Structure of an XCAP Diff Document . . . . . . . . . . . . . . 6
4. XML Schema . . . . . . . . . . . . . . . . . . . . . . . . . . 8 4. XML Schema . . . . . . . . . . . . . . . . . . . . . . . . . . 9
5. Example Document . . . . . . . . . . . . . . . . . . . . . . . 11 5. Example Document . . . . . . . . . . . . . . . . . . . . . . . 12
6. Security Considerations . . . . . . . . . . . . . . . . . . . 11 6. Basic Requirements For a System Exchanging XCAP Diff
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 Documents . . . . . . . . . . . . . . . . . . . . . . . . . . 13
7.1. application/xcap-diff+xml MIME Type . . . . . . . . . . . 12 7. Security Considerations . . . . . . . . . . . . . . . . . . . 14
7.2. URN Sub-Namespace Registration for 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15
urn:ietf:params:xml:ns:xcap-diff . . . . . . . . . . . . . 13 8.1. application/xcap-diff+xml MIME Type . . . . . . . . . . . 15
7.3. Schema Registration . . . . . . . . . . . . . . . . . . . 14 8.2. URN Sub-Namespace Registration for
8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 14 urn:ietf:params:xml:ns:xcap-diff . . . . . . . . . . . . . 16
9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 14 8.3. Schema Registration . . . . . . . . . . . . . . . . . . . 16
9.1. Normative References . . . . . . . . . . . . . . . . . . . 14 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 17
9.2. Informative References . . . . . . . . . . . . . . . . . . 15 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 15 10.1. Normative References . . . . . . . . . . . . . . . . . . . 17
10.2. Informative References . . . . . . . . . . . . . . . . . . 18
Appendix A. Informative Examples . . . . . . . . . . . . . . . . 19
A.1. Indicating Existing, Changed or Removed Documents . . . . 19
A.2. Indicating Actual Changes of Documents . . . . . . . . . . 22
A.3. Indicating XCAP Component Contents . . . . . . . . . . . . 24
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 25
1. Introduction 1. Introduction
The Extensible Markup Language (XML) Configuration Access Protocol The Extensible Markup Language (XML) Configuration Access Protocol
(XCAP) [RFC4825] is a protocol that allows clients to manipulate XML (XCAP) [RFC4825] is a protocol that allows XCAP clients to manipulate
documents stored on a server. These XML documents serve as XML documents stored on a server. These XML documents serve as
configuration information for application protocols. As an example, configuration information for application protocols. As an example,
resource list [RFC4662] subscriptions (also known as presence lists) resource list [RFC4662] subscriptions (also known as presence lists)
allow a client to have a single SIP subscription to a list of users, allow a SIP client to have a single SIP subscription to a list of
where the list is maintained on a server. The server will obtain users, where the list is maintained on a server. The server will
presence for those users and report it back to the client. This obtain presence for those users and report it back to the SIP client.
application requires the server, called a Resource List Server (RLS), This application requires the server, called a Resource List Server
to have access to the list of presentities. This list needs to be (RLS), to have access to the list of presentities [RFC2778]. This
manipulated by clients so they can add and remove their friends as list needs to be manipulated by XCAP clients so they can add and
they desire. remove their friends as they desire.
Complexities arise when multiple clients attempt to simultaneously Complexities arise when multiple XCAP clients attempt to
manipulate a document, such as a presence list. Frequently, a client simultaneously manipulate a document, such as a presence list.
will keep a copy of the current list in memory, so it can render it Frequently, an XCAP client will keep a copy of the current list in
to users. However, if another client modifies the document, the memory, so it can render it to users. However, if another XCAP
cached version becomes stale. This modification event must be made client modifies the document, the cached version becomes stale. This
known to all clients which have cached copies of the document, so modification event must be made known to all clients which have
that they can fetch the most recent one. cached copies of the document, so that they can fetch the most recent
one.
To deal with this problem, clients can use a Session Initiation To deal with this problem, clients can use a Session Initiation
Protocol (SIP) [RFC3261] event package [RFC3265] to subscribe to Protocol (SIP) [RFC3261] event package [RFC3265] to subscribe to
change events in XCAP documents. This notification needs to indicate change events [I-D.ietf-sip-xcapevent] in XCAP documents. This
the specific resource that changed, and how it changed. One solution notification needs to indicate the specific resource that changed,
for the format of such a change notification would be a content and how it changed. One solution for the format of such a change
indirection object [RFC4483]. Though content indirection can tell a notification would be a content indirection object [RFC4483]. Though
client that a document has changed, it provides it with MIME content indirection can tell a client that a document has changed, it
Content-ID indicating the new version of the document. The MIME provides it with MIME Content-ID indicating the new version of the
Content-ID is not the same as the entity tag, which is used by XCAP document. The MIME Content-ID is not the same as the entity tag,
for document versioning. As such, a client cannot easily ascertain which is used by XCAP for document versioning. As such, a client
whether an indication of a change in a document is due to a change it cannot easily ascertain whether an indication of a change in a
just made, or due to a change another client made at around the same document is due to a change it just made, or due to a change another
time. Furthermore, content indirections don't indicate how a XCAP client made at around the same time. Furthermore, content
document changed; they would only be able to indicate that it did indirections don't indicate how a document changed; they would only
change. be able to indicate that it did change.
To resolve these problems, this document defines a data format which To resolve these problems, this document defines a data format which
can convey the fact that an XML document managed by XCAP has changed. can convey the fact that an XML document managed by XCAP has changed.
This data format is an XML document format, called an XCAP diff This data format is an XML document format, called an XCAP diff
document. This format can indicate that a document has changed, and document. This format reports which document has changed and its
provide its previous and new entity tags. It can also optionally former and new entity tags. It can report the differences between
include a set of patch operations [RFC5261], which indicate how to versions of the document, using an XML patch format [RFC5261], which
transform the document from the version prior to the change, to the indicate how to transform the locally cached XCAP document from the
version after it. XML element and attribute content of XCAP version prior to the change, to the version after it. Its intent is
documents can also be delivered with this format. to reduce the required overall bandwidth and the number of separate
transmissions. It can also report existing element and attribute
content when versions of an XML document change at an XCAP server.
XML documents that are equivalent for the purposes of many XML documents that are equivalent for the purposes of many
applications may differ in their physical representation. Similar to applications may differ in their physical representation. Similar to
XCAP, the canonical form with comments [W3C.REC-xml-c14n-20010315] of XCAP, the canonical form with comments [W3C.REC-xml-c14n-20010315] of
an XML document determines the logical equivalence when this format an XML document determines the logical equivalence when this format
is used to patch XML documents. is used to patch locally cached XCAP documents.
2. Terminology 2. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119 [RFC2119] and document are to be interpreted as described in RFC 2119 [RFC2119] and
indicate requirement levels for compliant implementations. indicate requirement levels for compliant implementations.
This specification also defines the following additional terms: This specification also defines the following additional terms:
Document: When the term document is used without the "XCAP diff" in Document: When the term document is used without the "(XCAP) diff"
front of it, it refers to the XCAP document resource about whom in front of it, it refers to the XCAP document resource about whom
the XCAP diff document is reporting a change. the XCAP diff document is reporting a change.
XCAP diff document: The XML document defined by this specification Diff document: The XML document defined by this specification that
that reports on a set of changes in an XCAP document resource. reports on a set of changes in an XCAP document resource. It is
delivered from a server to a diff client by a transport which is
not defined by this specification.
Server: Typically an XCAP server, this is a protocol entity that XCAP server: A protocol entity that manages XCAP documents and their
generates XCAP diff documents based on its knowledge of a set of entity tags. It usually contains an integrated diff notifier.
XCAP documents.
Client: Typically an XCAP client and SIP User Agent (UA), the client Diff notifier: This is the entity of a server which generates XCAP
consumes XCAP diff documents in order to reconstruct the document diff documents based on its knowledge of a set of XCAP documents
stored on the server. and their changes, and it transmits the generated diff documents
to a diff client within a session.
Diff client: A client which consumes XCAP diff documents in order to
construct a locally cached document that is equivalent to a
specific version of a document resource stored at an XCAP server.
It is typically a SIP User Agent (UA) and an XCAP client.
XCAP Client: A client which updates and retrieves documents stored
at an XCAP server. It can also patch element and attribute
content of XCAP documents located at an XCAP server.
Locally cached resource: A resource which has typically been
downloaded by HTTP from an XCAP server to a diff client. It may
have been patched locally by a diff client based on the XCAP diff
document information. It is equivalent to a single version in its
change history at an XCAP server. Version history of XCAP
documents is indicated by HTTP entity tags (ETag).
ETag: A strong HTTP entity tag whose value is set by an XCAP server.
Documents at an XCAP server are updated by XCAP clients. The XCAP
server assigns a new ETag value to each document version according
to the HTTP specification.
3. Structure of an XCAP Diff Document 3. Structure of an XCAP Diff Document
An XCAP diff document is an XML [W3C.REC-xml-20060816] document that An XCAP diff document is an XML [W3C.REC-xml-20060816] document that
MUST be well-formed and SHOULD be valid. XCAP diff documents MUST be MUST be well-formed and SHOULD be valid. XCAP diff documents MUST be
based on XML 1.0 and MUST be encoded using UTF-8. This specification based on XML 1.0 and MUST be encoded using UTF-8. This specification
makes use of XML namespaces for identifying XCAP diff documents and makes use of XML namespaces for identifying XCAP diff documents and
document fragments. The namespace URI for elements defined by this document fragments. The namespace URI for elements defined by this
specification is a URN [RFC2141], using the namespace identifier specification is a URN [RFC2141], using the namespace identifier
'ietf' defined by [RFC2648] and extended by [RFC3688]. This URN is: 'ietf' defined by [RFC2648] and extended by [RFC3688]. This URN is:
skipping to change at page 6, line 9 skipping to change at page 6, line 38
An XCAP diff document begins with the root element tag <xcap-diff>. An XCAP diff document begins with the root element tag <xcap-diff>.
This element has a single mandatory attribute, "xcap-root". The This element has a single mandatory attribute, "xcap-root". The
value of this attribute is the XCAP root URI for the documents in value of this attribute is the XCAP root URI for the documents in
which the changes have taken place. A single XCAP diff document can which the changes have taken place. A single XCAP diff document can
only represent changes in documents within the same XCAP root. The only represent changes in documents within the same XCAP root. The
content of the <xcap-diff> element is a sequence of <document>, content of the <xcap-diff> element is a sequence of <document>,
<element> and <attribute> elements followed by any number of elements <element> and <attribute> elements followed by any number of elements
from other namespaces for the purposes of extensibility. Wherever from other namespaces for the purposes of extensibility. Wherever
the XML schema (see Section 4) allows extension elements or the XML schema (see Section 4) allows extension elements or
attributes, any such unknown content MUST be ignored by the client. attributes, any such unknown content MUST be ignored by the diff
client.
Each <document> element specifies changes in a specific document Each <document> element specifies changes in a specific document
within the XCAP root. If several <document> elements pinpoint to the within the XCAP root. If several <document> elements pinpoint to the
same specific document, i.e. for example, the full ETag change same specific document, i.e., for example, the full entity tag (ETag)
history is indicated, the corresponding patches MUST be appliable in change history is indicated, the corresponding patches MUST be able
the given document order. to be applied in the given XCAP diff document order.
Note: This requirement simplifies applications that process XCAP
diff documents since there's no need to sort patch instructions
when applying them.
The <document> element has one mandatory attribute, "sel", and a two The <document> element has one mandatory attribute, "sel", and a two
optional attributes, "new-etag" and "previous-etag". The "sel" optional attributes, "new-etag" and "previous-etag". The "sel"
attribute of the <document> element identifies the specific document attribute of the <document> element identifies the specific document
within the XCAP root for which changes are indicated. Its content within the XCAP root for which changes are indicated. Its content
MUST be a relative path reference, with the base URI being equal to MUST be a relative path reference, with the base URI being equal to
the XCAP root URI. The "new-etag" attribute provides the entity tag the XCAP root URI. The "new-etag" attribute provides the entity tag
(ETag) for the document after the application of the changes, (ETag) for the document after the application of the changes,
assuming the document exists after those changes. The "previous- assuming the document exists after those changes. The "previous-
etag" attribute provides an identifier for the document instance etag" attribute provides an identifier for the document instance
prior to the change. If the change being reported is the removal of prior to the change. If the change being reported is the removal of
a document, the "previous-etag" MUST only be included and the "new- a document, only the "previous-etag" MUST be included and the "new-
etag" attribute will not be present. The "new-etag" attribute MUST etag" attribute MUST NOT be present. The "new-etag" attribute MUST
only exist alone when the document either exists or it was just only exist alone when the document either exists or it was just
created (no patch included). Both attributes are present when a created (no patch included). Both attributes are present when a
patch (or series of XCAP operations) has been applied to the patch (or series of XCAP operations) has been applied to the
resource. Also both attributes MAY be used to indicate an ETag resource. Also both attributes MAY be used to indicate an ETag
change without any document modifications (patches). change without any document modifications (patches).
The "previous-etag" and "new-etag" need not have been sequentially The "previous-etag" and "new-etag" need not have been sequentially
assigned ETags at the server. An XCAP diff document can indicate assigned ETags at the server. An XCAP diff document can indicate
changes that have occurred over a series of XCAP operations. The changes that have occurred over a series of XCAP operations. The
only requirement then is that, the sequence of events, when executed only requirement then is that, the sequence of events, when executed
skipping to change at page 7, line 4 skipping to change at page 7, line 38
operations that occurred at the server. operations that occurred at the server.
Each <document> element contains either a sequence of patching Each <document> element contains either a sequence of patching
instructions or an indication that the body hasn't semantically instructions or an indication that the body hasn't semantically
changed. The latter means that the document has been assigned a new changed. The latter means that the document has been assigned a new
ETag but its content is unchanged and it is indicated by the <body- ETag but its content is unchanged and it is indicated by the <body-
not-changed> element. Patching instructions are described by the not-changed> element. Patching instructions are described by the
<add>, <replace> and <remove> elements. These elements use the <add>, <replace> and <remove> elements. These elements use the
corresponding add, replace and remove types defined in [RFC5261], and corresponding add, replace and remove types defined in [RFC5261], and
define a set of patch operations that can be applied to transform the define a set of patch operations that can be applied to transform the
document. See [RFC5261] for instructions on how this transformation locally cached document. See [RFC5261] for instructions on how this
is effected. The <document> element can also contain elements from transformation is effected. The <document> element can also contain
other namespaces for the purposes of extensibility. The <add>, elements from other namespaces for the purposes of extensibility.
<replace> and <remove> elements allow extension attributes from any The <add>, <replace> and <remove> elements allow extension attributes
namespace. from any namespace.
Figure 1 shows <document> element content and how corresponding Figure 1 shows <document> element content and how the corresponding
resource or metadata changes. An external document retrieval means resource or metadata changes. An external document retrieval means
in practice HTTP GET requests for target resources. in practice HTTP GET requests for target resources. The asterisk
character '*' means that a <document> element has child element(s):
<add>, <replace> or <remove>, or alternatively only a <body-not-
changed> element. The hyphen character '-' means that the
corresponding content (attribute or element) doesn't exist in a
<document> element. The 'xxx' and 'yyy' are values of entity tags
(ETag) of an XCAP document.
+-----------+----------+-----------+----------+-------------------+ +-----------+----------+-----------+----------+-------------------+
| previous- | new- | <add> | <body- | XCAP resource/ | | previous- | new- | <add> | <body- | locally cached |
| etag | etag | <replace> | not- | metadata change | | etag | etag | <replace> | not- | XCAP resource/ |
| | | <remove> | changed> | | | | | <remove> | changed> | metadata change |
+-----------+----------+-----------+----------+-------------------+ +-----------+----------+-----------+----------+-------------------+
| xxx | yyy | * | - | resource patched, | | xxx | yyy | * | - | resource patched, |
| | | | | patch included | | | | | | patch included |
+-----------+----------+-----------+----------+-------------------+ +-----------+----------+-----------+----------+-------------------+
| xxx | yyy | - | - | resource patched, | | xxx | yyy | - | - | resource patched, |
| | | | | external document | | | | | | external document |
| | | | | retrieval | | | | | | retrieval |
+-----------+----------+-----------+----------+-------------------+ +-----------+----------+-----------+----------+-------------------+
| xxx | yyy | - | * | only ETag changed | | xxx | yyy | - | * | only ETag changed |
+-----------+----------+-----------+----------+-------------------+ +-----------+----------+-----------+----------+-------------------+
skipping to change at page 7, line 39 skipping to change at page 8, line 40
| | | | | or exists, | | | | | | or exists, |
| | | | | external document | | | | | | external document |
| | | | | retrieval | | | | | | retrieval |
+-----------+----------+-----------+----------+-------------------+ +-----------+----------+-----------+----------+-------------------+
| xxx | - | - | - | resource removed | | xxx | - | - | - | resource removed |
+-----------+----------+-----------+----------+-------------------+ +-----------+----------+-----------+----------+-------------------+
Figure 1: <document> element content / corresponding resource changes Figure 1: <document> element content / corresponding resource changes
Each <element> element indicates the existing element content of an Each <element> element indicates the existing element content of an
XCAP document. It has one mandatory attribute, "sel", and one XCAP document. It has one mandatory attribute, "sel", and
optional attribute, "exists". The "sel" attribute of the <element> optionally, an "exists" attribute and extension attributes from any
element identifies an XML element of an XCAP document. It is a namespace. The "sel" attribute of the <element> element identifies
percent endoced relative URI following XCAP conventions when an XML element of an XCAP document. It is a percent encoded relative
selecting elements. The XCAP Node Selector MUST always locate a URI following XCAP conventions when selecting elements. The XCAP
unique node, the "exists" attribute thus shows whether an element Node Selector MUST always locate a unique node, the "exists"
exists or not in the XCAP document. When the "exists" attribute is attribute thus shows whether an element exists or not in the XCAP
absent from the <element> element, the indicated element still exists document. When the "exists" attribute is absent from the <element>
in the XCAP document. The located result element exists as a child element, the indicated element still exists in the XCAP document.
element of the <element> element. It should be noted, that only the The located element exists as a child element of the <element>
full content of an element is shown if it exists, there are no element. In a corner case where the content of this element cannot
conventions for patching these elements. In a corner case where the be presented for some reason (e.g. too large payload), although it
content of this element cannot be presented for some reason, although exists in the XCAP document, the <element> element MUST NOT have any
it exists in the XCAP document, the <element> element MUST NOT have child nodes.
any child nodes.
As the result XML element is typically namespace qualified, all As the located XML element is typically namespace qualified, all
needed namespace declarations MUST exist within the <xml-diff> needed namespace declarations MUST exist within the <xml-diff>
document. The possible local namespace declarations within the document. The possible local namespace declarations within the
result element exist unmodified as in the source document, similar to located element exist unmodified as in the source document, similar
XCAP conventions. Other namespace references MUST be resolved from to XCAP conventions. Other namespace references MUST be resolved
the context of the <element> or its parent elements. The prefixes of from the context of the <element> or its parent elements. The
qualified names (QName) [W3C.REC-xml-names-20060816] of XML nodes prefixes of qualified names (QName) [W3C.REC-xml-names-20060816] of
also remain as they exist originally in the source XCAP document. XML nodes also remain as they exist originally in the source XCAP
document.
Each <attribute> element indicates the existing attribute content of Each <attribute> element indicates the existing attribute content of
an XCAP document. It has one mandatory attribute, "sel", and one an XCAP document. It has one mandatory attribute, "sel", and
optional attribute, "exists". The "sel" attribute of the <attribute> optionally, an "exists" attribute and extension attributes from any
element identifies an XML attribute of an XCAP document. It is a namespace. The "sel" attribute of the <attribute> element identifies
percent endoced relative URI following XCAP conventions when an XML attribute of an XCAP document. It is a percent encoded
selecting attributes. The "exists" attribute indicates whether an relative URI following XCAP conventions when selecting attributes.
attribute exists or not in the XCAP document. When the "exists" The "exists" attribute indicates whether an attribute exists or not
attribute is absent from the <attribute> element, the indicated in the XCAP document. When the "exists" attribute is absent from the
attribute still exists in the XCAP document. The child text node of <attribute> element, the indicated attribute still exists in the XCAP
the <attribute> element indicates the value of the located attribute. document. The child text node of the <attribute> element indicates
Note that if the attribute is namespace qualified, the query the value of the located attribute. Note that if the attribute is
parameter of the XCAP URI indicates the attached namespace URI and namespace qualified, the query parameter of the XCAP URI indicates
the prefix in the XCAP source document. the attached namespace URI and the prefix in the XCAP source
document.
Namespaces of the "sel" attribute of the <attribute> and <element> Namespaces of the "sel" attribute of the <attribute> and <element>
elements MUST also be resolved properly. The Section 6.4. of elements MUST also be resolved properly. The Section 6.4. of
[RFC4825] describes the rules when using namespace prefixes in XCAP [RFC4825] describes the rules when using namespace prefixes in XCAP
Node Selectors. Without a namespace prefix in an element selector, Node Selectors. Without a namespace prefix in an element selector,
an XCAP Default Document Namespace MUST be applied. The namespace an XCAP Default Document Namespace MUST be applied. The namespace
resolving rules of Patch operation elements: <add>, <replace> and resolving rules of Patch operation elements: <add>, <replace> and
<remove> are described in Section 4.2.1 of [RFC5261]. <remove> are described in Section 4.2.1 of [RFC5261].
4. XML Schema 4. XML Schema
skipping to change at page 10, line 33 skipping to change at page 11, line 33
<xs:complexType name="elementType"> <xs:complexType name="elementType">
<xs:complexContent mixed="true"> <xs:complexContent mixed="true">
<xs:restriction base="xs:anyType"> <xs:restriction base="xs:anyType">
<xs:sequence> <xs:sequence>
<xs:any processContents="lax" namespace="##any" <xs:any processContents="lax" namespace="##any"
minOccurs="0" maxOccurs="1"/> minOccurs="0" maxOccurs="1"/>
</xs:sequence> </xs:sequence>
<xs:attribute name="sel" type="xs:string" <xs:attribute name="sel" type="xs:string"
use="required"/> use="required"/>
<xs:attribute name="exists" type="xs:boolean"/> <xs:attribute name="exists" type="xs:boolean"/>
<xs:anyAttribute processContents="lax"/>
</xs:restriction> </xs:restriction>
</xs:complexContent> </xs:complexContent>
</xs:complexType> </xs:complexType>
<!-- xcap attribute type --> <!-- xcap attribute type -->
<xs:complexType name="attributeType"> <xs:complexType name="attributeType">
<xs:simpleContent> <xs:simpleContent>
<xs:extension base="xs:string"> <xs:extension base="xs:string">
<xs:attribute name="sel" type="xs:string" <xs:attribute name="sel" type="xs:string"
use="required"/> use="required"/>
<xs:attribute name="exists" type="xs:boolean"/> <xs:attribute name="exists" type="xs:boolean"/>
<xs:anyAttribute processContents="lax"/>
</xs:extension> </xs:extension>
</xs:simpleContent> </xs:simpleContent>
</xs:complexType> </xs:complexType>
<!-- empty type --> <!-- empty type -->
<xs:complexType name="emptyType"/> <xs:complexType name="emptyType"/>
</xs:schema> </xs:schema>
5. Example Document 5. Example Document
skipping to change at page 11, line 47 skipping to change at page 13, line 5
This indicates that the document with URI "http://xcap.example.com/ This indicates that the document with URI "http://xcap.example.com/
root/resource-lists/users/sip:joe@example.com/coworkers" has changed. root/resource-lists/users/sip:joe@example.com/coworkers" has changed.
Its previous entity tag is "8a77f8d" and its new one is "7ahggs" but Its previous entity tag is "8a77f8d" and its new one is "7ahggs" but
actual changes are not shown. The <service> element exists in the actual changes are not shown. The <service> element exists in the
rls-services "index" document and its full content is shown. Note rls-services "index" document and its full content is shown. Note
that the <service> element is attached with a default namespace that the <service> element is attached with a default namespace
declaration within the original document. Similarly, a "uri" declaration within the original document. Similarly, a "uri"
attribute content is shown from the same "index" document as an attribute content is shown from the same "index" document as an
illustrative example. illustrative example.
6. Security Considerations 6. Basic Requirements For a System Exchanging XCAP Diff Documents
XCAP diff documents can include changes from one document to another. Documents at an XCAP server are identified by URIs, and updated by
As a consequence, if the document itself is sensitive and requires XCAP clients with HTTP (PUT and DELETE) methods. The XCAP server
confidentiality, integrity or authentication, then the same applies assigns a new entity tag value for each document version. An entity
to the XCAP diff format. Therefore, protocols which transport XCAP tag value is defined by the Section 3.11 of RFC 2616 [RFC2616]: an
diff documents must provide sufficient security capabilities for entity tag MUST be unique across all versions of all entities
transporting the document itself. associated with a particular resource. These entity tags are used to
protect requests from making overriding changes when multiple XCAP
clients update the same XCAP document. An entity tag value can be
interpreted as a unique identifier to a specific version of an XCAP
document in its change history.
The entity tag values of XCAP resources enable also a reliable way to
update the locally cached XCAP resource copies in an XCAP diff
implementation. When a diff client applies XCAP diff document
changes, it MUST apply a resource state change only if entity tag
values match with octet-by-octet equivalence according to the table
defined in Figure 1. If a diff client notices inconsistencies and/or
errors when it applies reported resource changes, it SHOULD tear down
the session.
State changes of an XCAP document MUST be delivered reliably from a
diff notifier to a diff client, and a diff client MUST be able to
apply all changes of an XCAP document in the same chronological order
that occurred at an XCAP server. When using an unreliable transport
with retransmissions, the application protocol used with XCAP diff
MUST ensure that duplicates are dropped. If an XCAP diff delivery is
lost, the diff session MUST be torn down. Note that a diff notifier
can easily notice a lost notification when a diff client must respond
to each XCAP diff delivery.
A diff notifier doesn't necessarily report all of these XCAP document
updates with ETags, it MAY skip over some intermediate version of a
document, for example with rapidly changing resources. However, it
MUST always report changes consistently to a diff client so that it
can properly update the latest state (content and ETag) of its
locally cached resources.
As an example, an XCAP document is updated by different 'a', 'b'
and 'c' versions identified with the same corresponding ETag
values in a relatively short period. The first reported
notification contains the 'a' "new-tag" information (no "previous-
etag" attribute), and the diff notifier decides to skip the update
notification identified by the 'b' ETag value. The second
notification to a diff client MUST then contain the 'a' "previous-
etag" and 'c' "new-etag" values with optional corresponding
content changes (from version 'a' to 'c').
Since XCAP documents are typically confidential, diff notifiers MUST
obey the XCAP authorization rules. In practice, this means following
the read privilege rules of XCAP resources when notifying changes to
authenticated diff clients. Transport SHOULD be secured by
encryption.
Note: This format specification doesn't define how to select the
resources whose differences a diff notifier should report. It
also doesn't define whether actual content changes should be
reported. Typically however, a diff client starts a session by
sending a resource listing request. Then it compares the remote
resource listings with locally cached ones, and probably downloads
those resources which aren't locally cached, or whose entity tags
differ. When a diff client receives an XCAP diff with a
"previous-etag" value that matches its current cached copy of a
document, it can apply the diffs to the cached copy. As it takes
some time to download reference documents, and diff notifications
appear after actual resource state changes, several round-trips
may be needed before a full synchronization is achieved,
especially with rapidly changing resources.
7. Security Considerations
XCAP diff documents can include changes from one version of a
document to another version. As a consequence, if the document
itself is sensitive and requires confidentiality, integrity or
authentication, then the same applies to the XCAP diff format.
Therefore, protocols which transport XCAP diff documents must provide
sufficient security capabilities for transporting the document
itself. Confidential XCAP documents are typically transported using
TLS-encrypted [RFC5246] communication; see RFC 4825 [RFC4825] for
further security details.
When this format is used to report content changes of XCAP documents,
all security considerations of RFC 5261 [RFC5261] apply. Very
frequent updates of XCAP documents and/or many diff clients per
subscribed resource impose a Denial-of-Service attack possibility to
the servers processing XCAP diff documents. An efficient patch
processing and throttling can however, decrease the required overall
processings and transactions.
The SIP event package framework specified in RFC 3265 [RFC3265] is The SIP event package framework specified in RFC 3265 [RFC3265] is
the most typical use-case for this format. Then in general its the most typical use-case for this format. Then an end-to-end SIP
security considerations apply, but event packages MAY also have other encryption mechanism, such as S/MIME described in Section 26.2.4 of
RFC 3261 [RFC3261], SHOULD be used. If that is not available, it is
RECOMMENDED that TLS [RFC5246] be used between elements to provide
hop-by-hop authentication and encryption mechanisms described in
Section 26.2.2 "SIPS URI Scheme" and Section 26.3.2.2 "Interdomain
Requests" of RFC 3261 [RFC3261]. Event packages MAY also have other
specific threats which MUST be considered on an application-by- specific threats which MUST be considered on an application-by-
application basis. application basis.
7. IANA Considerations 8. IANA Considerations
There are several IANA considerations associated with this There are several IANA considerations associated with this
specification. specification.
7.1. application/xcap-diff+xml MIME Type 8.1. application/xcap-diff+xml MIME Type
MIME media type name: application MIME media type name: application
MIME subtype name: xcap-diff+xml MIME subtype name: xcap-diff+xml
Mandatory parameters: none Mandatory parameters: none
Optional parameters: Same as charset parameter application/xml as Optional parameters: Same as charset parameter application/xml as
specified in RFC 3023 [RFC3023]. specified in RFC 3023 [RFC3023].
Encoding considerations: Same as encoding considerations of Encoding considerations: Same as encoding considerations of
application/xml as specified in RFC 3023 [RFC3023]. application/xml as specified in RFC 3023 [RFC3023].
Security considerations: See Section 10 of RFC 3023 [RFC3023] and Security considerations: See Section 10 of RFC 3023 [RFC3023] and
Section 6 of RFCXXXX [[NOTE TO RFC-EDITOR/IANA: Please replace Section 7 of RFCXXXX [[NOTE TO RFC-EDITOR/IANA: Please replace
XXXX with the RFC number of this specification.]]. XXXX with the RFC number of this specification.]].
Interoperability considerations: none. Interoperability considerations: none.
Published specification: This document. Published specification: This document.
Applications which use this media type: This document type has Applications which use this media type: This document type has
been used to support manipulation of resource lists [RFC4826] been used to support manipulation of resource lists [RFC4826]
using XCAP. using XCAP.
skipping to change at page 13, line 10 skipping to change at page 16, line 4
been used to support manipulation of resource lists [RFC4826] been used to support manipulation of resource lists [RFC4826]
using XCAP. using XCAP.
Additional Information: Additional Information:
Magic Number: None Magic Number: None
File Extension: .xdf File Extension: .xdf
Macintosh file type code: "TEXT" Macintosh file type code: "TEXT"
Personal and email address for further information: Jonathan Personal and email address for further information: Jonathan
Rosenberg, jdrosen@jdrosen.net Rosenberg, jdrosen@jdrosen.net
Intended usage: COMMON Intended usage: COMMON
Author/Change controller: The IETF. Author/Change controller: The IETF.
7.2. URN Sub-Namespace Registration for 8.2. URN Sub-Namespace Registration for
urn:ietf:params:xml:ns:xcap-diff urn:ietf:params:xml:ns:xcap-diff
This section registers a new XML namespace, as per the guidelines in This section registers a new XML namespace, as per the guidelines in
[RFC3688] [RFC3688]
URI: The URI for this namespace is URI: The URI for this namespace is
urn:ietf:params:xml:ns:xcap-diff. urn:ietf:params:xml:ns:xcap-diff.
Registrant Contact: IETF, SIMPLE working group, (simple@ietf.org), Registrant Contact: IETF, SIMPLE working group, (simple@ietf.org),
Jonathan Rosenberg (jdrosen@jdrosen.net). Jonathan Rosenberg (jdrosen@jdrosen.net).
skipping to change at page 14, line 5 skipping to change at page 16, line 45
<body> <body>
<h1>Namespace for XCAP Diff</h1> <h1>Namespace for XCAP Diff</h1>
<h2>urn:ietf:params:xml:ns:xcap-diff</h2> <h2>urn:ietf:params:xml:ns:xcap-diff</h2>
<p>See <a href="[URL of published RFC]">RFCXXXX[[NOTE <p>See <a href="[URL of published RFC]">RFCXXXX[[NOTE
TO IANA/RFC-EDITOR: Please replace XXXX with the RFC number of this TO IANA/RFC-EDITOR: Please replace XXXX with the RFC number of this
specification.]]</a>.</p> specification.]]</a>.</p>
</body> </body>
</html> </html>
END END
7.3. Schema Registration 8.3. Schema Registration
This section registers a new XML schema per the procedures in This section registers a new XML schema per the procedures in
[RFC3688]. [RFC3688].
URI: urn:ietf:params:xml:schema:xcap-diff URI: urn:ietf:params:xml:schema:xcap-diff
Registrant Contact: IETF, SIMPLE working group, (simple@ietf.org), Registrant Contact: IETF, SIMPLE working group, (simple@ietf.org),
Jonathan Rosenberg (jdrosen@jdrosen.net). Jonathan Rosenberg (jdrosen@jdrosen.net).
The XML for this schema can be found as the sole content of The XML for this schema can be found as the sole content of
Section 4. Section 4.
8. Acknowledgments 9. Acknowledgments
The authors would like to thank Pavel Dostal, Jeroen van Bemmel, The authors would like to thank Pavel Dostal, Jeroen van Bemmel,
Martin Hynar, Anders Lindgren, Mary Barnes and Ben Campbell for their Martin Hynar, Anders Lindgren, Mary Barnes, Ben Campbell, Francis
valuable comments. Dupont, David Harrington, Alexey Melnikov, Dan Romascanu and Robert
Sparks for their valuable comments.
9. References 10. References
9.1. Normative References 10.1. Normative References
[W3C.REC-xml-20060816] [W3C.REC-xml-20060816]
Maler, E., Paoli, J., Bray, T., Yergeau, F., and C. Maler, E., Paoli, J., Bray, T., Yergeau, F., and C.
Sperberg-McQueen, "Extensible Markup Language (XML) 1.0 Sperberg-McQueen, "Extensible Markup Language (XML) 1.0
(Fourth Edition)", World Wide Web Consortium (Fourth Edition)", World Wide Web Consortium
Recommendation REC-xml-20060816, August 2006, Recommendation REC-xml-20060816, August 2006,
<http://www.w3.org/TR/2006/REC-xml-20060816>. <http://www.w3.org/TR/2006/REC-xml-20060816>.
[W3C.REC-xml-c14n-20010315] [W3C.REC-xml-c14n-20010315]
Boyer, J., "Canonical XML Version 1.0", World Wide Web Boyer, J., "Canonical XML Version 1.0", World Wide Web
skipping to change at page 14, line 50 skipping to change at page 17, line 46
[W3C.REC-xml-names-20060816] [W3C.REC-xml-names-20060816]
Hollander, D., Bray, T., Layman, A., and R. Tobin, Hollander, D., Bray, T., Layman, A., and R. Tobin,
"Namespaces in XML 1.0 (Second Edition)", World Wide Web "Namespaces in XML 1.0 (Second Edition)", World Wide Web
Consortium Recommendation REC-xml-names-20060816, Consortium Recommendation REC-xml-names-20060816,
August 2006, August 2006,
<http://www.w3.org/TR/2006/REC-xml-names-20060816>. <http://www.w3.org/TR/2006/REC-xml-names-20060816>.
[RFC2141] Moats, R., "URN Syntax", RFC 2141, May 1997. [RFC2141] Moats, R., "URN Syntax", RFC 2141, May 1997.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
[RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media
Types", RFC 3023, January 2001. Types", RFC 3023, January 2001.
[RFC2648] Moats, R., "A URN Namespace for IETF Documents", RFC 2648, [RFC2648] Moats, R., "A URN Namespace for IETF Documents", RFC 2648,
August 1999. August 1999.
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
January 2004. January 2004.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC4825] Rosenberg, J., "The Extensible Markup Language (XML) [RFC4825] Rosenberg, J., "The Extensible Markup Language (XML)
Configuration Access Protocol (XCAP)", RFC 4825, May 2007. Configuration Access Protocol (XCAP)", RFC 4825, May 2007.
[RFC5261] Urpalainen, J., "An Extensible Markup Language (XML) Patch [RFC5261] Urpalainen, J., "An Extensible Markup Language (XML) Patch
Operations Framework Utilizing XML Path Language (XPath) Operations Framework Utilizing XML Path Language (XPath)
Selectors", RFC 5261, September 2008. Selectors", RFC 5261, September 2008.
9.2. Informative References [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246, August 2008.
10.2. Informative References
[I-D.ietf-sip-xcapevent]
Urpalainen, J. and D. Willis, "An Extensible Markup
Language (XML) Configuration Access Protocol (XCAP) Diff
Event Package", draft-ietf-sip-xcapevent-08 (work in
progress), July 2009.
[RFC2778] Day, M., Rosenberg, J., and H. Sugano, "A Model for
Presence and Instant Messaging", RFC 2778, February 2000.
[RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston,
A., Peterson, J., Sparks, R., Handley, M., and E. A., Peterson, J., Sparks, R., Handley, M., and E.
Schooler, "SIP: Session Initiation Protocol", RFC 3261, Schooler, "SIP: Session Initiation Protocol", RFC 3261,
June 2002. June 2002.
[RFC3265] Roach, A., "Session Initiation Protocol (SIP)-Specific [RFC3265] Roach, A., "Session Initiation Protocol (SIP)-Specific
Event Notification", RFC 3265, June 2002. Event Notification", RFC 3265, June 2002.
[RFC4662] Roach, A., Campbell, B., and J. Rosenberg, "A Session [RFC4662] Roach, A., Campbell, B., and J. Rosenberg, "A Session
Initiation Protocol (SIP) Event Notification Extension for Initiation Protocol (SIP) Event Notification Extension for
Resource Lists", RFC 4662, August 2006. Resource Lists", RFC 4662, August 2006.
[RFC4826] Rosenberg, J., "Extensible Markup Language (XML) Formats [RFC4826] Rosenberg, J., "Extensible Markup Language (XML) Formats
for Representing Resource Lists", RFC 4826, May 2007. for Representing Resource Lists", RFC 4826, May 2007.
[RFC4483] Burger, E., "A Mechanism for Content Indirection in [RFC4483] Burger, E., "A Mechanism for Content Indirection in
Session Initiation Protocol (SIP) Messages", RFC 4483, Session Initiation Protocol (SIP) Messages", RFC 4483,
May 2006. May 2006.
Appendix A. Informative Examples
These informative examples illustrate basic features of XCAP diff
format.
The following documents exist at an XCAP server (xcap.example.com)
with an imaginary "tests" application usage (there's no default
document namespace defined in this imaginary application usage).
http://xcap.example.com/tests/users/sip:joe@example.com/index:
<?xml version="1.0" encoding="UTF-8"?>
<doc id="bar">
<note>This is a sample document</note>
</doc>
and then
http://xcap.example.com/tests/users/sip:john@example.com/index:
<?xml version="1.0" encoding="UTF-8"?>
<doc>
<note>This is another sample document</note>
</doc>
A.1. Indicating Existing, Changed or Removed Documents
Firstly, an XCAP diff document can indicate what documents exist in a
collection. An XCAP diff document may then be:
<?xml version="1.0" encoding="UTF-8"?>
<xcap-diff xmlns="urn:ietf:params:xml:ns:xcap-diff"
xcap-root="http://xcap.example.com/">
<document new-etag="7ahggs"
sel="tests/users/sip:joe@example.com/index"/>
<document new-etag="terteer"
sel="tests/users/sip:john@example.com/index"/>
</xcap-diff>
This listing indicates current ETags of existing documents and their
relative URIs.
Let's say that Joe adds a new document to his collection:
PUT /tests/users/sip:joe@example.com/another_document HTTP/1.1
Host: xcap.example.com
....
Content-Type: application/xml
Content-Length: [XXX]
<?xml version="1.0" encoding="UTF-8"?>
<doc>
<note>This is another sample document</note>
</doc>
The requests result header has an HTTP ETag "terteer" for this new
document.
Then an XCAP diff document may then indicate only the creation of
this single new document:
<?xml version="1.0" encoding="UTF-8"?>
<xcap-diff xmlns="urn:ietf:params:xml:ns:xcap-diff"
xcap-root="http://xcap.example.com/">
<document new-etag="terteer"
sel="tests/users/sip:joe@example.com/another_document"/>
</xcap-diff>
A "new-etag" without a "previous-etag" attribute indicates a creation
of a new document.
Then Joe decides to modify an existing resource:
PUT /tests/users/sip:joe@example.com/another_document HTTP/1.1
Host: xcap.example.com
....
Content-Type: application/xml
Content-Length: [XXX]
<?xml version="1.0" encoding="UTF-8"?>
<doc>
<note>This is a modified document</note>
</doc>
The reported new HTTP ETag is "huwiias".
Then an XCAP diff document may be:
<?xml version="1.0" encoding="UTF-8"?>
<xcap-diff xmlns="urn:ietf:params:xml:ns:xcap-diff"
xcap-root="http://xcap.example.com/">
<document previous-etag="terteer" new-etag="huwiias"
sel="tests/users/sip:joe@example.com/another_document"/>
</xcap-diff>
Both "previous-etag" and "new-etag" attributes signal that a
modification has happened to a resource, but actual changes are not
shown.
Let's say that Joe then removes a document from his collection:
DELETE /tests/users/sip:joe@example.com/another_document HTTP/1.1
Host: xcap.example.com
This HTTP DELETE request results in the unlinking of the resource,
and the XCAP diff may be:
<?xml version="1.0" encoding="UTF-8"?>
<xcap-diff xmlns="urn:ietf:params:xml:ns:xcap-diff"
xcap-root="http://xcap.example.com/">
<document previous-etag="huwiias"
sel="tests/users/sip:joe@example.com/another_document"/>
</xcap-diff>
Thus a "previous-etag" without "new-etag" attribute indicates the
removal of a resource.
A.2. Indicating Actual Changes of Documents
Secondly, XCAP diff documents are capable of showing actual changes
to documents with [RFC5261] patching semantics.
Now Joe's XCAP client utilizes XCAP patching capability to add a new
element to a document:
PUT /tests/users/sip:joe@example.com/index/~~/doc/foo HTTP/1.1
Host: xcap.example.com
....
Content-Type: application/xcap-el+xml
Content-Length: [XXX]
<foo>this is a new element</foo>
Since the insertion of the element is successful, Joe's XCAP client
receives the new HTTP ETag "fgherhryt3" of the updated "index"
document.
Immediately thereafter, Joe's XCAP client issues another HTTP request
(this request could even be pipe-lined):
PUT /tests/users/sip:joe@example.com/index/~~/doc/bar HTTP/1.1
Host: xcap.example.com
....
Content-Type: application/xcap-el+xml
Content-Length: [XXX]
<bar>this is a bar element
</bar>
The reported new HTTP ETag of "index" is now "dgdgdfgrrr".
And then Joe's XCAP client issues yet another HTTP request:
PUT /tests/users/sip:joe@example.com/index/~~/doc/foobar HTTP/1.1
Host: xcap.example.com
....
Content-Type: application/xcap-el+xml
Content-Length: [XXX]
<foobar>this is a foobar element</foobar>
The reported new ETag of "index" is now "63hjjsll".
XCAP diff format document may then indicate these XCAP Component
changes by:
<?xml version="1.0" encoding="UTF-8"?>
<d:xcap-diff xmlns:d="urn:ietf:params:xml:ns:xcap-diff"
xcap-root="http://xcap.example.com/">
<d:document previous-etag="7ahggs3"
sel="tests/users/sip:joe@example.com/index"
new-etag="63hjjsll">
<d:add sel="*"
><foo>this is a new element</foo><bar>this is a bar element
</bar><foobar>this is a foobar element</foobar></d:add>
</d:document>
</d:xcap-diff>
Note how several XCAP component modifications were aggregated
together, and full history information got lost.
Alternatively, the content could have been:
<?xml version="1.0" encoding="UTF-8"?>
<d:xcap-diff xmlns:d="urn:ietf:params:xml:ns:xcap-diff"
xcap-root="http://xcap.example.com/">
<d:document previous-etag="7ahggs"
sel="tests/users/sip:joe@example.com/index"
new-etag="fgherhryt3">
<d:add sel="*"
><foo>this is a new element</foo></d:add></d:document>
<d:document previous-etag="fgherhryt3"
sel="tests/users/sip:joe@example.com/index"
new-etag="dgdgdfgrrr">
<d:add sel="*"
><bar>this is a bar element
</bar></d:add></d:document>
<d:document previous-etag="dgdgdfgrrr"
sel="tests/users/sip:joe@example.com/index"
new-etag="63hjjsll">
<d:add sel="*"
><foobar>this is a foobar element</foobar></d:add></d:document>
</d:xcap-diff>
This shows the full ETag change history of a document, and ETags
change chronologically in the reported XML document order.
A.3. Indicating XCAP Component Contents
Lastly, the XCAP diff format can also indicate the existing full
contents of XCAP Components, i.e. elements or attributes:
<?xml version="1.0" encoding="UTF-8"?>
<d:xcap-diff xmlns:d="urn:ietf:params:xml:ns:xcap-diff"
xcap-root="http://xcap.example.com/">
<d:attribute sel="tests/users/sip:joe@example.com/index/~~/doc/@id"
>bar</d:attribute>
<d:element sel="tests/users/sip:joe@example.com/index/~~/*/foo"
><foo>this is a new element</foo></d:element>
</d:xcap-diff>
Note that the HTTP ETag value of the new document is not shown as it
is irrelevant for this use-case.
Then Joe's XCAP client removes the "id" attribute:
DELETE /tests/users/sip:joe@example.com/index/~~/doc/@id HTTP/1.1
Host: xcap.example.com
....
Content-Length: 0
And the XCAP diff document may then be:
<?xml version="1.0" encoding="UTF-8"?>
<xcap-diff xmlns="urn:ietf:params:xml:ns:xcap-diff"
xcap-root="http://xcap.example.com/">
<attribute sel="tests/users/sip:joe@example.com/index/~~/doc/@id"
exists="0"/>
</xcap-diff>
This indicates that the subscribed attribute was removed from the
document. The element content in this use-case may be discarded from
the XCAP diff document, for example when the size of XCAP diff
document would be impractically large to the transport layer.
Authors' Addresses Authors' Addresses
Jonathan Rosenberg Jonathan Rosenberg
Cisco Cisco
Edison, NJ Edison, NJ
US USA
Email: jdrosen@cisco.com Email: jdrosen@cisco.com
URI: http://www.jdrosen.net URI: http://www.jdrosen.net
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
Email: jari.urpalainen@nokia.com Email: jari.urpalainen@nokia.com
 End of changes. 49 change blocks. 
165 lines changed or deleted 580 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/