idnits 2.17.00 (12 Aug 2021) /tmp/idnits43546/draft-ietf-simple-xcap-diff-10.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** The document seems to lack a License Notice according IETF Trust Provisions of 28 Dec 2009, Section 6.b.i or Provisions of 12 Sep 2009 Section 6.b -- however, there's a paragraph with a matching beginning. Boilerplate error? (You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Feb 2009 rather than one of the newer Notices. See https://trustee.ietf.org/license-info/.) == The document has an IETF Trust Provisions of 28 Dec 2009, Section 6.c(i) Publication Limitation clause. 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 lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (June 22, 2009) is 4715 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) ** Obsolete normative reference: RFC 2141 (Obsoleted by RFC 8141) ** Obsolete normative reference: RFC 3023 (Obsoleted by RFC 7303) ** Downref: Normative reference to an Informational RFC: RFC 2648 -- Obsolete informational reference (is this intentional?): RFC 3265 (Obsoleted by RFC 6665) Summary: 4 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: December 24, 2009 Nokia 6 June 22, 2009 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-10 12 Status of this Memo 14 This Internet-Draft is submitted to IETF in full conformance with the 15 provisions of BCP 78 and BCP 79. This document may not be modified, 16 and derivative works of it may not be created, except to format it 17 for publication as an RFC or to translate it into languages other 18 than English. 20 Internet-Drafts are working documents of the Internet Engineering 21 Task Force (IETF), its areas, and its working groups. Note that 22 other groups may also distribute working documents as Internet- 23 Drafts. 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet-Drafts as reference 28 material or to cite them other than as "work in progress." 30 The list of current Internet-Drafts can be accessed at 31 http://www.ietf.org/ietf/1id-abstracts.txt. 33 The list of Internet-Draft Shadow Directories can be accessed at 34 http://www.ietf.org/shadow.html. 36 This Internet-Draft will expire on December 24, 2009. 38 Copyright Notice 40 Copyright (c) 2009 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents in effect on the date of 45 publication of this document (http://trustee.ietf.org/license-info). 46 Please review these documents carefully, as they describe your rights 47 and restrictions with respect to this document. 49 Abstract 51 This specification defines a document format that can be used to 52 indicate that a change has occurred in a document managed by the 53 Extensible Markup Language (XML) Configuration Access Protocol 54 (XCAP). This format indicates the document that has changed and its 55 former and new entity tags. It also can indicate the specific change 56 that was made in the document, using an XML patch format. This 57 format allows also indications of element and attribute content of an 58 XML document. XCAP diff documents can be delivered to clients using 59 a number of means, including a Session Initiation Protocol (SIP) 60 event package. 62 Table of Contents 64 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 65 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 66 3. Structure of an XCAP Diff Document . . . . . . . . . . . . . . 4 67 4. XML Schema . . . . . . . . . . . . . . . . . . . . . . . . . . 7 68 5. Example Document . . . . . . . . . . . . . . . . . . . . . . . 9 69 6. Security Considerations . . . . . . . . . . . . . . . . . . . 10 70 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 71 7.1. application/xcap-diff+xml MIME Type . . . . . . . . . . . 11 72 7.2. URN Sub-Namespace Registration for 73 urn:ietf:params:xml:ns:xcap-diff . . . . . . . . . . . . . 12 74 7.3. Schema Registration . . . . . . . . . . . . . . . . . . . 13 75 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 13 76 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 13 77 9.1. Normative References . . . . . . . . . . . . . . . . . . . 13 78 9.2. Informative References . . . . . . . . . . . . . . . . . . 14 79 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 14 81 1. Introduction 83 The Extensible Markup Language (XML) Configuration Access Protocol 84 (XCAP) [RFC4825] is a protocol that allows clients to manipulate XML 85 documents stored on a server. These XML documents serve as 86 configuration information for application protocols. As an example, 87 resource list [RFC4662] subscriptions (also known as presence lists) 88 allow a client to have a single SIP subscription to a list of users, 89 where the list is maintained on a server. The server will obtain 90 presence for those users and report it back to the client. This 91 application requires the server, called a Resource List Server (RLS), 92 to have access to the list of presentities. This list needs to be 93 manipulated by clients so they can add and remove their friends as 94 they desire. 96 Complexities arise when multiple clients attempt to simultaneously 97 manipulate a document, such as a presence list. Frequently, a client 98 will keep a copy of the current list in memory, so it can render it 99 to users. However, if another client modifies the document, the 100 cached version becomes stale. This modification event must be made 101 known to all clients which have cached copies of the document, so 102 that they can fetch the most recent one. 104 To deal with this problem, clients can use a Session Initiation 105 Protocol (SIP) [RFC3261] event package [RFC3265] to subscribe to 106 change events in XCAP documents. This notification needs to indicate 107 the specific resource that changed, and how it changed. One solution 108 for the format of such a change notification would be a content 109 indirection object [RFC4483]. Though content indirection can tell a 110 client that a document has changed, it provides it with MIME 111 Content-ID indicating the new version of the document. The MIME 112 Content-ID is not the same as the entity tag, which is used by XCAP 113 for document versioning. As such, a client cannot easily ascertain 114 whether an indication of a change in a document is due to a change it 115 just made, or due to a change another client made at around the same 116 time. Furthermore, content indirections don't indicate how a 117 document changed; they would only be able to indicate that it did 118 change. 120 To resolve these problems, this document defines a data format which 121 can convey the fact that an XML document managed by XCAP has changed. 122 This data format is an XML document format, called an XCAP diff 123 document. This format can indicate that a document has changed, and 124 provide its previous and new entity tags. It can also optionally 125 include a set of patch operations [RFC5261], which indicate how to 126 transform the document from the version prior to the change, to the 127 version after it. XML element and attribute content of XCAP 128 documents can also be delivered with this format. 130 XML documents that are equivalent for the purposes of many 131 applications may differ in their physical representation. Similar to 132 XCAP, the canonical form with comments [W3C.REC-xml-c14n-20010315] of 133 an XML document determines the logical equivalence when this format 134 is used to patch XML documents. 136 2. Terminology 138 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 139 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 140 document are to be interpreted as described in RFC 2119 [RFC2119] and 141 indicate requirement levels for compliant implementations. 143 This specification also defines the following additional terms: 145 Document: When the term document is used without the "XCAP diff" in 146 front of it, it refers to the XCAP document resource about whom 147 the XCAP diff document is reporting a change. 149 XCAP diff document: The XML document defined by this specification 150 that reports on a set of changes in an XCAP document resource. 152 Server: Typically an XCAP server, this is a protocol entity that 153 generates XCAP diff documents based on its knowledge of a set of 154 XCAP documents. 156 Client: Typically an XCAP client and SIP User Agent (UA), the client 157 consumes XCAP diff documents in order to reconstruct the document 158 stored on the server. 160 3. Structure of an XCAP Diff Document 162 An XCAP diff document is an XML [W3C.REC-xml-20060816] document that 163 MUST be well-formed and SHOULD be valid. XCAP diff documents MUST be 164 based on XML 1.0 and MUST be encoded using UTF-8. This specification 165 makes use of XML namespaces for identifying XCAP diff documents and 166 document fragments. The namespace URI for elements defined by this 167 specification is a URN [RFC2141], using the namespace identifier 168 'ietf' defined by [RFC2648] and extended by [RFC3688]. This URN is: 170 urn:ietf:params:xml:ns:xcap-diff 172 An XCAP diff document begins with the root element tag . 173 This element has a single mandatory attribute, "xcap-root". The 174 value of this attribute is the XCAP root URI for the documents in 175 which the changes have taken place. A single XCAP diff document can 176 only represent changes in documents within the same XCAP root. The 177 content of the element is a sequence of , 178 and elements followed by any number of elements 179 from other namespaces for the purposes of extensibility. Any such 180 unknown elements MUST be ignored by the client. If several 181 elements with the same "sel" selector value exist in the 182 XCAP diff document, i.e. for example, the full ETag change history is 183 indicated, the corresponding patches MUST be appliable in the given 184 document order. Each element specifies changes in a 185 specific document within the XCAP root. It has one mandatory 186 attribute, "sel", and a two optional attributes, "new-etag" and 187 "previous-etag". The "sel" attribute of the element 188 identifies the specific document within the XCAP root for which 189 changes are indicated. Its content MUST be a relative path 190 reference, with the base URI being equal to the XCAP root URI. The 191 "new-etag" attribute provides the entity tag (ETag) for the document 192 after the application of the changes, assuming the document exists 193 after those changes. The "previous-etag" attribute provides an 194 identifier for the document instance prior to the change. If the 195 change being reported is the removal of a document, the "previous- 196 etag" MUST only be included and the "new-etag" attribute will not be 197 present. The "new-etag" attribute MUST only exist alone when the 198 document either exists or it was just created (no patch included). 199 Both attributes are present when a patch (or series of XCAP 200 operations) has been applied to the resource. Also both attributes 201 MAY be used to indicate an ETag change without any document 202 modifications (patches). 204 The "previous-etag" and "new-etag" need not have been sequentially 205 assigned ETags at the server. An XCAP diff document can indicate 206 changes that have occurred over a series of XCAP operations. The 207 only requirement then is that, the sequence of events, when executed 208 serially, will result in the transformation of the document with the 209 ETag "previous-etag" to the one whose ETag is "new-etag". Also the 210 series of operations do not have to be the same exact series of 211 operations that occurred at the server. 213 Each element contains either a sequence of patching 214 instructions or an indication that the body hasn't semantically 215 changed. The latter means that the document has been assigned a new 216 ETag but its content is unchanged and it is indicated by the element. Patching instructions are described by the 218 , and elements. These elements use the 219 corresponding add, replace and remove types defined in [RFC5261], and 220 define a set of patch operations that can be applied to transform the 221 document. See [RFC5261] for instructions on how this transformation 222 is effected. The element can also contain elements from 223 other namespaces for the purposes of extensibility. The , 224 and elements allow extension attributes from any 225 namespace. Any unknown elements element or attributes of 226 patch operation elements MUST be ignored. 228 Figure 1 shows element content and how corresponding 229 resource or metadata changes. An external document retrieval means 230 in practice HTTP GET requests for target resources. 232 +-----------+----------+-----------+----------+-------------------+ 233 | previous- | new- | | | not- | metadata change | 235 | | | | changed> | | 236 +-----------+----------+-----------+----------+-------------------+ 237 | xxx | yyy | * | - | resource patched, | 238 | | | | | patch included | 239 +-----------+----------+-----------+----------+-------------------+ 240 | xxx | yyy | - | - | resource patched, | 241 | | | | | external document | 242 | | | | | retrieval | 243 +-----------+----------+-----------+----------+-------------------+ 244 | xxx | yyy | - | * | only ETag changed | 245 +-----------+----------+-----------+----------+-------------------+ 246 | - | yyy | - | - | resource created | 247 | | | | | or exists, | 248 | | | | | external document | 249 | | | | | retrieval | 250 +-----------+----------+-----------+----------+-------------------+ 251 | xxx | - | - | - | resource removed | 252 +-----------+----------+-----------+----------+-------------------+ 254 Figure 1: element content / corresponding resource changes 256 Each element indicates the existing element content of an 257 XCAP document. It has one mandatory attribute, "sel", and one 258 optional attribute, "exists". The "sel" attribute of the 259 element identifies an XML element of an XCAP document. It is a 260 percent endoced relative URI following XCAP conventions when 261 selecting elements. The XCAP Node Selector MUST always locate a 262 unique node, the "exists" attribute thus shows whether an element 263 exists or not in the XCAP document. When the "exists" attribute is 264 absent from the element, the indicated element still exists 265 in the XCAP document. The located result element exists as a child 266 element of the element. It should be noted, that only the 267 full content of an element is shown if it exists, there are no 268 conventions for patching these elements. In a corner case where the 269 content of this element cannot be presented for some reason, although 270 it exists in the XCAP document, the element MUST NOT have 271 any child nodes. 273 As the result XML element is typically namespace qualified, all 274 needed namespace declarations MUST exist within the 275 document. The possible local namespace declarations within the 276 result element exist unmodified as in the source document, similar to 277 XCAP conventions. Other namespace references MUST be resolved from 278 the context of the or its parent elements. The prefixes of 279 qualified names (QName) [W3C.REC-xml-names-20060816] of XML nodes 280 also remain as they exist originally in the source XCAP document. 282 Each element indicates the existing attribute content of 283 an XCAP document. It has one mandatory attribute, "sel", and one 284 optional attribute, "exists". The "sel" attribute of the 285 element identifies an XML attribute of an XCAP document. It is a 286 percent endoced relative URI following XCAP conventions when 287 selecting attributes. The "exists" attribute indicates whether an 288 attribute exists or not in the XCAP document. When the "exists" 289 attribute is absent from the element, the indicated 290 attribute still exists in the XCAP document. The child text node of 291 the element indicates the value of the located attribute. 292 Note that if the attribute is namespace qualified, the query 293 parameter of the XCAP URI indicates the attached namespace URI and 294 the prefix in the XCAP source document. 296 4. XML Schema 298 The XML Schema for the XCAP diff format. 300 301 307 308 311 312 313 314 315 316 317 318 319 320 321 322 324 325 326 327 328 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 366 367 368 369 370 371 372 374 375 376 377 378 379 381 382 384 385 386 387 389 390 391 392 393 395 396 397 398 400 401 403 405 5. Example Document 407 The following is an example of a document compliant to the schema. 409 410 413 417 423 424 425 426 427 428 presence 429 430 432 sip:marketing@example.com 436 438 This indicates that the document with URI "http://xcap.example.com/ 439 root/resource-lists/users/sip:joe@example.com/coworkers" has changed. 440 Its previous entity tag is "8a77f8d" and its new one is "7ahggs" but 441 actual changes are not shown. The element exists in the 442 rls-services "index" document and its full content is shown. Note 443 that the element is attached with a default namespace 444 declaration within the original document. Similarly, a "uri" 445 attribute content is shown from the same "index" document as an 446 illustrative example. 448 6. Security Considerations 450 XCAP diff documents can include changes from one document to another. 451 As a consequence, if the document itself is sensitive and requires 452 confidentiality, integrity or authentication, then the same applies 453 to the XCAP diff format. Therefore, protocols which transport XCAP 454 diff documents must provide sufficient security capabilities for 455 transporting the document itself. 457 The SIP event package framework specified in RFC 3265 [RFC3265] is 458 the most typical use-case for this format. Then in general its 459 security considerations apply, but event packages MAY also have other 460 specific threats which MUST be considered on an application-by- 461 application basis. 463 7. IANA Considerations 465 There are several IANA considerations associated with this 466 specification. 468 7.1. application/xcap-diff+xml MIME Type 470 MIME media type name: application 472 MIME subtype name: xcap-diff+xml 474 Mandatory parameters: none 476 Optional parameters: Same as charset parameter application/xml as 477 specified in RFC 3023 [RFC3023]. 479 Encoding considerations: Same as encoding considerations of 480 application/xml as specified in RFC 3023 [RFC3023]. 482 Security considerations: See Section 10 of RFC 3023 [RFC3023] and 483 Section 6 of RFCXXXX [[NOTE TO RFC-EDITOR/IANA: Please replace 484 XXXX with the RFC number of this specification.]]. 486 Interoperability considerations: none. 488 Published specification: This document. 490 Applications which use this media type: This document type has 491 been used to support manipulation of resource lists [RFC4826] 492 using XCAP. 494 Additional Information: 496 Magic Number: None 498 File Extension: .xdf 499 Macintosh file type code: "TEXT" 501 Personal and email address for further information: Jonathan 502 Rosenberg, jdrosen@jdrosen.net 504 Intended usage: COMMON 506 Author/Change controller: The IETF. 508 7.2. URN Sub-Namespace Registration for 509 urn:ietf:params:xml:ns:xcap-diff 511 This section registers a new XML namespace, as per the guidelines in 512 [RFC3688] 514 URI: The URI for this namespace is 515 urn:ietf:params:xml:ns:xcap-diff. 517 Registrant Contact: IETF, SIMPLE working group, (simple@ietf.org), 518 Jonathan Rosenberg (jdrosen@jdrosen.net). 520 XML: 522 BEGIN 523 524 526 527 528 530 XCAP Diff Namespace 531 532 533

