idnits 2.17.00 (12 Aug 2021) /tmp/idnits39311/draft-ietf-simple-xcap-diff-11.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/.) 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 (June 24, 2009) is 4713 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 (~~), 1 warning (==), 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 26, 2009 Nokia 6 June 24, 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-11 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 contain material 16 from IETF Documents or IETF Contributions published or made publicly 17 available before November 10, 2008. The person(s) controlling the 18 copyright in some of this material may not have granted the IETF 19 Trust the right to allow modifications of such material outside the 20 IETF Standards Process. Without obtaining an adequate license from 21 the person(s) controlling the copyright in such materials, this 22 document may not be modified outside the IETF Standards Process, and 23 derivative works of it may not be created outside the IETF Standards 24 Process, except to format it for publication as an RFC or to 25 translate it into languages other than English. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF), its areas, and its working groups. Note that 29 other groups may also distribute working documents as Internet- 30 Drafts. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 The list of current Internet-Drafts can be accessed at 38 http://www.ietf.org/ietf/1id-abstracts.txt. 40 The list of Internet-Draft Shadow Directories can be accessed at 41 http://www.ietf.org/shadow.html. 43 This Internet-Draft will expire on December 26, 2009. 45 Copyright Notice 47 Copyright (c) 2009 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents in effect on the date of 52 publication of this document (http://trustee.ietf.org/license-info). 53 Please review these documents carefully, as they describe your rights 54 and restrictions with respect to this document. 56 Abstract 58 This specification defines a document format that can be used to 59 indicate that a change has occurred in a document managed by the 60 Extensible Markup Language (XML) Configuration Access Protocol 61 (XCAP). This format indicates the document that has changed and its 62 former and new entity tags. It also can indicate the specific change 63 that was made in the document, using an XML patch format. This 64 format allows also indications of element and attribute content of an 65 XML document. XCAP diff documents can be delivered to clients using 66 a number of means, including a Session Initiation Protocol (SIP) 67 event package. 69 Table of Contents 71 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 72 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 73 3. Structure of an XCAP Diff Document . . . . . . . . . . . . . . 5 74 4. XML Schema . . . . . . . . . . . . . . . . . . . . . . . . . . 8 75 5. Example Document . . . . . . . . . . . . . . . . . . . . . . . 10 76 6. Security Considerations . . . . . . . . . . . . . . . . . . . 11 77 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 78 7.1. application/xcap-diff+xml MIME Type . . . . . . . . . . . 12 79 7.2. URN Sub-Namespace Registration for 80 urn:ietf:params:xml:ns:xcap-diff . . . . . . . . . . . . . 13 81 7.3. Schema Registration . . . . . . . . . . . . . . . . . . . 14 82 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 14 83 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 14 84 9.1. Normative References . . . . . . . . . . . . . . . . . . . 14 85 9.2. Informative References . . . . . . . . . . . . . . . . . . 15 86 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 15 88 1. Introduction 90 The Extensible Markup Language (XML) Configuration Access Protocol 91 (XCAP) [RFC4825] is a protocol that allows clients to manipulate XML 92 documents stored on a server. These XML documents serve as 93 configuration information for application protocols. As an example, 94 resource list [RFC4662] subscriptions (also known as presence lists) 95 allow a client to have a single SIP subscription to a list of users, 96 where the list is maintained on a server. The server will obtain 97 presence for those users and report it back to the client. This 98 application requires the server, called a Resource List Server (RLS), 99 to have access to the list of presentities. This list needs to be 100 manipulated by clients so they can add and remove their friends as 101 they desire. 103 Complexities arise when multiple clients attempt to simultaneously 104 manipulate a document, such as a presence list. Frequently, a client 105 will keep a copy of the current list in memory, so it can render it 106 to users. However, if another client modifies the document, the 107 cached version becomes stale. This modification event must be made 108 known to all clients which have cached copies of the document, so 109 that they can fetch the most recent one. 111 To deal with this problem, clients can use a Session Initiation 112 Protocol (SIP) [RFC3261] event package [RFC3265] to subscribe to 113 change events in XCAP documents. This notification needs to indicate 114 the specific resource that changed, and how it changed. One solution 115 for the format of such a change notification would be a content 116 indirection object [RFC4483]. Though content indirection can tell a 117 client that a document has changed, it provides it with MIME 118 Content-ID indicating the new version of the document. The MIME 119 Content-ID is not the same as the entity tag, which is used by XCAP 120 for document versioning. As such, a client cannot easily ascertain 121 whether an indication of a change in a document is due to a change it 122 just made, or due to a change another client made at around the same 123 time. Furthermore, content indirections don't indicate how a 124 document changed; they would only be able to indicate that it did 125 change. 127 To resolve these problems, this document defines a data format which 128 can convey the fact that an XML document managed by XCAP has changed. 129 This data format is an XML document format, called an XCAP diff 130 document. This format can indicate that a document has changed, and 131 provide its previous and new entity tags. It can also optionally 132 include a set of patch operations [RFC5261], which indicate how to 133 transform the document from the version prior to the change, to the 134 version after it. XML element and attribute content of XCAP 135 documents can also be delivered with this format. 137 XML documents that are equivalent for the purposes of many 138 applications may differ in their physical representation. Similar to 139 XCAP, the canonical form with comments [W3C.REC-xml-c14n-20010315] of 140 an XML document determines the logical equivalence when this format 141 is used to patch XML documents. 143 2. Terminology 145 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 146 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 147 document are to be interpreted as described in RFC 2119 [RFC2119] and 148 indicate requirement levels for compliant implementations. 150 This specification also defines the following additional terms: 152 Document: When the term document is used without the "XCAP diff" in 153 front of it, it refers to the XCAP document resource about whom 154 the XCAP diff document is reporting a change. 156 XCAP diff document: The XML document defined by this specification 157 that reports on a set of changes in an XCAP document resource. 159 Server: Typically an XCAP server, this is a protocol entity that 160 generates XCAP diff documents based on its knowledge of a set of 161 XCAP documents. 163 Client: Typically an XCAP client and SIP User Agent (UA), the client 164 consumes XCAP diff documents in order to reconstruct the document 165 stored on the server. 167 3. Structure of an XCAP Diff Document 169 An XCAP diff document is an XML [W3C.REC-xml-20060816] document that 170 MUST be well-formed and SHOULD be valid. XCAP diff documents MUST be 171 based on XML 1.0 and MUST be encoded using UTF-8. This specification 172 makes use of XML namespaces for identifying XCAP diff documents and 173 document fragments. The namespace URI for elements defined by this 174 specification is a URN [RFC2141], using the namespace identifier 175 'ietf' defined by [RFC2648] and extended by [RFC3688]. This URN is: 177 urn:ietf:params:xml:ns:xcap-diff 179 An XCAP diff document begins with the root element tag . 180 This element has a single mandatory attribute, "xcap-root". The 181 value of this attribute is the XCAP root URI for the documents in 182 which the changes have taken place. A single XCAP diff document can 183 only represent changes in documents within the same XCAP root. The 184 content of the element is a sequence of , 185 and elements followed by any number of elements 186 from other namespaces for the purposes of extensibility. Any such 187 unknown elements MUST be ignored by the client. 189 Each element specifies changes in a specific document 190 within the XCAP root. If several elements pinpoint to the 191 same specific document, i.e. for example, the full ETag change 192 history is indicated, the corresponding patches MUST be appliable in 193 the given document order. 195 The element has one mandatory attribute, "sel", and a two 196 optional attributes, "new-etag" and "previous-etag". The "sel" 197 attribute of the element identifies the specific document 198 within the XCAP root for which changes are indicated. Its content 199 MUST be a relative path reference, with the base URI being equal to 200 the XCAP root URI. The "new-etag" attribute provides the entity tag 201 (ETag) for the document after the application of the changes, 202 assuming the document exists after those changes. The "previous- 203 etag" attribute provides an identifier for the document instance 204 prior to the change. If the change being reported is the removal of 205 a document, the "previous-etag" MUST only be included and the "new- 206 etag" attribute will not be present. The "new-etag" attribute MUST 207 only exist alone when the document either exists or it was just 208 created (no patch included). Both attributes are present when a 209 patch (or series of XCAP operations) has been applied to the 210 resource. Also both attributes MAY be used to indicate an ETag 211 change without any document modifications (patches). 213 The "previous-etag" and "new-etag" need not have been sequentially 214 assigned ETags at the server. An XCAP diff document can indicate 215 changes that have occurred over a series of XCAP operations. The 216 only requirement then is that, the sequence of events, when executed 217 serially, will result in the transformation of the document with the 218 ETag "previous-etag" to the one whose ETag is "new-etag". Also the 219 series of operations do not have to be the same exact series of 220 operations that occurred at the server. 222 Each element contains either a sequence of patching 223 instructions or an indication that the body hasn't semantically 224 changed. The latter means that the document has been assigned a new 225 ETag but its content is unchanged and it is indicated by the element. Patching instructions are described by the 227 , and elements. These elements use the 228 corresponding add, replace and remove types defined in [RFC5261], and 229 define a set of patch operations that can be applied to transform the 230 document. See [RFC5261] for instructions on how this transformation 231 is effected. The , and elements allow 232 extension attributes from any namespace. Any unknown attributes of 233 patch operation elements MUST be ignored. 235 Figure 1 shows element content and how corresponding 236 resource or metadata changes. An external document retrieval means 237 in practice HTTP GET requests for target resources. 239 +-----------+----------+-----------+----------+-------------------+ 240 | previous- | new- | | | not- | metadata change | 242 | | | | changed> | | 243 +-----------+----------+-----------+----------+-------------------+ 244 | xxx | yyy | * | - | resource patched, | 245 | | | | | patch included | 246 +-----------+----------+-----------+----------+-------------------+ 247 | xxx | yyy | - | - | resource patched, | 248 | | | | | external document | 249 | | | | | retrieval | 250 +-----------+----------+-----------+----------+-------------------+ 251 | xxx | yyy | - | * | only ETag changed | 252 +-----------+----------+-----------+----------+-------------------+ 253 | - | yyy | - | - | resource created | 254 | | | | | or exists, | 255 | | | | | external document | 256 | | | | | retrieval | 257 +-----------+----------+-----------+----------+-------------------+ 258 | xxx | - | - | - | resource removed | 259 +-----------+----------+-----------+----------+-------------------+ 261 Figure 1: element content / corresponding resource changes 263 Each element indicates the existing element content of an 264 XCAP document. It has one mandatory attribute, "sel", and one 265 optional attribute, "exists". The "sel" attribute of the 266 element identifies an XML element of an XCAP document. It is a 267 percent endoced relative URI following XCAP conventions when 268 selecting elements. The XCAP Node Selector MUST always locate a 269 unique node, the "exists" attribute thus shows whether an element 270 exists or not in the XCAP document. When the "exists" attribute is 271 absent from the element, the indicated element still exists 272 in the XCAP document. The located result element exists as a child 273 element of the element. It should be noted, that only the 274 full content of an element is shown if it exists, there are no 275 conventions for patching these elements. In a corner case where the 276 content of this element cannot be presented for some reason, although 277 it exists in the XCAP document, the element MUST NOT have 278 any child nodes. 280 As the result XML element is typically namespace qualified, all 281 needed namespace declarations MUST exist within the 282 document. The possible local namespace declarations within the 283 result element exist unmodified as in the source document, similar to 284 XCAP conventions. Other namespace references MUST be resolved from 285 the context of the or its parent elements. The prefixes of 286 qualified names (QName) [W3C.REC-xml-names-20060816] of XML nodes 287 also remain as they exist originally in the source XCAP document. 289 Each element indicates the existing attribute content of 290 an XCAP document. It has one mandatory attribute, "sel", and one 291 optional attribute, "exists". The "sel" attribute of the 292 element identifies an XML attribute of an XCAP document. It is a 293 percent endoced relative URI following XCAP conventions when 294 selecting attributes. The "exists" attribute indicates whether an 295 attribute exists or not in the XCAP document. When the "exists" 296 attribute is absent from the element, the indicated 297 attribute still exists in the XCAP document. The child text node of 298 the element indicates the value of the located attribute. 299 Note that if the attribute is namespace qualified, the query 300 parameter of the XCAP URI indicates the attached namespace URI and 301 the prefix in the XCAP source document. 303 4. XML Schema 305 The XML Schema for the XCAP diff format. 307 308 314 315 318 319 320 321 322 323 324 325 326 327 328 329 331 332 333 334 335 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 365 366 367 368 369 370 371 373 374 375 376 377 378 379 381 382 383 384 385 386 388 389 391 392 393 394 396 397 398 399 400 402 403 404 405 407 408 410 412 5. Example Document 414 The following is an example of a document compliant to the schema. 416 417 420 424 430 431 432 433 434 435 presence 436 437 439 sip:marketing@example.com 443 445 This indicates that the document with URI "http://xcap.example.com/ 446 root/resource-lists/users/sip:joe@example.com/coworkers" has changed. 447 Its previous entity tag is "8a77f8d" and its new one is "7ahggs" but 448 actual changes are not shown. The element exists in the 449 rls-services "index" document and its full content is shown. Note 450 that the element is attached with a default namespace 451 declaration within the original document. Similarly, a "uri" 452 attribute content is shown from the same "index" document as an 453 illustrative example. 455 6. Security Considerations 457 XCAP diff documents can include changes from one document to another. 458 As a consequence, if the document itself is sensitive and requires 459 confidentiality, integrity or authentication, then the same applies 460 to the XCAP diff format. Therefore, protocols which transport XCAP 461 diff documents must provide sufficient security capabilities for 462 transporting the document itself. 464 The SIP event package framework specified in RFC 3265 [RFC3265] is 465 the most typical use-case for this format. Then in general its 466 security considerations apply, but event packages MAY also have other 467 specific threats which MUST be considered on an application-by- 468 application basis. 470 7. IANA Considerations 472 There are several IANA considerations associated with this 473 specification. 475 7.1. application/xcap-diff+xml MIME Type 477 MIME media type name: application 479 MIME subtype name: xcap-diff+xml 481 Mandatory parameters: none 483 Optional parameters: Same as charset parameter application/xml as 484 specified in RFC 3023 [RFC3023]. 486 Encoding considerations: Same as encoding considerations of 487 application/xml as specified in RFC 3023 [RFC3023]. 489 Security considerations: See Section 10 of RFC 3023 [RFC3023] and 490 Section 6 of RFCXXXX [[NOTE TO RFC-EDITOR/IANA: Please replace 491 XXXX with the RFC number of this specification.]]. 493 Interoperability considerations: none. 495 Published specification: This document. 497 Applications which use this media type: This document type has 498 been used to support manipulation of resource lists [RFC4826] 499 using XCAP. 501 Additional Information: 503 Magic Number: None 505 File Extension: .xdf 506 Macintosh file type code: "TEXT" 508 Personal and email address for further information: Jonathan 509 Rosenberg, jdrosen@jdrosen.net 511 Intended usage: COMMON 513 Author/Change controller: The IETF. 515 7.2. URN Sub-Namespace Registration for 516 urn:ietf:params:xml:ns:xcap-diff 518 This section registers a new XML namespace, as per the guidelines in 519 [RFC3688] 521 URI: The URI for this namespace is 522 urn:ietf:params:xml:ns:xcap-diff. 524 Registrant Contact: IETF, SIMPLE working group, (simple@ietf.org), 525 Jonathan Rosenberg (jdrosen@jdrosen.net). 527 XML: 529 BEGIN 530 531 533 534 535 537 XCAP Diff Namespace 538 539 540

Namespace for XCAP Diff

541

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

542

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

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