idnits 2.17.00 (12 Aug 2021) /tmp/idnits44563/draft-ietf-simple-xcap-diff-12.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 26, 2009) is 4711 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 28, 2009 Nokia 6 June 26, 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-12 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 28, 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 . . . . . . . . . . . . . . . . . . . . . . . 11 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. Wherever 187 the XML schema (see Section 4) allows extension elements or 188 attributes, any such unknown content MUST be ignored by the client. 190 Each element specifies changes in a specific document 191 within the XCAP root. If several elements pinpoint to the 192 same specific document, i.e. for example, the full ETag change 193 history is indicated, the corresponding patches MUST be appliable in 194 the given document order. 196 The element has one mandatory attribute, "sel", and a two 197 optional attributes, "new-etag" and "previous-etag". The "sel" 198 attribute of the element identifies the specific document 199 within the XCAP root for which changes are indicated. Its content 200 MUST be a relative path reference, with the base URI being equal to 201 the XCAP root URI. The "new-etag" attribute provides the entity tag 202 (ETag) for the document after the application of the changes, 203 assuming the document exists after those changes. The "previous- 204 etag" attribute provides an identifier for the document instance 205 prior to the change. If the change being reported is the removal of 206 a document, the "previous-etag" MUST only be included and the "new- 207 etag" attribute will not be present. The "new-etag" attribute MUST 208 only exist alone when the document either exists or it was just 209 created (no patch included). Both attributes are present when a 210 patch (or series of XCAP operations) has been applied to the 211 resource. Also both attributes MAY be used to indicate an ETag 212 change without any document modifications (patches). 214 The "previous-etag" and "new-etag" need not have been sequentially 215 assigned ETags at the server. An XCAP diff document can indicate 216 changes that have occurred over a series of XCAP operations. The 217 only requirement then is that, the sequence of events, when executed 218 serially, will result in the transformation of the document with the 219 ETag "previous-etag" to the one whose ETag is "new-etag". Also the 220 series of operations do not have to be the same exact series of 221 operations that occurred at the server. 223 Each element contains either a sequence of patching 224 instructions or an indication that the body hasn't semantically 225 changed. The latter means that the document has been assigned a new 226 ETag but its content is unchanged and it is indicated by the element. Patching instructions are described by the 228 , and elements. These elements use the 229 corresponding add, replace and remove types defined in [RFC5261], and 230 define a set of patch operations that can be applied to transform the 231 document. See [RFC5261] for instructions on how this transformation 232 is effected. The element can also contain elements from 233 other namespaces for the purposes of extensibility. The , 234 and elements allow extension attributes from any 235 namespace. 237 Figure 1 shows element content and how corresponding 238 resource or metadata changes. An external document retrieval means 239 in practice HTTP GET requests for target resources. 241 +-----------+----------+-----------+----------+-------------------+ 242 | previous- | new- | | | not- | metadata change | 244 | | | | changed> | | 245 +-----------+----------+-----------+----------+-------------------+ 246 | xxx | yyy | * | - | resource patched, | 247 | | | | | patch included | 248 +-----------+----------+-----------+----------+-------------------+ 249 | xxx | yyy | - | - | resource patched, | 250 | | | | | external document | 251 | | | | | retrieval | 252 +-----------+----------+-----------+----------+-------------------+ 253 | xxx | yyy | - | * | only ETag changed | 254 +-----------+----------+-----------+----------+-------------------+ 255 | - | yyy | - | - | resource created | 256 | | | | | or exists, | 257 | | | | | external document | 258 | | | | | retrieval | 259 +-----------+----------+-----------+----------+-------------------+ 260 | xxx | - | - | - | resource removed | 261 +-----------+----------+-----------+----------+-------------------+ 263 Figure 1: element content / corresponding resource changes 265 Each element indicates the existing element content of an 266 XCAP document. It has one mandatory attribute, "sel", and one 267 optional attribute, "exists". The "sel" attribute of the 268 element identifies an XML element of an XCAP document. It is a 269 percent endoced relative URI following XCAP conventions when 270 selecting elements. The XCAP Node Selector MUST always locate a 271 unique node, the "exists" attribute thus shows whether an element 272 exists or not in the XCAP document. When the "exists" attribute is 273 absent from the element, the indicated element still exists 274 in the XCAP document. The located result element exists as a child 275 element of the element. It should be noted, that only the 276 full content of an element is shown if it exists, there are no 277 conventions for patching these elements. In a corner case where the 278 content of this element cannot be presented for some reason, although 279 it exists in the XCAP document, the element MUST NOT have 280 any child nodes. 282 As the result XML element is typically namespace qualified, all 283 needed namespace declarations MUST exist within the 284 document. The possible local namespace declarations within the 285 result element exist unmodified as in the source document, similar to 286 XCAP conventions. Other namespace references MUST be resolved from 287 the context of the or its parent elements. The prefixes of 288 qualified names (QName) [W3C.REC-xml-names-20060816] of XML nodes 289 also remain as they exist originally in the source XCAP document. 291 Each element indicates the existing attribute content of 292 an XCAP document. It has one mandatory attribute, "sel", and one 293 optional attribute, "exists". The "sel" attribute of the 294 element identifies an XML attribute of an XCAP document. It is a 295 percent endoced relative URI following XCAP conventions when 296 selecting attributes. The "exists" attribute indicates whether an 297 attribute exists or not in the XCAP document. When the "exists" 298 attribute is absent from the element, the indicated 299 attribute still exists in the XCAP document. The child text node of 300 the element indicates the value of the located attribute. 301 Note that if the attribute is namespace qualified, the query 302 parameter of the XCAP URI indicates the attached namespace URI and 303 the prefix in the XCAP source document. 305 Namespaces of the "sel" attribute of the and 306 element MUST also be resolved by clients. The conventions described 307 in Section 4.2.1 of [RFC5261] MUST be followed with this format. In 308 other words, the same namespace resolving rules of selector values 309 apply to these and elements than patch 310 operation elements of [RFC5261]. 312 4. XML Schema 314 The XML Schema for the XCAP diff format. 316 317 323 324 327 328 329 330 331 332 333 334 335 336 337 338 340 341 342 343 344 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 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 389 390 391 392 393 394 396 397 399 400 401 402 404 405 406 407 408 410 411 412 413 415 416 418 420 5. Example Document 422 The following is an example of a document compliant to the schema. 424 425 429 433 437 438 439 440 441 442 presence 443 444 446 sip:marketing@example.com 450 452 This indicates that the document with URI "http://xcap.example.com/ 453 root/resource-lists/users/sip:joe@example.com/coworkers" has changed. 454 Its previous entity tag is "8a77f8d" and its new one is "7ahggs" but 455 actual changes are not shown. The element exists in the 456 rls-services "index" document and its full content is shown. Note 457 that the element is attached with a default namespace 458 declaration within the original document. Similarly, a "uri" 459 attribute content is shown from the same "index" document as an 460 illustrative example. 462 6. Security Considerations 464 XCAP diff documents can include changes from one document to another. 465 As a consequence, if the document itself is sensitive and requires 466 confidentiality, integrity or authentication, then the same applies 467 to the XCAP diff format. Therefore, protocols which transport XCAP 468 diff documents must provide sufficient security capabilities for 469 transporting the document itself. 471 The SIP event package framework specified in RFC 3265 [RFC3265] is 472 the most typical use-case for this format. Then in general its 473 security considerations apply, but event packages MAY also have other 474 specific threats which MUST be considered on an application-by- 475 application basis. 477 7. IANA Considerations 479 There are several IANA considerations associated with this 480 specification. 482 7.1. application/xcap-diff+xml MIME Type 484 MIME media type name: application 486 MIME subtype name: xcap-diff+xml 488 Mandatory parameters: none 490 Optional parameters: Same as charset parameter application/xml as 491 specified in RFC 3023 [RFC3023]. 493 Encoding considerations: Same as encoding considerations of 494 application/xml as specified in RFC 3023 [RFC3023]. 496 Security considerations: See Section 10 of RFC 3023 [RFC3023] and 497 Section 6 of RFCXXXX [[NOTE TO RFC-EDITOR/IANA: Please replace 498 XXXX with the RFC number of this specification.]]. 500 Interoperability considerations: none. 502 Published specification: This document. 504 Applications which use this media type: This document type has 505 been used to support manipulation of resource lists [RFC4826] 506 using XCAP. 508 Additional Information: 510 Magic Number: None 512 File Extension: .xdf 514 Macintosh file type code: "TEXT" 516 Personal and email address for further information: Jonathan 517 Rosenberg, jdrosen@jdrosen.net 519 Intended usage: COMMON 521 Author/Change controller: The IETF. 523 7.2. URN Sub-Namespace Registration for 524 urn:ietf:params:xml:ns:xcap-diff 526 This section registers a new XML namespace, as per the guidelines in 527 [RFC3688] 529 URI: The URI for this namespace is 530 urn:ietf:params:xml:ns:xcap-diff. 532 Registrant Contact: IETF, SIMPLE working group, (simple@ietf.org), 533 Jonathan Rosenberg (jdrosen@jdrosen.net). 535 XML: 537 BEGIN 538 539 541 542 543 545 XCAP Diff Namespace 546 547 548

Namespace for XCAP Diff

549

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

550

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

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