Namespace for XCAP Diff

534

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

535

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

538 539 540 END 542 7.3. Schema Registration 544 This section registers a new XML schema per the procedures in 545 [RFC3688]. 547 URI: urn:ietf:params:xml:schema:xcap-diff 549 Registrant Contact: IETF, SIMPLE working group, (simple@ietf.org), 550 Jonathan Rosenberg (jdrosen@jdrosen.net). 552 The XML for this schema can be found as the sole content of 553 Section 4. 555 8. Acknowledgments 557 The authors would like to thank Pavel Dostal, Jeroen van Bemmel, 558 Martin Hynar, Anders Lindgren, Mary Barnes and Ben Campbell for their 559 valuable comments. 561 9. References 563 9.1. Normative References 565 [W3C.REC-xml-20060816] 566 Maler, E., Paoli, J., Bray, T., Yergeau, F., and C. 567 Sperberg-McQueen, "Extensible Markup Language (XML) 1.0 568 (Fourth Edition)", World Wide Web Consortium 569 Recommendation REC-xml-20060816, August 2006, 570 . 572 [W3C.REC-xml-c14n-20010315] 573 Boyer, J., "Canonical XML Version 1.0", World Wide Web 574 Consortium Recommendation REC-xml-c14n-20010315, 575 March 2001, 576 . 578 [W3C.REC-xml-names-20060816] 579 Hollander, D., Bray, T., Layman, A., and R. Tobin, 580 "Namespaces in XML 1.0 (Second Edition)", World Wide Web 581 Consortium Recommendation REC-xml-names-20060816, 582 August 2006, 583 . 585 [RFC2141] Moats, R., "URN Syntax", RFC 2141, May 1997. 587 [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media 588 Types", RFC 3023, January 2001. 590 [RFC2648] Moats, R., "A URN Namespace for IETF Documents", RFC 2648, 591 August 1999. 593 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 594 January 2004. 596 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 597 Requirement Levels", BCP 14, RFC 2119, March 1997. 599 [RFC4825] Rosenberg, J., "The Extensible Markup Language (XML) 600 Configuration Access Protocol (XCAP)", RFC 4825, May 2007. 602 [RFC5261] Urpalainen, J., "An Extensible Markup Language (XML) Patch 603 Operations Framework Utilizing XML Path Language (XPath) 604 Selectors", RFC 5261, September 2008. 606 9.2. Informative References 608 [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, 609 A., Peterson, J., Sparks, R., Handley, M., and E. 610 Schooler, "SIP: Session Initiation Protocol", RFC 3261, 611 June 2002. 613 [RFC3265] Roach, A., "Session Initiation Protocol (SIP)-Specific 614 Event Notification", RFC 3265, June 2002. 616 [RFC4662] Roach, A., Campbell, B., and J. Rosenberg, "A Session 617 Initiation Protocol (SIP) Event Notification Extension for 618 Resource Lists", RFC 4662, August 2006. 620 [RFC4826] Rosenberg, J., "Extensible Markup Language (XML) Formats 621 for Representing Resource Lists", RFC 4826, May 2007. 623 [RFC4483] Burger, E., "A Mechanism for Content Indirection in 624 Session Initiation Protocol (SIP) Messages", RFC 4483, 625 May 2006. 627 Authors' Addresses 629 Jonathan Rosenberg 630 Cisco 631 Edison, NJ 632 US 634 Email: jdrosen@cisco.com 635 URI: http://www.jdrosen.net 637 Jari Urpalainen 638 Nokia 639 Itamerenkatu 11-13 640 Helsinki 00180 641 Finland 643 Phone: +358 7180 37686 644 Email: jari.urpalainen@nokia.com