idnits 2.17.1 draft-ietf-simple-xcap-diff-14.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Sep 2009 rather than the newer Notice from 28 Dec 2009. (See https://trustee.ietf.org/license-info/) Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document seems to contain a disclaimer for pre-RFC5378 work, and may have content which was first submitted before 10 November 2008. The disclaimer is necessary when there are original authors that you have been unable to contact, or if some do not wish to grant the BCP78 rights to the IETF Trust. If you are able to get all authors (current and original) to grant those rights, you can and should remove the disclaimer; otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (February 1, 2010) is 5169 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'XXX' is mentioned on line 960, but not defined ** Obsolete normative reference: RFC 2141 (Obsoleted by RFC 8141) ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 3023 (Obsoleted by RFC 7303) ** Downref: Normative reference to an Informational RFC: RFC 2648 ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) -- Obsolete informational reference (is this intentional?): RFC 3265 (Obsoleted by RFC 6665) Summary: 6 errors (**), 0 flaws (~~), 2 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 SIMPLE J. Rosenberg 3 Internet-Draft Cisco 4 Intended status: Standards Track J. Urpalainen 5 Expires: August 5, 2010 Nokia 6 February 1, 2010 8 An Extensible Markup Language (XML) Document Format for Indicating A 9 Change in XML Configuration Access Protocol (XCAP) Resources 10 draft-ietf-simple-xcap-diff-14 12 Abstract 14 This specification defines a document format that can be used to 15 indicate that a change has occurred in a document managed by the 16 Extensible Markup Language (XML) Configuration Access Protocol 17 (XCAP). This format reports which document has changed and its 18 former and new entity tags. It can report the differences between 19 versions of the document, using an XML patch format. It can report 20 existing element and attribute content when versions of an XCAP 21 server document change. XCAP diff documents can be delivered to diff 22 clients using a number of means, including a Session Initiation 23 Protocol (SIP) event package. 25 Status of this Memo 27 This Internet-Draft is submitted to IETF in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF), its areas, and its working groups. Note that 32 other groups may also distribute working documents as Internet- 33 Drafts. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 The list of current Internet-Drafts can be accessed at 41 http://www.ietf.org/ietf/1id-abstracts.txt. 43 The list of Internet-Draft Shadow Directories can be accessed at 44 http://www.ietf.org/shadow.html. 46 This Internet-Draft will expire on August 5, 2010. 48 Copyright Notice 49 Copyright (c) 2010 IETF Trust and the persons identified as the 50 document authors. All rights reserved. 52 This document is subject to BCP 78 and the IETF Trust's Legal 53 Provisions Relating to IETF Documents 54 (http://trustee.ietf.org/license-info) in effect on the date of 55 publication of this document. Please review these documents 56 carefully, as they describe your rights and restrictions with respect 57 to this document. Code Components extracted from this document must 58 include Simplified BSD License text as described in Section 4.e of 59 the Trust Legal Provisions and are provided without warranty as 60 described in the BSD License. 62 This document may contain material from IETF Documents or IETF 63 Contributions published or made publicly available before November 64 10, 2008. The person(s) controlling the copyright in some of this 65 material may not have granted the IETF Trust the right to allow 66 modifications of such material outside the IETF Standards Process. 67 Without obtaining an adequate license from the person(s) controlling 68 the copyright in such materials, this document may not be modified 69 outside the IETF Standards Process, and derivative works of it may 70 not be created outside the IETF Standards Process, except to format 71 it for publication as an RFC or to translate it into languages other 72 than English. 74 Table of Contents 76 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 77 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 78 3. Structure of an XCAP Diff Document . . . . . . . . . . . . . . 6 79 4. XML Schema . . . . . . . . . . . . . . . . . . . . . . . . . . 9 80 5. Example Document . . . . . . . . . . . . . . . . . . . . . . . 12 81 6. Basic Requirements For a System Exchanging XCAP Diff 82 Documents . . . . . . . . . . . . . . . . . . . . . . . . . . 13 83 7. Security Considerations . . . . . . . . . . . . . . . . . . . 14 84 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 85 8.1. application/xcap-diff+xml MIME Type . . . . . . . . . . . 15 86 8.2. URN Sub-Namespace Registration for 87 urn:ietf:params:xml:ns:xcap-diff . . . . . . . . . . . . . 16 88 8.3. Schema Registration . . . . . . . . . . . . . . . . . . . 16 89 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 17 90 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 17 91 10.1. Normative References . . . . . . . . . . . . . . . . . . . 17 92 10.2. Informative References . . . . . . . . . . . . . . . . . . 18 93 Appendix A. Informative Examples . . . . . . . . . . . . . . . . 19 94 A.1. Indicating Existing, Changed or Removed Documents . . . . 19 95 A.2. Indicating Actual Changes of Documents . . . . . . . . . . 22 96 A.3. Indicating XCAP Component Contents . . . . . . . . . . . . 24 97 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 25 99 1. Introduction 101 The Extensible Markup Language (XML) Configuration Access Protocol 102 (XCAP) [RFC4825] is a protocol that allows XCAP clients to manipulate 103 XML documents stored on a server. These XML documents serve as 104 configuration information for application protocols. As an example, 105 resource list [RFC4662] subscriptions (also known as presence lists) 106 allow a SIP client to have a single SIP subscription to a list of 107 users, where the list is maintained on a server. The server will 108 obtain presence for those users and report it back to the SIP client. 109 This application requires the server, called a Resource List Server 110 (RLS), to have access to the list of presentities [RFC2778]. This 111 list needs to be manipulated by XCAP clients so they can add and 112 remove their friends as they desire. 114 Complexities arise when multiple XCAP clients attempt to 115 simultaneously manipulate a document, such as a presence list. 116 Frequently, an XCAP client will keep a copy of the current list in 117 memory, so it can render it to users. However, if another XCAP 118 client modifies the document, the cached version becomes stale. This 119 modification event must be made known to all clients which have 120 cached copies of the document, so that they can fetch the most recent 121 one. 123 To deal with this problem, clients can use a Session Initiation 124 Protocol (SIP) [RFC3261] event package [RFC3265] to subscribe to 125 change events [I-D.ietf-sip-xcapevent] in XCAP documents. This 126 notification needs to indicate the specific resource that changed, 127 and how it changed. One solution for the format of such a change 128 notification would be a content indirection object [RFC4483]. Though 129 content indirection can tell a client that a document has changed, it 130 provides it with MIME Content-ID indicating the new version of the 131 document. The MIME Content-ID is not the same as the entity tag, 132 which is used by XCAP for document versioning. As such, a client 133 cannot easily ascertain whether an indication of a change in a 134 document is due to a change it just made, or due to a change another 135 XCAP client made at around the same time. Furthermore, content 136 indirections don't indicate how a document changed; they would only 137 be able to indicate that it did change. 139 To resolve these problems, this document defines a data format which 140 can convey the fact that an XML document managed by XCAP has changed. 141 This data format is an XML document format, called an XCAP diff 142 document. This format reports which document has changed and its 143 former and new entity tags. It can report the differences between 144 versions of the document, using an XML patch format [RFC5261], which 145 indicate how to transform the locally cached XCAP document from the 146 version prior to the change, to the version after it. Its intent is 147 to reduce the required overall bandwidth and the number of separate 148 transmissions. It can also report existing element and attribute 149 content when versions of an XML document change at an XCAP server. 151 XML documents that are equivalent for the purposes of many 152 applications may differ in their physical representation. Similar to 153 XCAP, the canonical form with comments [W3C.REC-xml-c14n-20010315] of 154 an XML document determines the logical equivalence when this format 155 is used to patch locally cached XCAP documents. 157 2. Terminology 159 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 160 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 161 document are to be interpreted as described in RFC 2119 [RFC2119] and 162 indicate requirement levels for compliant implementations. 164 This specification also defines the following additional terms: 166 Document: When the term document is used without the "(XCAP) diff" 167 in front of it, it refers to the XCAP document resource about whom 168 the XCAP diff document is reporting a change. 170 Diff document: The XML document defined by this specification that 171 reports on a set of changes in an XCAP document resource. It is 172 delivered from a server to a diff client by a transport which is 173 not defined by this specification. 175 XCAP server: A protocol entity that manages XCAP documents and their 176 entity tags. It usually contains an integrated diff notifier. 178 Diff notifier: This is the entity of a server which generates XCAP 179 diff documents based on its knowledge of a set of XCAP documents 180 and their changes, and it transmits the generated diff documents 181 to a diff client within a session. 183 Diff client: A client which consumes XCAP diff documents in order to 184 construct a locally cached document that is equivalent to a 185 specific version of a document resource stored at an XCAP server. 186 It is typically a SIP User Agent (UA) and an XCAP client. 188 XCAP Client: A client which updates and retrieves documents stored 189 at an XCAP server. It can also patch element and attribute 190 content of XCAP documents located at an XCAP server. 192 Locally cached resource: A resource which has typically been 193 downloaded by HTTP from an XCAP server to a diff client. It may 194 have been patched locally by a diff client based on the XCAP diff 195 document information. It is equivalent to a single version in its 196 change history at an XCAP server. Version history of XCAP 197 documents is indicated by HTTP entity tags (ETag). 199 ETag: A strong HTTP entity tag whose value is set by an XCAP server. 200 Documents at an XCAP server are updated by XCAP clients. The XCAP 201 server assigns a new ETag value to each document version according 202 to the HTTP specification. 204 3. Structure of an XCAP Diff Document 206 An XCAP diff document is an XML [W3C.REC-xml-20060816] document that 207 MUST be well-formed and SHOULD be valid. XCAP diff documents MUST be 208 based on XML 1.0 and MUST be encoded using UTF-8. This specification 209 makes use of XML namespaces for identifying XCAP diff documents and 210 document fragments. The namespace URI for elements defined by this 211 specification is a URN [RFC2141], using the namespace identifier 212 'ietf' defined by [RFC2648] and extended by [RFC3688]. This URN is: 214 urn:ietf:params:xml:ns:xcap-diff 216 An XCAP diff document begins with the root element tag . 217 This element has a single mandatory attribute, "xcap-root". The 218 value of this attribute is the XCAP root URI for the documents in 219 which the changes have taken place. A single XCAP diff document can 220 only represent changes in documents within the same XCAP root. The 221 content of the element is a sequence of , 222 and elements followed by any number of elements 223 from other namespaces for the purposes of extensibility. Wherever 224 the XML schema (see Section 4) allows extension elements or 225 attributes, any such unknown content MUST be ignored by the diff 226 client. 228 Each element specifies changes in a specific document 229 within the XCAP root. If several elements pinpoint to the 230 same specific document, i.e., for example, the full entity tag (ETag) 231 change history is indicated, the corresponding patches MUST be able 232 to be applied in the given XCAP diff document order. 234 Note: This requirement simplifies applications that process XCAP 235 diff documents since there's no need to sort patch instructions 236 when applying them. 238 The element has one mandatory attribute, "sel", and a two 239 optional attributes, "new-etag" and "previous-etag". The "sel" 240 attribute of the element identifies the specific document 241 within the XCAP root for which changes are indicated. Its content 242 MUST be a relative path reference, with the base URI being equal to 243 the XCAP root URI. The "new-etag" attribute provides the entity tag 244 (ETag) for the document after the application of the changes, 245 assuming the document exists after those changes. The "previous- 246 etag" attribute provides an identifier for the document instance 247 prior to the change. If the change being reported is the removal of 248 a document, only the "previous-etag" MUST be included and the "new- 249 etag" attribute MUST NOT be present. The "new-etag" attribute MUST 250 only exist alone when the document either exists or it was just 251 created (no patch included). Both attributes are present when a 252 patch (or series of XCAP operations) has been applied to the 253 resource. Also both attributes MAY be used to indicate an ETag 254 change without any document modifications (patches). 256 The "previous-etag" and "new-etag" need not have been sequentially 257 assigned ETags at the server. An XCAP diff document can indicate 258 changes that have occurred over a series of XCAP operations. The 259 only requirement then is that, the sequence of events, when executed 260 serially, will result in the transformation of the document with the 261 ETag "previous-etag" to the one whose ETag is "new-etag". Also the 262 series of operations do not have to be the same exact series of 263 operations that occurred at the server. 265 Each element contains either a sequence of patching 266 instructions or an indication that the body hasn't semantically 267 changed. The latter means that the document has been assigned a new 268 ETag but its content is unchanged and it is indicated by the element. Patching instructions are described by the 270 , and elements. These elements use the 271 corresponding add, replace and remove types defined in [RFC5261], and 272 define a set of patch operations that can be applied to transform the 273 locally cached document. See [RFC5261] for instructions on how this 274 transformation is effected. The element can also contain 275 elements from other namespaces for the purposes of extensibility. 276 The , and elements allow extension attributes 277 from any namespace. 279 Figure 1 shows element content and how the corresponding 280 resource or metadata changes. An external document retrieval means 281 in practice HTTP GET requests for target resources. The asterisk 282 character '*' means that a element has child element(s): 283 , or , or alternatively only a element. The hyphen character '-' means that the 285 corresponding content (attribute or element) doesn't exist in a 286 element. The 'xxx' and 'yyy' are values of entity tags 287 (ETag) of an XCAP document. 289 +-----------+----------+-----------+----------+-------------------+ 290 | previous- | new- | | | not- | XCAP resource/ | 292 | | | | changed> | metadata change | 293 +-----------+----------+-----------+----------+-------------------+ 294 | xxx | yyy | * | - | resource patched, | 295 | | | | | patch included | 296 +-----------+----------+-----------+----------+-------------------+ 297 | xxx | yyy | - | - | resource patched, | 298 | | | | | external document | 299 | | | | | retrieval | 300 +-----------+----------+-----------+----------+-------------------+ 301 | xxx | yyy | - | * | only ETag changed | 302 +-----------+----------+-----------+----------+-------------------+ 303 | - | yyy | - | - | resource created | 304 | | | | | or exists, | 305 | | | | | external document | 306 | | | | | retrieval | 307 +-----------+----------+-----------+----------+-------------------+ 308 | xxx | - | - | - | resource removed | 309 +-----------+----------+-----------+----------+-------------------+ 311 Figure 1: element content / corresponding resource changes 313 Each element indicates the existing element content of an 314 XCAP document. It has one mandatory attribute, "sel", and 315 optionally, an "exists" attribute and extension attributes from any 316 namespace. The "sel" attribute of the element identifies 317 an XML element of an XCAP document. It is a percent encoded relative 318 URI following XCAP conventions when selecting elements. The XCAP 319 Node Selector MUST always locate a unique node, the "exists" 320 attribute thus shows whether an element exists or not in the XCAP 321 document. When the "exists" attribute is absent from the 322 element, the indicated element still exists in the XCAP document. 323 The located element exists as a child element of the 324 element. In a corner case where the content of this element cannot 325 be presented for some reason (e.g. too large payload), although it 326 exists in the XCAP document, the element MUST NOT have any 327 child nodes. 329 As the located XML element is typically namespace qualified, all 330 needed namespace declarations MUST exist within the 331 document. The possible local namespace declarations within the 332 located element exist unmodified as in the source document, similar 333 to XCAP conventions. Other namespace references MUST be resolved 334 from the context of the or its parent elements. The 335 prefixes of qualified names (QName) [W3C.REC-xml-names-20060816] of 336 XML nodes also remain as they exist originally in the source XCAP 337 document. 339 Each element indicates the existing attribute content of 340 an XCAP document. It has one mandatory attribute, "sel", and 341 optionally, an "exists" attribute and extension attributes from any 342 namespace. The "sel" attribute of the element identifies 343 an XML attribute of an XCAP document. It is a percent encoded 344 relative URI following XCAP conventions when selecting attributes. 345 The "exists" attribute indicates whether an attribute exists or not 346 in the XCAP document. When the "exists" attribute is absent from the 347 element, the indicated attribute still exists in the XCAP 348 document. The child text node of the element indicates 349 the value of the located attribute. Note that if the attribute is 350 namespace qualified, the query parameter of the XCAP URI indicates 351 the attached namespace URI and the prefix in the XCAP source 352 document. 354 Namespaces of the "sel" attribute of the and 355 elements MUST also be resolved properly. The Section 6.4. of 356 [RFC4825] describes the rules when using namespace prefixes in XCAP 357 Node Selectors. Without a namespace prefix in an element selector, 358 an XCAP Default Document Namespace MUST be applied. The namespace 359 resolving rules of Patch operation elements: , and 360 are described in Section 4.2.1 of [RFC5261]. 362 4. XML Schema 364 The XML Schema for the XCAP diff format. 366 367 372 373 376 377 378 379 380 381 382 383 384 385 386 387 389 390 391 392 393 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 438 439 440 441 442 443 445 446 448 449 450 451 452 454 455 456 457 458 460 461 462 463 464 466 467 469 471 5. Example Document 473 The following is an example of a document compliant to the schema. 475 476 480 484 488 489 490 491 492 493 presence 494 495 497 sip:marketing@example.com 501 503 This indicates that the document with URI "http://xcap.example.com/ 504 root/resource-lists/users/sip:joe@example.com/coworkers" has changed. 505 Its previous entity tag is "8a77f8d" and its new one is "7ahggs" but 506 actual changes are not shown. The element exists in the 507 rls-services "index" document and its full content is shown. Note 508 that the element is attached with a default namespace 509 declaration within the original document. Similarly, a "uri" 510 attribute content is shown from the same "index" document as an 511 illustrative example. 513 6. Basic Requirements For a System Exchanging XCAP Diff Documents 515 Documents at an XCAP server are identified by URIs, and updated by 516 XCAP clients with HTTP (PUT and DELETE) methods. The XCAP server 517 assigns a new entity tag value for each document version. An entity 518 tag value is defined by the Section 3.11 of RFC 2616 [RFC2616]: an 519 entity tag MUST be unique across all versions of all entities 520 associated with a particular resource. These entity tags are used to 521 protect requests from making overriding changes when multiple XCAP 522 clients update the same XCAP document. An entity tag value can be 523 interpreted as a unique identifier to a specific version of an XCAP 524 document in its change history. 526 The entity tag values of XCAP resources enable also a reliable way to 527 update the locally cached XCAP resource copies in an XCAP diff 528 implementation. When a diff client applies XCAP diff document 529 changes, it MUST apply a resource state change only if entity tag 530 values match with octet-by-octet equivalence according to the table 531 defined in Figure 1. If a diff client notices inconsistencies and/or 532 errors when it applies reported resource changes, it SHOULD tear down 533 the session. 535 State changes of an XCAP document MUST be delivered reliably from a 536 diff notifier to a diff client, and a diff client MUST be able to 537 apply all changes of an XCAP document in the same chronological order 538 that occurred at an XCAP server. When using an unreliable transport 539 with retransmissions, the application protocol used with XCAP diff 540 MUST ensure that duplicates are dropped. If an XCAP diff delivery is 541 lost, the diff session MUST be torn down. Note that a diff notifier 542 can easily notice a lost notification when a diff client must respond 543 to each XCAP diff delivery. 545 A diff notifier doesn't necessarily report all of these XCAP document 546 updates with ETags, it MAY skip over some intermediate version of a 547 document, for example with rapidly changing resources. However, it 548 MUST always report changes consistently to a diff client so that it 549 can properly update the latest state (content and ETag) of its 550 locally cached resources. 552 As an example, an XCAP document is updated by different 'a', 'b' 553 and 'c' versions identified with the same corresponding ETag 554 values in a relatively short period. The first reported 555 notification contains the 'a' "new-tag" information (no "previous- 556 etag" attribute), and the diff notifier decides to skip the update 557 notification identified by the 'b' ETag value. The second 558 notification to a diff client MUST then contain the 'a' "previous- 559 etag" and 'c' "new-etag" values with optional corresponding 560 content changes (from version 'a' to 'c'). 562 Since XCAP documents are typically confidential, diff notifiers MUST 563 obey the XCAP authorization rules. In practice, this means following 564 the read privilege rules of XCAP resources when notifying changes to 565 authenticated diff clients. Transport SHOULD be secured by 566 encryption. 568 Note: This format specification doesn't define how to select the 569 resources whose differences a diff notifier should report. It 570 also doesn't define whether actual content changes should be 571 reported. Typically however, a diff client starts a session by 572 sending a resource listing request. Then it compares the remote 573 resource listings with locally cached ones, and probably downloads 574 those resources which aren't locally cached, or whose entity tags 575 differ. When a diff client receives an XCAP diff with a 576 "previous-etag" value that matches its current cached copy of a 577 document, it can apply the diffs to the cached copy. As it takes 578 some time to download reference documents, and diff notifications 579 appear after actual resource state changes, several round-trips 580 may be needed before a full synchronization is achieved, 581 especially with rapidly changing resources. 583 7. Security Considerations 585 XCAP diff documents can include changes from one version of a 586 document to another version. As a consequence, if the document 587 itself is sensitive and requires confidentiality, integrity or 588 authentication, then the same applies to the XCAP diff format. 589 Therefore, protocols which transport XCAP diff documents must provide 590 sufficient security capabilities for transporting the document 591 itself. Confidential XCAP documents are typically transported using 592 TLS-encrypted [RFC5246] communication; see RFC 4825 [RFC4825] for 593 further security details. 595 When this format is used to report content changes of XCAP documents, 596 all security considerations of RFC 5261 [RFC5261] apply. Very 597 frequent updates of XCAP documents and/or many diff clients per 598 subscribed resource impose a Denial-of-Service attack possibility to 599 the servers processing XCAP diff documents. An efficient patch 600 processing and throttling can however, decrease the required overall 601 processings and transactions. 603 The SIP event package framework specified in RFC 3265 [RFC3265] is 604 the most typical use-case for this format. Then an end-to-end SIP 605 encryption mechanism, such as S/MIME described in Section 26.2.4 of 606 RFC 3261 [RFC3261], SHOULD be used. If that is not available, it is 607 RECOMMENDED that TLS [RFC5246] be used between elements to provide 608 hop-by-hop authentication and encryption mechanisms described in 609 Section 26.2.2 "SIPS URI Scheme" and Section 26.3.2.2 "Interdomain 610 Requests" of RFC 3261 [RFC3261]. Event packages MAY also have other 611 specific threats which MUST be considered on an application-by- 612 application basis. 614 8. IANA Considerations 616 There are several IANA considerations associated with this 617 specification. 619 8.1. application/xcap-diff+xml MIME Type 621 MIME media type name: application 623 MIME subtype name: xcap-diff+xml 625 Mandatory parameters: none 627 Optional parameters: Same as charset parameter application/xml as 628 specified in RFC 3023 [RFC3023]. 630 Encoding considerations: Same as encoding considerations of 631 application/xml as specified in RFC 3023 [RFC3023]. 633 Security considerations: See Section 10 of RFC 3023 [RFC3023] and 634 Section 7 of RFCXXXX [[NOTE TO RFC-EDITOR/IANA: Please replace 635 XXXX with the RFC number of this specification.]]. 637 Interoperability considerations: none. 639 Published specification: This document. 641 Applications which use this media type: This document type has 642 been used to support manipulation of resource lists [RFC4826] 643 using XCAP. 645 Additional Information: 647 Magic Number: None 649 File Extension: .xdf 651 Macintosh file type code: "TEXT" 652 Personal and email address for further information: Jonathan 653 Rosenberg, jdrosen@jdrosen.net 655 Intended usage: COMMON 657 Author/Change controller: The IETF. 659 8.2. URN Sub-Namespace Registration for 660 urn:ietf:params:xml:ns:xcap-diff 662 This section registers a new XML namespace, as per the guidelines in 663 [RFC3688] 665 URI: The URI for this namespace is 666 urn:ietf:params:xml:ns:xcap-diff. 668 Registrant Contact: IETF, SIMPLE working group, (simple@ietf.org), 669 Jonathan Rosenberg (jdrosen@jdrosen.net). 671 XML: 673 BEGIN 674 675 677 678 679 681 XCAP Diff Namespace 682 683 684

Namespace for XCAP Diff

685

urn:ietf:params:xml:ns:xcap-diff

686

See RFCXXXX[[NOTE 687 TO IANA/RFC-EDITOR: Please replace XXXX with the RFC number of this 688 specification.]].

689 690 691 END 693 8.3. Schema Registration 695 This section registers a new XML schema per the procedures in 696 [RFC3688]. 698 URI: urn:ietf:params:xml:schema:xcap-diff 700 Registrant Contact: IETF, SIMPLE working group, (simple@ietf.org), 701 Jonathan Rosenberg (jdrosen@jdrosen.net). 703 The XML for this schema can be found as the sole content of 704 Section 4. 706 9. Acknowledgments 708 The authors would like to thank Pavel Dostal, Jeroen van Bemmel, 709 Martin Hynar, Anders Lindgren, Mary Barnes, Ben Campbell, Francis 710 Dupont, David Harrington, Alexey Melnikov, Dan Romascanu and Robert 711 Sparks for their valuable comments. 713 10. References 715 10.1. Normative References 717 [W3C.REC-xml-20060816] 718 Maler, E., Paoli, J., Bray, T., Yergeau, F., and C. 719 Sperberg-McQueen, "Extensible Markup Language (XML) 1.0 720 (Fourth Edition)", World Wide Web Consortium 721 Recommendation REC-xml-20060816, August 2006, 722 . 724 [W3C.REC-xml-c14n-20010315] 725 Boyer, J., "Canonical XML Version 1.0", World Wide Web 726 Consortium Recommendation REC-xml-c14n-20010315, 727 March 2001, 728 . 730 [W3C.REC-xml-names-20060816] 731 Hollander, D., Bray, T., Layman, A., and R. Tobin, 732 "Namespaces in XML 1.0 (Second Edition)", World Wide Web 733 Consortium Recommendation REC-xml-names-20060816, 734 August 2006, 735 . 737 [RFC2141] Moats, R., "URN Syntax", RFC 2141, May 1997. 739 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 740 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 741 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 743 [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media 744 Types", RFC 3023, January 2001. 746 [RFC2648] Moats, R., "A URN Namespace for IETF Documents", RFC 2648, 747 August 1999. 749 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 750 January 2004. 752 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 753 Requirement Levels", BCP 14, RFC 2119, March 1997. 755 [RFC4825] Rosenberg, J., "The Extensible Markup Language (XML) 756 Configuration Access Protocol (XCAP)", RFC 4825, May 2007. 758 [RFC5261] Urpalainen, J., "An Extensible Markup Language (XML) Patch 759 Operations Framework Utilizing XML Path Language (XPath) 760 Selectors", RFC 5261, September 2008. 762 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 763 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 765 10.2. Informative References 767 [I-D.ietf-sip-xcapevent] 768 Urpalainen, J. and D. Willis, "An Extensible Markup 769 Language (XML) Configuration Access Protocol (XCAP) Diff 770 Event Package", draft-ietf-sip-xcapevent-08 (work in 771 progress), July 2009. 773 [RFC2778] Day, M., Rosenberg, J., and H. Sugano, "A Model for 774 Presence and Instant Messaging", RFC 2778, February 2000. 776 [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, 777 A., Peterson, J., Sparks, R., Handley, M., and E. 778 Schooler, "SIP: Session Initiation Protocol", RFC 3261, 779 June 2002. 781 [RFC3265] Roach, A., "Session Initiation Protocol (SIP)-Specific 782 Event Notification", RFC 3265, June 2002. 784 [RFC4662] Roach, A., Campbell, B., and J. Rosenberg, "A Session 785 Initiation Protocol (SIP) Event Notification Extension for 786 Resource Lists", RFC 4662, August 2006. 788 [RFC4826] Rosenberg, J., "Extensible Markup Language (XML) Formats 789 for Representing Resource Lists", RFC 4826, May 2007. 791 [RFC4483] Burger, E., "A Mechanism for Content Indirection in 792 Session Initiation Protocol (SIP) Messages", RFC 4483, 793 May 2006. 795 Appendix A. Informative Examples 797 These informative examples illustrate basic features of XCAP diff 798 format. 800 The following documents exist at an XCAP server (xcap.example.com) 801 with an imaginary "tests" application usage (there's no default 802 document namespace defined in this imaginary application usage). 804 http://xcap.example.com/tests/users/sip:joe@example.com/index: 806 807 808 This is a sample document 809 811 and then 813 http://xcap.example.com/tests/users/sip:john@example.com/index: 815 816 817 This is another sample document 818 820 A.1. Indicating Existing, Changed or Removed Documents 822 Firstly, an XCAP diff document can indicate what documents exist in a 823 collection. An XCAP diff document may then be: 825 826 829 832 835 837 This listing indicates current ETags of existing documents and their 838 relative URIs. 840 Let's say that Joe adds a new document to his collection: 842 PUT /tests/users/sip:joe@example.com/another_document HTTP/1.1 843 Host: xcap.example.com 844 .... 845 Content-Type: application/xml 846 Content-Length: [XXX] 848 849 850 This is another sample document 851 853 The requests result header has an HTTP ETag "terteer" for this new 854 document. 856 Then an XCAP diff document may then indicate only the creation of 857 this single new document: 859 860 863 866 867 A "new-etag" without a "previous-etag" attribute indicates a creation 868 of a new document. 870 Then Joe decides to modify an existing resource: 872 PUT /tests/users/sip:joe@example.com/another_document HTTP/1.1 873 Host: xcap.example.com 874 .... 875 Content-Type: application/xml 876 Content-Length: [XXX] 878 879 880 This is a modified document 881 883 The reported new HTTP ETag is "huwiias". 885 Then an XCAP diff document may be: 887 888 891 894 896 Both "previous-etag" and "new-etag" attributes signal that a 897 modification has happened to a resource, but actual changes are not 898 shown. 900 Let's say that Joe then removes a document from his collection: 902 DELETE /tests/users/sip:joe@example.com/another_document HTTP/1.1 903 Host: xcap.example.com 905 This HTTP DELETE request results in the unlinking of the resource, 906 and the XCAP diff may be: 908 909 912 915 917 Thus a "previous-etag" without "new-etag" attribute indicates the 918 removal of a resource. 920 A.2. Indicating Actual Changes of Documents 922 Secondly, XCAP diff documents are capable of showing actual changes 923 to documents with [RFC5261] patching semantics. 925 Now Joe's XCAP client utilizes XCAP patching capability to add a new 926 element to a document: 928 PUT /tests/users/sip:joe@example.com/index/~~/doc/foo HTTP/1.1 929 Host: xcap.example.com 930 .... 931 Content-Type: application/xcap-el+xml 932 Content-Length: [XXX] 934 this is a new element 936 Since the insertion of the element is successful, Joe's XCAP client 937 receives the new HTTP ETag "fgherhryt3" of the updated "index" 938 document. 940 Immediately thereafter, Joe's XCAP client issues another HTTP request 941 (this request could even be pipe-lined): 943 PUT /tests/users/sip:joe@example.com/index/~~/doc/bar HTTP/1.1 944 Host: xcap.example.com 945 .... 946 Content-Type: application/xcap-el+xml 947 Content-Length: [XXX] 949 this is a bar element 950 952 The reported new HTTP ETag of "index" is now "dgdgdfgrrr". 954 And then Joe's XCAP client issues yet another HTTP request: 956 PUT /tests/users/sip:joe@example.com/index/~~/doc/foobar HTTP/1.1 957 Host: xcap.example.com 958 .... 959 Content-Type: application/xcap-el+xml 960 Content-Length: [XXX] 962 this is a foobar element 964 The reported new ETag of "index" is now "63hjjsll". 966 XCAP diff format document may then indicate these XCAP Component 967 changes by: 969 970 973 976 this is a new elementthis is a bar element 978 this is a foobar element 979 981 983 Note how several XCAP component modifications were aggregated 984 together, and full history information got lost. 986 Alternatively, the content could have been: 988 989 992 995 this is a new element 998 1001 this is a bar element 1003 1005 1008 this is a foobar element 1011 1013 This shows the full ETag change history of a document, and ETags 1014 change chronologically in the reported XML document order. 1016 A.3. Indicating XCAP Component Contents 1018 Lastly, the XCAP diff format can also indicate the existing full 1019 contents of XCAP Components, i.e. elements or attributes: 1021 1022 1025 bar 1028 this is a new element 1031 1032 Note that the HTTP ETag value of the new document is not shown as it 1033 is irrelevant for this use-case. 1035 Then Joe's XCAP client removes the "id" attribute: 1037 DELETE /tests/users/sip:joe@example.com/index/~~/doc/@id HTTP/1.1 1038 Host: xcap.example.com 1039 .... 1040 Content-Length: 0 1042 And the XCAP diff document may then be: 1044 1045 1048 1051 1053 This indicates that the subscribed attribute was removed from the 1054 document. The element content in this use-case may be discarded from 1055 the XCAP diff document, for example when the size of XCAP diff 1056 document would be impractically large to the transport layer. 1058 Authors' Addresses 1060 Jonathan Rosenberg 1061 Cisco 1062 Edison, NJ 1063 USA 1065 Email: jdrosen@cisco.com 1066 URI: http://www.jdrosen.net 1067 Jari Urpalainen 1068 Nokia 1069 Itamerenkatu 11-13 1070 Helsinki 00180 1071 Finland 1073 Phone: +358 7180 37686 1074 Email: jari.urpalainen@nokia.com