| < 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/ | ||||