idnits 2.17.1 draft-ietf-simple-xcap-11.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 15. -- Found old boilerplate from RFC 3978, Section 5.5 on line 3223. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 3200. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 3207. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 3213. ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: The remainder of the document selector (the path following "global" or the XUI) points to specific documents for that application usage. Subdirectories are permitted, but are NOT RECOMMENDED. XCAP provides no way to create sub-directories or to list their contents, thus limiting their utility. If subdirectories are used, there MUST not be a document in a directory with the same name as a sub-directory. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: If the creation or replacement was successful, and the resource interdependencies are resolved, the server returns a 201 Created or or 200 OK, respectively. Note that a 201 Created is generated for creation of new documents, elements, or attributes. A 200 OK response to PUT MUST not contain any content. Per the recommendations of RFC 2616, the 201 can contain a Location header field and entity that identify the resource that was created. -- 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 (May 5, 2006) is 6564 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) -- Possible downref: Non-RFC (?) normative reference: ref. '1' -- Possible downref: Non-RFC (?) normative reference: ref. '2' -- Possible downref: Non-RFC (?) normative reference: ref. '3' -- Possible downref: Non-RFC (?) normative reference: ref. '4' -- Possible downref: Non-RFC (?) normative reference: ref. '5' ** Obsolete normative reference: RFC 2616 (ref. '6') (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 2048 (ref. '8') (Obsoleted by RFC 4288, RFC 4289) ** Obsolete normative reference: RFC 3023 (ref. '9') (Obsoleted by RFC 7303) -- Possible downref: Non-RFC (?) normative reference: ref. '10' -- Possible downref: Non-RFC (?) normative reference: ref. '11' ** Obsolete normative reference: RFC 4234 (ref. '12') (Obsoleted by RFC 5234) ** Obsolete normative reference: RFC 2818 (ref. '14') (Obsoleted by RFC 9110) -- Possible downref: Non-RFC (?) normative reference: ref. '19' -- Obsolete informational reference (is this intentional?): RFC 2434 (ref. '27') (Obsoleted by RFC 5226) -- Obsolete informational reference (is this intentional?): RFC 3265 (ref. '28') (Obsoleted by RFC 6665) Summary: 8 errors (**), 0 flaws (~~), 5 warnings (==), 18 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 SIMPLE J. Rosenberg 3 Internet-Draft Cisco Systems 4 Expires: November 6, 2006 May 5, 2006 6 The Extensible Markup Language (XML) Configuration Access Protocol 7 (XCAP) 8 draft-ietf-simple-xcap-11 10 Status of this Memo 12 By submitting this Internet-Draft, each author represents that any 13 applicable patent or other IPR claims of which he or she is aware 14 have been or will be disclosed, and any of which he or she becomes 15 aware will be disclosed, in accordance with Section 6 of BCP 79. 17 Internet-Drafts are working documents of the Internet Engineering 18 Task Force (IETF), its areas, and its working groups. Note that 19 other groups may also distribute working documents as Internet- 20 Drafts. 22 Internet-Drafts are draft documents valid for a maximum of six months 23 and may be updated, replaced, or obsoleted by other documents at any 24 time. It is inappropriate to use Internet-Drafts as reference 25 material or to cite them other than as "work in progress." 27 The list of current Internet-Drafts can be accessed at 28 http://www.ietf.org/ietf/1id-abstracts.txt. 30 The list of Internet-Draft Shadow Directories can be accessed at 31 http://www.ietf.org/shadow.html. 33 This Internet-Draft will expire on November 6, 2006. 35 Copyright Notice 37 Copyright (C) The Internet Society (2006). 39 Abstract 41 This specification defines the Extensible Markup Language (XML) 42 Configuration Access Protocol (XCAP). XCAP allows a client to read, 43 write and modify application configuration data, stored in XML format 44 on a server. XCAP maps XML document sub-trees and element attributes 45 to HTTP URIs, so that these components can be directly accessed by 46 HTTP. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 51 2. Overview of Operation . . . . . . . . . . . . . . . . . . . . 4 52 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 53 4. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 5 54 5. Application Usages . . . . . . . . . . . . . . . . . . . . . . 7 55 5.1. Application Unique ID (AUID) . . . . . . . . . . . . . . . 7 56 5.2. Default Namespace Binding . . . . . . . . . . . . . . . . 8 57 5.3. Data Validation . . . . . . . . . . . . . . . . . . . . . 8 58 5.4. Data Semantics . . . . . . . . . . . . . . . . . . . . . . 10 59 5.5. Naming Conventions . . . . . . . . . . . . . . . . . . . . 10 60 5.6. Resource Interdependencies . . . . . . . . . . . . . . . . 11 61 5.7. Authorization Policies . . . . . . . . . . . . . . . . . . 11 62 5.8. Data Extensibility . . . . . . . . . . . . . . . . . . . . 12 63 5.9. Documenting Application Usages . . . . . . . . . . . . . . 12 64 5.10. Guidelines for Creating Application Usages . . . . . . . . 13 65 6. URI Construction . . . . . . . . . . . . . . . . . . . . . . . 14 66 6.1. XCAP Root . . . . . . . . . . . . . . . . . . . . . . . . 15 67 6.2. Document Selector . . . . . . . . . . . . . . . . . . . . 16 68 6.3. Node Selector . . . . . . . . . . . . . . . . . . . . . . 18 69 6.4. Namespace Bindings for the Selector . . . . . . . . . . . 22 70 7. Client Operations . . . . . . . . . . . . . . . . . . . . . . 24 71 7.1. Create or Replace a Document . . . . . . . . . . . . . . . 25 72 7.2. Delete a Document . . . . . . . . . . . . . . . . . . . . 25 73 7.3. Fetch a Document . . . . . . . . . . . . . . . . . . . . . 26 74 7.4. Create or Replace an Element . . . . . . . . . . . . . . . 26 75 7.5. Delete an Element . . . . . . . . . . . . . . . . . . . . 28 76 7.6. Fetch an Element . . . . . . . . . . . . . . . . . . . . . 29 77 7.7. Create or Replace an Attribute . . . . . . . . . . . . . . 30 78 7.8. Delete an Attribute . . . . . . . . . . . . . . . . . . . 31 79 7.9. Fetch an Attribute . . . . . . . . . . . . . . . . . . . . 31 80 7.10. Fetch Namespace Bindings . . . . . . . . . . . . . . . . . 31 81 7.11. Conditional Operations . . . . . . . . . . . . . . . . . . 32 82 8. Server Behavior . . . . . . . . . . . . . . . . . . . . . . . 34 83 8.1. POST Handling . . . . . . . . . . . . . . . . . . . . . . 34 84 8.2. PUT Handling . . . . . . . . . . . . . . . . . . . . . . . 35 85 8.2.1. Locating the Parent . . . . . . . . . . . . . . . . . 35 86 8.2.2. Verifying Document Content . . . . . . . . . . . . . . 36 87 8.2.3. Creation . . . . . . . . . . . . . . . . . . . . . . . 37 88 8.2.4. Replacement . . . . . . . . . . . . . . . . . . . . . 41 89 8.2.5. Validation . . . . . . . . . . . . . . . . . . . . . . 42 90 8.2.6. Conditional Processing . . . . . . . . . . . . . . . . 42 91 8.2.7. Resource Interdependencies . . . . . . . . . . . . . . 43 92 8.3. GET Handling . . . . . . . . . . . . . . . . . . . . . . . 43 93 8.4. DELETE Handling . . . . . . . . . . . . . . . . . . . . . 44 94 8.5. Managing Etags . . . . . . . . . . . . . . . . . . . . . . 45 95 9. Cache Control . . . . . . . . . . . . . . . . . . . . . . . . 45 96 10. Namespace Binding Format . . . . . . . . . . . . . . . . . . . 46 97 11. Detailed Conflict Reports . . . . . . . . . . . . . . . . . . 46 98 11.1. Document Structure . . . . . . . . . . . . . . . . . . . . 46 99 11.2. XML Schema . . . . . . . . . . . . . . . . . . . . . . . . 48 100 12. XCAP Server Capabilities . . . . . . . . . . . . . . . . . . . 52 101 12.1. Application Unique ID (AUID) . . . . . . . . . . . . . . . 53 102 12.2. XML Schema . . . . . . . . . . . . . . . . . . . . . . . . 53 103 12.3. Default Namespace . . . . . . . . . . . . . . . . . . . . 54 104 12.4. MIME Type . . . . . . . . . . . . . . . . . . . . . . . . 54 105 12.5. Validation Constraints . . . . . . . . . . . . . . . . . . 54 106 12.6. Data Semantics . . . . . . . . . . . . . . . . . . . . . . 54 107 12.7. Naming Conventions . . . . . . . . . . . . . . . . . . . . 55 108 12.8. Resource Interdependencies . . . . . . . . . . . . . . . . 55 109 12.9. Authorization Policies . . . . . . . . . . . . . . . . . . 55 110 13. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 111 14. Security Considerations . . . . . . . . . . . . . . . . . . . 58 112 15. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 59 113 15.1. XCAP Application Unique IDs . . . . . . . . . . . . . . . 59 114 15.2. MIME Types . . . . . . . . . . . . . . . . . . . . . . . . 59 115 15.2.1. application/xcap-el+xml MIME Type . . . . . . . . . . 60 116 15.2.2. application/xcap-att+xml MIME Type . . . . . . . . . . 61 117 15.2.3. application/xcap-ns+xml MIME Type . . . . . . . . . . 61 118 15.2.4. application/xcap-error+xml MIME Type . . . . . . . . . 62 119 15.2.5. application/xcap-caps+xml MIME Type . . . . . . . . . 63 120 15.3. URN Sub-Namespace Registrations . . . . . . . . . . . . . 64 121 15.3.1. urn:ietf:params:xml:ns:xcap-error . . . . . . . . . . 64 122 15.3.2. urn:ietf:params:xml:ns:xcap-caps . . . . . . . . . . . 65 123 15.4. XML Schema Registrations . . . . . . . . . . . . . . . . . 66 124 15.4.1. XCAP Error Schema Registration . . . . . . . . . . . . 66 125 15.4.2. XCAP Capabilities Schema Registration . . . . . . . . 66 126 16. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 66 127 17. References . . . . . . . . . . . . . . . . . . . . . . . . . . 67 128 17.1. Normative References . . . . . . . . . . . . . . . . . . . 67 129 17.2. Informative References . . . . . . . . . . . . . . . . . . 68 130 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 70 131 Intellectual Property and Copyright Statements . . . . . . . . . . 71 133 1. Introduction 135 In many communications applications, such as Voice over IP, instant 136 messaging, and presence, it is necessary for network servers to 137 access per-user information in the process of servicing a request. 138 This per-user information resides within the network, but is managed 139 by the end user themselves. Its management can be done through a 140 multiplicity of access points, including the web, a wireless handset, 141 or a PC application. 143 There are many examples of per-user information. One is presence 144 [20] authorization policy, which defines rules about which watchers 145 are allowed to subscribe to a presentity, and what information they 146 are allowed to access. Another is presence lists, which are lists of 147 users whose presence is desired by a watcher [26]. One way to obtain 148 presence information for the list is to subscribe to a resource which 149 represents that list [21]. In this case, the Resource List Server 150 (RLS) requires access to this list in order to process a SIP [16] 151 SUBSCRIBE [28] request for it. Another way to obtain presence for 152 the users on the list is for a watcher to subscribe to each user 153 individually. In that case, it is convenient to have a server store 154 the list, and when the client boots, it fetches the list from the 155 server. This would allow a user to access their resource lists from 156 different clients. 158 This specification describes a protocol that can be used to 159 manipulate this per-user data. It is called the Extensible Markup 160 Language (XML) Configuration Access Protocol (XCAP). XCAP is a set 161 of conventions for mapping XML documents and document components into 162 HTTP URIs, rules for how the modification of one resource affects 163 another, data validation constraints, and authorization policies 164 associated with access to those resources. Because of this 165 structure, normal HTTP primitives can be used to manipulate the data. 166 XCAP is based heavily on ideas borrowed from the Application 167 Configuration Access Protocol (ACAP) [25], but it is not an extension 168 of it, nor does it have any dependencies on it. Like ACAP, XCAP is 169 meant to support the configuration needs for a multiplicity of 170 applications, rather than just a single one. 172 2. Overview of Operation 174 Each application that makes use of XCAP specifies an application 175 usage (Section 5). This application usage defines the XML schema [2] 176 for the data used by the application, along with other key pieces of 177 information. The principal task of XCAP is to allow clients to read, 178 write, modify, create and delete pieces of that data. These 179 operations are supported using HTTP/1.1 [6]. An XCAP server acts as 180 a repository for collections of XML documents. There will be 181 documents stored for each application. Within each application, 182 there are documents stored for each user. Each user can have a 183 multiplicity of documents for a particular application. To access 184 some component of one of those documents, XCAP defines an algorithm 185 for constructing a URI that can be used to reference that component. 186 Components refer to any element or attribute within the document. 187 Thus, the HTTP URIs used by XCAP point to a document, or to pieces of 188 information that are finer grained than the XML document itself. An 189 HTTP resource which follows the naming conventions and validation 190 constraints defined here is called an XCAP resource. 192 Since XCAP resources are also HTTP resources, they can be accessed 193 using HTTP methods. Reading an XCAP resource is accomplished with 194 HTTP GET, creating or modifying one is done with HTTP PUT, and 195 removing one of the resources is done with an HTTP DELETE. XCAP 196 resources do not represent processing scripts; as a result, POST 197 operations to HTTP URIs representing XCAP resources are not defined. 198 Properties that HTTP associates with resources, such as entity tags, 199 also apply to XCAP resources. Indeed, entity tags are particularly 200 useful in XCAP, as they allow a number of conditional operations to 201 be performed. 203 XML documents which are equivalent for the purposes of many 204 applications may differ in their physical representation. With XCAP 205 resources, the canonical form with comments [19] of an XML document 206 determines the logical equivalence. In other words, the canonical 207 specification determines, how significant whitespace MUST be 208 processed and for example, that new inserted attributes may appear in 209 any order within the physical representation. 211 3. Terminology 213 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 214 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 215 and "OPTIONAL" are to be interpreted as described in RFC 2119 [7] and 216 indicate requirement levels for compliant implementations. 218 4. Definitions 220 The following terms are used throughout this document: 222 XCAP Resource: An HTTP resource representing an XML document, an 223 element within an XML document, or an attribute of an element 224 within an XML document that follows the naming and validation 225 constraints of XCAP. 227 XCAP Server: An HTTP server that understands how to follow the naming 228 and validation constraints defined in this specification. 230 XCAP Client: An HTTP client that understands how to follow the naming 231 and validation constraints defined in this specification. 233 Application: A collection of software components within a network 234 whose operation depends on data managed and stored on an XCAP 235 server. 237 Application Usage: Detailed information on the interaction of an 238 application with the XCAP server. 240 Application Unique ID (AUID): A unique identifier within the 241 namespace of application unique IDs created by this specification 242 that differentiates XCAP resources accessed by one application 243 from XCAP resources accessed by another. 245 Naming Conventions: The part of an application usage that specifies 246 well-known URIs used by an application, or more generally, 247 specifies the URIs that are typically accessed by an application 248 during its processing. 250 XCAP User Identifier (XUI): The XUI is a string, valid as a path 251 element in an HTTP URI, that is associated with each user served 252 by the XCAP server. 254 XCAP Root: A context that contains all of the documents across all 255 application usages and users that are managed by the server. 257 Document Selector: A sequence of path segments, with each segment 258 being separated by a "/", that identify the XML document within an 259 XCAP root that is being selected. 261 Node Selector: A sequence of path segments, with each segment being 262 separated by a "/", that identify the XML node (element or 263 attribute) being selected within a document. 265 Node Selector Separator: A single path segment equal to two tilde 266 characters "~~" that is used to separate the document selector 267 from the node selector within an HTTP URI. 269 Document URI: The HTTP URI containing the XCAP root and document 270 selector, resulting in the selection of a specific document. As a 271 result, performing a GET against the document URI would retrieve 272 the document. 274 Node URI: The HTTP URI containing the XCAP root, document selector, 275 node selector separator and node selector, resulting in the 276 selection of a specific XML node. 278 XCAP Root URI: An HTTP URI that representing the XCAP root. Although 279 a syntactically valid URI, the XCAP Root URI does not correspond 280 to an actual resource on an XCAP server. Actual resources are 281 created by appending additional path information to the XCAP Root 282 URI. 284 Global Tree: A URI that represents the parent for all global 285 documents for a particular application usage within a particular 286 XCAP root. 288 Home Directory: A URI that represents the parent for all documents 289 for a particular user for a particular application usage within a 290 particular XCAP root. 292 Positional Insertion: A PUT operation that results in the insertion 293 of a new element into a document such that its position relative 294 to other children of the same parent is set by the client. 296 5. Application Usages 298 Each XCAP resource on a server is associated with an application. In 299 order for an application to use those resources, application specific 300 conventions must be specified. Those conventions include the XML 301 schema that defines the structure and constraints of the data, well 302 known URIs to bootstrap access to the data, and so on. All of those 303 application specific conventions are defined by the application 304 usage. 306 5.1. Application Unique ID (AUID) 308 Each application usage is associated with a name, called an 309 Application Unique ID (AUID). This name uniquely identifies the 310 application usage within the namespace of application usages, and is 311 different from AUIDs used by other applications. AUIDs exist in one 312 of two namespaces. The first namespace is the IETF namespace. This 313 namespace contains a set of tokens, each of which is registered with 314 IANA. These registrations occur with the publication of standards 315 track RFCs [27] based on the guidelines in Section 15. The second 316 namespace is the vendor-proprietary namespace. Each AUID in that 317 namespace is prefixed with the reverse domain name of the 318 organization creating the AUID, followed by a period, followed by any 319 vendor defined token. As an example, the example.com domain can 320 create an AUID with the value "com.example.foo" but cannot create one 321 with the value "org.example.foo". AUIDs within the vendor namespace 322 do not need to be registered with IANA. The vendor namespace is also 323 meant to be used in lab environments where no central registry is 324 needed. The syntax for AUIDs, expressed in ABNF [12] (and using some 325 of the BNF defined in RFC 3986 [13]) is: 327 AUID = global-auid / vendor-auid 328 global-auid = auid 329 auid = 1*auid-char 330 vendor-auid = rev-hostname "." auid 331 rev-hostname = toplabel *( "." domainlabel ) 332 domainlabel = alphanum 333 / alphanum *( alphanum / "-" ) alphanum 334 toplabel = ALPHA / ALPHA *( alphanum / "-" ) alphanum 335 auid-char = auid-unreserved / pct-encoded / sub-delims 336 / ":" / "@" 337 auid-unreserved = ALPHA / DIGIT / "-" / "_" / "~" 339 The allowed characters for the auid production is a subset of the 340 pchar production defined in RFC3986. In particular, it omits the 341 ".", which allows for the auid to be separated from the reverse 342 hostname. 344 5.2. Default Namespace Binding 346 In order for the XCAP server to match a URI to an element or 347 attribute of a document, any XML namespace prefixes used within the 348 URI must be expanded [3]. This expansion requires a namespace 349 binding context. That context maps namespace prefixes to namespace 350 URIs. It also defines a default namespace that applies to elements 351 without namespace prefixes. The namespace binding context comes from 352 two sources. Firstly, the mapping of namespace prefixes to namespace 353 URIs is obtained from the URI itself (see Section 6.4). However, the 354 default namespace URI is defined by the application usage itself, and 355 applies to all URIs referencing resources within that application 356 usage. All application usages MUST define a namespace URI that 357 represents the default namespace to be used when evaluating URIs. 358 The default namespace does not apply to elements or attributes within 359 the documents themselves. However, if a document contains a URI 360 representing an XCAP resource, the default namespace defined by the 361 application usage applies to that URI as well. 363 5.3. Data Validation 365 One of the responsibilities of an XCAP server is to validate the 366 content of each XCAP resource when an XCAP client tries to modify 367 one. This is done using two mechanisms. Firstly, all application 368 usages MUST describe their document contents using XML schema [2]. 369 The application usage MUST also identify the MIME type for documents 370 compliant to that schema. 372 Unfortunately, XML schemas cannot represent every form of data 373 constraint. As an example, one XML element may contain an integer 374 which defines the maximum number of instances of another element. 375 This constraint cannot be represented with XML schema. However, such 376 constraints may be important to the application usage. The 377 application usage defines any additional constraints beyond those in 378 the schema. 380 Of particular importance are uniqueness constraints. In many cases, 381 an application will require that there only be one instance of some 382 element or attribute within a particular scope. Each uniqueness 383 constraint needs to be specified by identifying the field, or 384 combinations of fields, that need to be unique, and then identifying 385 the scope in which that uniqueness applies. One typical scope is the 386 set of all elements of a certain name within the same parent. 387 Another typical scope is the set of all URIs valid within a 388 particular domain. In some cases these constraints can be specified 389 using XML schema, which provides the element for this 390 purpose. Other uniqueness constraints, such as URI uniqueness across 391 a domain, cannot be expressed by schema. Whether or not the schema 392 is used to express some of the uniqueness requirements, the 393 application usage MUST specify all uniqueness requirements when it 394 defines its data validation needs. 396 For example, the resource lists application usage [22] requires that 397 each element have a unique value for the "name" attribute 398 within a single parent. As another example, the RLS services 399 application usage [22] requires that the value of the "uri" attribute 400 of the element be a URI that is unique within the domain of 401 the URI. 403 URI constraints represent another form of constraints. These are 404 constraints on the scheme or structure of the scheme specific part of 405 the URI. These kinds of constraints cannot be expressed in an XML 406 schema. If these constraints are important to an application usage, 407 they need to be explicitly called out. 409 Another important data constraint is referential integrity. 410 Referential integrity is important when the name or value of an 411 element or attribute is used as a key to select another element or 412 attribute. An application usage MAY specify referential integrity 413 constraints. However, XCAP servers are not a replacement for 414 Relational Database Management Systems (RDBMS), and therefore servers 415 are never responsible for maintaining referential integrity. XCAP 416 clients are responsible for making all of the appropriate changes to 417 documents in order to maintain referential integrity. 419 Another constraint is character encoding. XML allows documents to be 420 encoded using several different character sets. However, this 421 specification mandates that all documents used with XCAP MUST be 422 encoded using UTF-8. This cannot be changed by an application usage. 424 The data validation information is consumed by both clients, which 425 use them to make sure they construct requests that will be accepted 426 by the server, and by servers, which validate the constraints when 427 they receive a request (with the exception of referential integrity 428 constraints, which are not validated by the server). 430 5.4. Data Semantics 432 For each application usage, the data present in the XML document has 433 a well defined semantic. The application usage defines that 434 semantic, so that a client can properly construct a document in order 435 to achieve the desired result. They are not used by the server, as 436 it is purposefully unaware of the semantics of the data it is 437 managing. The data semantics are expressed in English prose by the 438 application usage. 440 One particularly important semantic is the base URI to be used for 441 the resolution of any relative URI references pointed to XCAP 442 resources. As discussed below, relative URI references pointing to 443 XCAP resources cannot be resolved using the retrieval URI as the base 444 URI. Therefore, it is up to the application usage to specify the 445 base URI. 447 5.5. Naming Conventions 449 In addition to defining the meaning of the document in the context of 450 a particular application, an application usage has to specify how the 451 applications obtain the documents they need. In particular, it needs 452 to define any well-known URIs used for bootstrapping purposes, and 453 document any other conventions on the URIs used by an application. 454 It should also document how documents reference each other. These 455 conventions are called naming conventions. 457 For many application usages, users need only a single document. In 458 such a case, it is RECOMMENDED that the application usage require 459 that this document be called "index" and exist within the users home 460 directory. 462 As an example, the RLS services application usage allows an RLS to 463 obtain the contents of a resource list when the RLS receives a 464 SUBSCRIBE request for a SIP URI identifying an RLS service. The 465 application usage specifies that the list of service definitions is 466 present within a specific document with a specific name within the 467 global tree. This allows the RLS to perform a single XCAP request to 468 fetch the service definition for the service associated with the SIP 469 URI in a SUBSCRIBE request. 471 Naming conventions are used by XCAP clients to construct their URIs. 472 The XCAP server does not make use of them. 474 5.6. Resource Interdependencies 476 When a user modifies an XCAP resource, the content of many other 477 resources is affected. For example, when a user deletes an XML 478 element within a document, it does so by issuing a DELETE request 479 against the URI for the element resource. However, deleting this 480 element also deletes all child elements and their attributes, each of 481 which is also an XCAP resource. As such, manipulation of one 482 resource affects the state of other resources. 484 For the most part, these interdependencies are fully specified by the 485 XML schema used by the application usage. However, in some 486 application usages, there is a need for the server to relate 487 resources together, and such a relationship cannot be specified 488 through a schema. This occurs when changes in one document will 489 affect another document. Typically, this is the case when an 490 application usage is defining a document that acts as a collection of 491 information defined in other documents. 493 As an example, when a user creates a new RLS service (that is, it 494 creates a new element within an RLS services document), the 495 server adds that element to a read-only global list of services 496 maintained by the server in the global tree. This read-only global 497 list is accessed by the RLS when processing a SIP SUBSCRIBE request. 499 Resource interdependencies are used by both XCAP clients and servers. 501 5.7. Authorization Policies 503 By default, each user is able to access (read, modify, and delete) 504 all of the documents below their home directory, and any user is able 505 to read documents within the global directory. However, only trusted 506 users, explicitly provisioned into the server, can modify global 507 documents. 509 The application usage can specify a different authorization policy 510 that applies to all documents associated with that application usage. 511 An application usage can also specify whether another application 512 usage is used to define the authorization policies. An application 513 usage for setting authorization policies can also be defined 514 subsequent to the definition of the the main application usage. In 515 such a case, the main application usage needs only to specify that 516 such a usage will be defined in the future. 518 If an application usage does not wish to change the default 519 authorization policy, it can merely state that the default policy is 520 used. 522 The authorization policies defined by the application usage are used 523 by the XCAP server during its operation. 525 5.8. Data Extensibility 527 An XCAP server MUST understand an application usage in order to 528 process an HTTP request made against a resource for that particular 529 application usage. However, it is not required for the server to 530 understand all of the contents of a document used by an application 531 usage. A server is required to understand the baseline schema 532 defined by the application usage. However, those schemas can define 533 points of extensibility where new content can be added from other 534 namespaces and corresponding schemas. Sometimes, the server will 535 understand those namespaces and therefore have access to their 536 schemas. Sometimes, it will not. 538 A server MUST allow for documents that contain elements from 539 namespaces not known to the server. In such a case, the server 540 cannot validate that such content is schema compliant; it will only 541 verify that the XML is well-formed. 543 If a client wants to verify that a server supports a particular 544 namespace before operating on a resource, it can query the server for 545 its capabilities using the XCAP Capabilities application usage, 546 discussed in Section 12. 548 5.9. Documenting Application Usages 550 Application usages are documented in specifications which convey the 551 information described above. In particular, an application usage 552 specification MUST provide the following information: 554 o Application Unique ID (AUID): If the application usage is meant 555 for general use on the Internet, the application usage MUST 556 register the AUID into the IETF tree using the IANA procedures 557 defined in Section 15. 559 o XML Schema 561 o Default Namespace 563 o MIME Type 565 o Validation Constraints 567 o Data Semantics 569 o Naming Conventions 571 o Resource Interdependencies 573 o Authorization Policies 575 5.10. Guidelines for Creating Application Usages 577 The primary design task when creating a new application usage is to 578 define the schema. Although XCAP can be used with any XML document, 579 intelligent schema design will improve the efficiency and utility of 580 the document when it is manipulated with XCAP. 582 XCAP provides three fundamental ways to select elements amongst a set 583 of siblings - by the expanded name of the element, by its position, 584 or by the value of a specific attribute. Positional selection always 585 allows a client to get exactly what it wants. However, it requires a 586 client to cache a copy of the document in order to construct the 587 predicate. Furthermore, if a client performs a PUT, it requires the 588 client to reconstruct the PUT processing that a server would follow 589 in order to update its local cached copy. Otherwise, the client will 590 be forced to re-GET the document after every PUT, which is 591 inefficient. As such, it is a good idea to design schemas such that 592 common operations can be performed without requiring the client to 593 cache a copy of the document. 595 Without positional selection, a client can pick the element at each 596 step by its expanded name or the value of an attribute. Many schemas 597 include elements that can be repeated within a parent (often, 598 minOccurs equals zero or one, and maxOccurs is unbounded). As such, 599 all of the elements have the same name. This leaves the attribute 600 value as the only way to select an element. Because of this, if an 601 application usage expects user to manipulate elements or attributes 602 that are descendants of an element which can repeat, that element 603 SHOULD include, in its schema, an attribute which can be suitably 604 used as a unique index. Furthermore, the naming conventions defined 605 by that application usage SHOULD specify this uniqueness constraint 606 explicitly. 608 URIs often make a good choice for such unique index. They have 609 fundamental uniqueness properties, and are also usually of semantic 610 significance in the application usage. However, care must be taken 611 when using a URI as an attribute value. URI equality is usually 612 complex. However, attribute equality is performed by the server 613 using XML rules, which are based on case sensitive string comparison. 614 Thus, XCAP will match URIs based on lexical equality, not functional 615 equality. In such cases, an application usage SHOULD consider these 616 implications carefully. 618 XCAP provides the ability of a client to operate on a single element, 619 attribute or document at a time. As a result, it may be possible 620 that common operations the client might perform will require a 621 sequence of multiple requests. This is inefficient, and introduces 622 the possibility of failure conditions when another client modifies 623 the document in the middle of a sequence. In such a case, the client 624 will be forced to detect this case using entity tags (discussed below 625 in Section 7.11), and undo its previous changes. This is very 626 difficult. 628 As a result, the schemas SHOULD be defined so that common operations 629 generally require a single request to perform. Consider an example. 630 Lets say an application usage is defining permissions for users to 631 perform certain operations. The schema can be designed in two ways. 632 The top level of the tree can identify users, and within each user, 633 there can be the permissions associated with the user. In an 634 alternative design, the top level of the tree identifies each 635 permission, and within that permission, the set of users who have it. 636 If, in this application usage, it is common to change the permission 637 for a user from one value to another, the former schema design is 638 better for xcap; it will require a single PUT to make such a change. 639 In the latter case, either the entire document needs to be replaced 640 (which is a single operation), or two PUT operations need to occur - 641 one to remove the user from the old permission, and one to add the 642 user to the new permission. 644 Naming conventions form another key part of the design of an 645 application usage. The application usage should be certain that XCAP 646 clients know where to "start" to retrieve and modify documents of 647 interest. Generally, this will involve the specification of a well- 648 known document at a well-known URI. That document can contain 649 references to other documents that the client needs to read or 650 modify. 652 6. URI Construction 654 In order to manipulate an XCAP resource, the data must be represented 655 by an HTTP URI. XCAP defines a specific naming convention for 656 constructing these URIs. The URI is constructed by concatenating the 657 XCAP root with the document selector with the node selector separator 658 with a percent-encoded form of the node selector. This is followed 659 by an optional query component that defines namespace bindings used 660 in evaluating the URI. The XCAP root is the enclosing context in 661 which all XCAP resources live. The document selector is a path that 662 identifies a document within the XCAP root. The node selector 663 separator is a path segment with a value of double tilde ("~~"), and 664 SHOULD NOT be percent-encoded, as advised in Section 2.3 of RFC 3986 665 [13]. URIs containing %7E%7E should be normalized to ~~ for 666 comparison; they are equivalent. The node selector separator is 667 piece of syntactic sugar that separates the document selector from 668 the node selector. The node selector is an expression that 669 identifies a component of the document, such as an element or 670 attribute. 672 The sections below describe these components in more detail. 674 6.1. XCAP Root 676 The root of the XCAP hierarchy is called the XCAP root. It defines 677 the context in which all other resources exist. The XCAP root is 678 represented with an HTTP URI, called the XCAP Root URI. This URI is 679 a valid HTTP URI; however, it doesn't point to any resource that 680 actually exists on the server. Its purpose is to identify the root 681 of the tree within the domain where all XCAP documents are stored. 682 It can be any valid HTTP URI, but MUST NOT contain a query component 683 (a complete XCAP URI may have a query component, but it is not part 684 of the XCAP root URI). It is RECOMMENDED that it be equal to 685 xcap.domain where domain is the domain of the provider. As an 686 example, "http://xcap.example.com" might be used as the XCAP root URI 687 within the example.com domain. Typically, the XCAP root URI is 688 provisioned into client devices. If not explicitly provisioned, 689 clients SHOULD assume the form xcap.domain where domain is the domain 690 of their service provider (for SIP, this would be the domain part of 691 their Address-of-Record (AOR)). A server or domain MAY support 692 multiple XCAP root URIs. In such a case, it is effectively operating 693 as if it were serving separate domains. There is never information 694 carryover or interactions between resources in different XCAP root 695 URIs. 697 When a client generates an HTTP request to a URI identifying an XCAP 698 resource, RFC 2616 procedures for the construction of the Request-URI 699 apply. In particular, the authority component of the URI may not be 700 present in the Request-URI if the request is sent directly to the 701 origin server. 703 The XCAP root URI can also be a relative HTTP URI. It is the 704 responsibility of the application usage to specify the base URI for 705 an HTTP URI representing an XCAP resource whenever such a URI appears 706 within a document defined by that application usage. Generally 707 speaking, it is unsafe to use the retrieval URI as the base URI. 708 This is because any URI that points to an ancestor for a particular 709 element or attribute can contain content including that element or 710 attribute. If that element or attribute contained a relative URI 711 reference, it would be resolved relative to whatever happened to be 712 used to retrieve the content, and this will often not be the base URI 713 defined by the application usage. 715 6.2. Document Selector 717 Each document within the XCAP root is identified by its document 718 selector. The document selector is a sequence of path segments, 719 separated by a slash ("/"). These path segments define a 720 hierarchical structure for organizing documents within any XCAP root. 721 The first path segment MUST be the XCAP AUID. So, continuing the 722 example above, all of the documents used by the resource lists 723 application would be under "http://xcap.example.com/resource-lists". 725 It is assumed that each application will have data that is set by 726 users, and/or it will have global data that applies to all users. As 727 a result, beneath each AUID there are two sub-trees. One, called 728 "users", holds the documents that are applicable to specific users, 729 and the other, called "global", holds documents applicable to all 730 users. The subtree beneath "global" is called the global tree. The 731 path segment after the AUID MUST either be "global" or "users". 733 Within the "users" tree are zero or more sub-trees, each of which 734 identifies documents that apply to a specific user. Each user known 735 to the server is associated with a username, called the XCAP User 736 Identifier (XUI). Typically, an endpoint is provisioned with the 737 value of the XUI. For systems that support SIP applications, it is 738 RECOMMENDED that the XUI be equal to the Address-of-Record (AOR) for 739 the user (i.e., sip:joe@example.com). Since SIP endpoints generally 740 know their AOR, they will also know their XUI. As a consequence, if 741 no XUI is explicitly provisioned, a SIP UA SHOULD assume it is equal 742 to their AOR. This XUI MUST be used as the path segment beneath the 743 "users" segment. Since the SIP URI allows for characters which are 744 not permitted in HTTP URI path segments (such as the '?' and '/' 745 characters, which are permitted in the user part of the SIP URI), any 746 such characters MUST be percent encoded. The subtree beneath an XUI 747 for a particular user is called their home directory. "User" in this 748 context should be interpreted loosely; a user might correspond to 749 device, for example. 751 XCAP does not itself define what it means for documents to "apply" to 752 a user, beyond specification of a baseline authorization policy, 753 described below in Section 8. Each application usage can specify 754 additional authorization policies which depend on data used by the 755 application itself. 757 The remainder of the document selector (the path following "global" 758 or the XUI) points to specific documents for that application usage. 759 Subdirectories are permitted, but are NOT RECOMMENDED. XCAP provides 760 no way to create sub-directories or to list their contents, thus 761 limiting their utility. If subdirectories are used, there MUST not 762 be a document in a directory with the same name as a sub-directory. 764 The final path segment in the document selector identifies the actual 765 document in the hierarchy. This is equivalent to a filename, except 766 that XCAP does not require that its document resources be stored as 767 files in a file system. However, the term "filename" is used to 768 describe the final path segment in the document selector. In 769 traditional filesystems, the filename would have a filename 770 extension, such as ".xml". There is nothing in this specification 771 that requires or prevents such extensions from being used in the 772 filename. In some cases, the application usage will specify a naming 773 convention for documents, and those naming conventions may or may not 774 specify a file extension. For example, in the RLS services 775 application usage [22], documents in the user's home directory with 776 the filename "index" will be used by the server to compute the global 777 index, which is also a document with the filename "index". Barring 778 specific guidelines in the application usage, if a user has a single 779 document for a particular application usage, this SHOULD be called 780 "index". 782 When the naming conventions in an application usage do not constrain 783 the filename conventions (or, more generally, the document selector), 784 an application will know the filename (or more generally, the 785 document selector) because it is included as a reference in a 786 document which is at a well known location. As another example, 787 within the index document defined by RLS services, the 788 element has a child element called whose content is a 789 URI pointing to a resource list within the users home directory. 791 As a result, if the user creates a new document, and then references 792 that document from a well-known document (such as the index document 793 above), it doesn't matter whether the user includes an extension in 794 the filename or not, as long as the user is consistent and maintains 795 referential integrity. 797 As an example, the path segment 798 "/resource-lists/users/sip:joe@example.com/index" is a document 799 selector. Concatenating the XCAP root URI with the document selector 800 produces the HTTP URI "http://xcap.example.com/resource-lists/users/ 801 sip:joe@example.com/index". In this URI, the AUID is "resource- 802 lists", and the document is in the user tree with the XUI 803 "sip:joe@example.com" with filename "index". 805 6.3. Node Selector 807 The node selector specifies specific nodes of the XML document which 808 are to be accessed. A node refers to an XML element, an attribute of 809 an element, or a set of namespace bindings. The node selector is an 810 expression which identifies an element, attribute or set of namespace 811 bindings. Its grammar is: 813 node-selector = element-selector ["/" terminal-selector] 814 terminal-selector = attribute-selector / namespace-selector / 815 extension-selector 816 element-selector = step *( "/" step) 817 step = by-name / by-pos / by-attr / by-pos-attr / 818 extension-selector 819 by-name = NameorAny 820 by-pos = NameorAny "[" position "]" 821 position = 1*DIGIT 822 attr-test = ( "@" att-name "=" <"> att-value <"> ) / 823 ( "@" att-name "=" <'> att-value <'> ) 824 by-attr = NameorAny "[" attr-test "]" 825 by-pos-attr = NameorAny "[" position "]" "[" attr-test "]" 826 NameorAny = QName / "*" ; QName from XML Namespaces 827 att-name = QName 828 att-value = AttValue ; from XML specification 829 attribute-selector = "@" att-name 830 namespace-selector = "namespace::*" 831 extension-selector = 1*( %x00-2e / %x30-ff ) ; anything but "/" 833 The QName grammar is defined in the XML namespaces [3] specification, 834 and the AttValue grammar is defined in the XML specification XML 1.0 835 [1]. 837 The extension-selector is included for purposes of extensibility. It 838 can be composed of any character except the slash, which is the 839 delimeter amongst steps. Any characters in an extension that cannot 840 be represented in a URI MUST be percent-encoded before placement into 841 a URI. 843 Note that the double quote, left square bracket and right square 844 bracket characters, which are meaningful to XCAP, cannot be directly 845 represented in the HTTP URI. As a result, they are percent-encoded 846 when placed within the HTTP URI. In addition to these characters, an 847 apostrophe (') character can be used as a delimiter within XPath 848 expressions. Furthermore, since XML allows for non-ASCII characters, 849 the names of elements and attributes may not be directly 850 representable in a URI. Any such characters MUST be represented by 851 converting them to an octet sequence corresponding to their 852 representation in UTF-8, and then percent-encoding that sequence of 853 octets. 855 Similarly, the XML specification defines the QName production for the 856 grammar for element and attribute names, and the AttValue production 857 for the attribute values. Unfortunately, the characters permitted by 858 these productions include some that are not allowed for pchar, which 859 is the production for the allowed set of characters in path segments 860 in the URI. The AttValue production allows many such characters 861 within the US-ASCII set, including the space. Those characters MUST 862 be percent- encoded when placed in the URI. Furthermore, QName and 863 AttValue allow many Unicode characters, outside of US-ASCII. When 864 these characters need to be represented in the HTTP URI, they are 865 percent- encoded. To do this, the data should be encoded first as 866 octets according to the UTF-8 character encoding [18] and then only 867 those octets that do not correspond to characters in the pchar set 868 should be percent-encoded. For example, the character A would be 869 represented as "A", the character LATIN CAPITAL LETTER A WITH GRAVE 870 would be represented as "%C3%80", and the character KATAKANA LETTER A 871 would be represented as "%E3%82%A2". 873 As a result, the grammar above represents the expressions processed 874 by the XCAP server internally after it has decoded the URI. The on- 875 the-wire format is dictated by RFC 3986 [13]. In the discussions and 876 examples below, when the node selectors are not part of an HTTP URI, 877 they are presented in their internal format prior to encoding. If an 878 example includes a node selector within an HTTP URI, it is presented 879 in its percent-encoded form. 881 The node selector is based on the concepts in XPath [10]. Indeed, 882 the node selector expression, before it is percent-encoded for 883 representation in the HTTP URI, happens to be a valid XPath 884 expression. However, XPath provides a set of functionality far 885 richer than is needed here, and its breadth would introduce much 886 unneeded complexity into XCAP. 888 To determine the XML element, attribute or namespace bindings 889 selected by the node selector, processing begins at the root node of 890 the XML document. The first step in the element selector is then 891 taken. Each step chooses a single XML element within the current 892 document context. The document context is the point within the XML 893 document from which a specific step is evaluated. The document 894 context begins at the root node of the document. When a step 895 determines an element within that context, that element becomes the 896 new context for evaluation of the next step. Each step can select an 897 element by its name (expanded), by a combination of name and 898 attribute value, by name and position, or by name, position and 899 attribute. In all cases, the name can be wildcarded, so that all 900 elements get selected. 902 The selection operation operates as follows. Within the current 903 document context, the children of that context are enumerated in 904 document order. If the context is the root node of the document, its 905 child element is the root element of the document. If the context is 906 an element, its children are all of the children of that element 907 (naturally). Next, those elements whose name is not a match for 908 NameorAny are discarded. An element name is a match if NameorAny is 909 the wildcard, or, if its not a wildcard, the element name matches 910 NameorAny. Matching is discussed below. The result is an ordered 911 list of elements. 913 The elements in the list are further filtered by the predicates, 914 which are the expressions in square brackets following NameorAny. 915 Each predicate further prunes the elements from the current ordered 916 list. These predicates are evaluated in order. If the content of 917 the predicate is a position, the position-th element is selected 918 (that is, treat "position" as a variable, and take the element whose 919 position equals that variable), and all others are discarded. If 920 there are fewer elements in the list than the value of position, the 921 result is a no-match. 923 If the content of the predicate is an attribute name and value, all 924 elements possessing that attribute with that value are selected, and 925 all others are discarded. Note that, although a document can have 926 namespace declarations within elements, those elements cannot be 927 selected using a namespace declaration as a predicate. That is, a 928 step like "el-name[@xmlns='namespace']" will never match an element, 929 even if there is an element in the list that specifies a default 930 namespace of "namespace". In other words, a namespace node is NOT an 931 attribute. If the namespaces in scope for an element are needed, 932 they can be selected using the namespace-selector described below. 933 If there are no elements with attributes having the given name and 934 value, the result is a no-match. 936 After the predicates have been applied, the result will be a no- 937 match, one element, or multiple elements. If the result is multiple 938 elements, the node selector is invalid. Each step in a node selector 939 MUST produce a single element to form the context for the next step. 940 This is more restrictive than general XPath expressions, which allow 941 a context to contain multiple nodes. If the result is a no-match, 942 the node selector is invalid. The node selector is only valid if a 943 single element was selected. This element becomes the context for 944 the evaluation of the next step in the node selector expression. 946 The last location step is either the previously described element 947 selector or a "terminal selector". If the terminal selector is an 948 attribute selector, the server checks to see if there is an attribute 949 with the same expanded name in the current element context. If there 950 is not, the result is considered a no-match. Otherwise, that 951 attribute is selected. If the terminal selector is a namespace 952 selector, the result is equal to the set of namespace bindings in 953 scope for the element, including the possible default namespace 954 declaration. This specification defines a syntax for representing 955 namespace bindings, so they can be returned to the client in an HTTP 956 response. 958 As a result, once the entire node selector is evaluated against the 959 document, the result will either be a no-match, invalid, a single 960 element, a single attribute or a set of namespace bindings. 962 Matching of element names is performed as follows. The element being 963 compared in the step has its name expanded as described in XML 964 namespaces [3]. The element name in the step is also expanded. This 965 expansion requires that any namespace prefix is converted to its 966 namespace URI. Doing that requires a set of bindings from prefixes 967 to namespace URIs. This set of bindings is obtained from the query 968 component of the URI (see Section 6.4). If the prefix of the QName 969 of an element is empty, the corresponding URI is then the default 970 namespace URI defined by the application usage, or null if not 971 defined. Comparisons are then performed as described in XML 972 namespaces [3]. Note that the namespace prefix expansions described 973 here are different than those specified in the XPath 1.0 974 specification, but are closer to those currently defined by the XPath 975 2.0 specification [24]. 977 Matching of attribute names proceeds in a similar way. The attribute 978 in the document has its name expanded as described in XML namespaces 979 [3]. If the attribute name in the attribute selector has a namespace 980 prefix, its name is expanded using the namespace bindings obtained 981 from the query component of the URI. An unprefixed attribute QName 982 is in no namespace. 984 Comments, text content (including whitespace), and processing 985 instructions can be present in a document, but cannot be selected by 986 the expressions defined here. Of course, if such information is 987 present in a document, and a user selects an XML element enclosing 988 that data, that information would be included in a resulting GET, for 989 example. Furthermore, whitespace is respected by XCAP. If a client 990 PUTs an element or document that contains whitespace, the server 991 retains that whitespace, and will return the element or document back 992 to the client with exactly the same whitespace. Similarly, when an 993 element is inserted, no additional whitespace is added around the 994 inserted element, and the element gets inserted in a very specific 995 location relative to any whitespace, comments or processing 996 instructions around it. Section 8.2.3 describes where the insertion 997 occurs. 999 As an example, consider the following XML document: 1001 1002 1004 1006 sip:userA@example.net 1010 sip:userB@example.org 1014 1015 1017 Figure 3: Example XML Document 1019 Assuming that the default namespace URI for this application usage is 1020 "urn:ietf:params:xml:ns:watcherinfo", the node selector watcherinfo/ 1021 watcher-list/watcher[@id="8ajksjda7s"] would select the following XML 1022 element: 1024 sip:userA@example.net 1029 6.4. Namespace Bindings for the Selector 1031 In order to expand the namespace prefixes used in the node selector, 1032 a set of bindings from those namespace prefixes to namespace URI must 1033 be used. Those bindings are contained in the query component of the 1034 URI. If no query component is present, it means that only the 1035 default namespace URI (as identified by the application usage) is 1036 defined. The query component is formatted as a valid xpointer 1037 expression [5] after suitable URI encoding as defined in Section 4.1 1038 of the Xpointer framework. This xpointer expression SHOULD only 1039 contain expressions from the xmlns() scheme [4]. A server compliant 1040 to this specification MUST ignore any xpointer expressions not from 1041 the xmlns() scheme. The xmlns() xpointer expressions define the set 1042 of namespace bindings in use for evaluating the URI. 1044 Note that xpointer expressions were originally designed for usage 1045 within fragment identifiers of URIs. However, within XCAP, they are 1046 used within query components of URIs. 1048 The following example shows a more complex matching operation, this 1049 time including the usage of namespace bindings. Consider the 1050 following document: 1052 1053 1054 1056 1057 1058 1059 1060 1061 1062 1064 Assume that this document has a document URI of 1065 "http://xcap.example.com/test/users/sip:joe@example.com/index", where 1066 "test" is the application usage. This application usage defines a 1067 default namespace URI of "urn:test:default-namespace". The XCAP URI: 1069 http://xcap.example.com/test/users/sip:joe@example.com/index/ 1070 ~~/foo/a:bar/b:baz?xmlns(a=urn:test:namespace1-uri) 1071 xmlns(b=urn:test:namespace1-uri) 1073 will select the first child element of the element in the 1074 document. The XCAP URI: 1076 http://xcap.example.com/test/users/sip:joe@example.com/index/ 1077 ~~/foo/a:bar/b:baz?xmlns(a=urn:test:namespace1-uri) 1078 xmlns(b=urn:test:namespace2-uri) 1080 will select the second child element of the element in 1081 the document. The following XCAP URI will also select the second 1082 element in the document: 1084 http://xcap.example.com/test/users/sip:joe@example.com/index/ 1085 ~~/d:foo/a:bar/b:baz?xmlns(a=urn:test:namespace1-uri) 1086 xmlns(b=urn:test:namespace2-uri) 1087 xmlns(d=urn:test:default-namespace) 1089 7. Client Operations 1091 An XCAP client is an HTTP/1.1 compliant client. Specific data 1092 manipulation tasks are accomplished by invoking the right set of HTTP 1093 methods with the right set of headers on the server. This section 1094 describes those in detail. 1096 In all cases where the client modifies a document, by deleting or 1097 inserting a document, element or attribute resource, the client 1098 SHOULD verify that, if the operation were to succeed, the resulting 1099 document would meet the data constraints defined by the application 1100 usage, including schema validation. For example, if the client 1101 performs a PUT operation to 1102 "http://xcap.example.com/rls-services/users/joe/mybuddies", rls- 1103 services is the application unique ID, and the constraints defined by 1104 it SHOULD be followed. 1106 The client will know what URI to use based on the naming conventions 1107 described by the application usage. 1109 If the document, after modification, does not meet the data 1110 constraints, the server will reject it with a 409. The 409 response 1111 may contain an XML body, formatted according to the schema in 1112 Section 11.2, which provides further information on the nature of the 1113 error. The client MAY use this information to try and alter the 1114 request so that this time, it might succeed. The client SHOULD NOT 1115 simply retry the request without changing some aspect of it. 1117 In some cases, the application usage will dictate a uniqueness 1118 constraint that the client cannot guarantee on its own. One such 1119 example is that a URI has to be unique within a domain. Typically, 1120 the client is not the owner of the domain, and so it cannot be sure 1121 that a URI is unique. In such a case, the client can either generate 1122 a sufficiently random identifier, or it can pick a "vanity" 1123 identifier in the hopes that it is not taken. In either case, if the 1124 identifier is not unique, the server will reject the request with a 1125 409 and suggest alternatives that the client can use to try again. 1126 If the server does not suggest alternatives, the client SHOULD 1127 attempt to use random identifiers with increasing amounts of 1128 randomness. 1130 HTTP also specifies that PUT and DELETE requests are idempotent. 1131 This means that, if the client performs a PUT on a document and it 1132 succeeds, it can perform the same PUT, and the resulting document 1133 will look the same. Similarly, when a client performs a DELETE, if 1134 it succeeds, a subsequent DELETE to the same URI will generate a 404; 1135 the resource no longer exists on the server since it was deleted by 1136 the previous DELETE operation. To maintain this property, the client 1137 SHOULD construct its URIs such that, after the modification has taken 1138 place, the URI in the request will point to the resource just 1139 inserted for PUT (i.e., the body of the request), and will point to 1140 nothing for DELETE. If this property is maintained, it is the case 1141 that GET to the URI in the PUT will return the same content (i.e., 1142 GET(PUT(X)) == x). This property implies idempotency. Although a 1143 request can still be idempotent if it does not possess this property, 1144 XCAP does not permit such requests. If the client's request does not 1145 have this property, the server will reject the request with a 409 and 1146 indicate a cannot-insert error condition. 1148 If the result of the PUT is a 200 or 201 response, the operation was 1149 successful. Other response codes to any request, such as a 1150 redirection, are processed as per RFC 2616 [6]. 1152 7.1. Create or Replace a Document 1154 To create or replace a document, the client constructs a URI that 1155 references the location where the document is to be placed. This URI 1156 MUST be a document URI, and therefore contain the XCAP root and 1157 document selector. The client then invokes a PUT method on that URI. 1159 The MIME content type MUST be the type defined by the application 1160 usage. For example, it would be "application/rls-services+xml" for 1161 an RLS services [22] document, and not "application/xml". 1163 If the Request-URI identifies a document that already exists in the 1164 server, the PUT operation replaces that document with the content of 1165 the request. If the Request-URI does not identify an existing 1166 document, the document is created on the server at that specific URI. 1168 7.2. Delete a Document 1170 To delete a document, the client constructs a URI that references the 1171 document to be deleted. This URI MUST be a document URI. The client 1172 then invokes a DELETE operation on the URI to delete the document. 1174 7.3. Fetch a Document 1176 As one would expect, fetching a document is trivially accomplished by 1177 performing an HTTP GET request with the Request URI set to the 1178 document URI. 1180 7.4. Create or Replace an Element 1182 To create or replace an XML element within an existing document, the 1183 client constructs a URI whose document selector points to the 1184 document to be modified. The node selector MUST be present in the 1185 URI, delimited from the document selector with the node selector 1186 separator. The query component MUST be present if the node selector 1187 makes use of namespace prefixes, in which case the xmlns() 1188 expressions in the query component MUST define those prefixes. To 1189 create this element within the document, the node selector is 1190 constructed such that it is a no-match against the current document, 1191 but if the element in the body of the request was added to the 1192 document as desired by the client, the node selector would select 1193 that element. To replace an element in the document, the node 1194 selector is constructed so that it is a match against the element in 1195 the current document to be replaced, as well as a match to the new 1196 element (present in the body of the PUT request) that is to replace 1197 it. 1199 Oftentimes, the client will wish to insert an element into a document 1200 in a certain position relative to other children of the same parent. 1201 This is called a positional insertion. They often arise because the 1202 schema constrains where the element can occur, or because ordering of 1203 elements is significant within the schema. To accomplish this, the 1204 client can use a node selector of the following form: 1206 parent/*[position][unique-attribute-value] 1208 Here, "parent" is an expression for the parent of the element to be 1209 inserted. "position" is the position amongst the existing child 1210 elements of this parent where the new element is to be inserted. 1211 "unique-attribute-value" is an attribute name and value for the 1212 element to be inserted, which is different from the current element 1213 in "position". The second predicate is needed so that the overall 1214 expression is a no-match when evaluated against the current children. 1215 Otherwise, the PUT would replace the existing element in that 1216 position. Note that in addition to wildcard "*" a QName can also be 1217 used as a node test. The insert logic is described in more detail in 1218 Section 8.2.3. 1220 Consider the example document in Figure 3. The client would like to 1221 insert a new element as the second element underneath 1222 . However, it cannot just PUT to a URI with the 1223 watcherinfo/watcher-list/*[2] node selector; this node selector would 1224 select the existing 2nd child element of and replace 1225 it. Thus, the PUT has to be made to a URI with watcherinfo/ 1226 watcher-list/*[2][@id="hhggff"] as the node selector, where "hhggff" 1227 is the value of the "id" attribute of the new element to be inserted. 1228 This node-selector is a no-match against the current document, and 1229 would be a match against the new element if it was inserted as the 1230 2nd child element of . 1232 The "*" indicates that all element children of are to 1233 be considered when computing the position for insertion. If, instead 1234 of a wildcard *, an element name (QName) was present, the expression 1235 above would insert the new element as the position-th element amongst 1236 those with the same expanded name (see Section 8.2.3 for a discussion 1237 on insertion rules). 1239 Once the client constructs the URI, it invokes the HTTP PUT method. 1240 The content in the request MUST be an XML element. Specifically, it 1241 contains the element, starting with the opening bracket for the begin 1242 tag for that element, including the attributes and content of that 1243 element (whether it be text or other child elements), and ending with 1244 the closing bracket for the end tag for that element. The MIME type 1245 in the request MUST be "application/xcap-el+xml", defined in 1246 Section 15.2.1. If the node selector, when evaluated against the 1247 current document, results in a no-match, the server performs a 1248 creation operation. If the node selector, when evaluated against the 1249 current document, is a match for an element in the current document, 1250 the server replaces it with the content of the PUT request. This 1251 replacement is complete; that is, the old element (including its 1252 attributes, namespace declarations and content: text, element, 1253 comment and processing instruction nodes) are removed, and the new 1254 one, including its attributes, namespace declarations and content, is 1255 put in its place. 1257 To be certain that element insertions have the GET(PUT(x))==x 1258 property, the client can check that the attribute predicates in the 1259 final path segment of the URI match the attributes of the element in 1260 the body of the request. As an example of an request that would not 1261 have this property and therefore not be idempotent, consider the 1262 following PUT request (URIs are line-folded for readability): 1264 PUT 1265 /rls-services/users/sip:bill@example.com/index/~~/rls-services/ 1266 service%5b@uri=%22sip:good-friends@example.com%22%5d 1267 HTTP/1.1 1268 Content-Type:application/xcap-el+xml 1269 Host: xcap.example.com 1271 1272 http://xcap.example.com/resource-lists/users 1273 /sip:joe@example.com/index/~~/resource-lists/list%5b@name=%22l1%22%5d 1274 1275 1276 presence 1277 1278 1280 This request will fail with a 409. The Request URI contains a final 1281 path segment with a predicate based on attributes - 1282 @uri="sip:good-friends@example.com". However, this will not match 1283 the value of the "uri" attribute in the element in the body 1284 (sip:mybuddies@example.com). 1286 The GET(PUT(x))==x property introduces some limitations on the types 1287 of operations possible. It will not be possible to replace an 1288 element with one that has a new value for an attribute that is the 1289 sole unique element identifier, if the URI contained a node selector 1290 which was using the previous value of that attribute for purposes of 1291 selecting the element. This is exactly the use case in the example 1292 above. To get around this limitation, the selection can be done by 1293 position instead of attribute value, or the parent of the element to 1294 be replaced can be selected, and then the body of the PUT operation 1295 would contain the parent, the child to be replaced, and all other 1296 siblings. 1298 7.5. Delete an Element 1300 To delete an element from a document, the client constructs a URI 1301 whose document selector points to the document containing the element 1302 to be deleted. The node selector MUST identify a single element. 1303 The node selector MUST be present following the node selector 1304 separator, and identify the specific element to be deleted. 1305 Furthermore, the node selector MUST match no element after the 1306 deletion of the target element. This is required to maintain the 1307 idempotency property of HTTP deletions. The query component MUST be 1308 present if the node selector makes use of namespace prefixes, in 1309 which case the xmlns() expressions in the query component MUST define 1310 those prefixes. 1312 If the client wishes to delete an element in a specific position, 1313 this is referred to as a positional deletions. Like a positional 1314 insertion, the node selector has the following form: 1316 parent/*[position][unique-attribute-value] 1318 Where "parent" is an expression for the parent of the element to be 1319 deleted, "position" is the position of the element to be deleted 1320 amongst the existing child elements of this parent, and "unique- 1321 attribute-value" is an attribute name and value for the element to be 1322 deleted, where this attribute name and value are different than any 1323 of the siblings of the element. 1325 Positional deletions without using a unique attribute name and value 1326 are possible, but only in limited cases where idempotency is 1327 guaranteed. In particular, if a DELETE operation refers to an 1328 element by name and position alone (parent/elname[n]), this is 1329 permitted only when the element to be deleted is the last element 1330 amongst all its siblings with that name. Similarly, if a DELETE 1331 operation refers to an element by position alone (parent/*[n]), this 1332 is permitted only when the elemented to be deleted is the last 1333 amongst all sibling elements, regardless of name. 1335 The client then invokes the HTTP DELETE method. The server will 1336 remove the element from the document (including its attributes, 1337 namespace declarations and its descendant nodes, such as any 1338 children). 1340 7.6. Fetch an Element 1342 To fetch an element of a document, the client constructs a URI whose 1343 document selector points to the document containing the element to be 1344 fetched. The node selector MUST be present following the node 1345 selector separator, and must identify the element to be fetched. The 1346 query component MUST be present if the node selector makes use of 1347 namespace prefixes, in which case the xmlns() expressions in the 1348 query component MUST define those prefixes. 1350 The client then invokes the GET method. The 200 OK response will 1351 contain that XML element. Specifically, it contains the content of 1352 the XML document, starting with the opening bracket for the begin tag 1353 for that element, and ending with the closing bracket for the end tag 1354 for that element. This will, as a result, include all attributes, 1355 namespace declarations and descendant nodes: elements, comments, text 1356 and processing instructions of that element. 1358 7.7. Create or Replace an Attribute 1360 To create or replace an attribute in an existing element of a 1361 document, the client constructs a URI whose document selector points 1362 to the document to be modified. The node selector, following the 1363 node selector separator, MUST be present. The node selector MUST be 1364 constructed such that, if the attribute was created or replaced as 1365 desired, the node selector would select that attribute. If the node 1366 selector, when evaluated against the current document, results in a 1367 no-match, it is a creation operation. If it matches an existing 1368 attribute, it is a replacement operation. The query component MUST 1369 be present if the node selector makes use of namespace prefixes, in 1370 which case the xmlns() expressions in the query component MUST define 1371 those prefixes. 1373 The client then invokes the HTTP PUT method. The content defined by 1374 the request MUST be the value of the attribute, compliant to the 1375 grammar for AttValue as defined in XML 1.0 [1]. Note that, unlike 1376 when AttValue is present in the URI, there is no percent-encoding 1377 which only applies to URIs. This request MUST be sent with the 1378 Content-Type of "application/xcap-att+xml" as defined in 1379 Section 15.2.2. The server will add that attribute such that, if the 1380 node selector is evaluated on the resulting document, it returns the 1381 attribute present in the request. 1383 To be certain that attribute insertions have the GET(PUT(x))==x 1384 property, the client can check that any attribute predicate in the 1385 path segment that selects the element into which the attribute is 1386 inserted, matches a different attribute than the one being inserted 1387 by the request. As an example of a request that would not have this 1388 property and therefore not be idempotent, consider the following PUT 1389 request (URIs are line folded for readability): 1391 PUT 1392 /rls-services/users/sip:bill@example.com/index/~~/rls-services 1393 /service%5b@uri=%22sip:good-friends@example.com%22%5d/@uri 1394 HTTP/1.1 1395 Content-Type:application/xcap-att+xml 1396 Host: xcap.example.com 1398 "sip:bad-friends@example.com" 1400 As with element insertions and replacements, the GET(PUT(x))==x 1401 property introduces limitations on attribute insertions and 1402 replacements. It will not be possible to replace the attribute value 1403 of an attribute, when that attribute is the sole unique element 1404 identifier, and the URI contains a node selector that uses the 1405 previous value of the attribute to select the affected element. This 1406 is the use case in the example above. Instead, the element can be 1407 selected positionally, or its entire parent replaced. 1409 This request will fail with a 409. 1411 7.8. Delete an Attribute 1413 To delete attributes from the document, the client constructs a URI 1414 whose document selector points to the document containing the 1415 attributes to be deleted. The node selector MUST be present 1416 following the node selector separator, and evaluate to an attribute 1417 in the document to be deleted. The query component MUST be present 1418 if the node selector makes use of namespace prefixes, in which case 1419 the xmlns() expressions in the query component MUST define those 1420 prefixes. 1422 The client then invokes the HTTP DELETE method. The server will 1423 remove the attribute from the document. 1425 7.9. Fetch an Attribute 1427 To fetch an attribute of a document, the client constructs a URI 1428 whose document selector points to the document containing the 1429 attribute to be fetched. The node selector MUST be present following 1430 the node selector separator, containing an expression identifying the 1431 attribute whose value is to be fetched. The query component MUST be 1432 present if the node selector makes use of namespace prefixes, in 1433 which case the xmlns() expressions in the query component MUST define 1434 those prefixes. 1436 The client then invokes the GET method. The 200 OK response will 1437 contain an "application/xcap-att+xml" document with the specified 1438 attribute, formatted according to the grammar of AttValue as defined 1439 in the XML 1.0 specifications. 1441 7.10. Fetch Namespace Bindings 1443 If a client wishes to insert an element or attribute into a document, 1444 and that element or attribute are part of a namespace declared 1445 elsewhere in the document, the client will need to know the namespace 1446 bindings in order to construct the XML content in the request. If 1447 the client has a cached copy of the document, it will know the 1448 bindings. However, if it doesn't have the whole document cached, it 1449 can be useful to fetch just the bindings that are in scope for an 1450 element, in order to construct a subsequent PUT request. 1452 To get those bindings, the client constructs a URI whose document 1453 selector points to the document containing the element whose 1454 namespace bindings are to be fetched. The node selector MUST be 1455 present following the node selector separator, containing an 1456 expression identifying the desired namespace bindings. The query 1457 component MUST be present if the node selector makes use of namespace 1458 prefixes, in which case the xmlns() expressions in the query 1459 component MUST define those prefixes. 1461 The client then invokes the GET method. The 200 OK response will 1462 contain an "application/xcap-ns+xml" document with the namespace 1463 definitions. The format for this document is defined in Section 10. 1465 A client cannot set the namespace prefixes in scope for an element. 1466 As such, a node selector that identifies namespace prefixes MUST NOT 1467 appear in a PUT or DELETE request. 1469 7.11. Conditional Operations 1471 The HTTP specification defines several header fields that can be used 1472 by a client to make the processing of the request conditional. In 1473 particular, the If-None-Match and If-Match header fields allow a 1474 client to make them conditional on the current value of the entity 1475 tag for the resource. These conditional operations are particularly 1476 useful for XCAP resources. 1478 For example, it is anticipated that clients will frequently wish to 1479 cache the current version of a document. So, when the client starts 1480 up, it will fetch the current document from the server and store it. 1481 When it does so, the GET response will contain the entity tag for the 1482 document resource. Each resource within a document maintained by the 1483 server will share the same value of the entity tag. As a result, the 1484 entity tag returned by the server for the document resource is 1485 applicable to element and attribute resources within the document. 1487 If the client wishes to insert or modify an element or attribute 1488 within the document, but it wants to be certain that the document 1489 hasn't been modified since the client last operated on it, it can 1490 include an If-Match header field in the request, containing the value 1491 of the entity tag known to the client for all resources within the 1492 document. If the document has changed, the server will reject this 1493 request with a 412 response. In that case, the client will need to 1494 flush its cached version, fetch the entire document, and store the 1495 new entity tag returned by the server in the 200 OK to the GET 1496 request. It can then retry the request, placing the new entity tag 1497 in the If-Match header field. If this succeeds, the Etag header 1498 field in the response to PUT contains the entity tag for the resource 1499 that was just inserted or modified. Because all resources in a 1500 document share the same value for their entity tag, this entity tag 1501 value can be applied to the modification of other resources. 1503 A client can also conditionally delete elements or attributes by 1504 including an If-Match header field in DELETE requests. Note that the 1505 200 OK responses to a DELETE will contain an Etag header field, 1506 containing the entity tag for all of the other resources in the 1507 document, even though the resource identified by the DELETE request 1508 no longer exists. 1510 When a client uses conditional PUT and DELETE operations, it can 1511 apply those changes to its local cached copy, and update the value of 1512 the entity tag for the locally cached copy based on the Etag header 1513 field returned in the response. As long as no other clients try to 1514 modify the document, the client will be able to perform conditional 1515 operations on the document without ever having to perform separate 1516 GET operations to synchronize the document and it's entity tags with 1517 the server. If another client tries to modify the document, this 1518 will be detected by the conditional mechanisms, and the client will 1519 need to perform a GET to resynchronize its copy unless it has some 1520 other means to learn about the change. 1522 If a client does not perform a conditional operation, but did have a 1523 cached copy of the document, that cached copy will become invalid 1524 once the operation is performed (indeed, it may have become invalid 1525 even beforehand). Unconditional operations should only be performed 1526 by clients when knowledge of the entire document is not important for 1527 the operation to succeed. 1529 In another example, a client may wish to insert a new element into a 1530 document, but wants to be sure that the insertion will only take 1531 place if that element does not exist. In other words, the client 1532 wants the PUT operation to be a creation, not a replacement. To 1533 accomplish that, the client can insert the If-None-Match header field 1534 into the PUT request, with a value of *. This tells the server to 1535 reject the request with a 412 if resource exists. 1537 As another example, a when a client fetches a document, and there is 1538 an older version cached, it is useful for clients to use a 1539 conditional GET in order to reduce network usage if the cached copy 1540 is still valid. This is done by including, in the GET request, the 1541 If-None-Match header field with a value equal to the current etag 1542 held by the client for the document. The server will only generate a 1543 200 OK reponse if the etag held by the server differs than that held 1544 by the client. If it doesn't differ, the server will respond with a 1545 304 response. 1547 8. Server Behavior 1549 An XCAP server is an HTTP/1.1 compliant origin server. The behaviors 1550 mandated by this specification relate to the way in which the HTTP 1551 URI is interpreted and the content is constructed. 1553 An XCAP server MUST be explicitly aware of the application usage 1554 against which requests are being made. That is, the server must be 1555 explicitly configured to handle URIs for each specific application 1556 usage, and must be aware of the constraints imposed by that 1557 application usage. 1559 When the server receives a request, the treatment depends on the URI. 1560 If the URI refers to an application usage not understood by the 1561 server, the server MUST reject the request with a 404 (Not Found) 1562 response. If the URI refers to a user that is not recognized by the 1563 server, it MUST reject the request with a 404 (Not Found). If the 1564 URI includes extension-selectors that the server doesn't understand, 1565 it MUST reject the request with a 404 (Not Found). 1567 Next, the server authenticates the request. All XCAP servers MUST 1568 implement HTTP Digest [11]. Furthermore, servers MUST implement HTTP 1569 over TLS, RFC 2818 [14]. It is RECOMMENDED that administrators use 1570 an HTTPS URI as the XCAP root URI, so that the digest client 1571 authentication occurs over TLS. 1573 Next, the server determines if the client has authorization to 1574 perform the requested operation on the resource. The application 1575 usage defines the authorization policies. An application usage may 1576 specify that the default is used. This default is described in 1577 Section 5.7. 1579 Next, the server makes sure that it can properly evaluate the request 1580 URI. The server MUST check the node selector in the request URI, if 1581 present. If any qualified names are present that use a namespace 1582 prefix, and that prefix is not defined in an xmlns() expression in 1583 the query component of the request URI, the server MUST reject the 1584 request with a 400 response. 1586 After checking the namespace prefix definitions, the specific 1587 behavior depends on the method and what the URI refers to. 1589 8.1. POST Handling 1591 XCAP resources do not represent processing scripts. As a result, 1592 POST operations to HTTP URIs representing XCAP resources are not 1593 defined. A server receiving such a request for an XCAP resource 1594 SHOULD return a 405. 1596 8.2. PUT Handling 1598 The behavior of a server in receipt of a PUT request is as specified 1599 in HTTP/1.1 Section 9.6 - the content of the request is placed at the 1600 specified location. This section serves to define the notion of 1601 "placement" and "specified location" within the context of XCAP 1602 resources. 1604 If the request URI contained a namespace-selector, the server MUST 1605 reject the request with a 405 (Method Not Allowed) and MUST include 1606 an Allow header field including the GET method. 1608 8.2.1. Locating the Parent 1610 The first step the server performs is to locate the parent, whether 1611 it is a directory or element, in which the resource is to be placed. 1612 To do that, the server removes the last path segment from the URI. 1613 The rest of the URI refers to the parent. This parent can be a 1614 document, element, or prefix of a document selector (called a 1615 directory, even though this specification does not mandate that 1616 documents are actually stored in a filesystem). This URI is called 1617 the parent URI. The path segment that was removed is called the 1618 target selector, and the node (element, document or attribute) it 1619 describes is called the target node. 1621 If the parent URI has no node selector separator, it is referring to 1622 the directory into which the document should be inserted. In normal 1623 XCAP operations, this will be either the users home directory or the 1624 global directory, which will always exist on the server. However, if 1625 an application usage is making use of subdirectories (despite the 1626 fact that this is not recommended), it is possible that the directory 1627 into which the document should be inserted does not exist. In this 1628 case, the server MUST return a 409 response, and SHOULD include a 1629 detailed conflict report including the element. Detailed 1630 conflict reports are discussed in Section 11. If the directory does 1631 exist, the server checks to see if there is a document with the same 1632 filename as the target node. If there is, the operation is the 1633 replacement operation discussed in Section 8.2.4. If it does not 1634 exist, it is the creation operation, discussed in Section 8.2.3. 1636 If the parent URI has a node selector separator, the document 1637 selector is extracted, and that document is retrieved. If the 1638 document does not exist, the server MUST return a 409 response, and 1639 SHOULD include a detailed conflict report including the 1640 element. If it does exist, the node selector is extracted, and 1641 decoded (recall that the node selector is percent-encoded). The node 1642 selector is applied to the document based on the matching operations 1643 discussed in Section 6.3. If the result is a no-match or invalid, 1644 the server MUST return a 409 response, and SHOULD include a detailed 1645 conflict report including the element. 1647 If the node-selector is valid, the server examines the target 1648 selector, and evaluates it within the context of the parent node. If 1649 the target node exists within the parent, the operation is a 1650 replacement, as described in Section 8.2.4. If it does not exist, it 1651 is the creation operation, discussed in Section 8.2.3. 1653 Before performing the replacement or creation, as determined based on 1654 the logic above, the server validates the content of the request as 1655 described in Section 8.2.2 1657 8.2.2. Verifying Document Content 1659 If the PUT request is for a document (the request URI had no node 1660 selector separator), the content of the request body has to be a 1661 well-formed XML document. If it is not, the server MUST reject the 1662 request with a 409 response code. That response SHOULD include a 1663 detailed conflict report including the element. If 1664 the document is well-formed but not UTF-8 encoded, the server MUST 1665 reject the request with a 409 response code. That response SHOULD 1666 include a detailed conflict report including the element. 1667 If the MIME type in the Content-Type header field of the request is 1668 not equal to the MIME type defined for the application usage, the 1669 server MUST reject the request with a 415. 1671 If the PUT request is for an element, the content of the request body 1672 has to be a well-balanced region of an XML document, also known as an 1673 XML fragment body in The XML Fragment Interchange [23] specification, 1674 including only a single element. If it is not, the server MUST 1675 reject the request with a 409 response code. That response SHOULD 1676 include a detailed conflict report including the 1677 element. If the fragment body is well-balanced but contains 1678 characters outside of the UTF-8 character set, the server MUST reject 1679 the request with a 409 response code. That response SHOULD include a 1680 detailed conflict report including the element. If the 1681 MIME type in the Content-Type header field of the request is not 1682 equal to "application/xcap-el+xml", the server MUST reject the 1683 request with a 415. 1685 If the PUT request is for an attribute, the content of the request 1686 body has to be a sequence of characters that comply with the grammar 1687 for AttValue as defined above. If it is not, the server MUST reject 1688 the request with a 409 response code. That response SHOULD include a 1689 detailed conflict report including the element. 1690 If the attribute value is valid but contains characters outside of 1691 the UTF-8 character set, the server MUST reject the request with a 1692 409 response code. That response SHOULD include a detailed conflict 1693 report including the element.If the MIME type in the 1694 Content-Type header field of the request is not equal to 1695 "application/xcap-att+xml", the server MUST reject the request with a 1696 415. 1698 8.2.3. Creation 1700 The steps in this sub-section are followed if the PUT request will 1701 result in the creation of a new document, element or attribute. 1703 If the PUT request is for a document, the content of the request body 1704 is placed into the directory, and its filename is associated with the 1705 target node, which is a document. 1707 If the PUT request is for an element, the server inserts the content 1708 of the request body as a new child element of the parent element 1709 selected in Section 8.2.1. The insertion is done such that, the 1710 request URI, when evaluated, would now point to the element which was 1711 inserted. There exist three possible ways how new elements are 1712 positioned. 1714 First, if there were no other sibling elements with the same expanded 1715 name, and the insertion is not positionally constrained, the new 1716 element is inserted such that it is the last element amongst all 1717 element siblings. Furthermore, if there were comment, text, or 1718 processing instruction nodes after the former last element, they MUST 1719 occur prior to the insertion of the new element. This case occurs 1720 when one of the following are true: 1722 o The element name in the target selector is not wildcarded. There 1723 could be an attribute selector (in which case, it would have to 1724 match an attribute of the element being inserted), and the 1725 position in the target selector will either be absent or have a 1726 value of 1 (a value greater than one would always result in 1727 rejection of the request, since this is the first element with the 1728 given name underneath the parent). 1730 o The element name in the target selector is wildcarded, but there 1731 are no other elements underneath the same parent. There could be 1732 an attribute selector (in which case, it would have to match an 1733 attribute of the element being inserted), and the position in the 1734 target selector will either be absent or have a value of 1 (a 1735 value greater than one would always result in rejection of the 1736 request, since this is the first element underneath the parent). 1738 o The element name in the target selector is wildcarded, and there 1739 are other elements underneath the same parent. However, there is 1740 an attribute selector which matches none of the attributes in the 1741 other sibling elements underneath the parent, but does match an 1742 attribute of the element to be inserted. The position in the 1743 target selector is absent. 1745 Secondly, if there were sibling elements with the same name already 1746 in the document, but the insertion is positionally unconstrained, the 1747 server MUST insert the element such that it is in the "earliest last" 1748 position. "Earliest last" means that the new element MUST be 1749 inserted so that there are no elements after it with the same 1750 expanded name, and for all insertion positions where this is true, it 1751 is inserted such that as many sibling nodes (element, comment, text 1752 or processing instruction) appear after it as possible. This case 1753 occurs when the target selector is defined by a by-name or by-attr 1754 production, and there is no position indicated. 1756 Lastly, if the element is positionally constrained, the server MUST 1757 insert the element so that it is in the "earliest nth" position. 1758 When n>1 and NameofAny is not a wildcard, the element MUST be 1759 inserted so that there are n-1 sibling elements before it with the 1760 same expanded name. If there are not n-1 sibling elements with the 1761 same expanded name, the request will fail. When n>1 and NameorAny is 1762 a wildcard, the element MUST be inserted so that there are n-1 1763 sibling elements before it, each of which can have any expanded name. 1764 If there are not n-1 sibling elements in the document, the request 1765 will fail. In both of these cases, the new element is inserted such 1766 that as many sibling nodes appear after it as possible. When n=1 and 1767 NameorAny is not a wildcard, the insertion is positionally 1768 constrained when an element with the same expanded name already 1769 appears as a child of the same parent. In this case, the new element 1770 MUST appear just before the existing first element with this same 1771 expanded name. When n=1 and NameorAny is wildcarded, the insertion 1772 is positionally constrained when there is also an attribute selector 1773 that didn't match the first sibling of the parent (if it did match, 1774 or was absent, this wouldn't have been an insertion). In this case, 1775 the new element MUST appear just before all existing elements 1776 regardless of their expanded name. 1778 In practice, this insertion logic keeps elements with the same 1779 expanded names closely together. This simplifies the application 1780 logic when the content model is described by XML schema with 1781 rules and maxOccurs="unbounded" cardinalities, like: 1783 1784 1785 1786 1787 1788 1789 1790 1792 Not any element may precede one or multiple elements. 1793 Either or elements may easily be added without wildcards 1794 and positional constraints. Note that if "minOccurs" cardinality of 1795 element were zero and elements don't exist yet, a 1796 positional predicate with the * wildcard MUST be used. 1798 The whole insert logic is best described by complete examples, 1799 consider the following document: 1801 1802 1803 1804 1805 1806 and whose node 1810 selector is root/el1[@att="third"] would result in the following 1811 document: 1813 1814 1815 1816 1817 1818 and the 1827 node selector was root/el3, it would result in the following 1828 document: 1830 1831 1832 1833 1834 1835 1838 A PUT request whose content is and whose node selector 1839 is root/el2[@att="2"] would result in the following document: 1841 1842 1843 1844 1845 1846 1847 1849 It would have been inserted in exactly the same place if the node 1850 selector had been root/el2[2][@att="2"]. However, a selector root/ 1851 *[2][@att="2"] would result in the following document: 1853 1854 1855 1856 1857 1858 1859 1861 Lastly, if the node selector had been root/el2[1][@att="2"] the 1862 result would be: 1864 1865 1866 1867 1868 1869 1870 1872 It is possible that the element cannot be inserted such that the 1873 request URI, when evaluated, returns the content provided in the 1874 request. Such a request is not allowed for PUT. This happens when 1875 the element in the body is not described by the expression in the 1876 target selector. An example of this case is described in 1877 Section 7.4. If this happens the server MUST NOT perform the 1878 insertion, and MUST reject the request with a 409 response. The body 1879 of the response SHOULD contain a detailed conflict report containing 1880 the element. It is important to note that schema 1881 compliance does not play a role while performing the insertion. That 1882 is, the decision of where the element gets inserted is dictated 1883 entirely by the structure of the request-URI, the current document, 1884 and the rules in this specification. 1886 If the PUT request is for an attribute, the server inserts the 1887 content of the request body as the value of the attribute. The name 1888 of the attribute is equal to the att-name from the attribute-selector 1889 in the target selector. 1891 Assuming that the insertion can be accomplished, the server verifies 1892 that the insertion results in a document that meets the constraints 1893 of the application usage. This is dicussed in Section 8.2.5. 1895 8.2.4. Replacement 1897 The steps in this sub-section are followed if the PUT request will 1898 result in the replacement of a document, element or attribute with 1899 the contents of the request. 1901 If the PUT request is for a document, the content of the request body 1902 is placed into the directory, replacing the document with the same 1903 filename. 1905 If the PUT request is for an element, the server replaces the target 1906 node with the content of the request body. As in the creation case, 1907 it is possible that, after replacement, the request URI does not 1908 select the element that was just inserted. If this happens the 1909 server MUST NOT perform the replacement, and MUST reject the request 1910 with a 409 response. The body of the response SHOULD contain a 1911 detailed conflict report containing the element. 1913 If the PUT request is for an attribute, the server sets the value of 1914 the selected attribute to the content of the request body. It is 1915 possible in the replacement case (but not in the creation case), 1916 that, after replacement of the attribute, the request URI no longer 1917 selects the attribute that was just replaced. The scenario in which 1918 this can happen is discussed in Section 7.7. If this is the case, 1919 the server MUST NOT perform the replacement, and MUST reject the 1920 request with a 409 response. The body of the response SHOULD contain 1921 a detailed conflict report containing the element. 1923 8.2.5. Validation 1925 Once the document, element or attribute has been tentatively inserted 1926 the server needs to verify that the resulting document meets the data 1927 constraints outlined by the application usage. 1929 First, the server checks that the final document is compliant to the 1930 schema. If it is not, the server MUST NOT perform the insertion. It 1931 MUST reject the request with a 409 response. That response SHOULD 1932 contain a detailed conflict report containing the element. 1935 Next, the server checks for any uniqueness constraints identified by 1936 the application usage. If the application usage required that a 1937 particular element or attribute had a unique value within a specific 1938 scope, the server would check that this uniqueness property still 1939 exists. If the application usage required that a URI within the 1940 document was unique within the domain, the server checks whether it 1941 is the case. If any of these uniqueness constraints are not met, the 1942 server MUST NOT perform the insertion. It MUST reject the request 1943 with a 409 response. That response SHOULD contain a detailed 1944 conflict report containing the element. That 1945 element can contain suggested values that the client can retry with. 1946 These SHOULD be values that, at the time the server generates the 1947 409, would meet the uniqueness constraints. 1949 The server also checks for URI constraints and other non-schema data 1950 constraints. If the document fails one of these constraints, the 1951 server MUST NOT perform the insertion. It MUST reject the request 1952 with a 409 response. That response SHOULD contain a detailed 1953 conflict report containing the element. That 1954 element indicates that the document failed non-schema data 1955 constraints explicitly called out by the application usage. 1957 Element or attribute removals have similar constraints. The server 1958 checks the document for schema validity and compliance to constraints 1959 defined by the application usage, and rejects the request as 1960 described above if either check fails. 1962 8.2.6. Conditional Processing 1964 A PUT request for an XCAP resource, like any other HTTP resource, can 1965 be made conditional through usage of the If-Match and If-None-Match 1966 header fields. For a replacement, these are processed as defined in 1967 [6]. For an insertion of an element or attribute, conditional 1968 operations are permitted. The entity tag that is used for the 1969 procedures in [6] is the one for all of the resources within the same 1970 document as the parent of the element or attribute being inserted. 1972 One way to think of this is that, logically speaking, on receipt of 1973 the PUT request, the XCAP server instantiates the resource referenced 1974 by the request and assigns it its entity tag, and then applies the 1975 processing of the request. 1977 8.2.7. Resource Interdependencies 1979 Because XCAP resources include elements, attributes and documents, 1980 each of which has its own HTTP URI, the creation or modification of 1981 one resource affects the state of many others. For example, 1982 insertion of a document creates resources on the server for all of 1983 the elements and attributes within that document. After the server 1984 has performed the insertion associated with the PUT, the server MUST 1985 create and/or modify those resources affected by that PUT. The 1986 structure of the document completely defines the inter-relationship 1987 between those resources. 1989 However, the application usage can specify other resource inter- 1990 dependencies. The server MUST create or modify the resources 1991 specified by the application usage. 1993 If the creation or replacement was successful, and the resource 1994 interdependencies are resolved, the server returns a 201 Created or 1995 or 200 OK, respectively. Note that a 201 Created is generated for 1996 creation of new documents, elements, or attributes. A 200 OK 1997 response to PUT MUST not contain any content. Per the 1998 recommendations of RFC 2616, the 201 can contain a Location header 1999 field and entity that identify the resource that was created. 2001 8.3. GET Handling 2003 The semantics of GET are as specified in RFC 2616. This section 2004 clarifies the specific content to be returned for a particular URI 2005 that represents an XCAP resource. 2007 If the request URI contains only a document selector, the server 2008 returns the document specified by the URI if it exists, else returns 2009 a 404 response. The MIME type of the body of the 200 OK response 2010 MUST be the MIME type defined by that application usage (i.e., 2011 "application/resource-lists+xml"). 2013 If the request URI contains a node selector, the server obtains the 2014 document specified by the document selector, and if it is found, 2015 evaluates the node-selector within that document. If no document is 2016 found, or if the node-selector is a no-match or invalid, the server 2017 returns a 404 response. Otherwise, the server returns a 200 OK 2018 response. If the node selector identifies an XML element, that 2019 element is returned in the 200 OK response as an XML fragment body 2020 containing the selected element. The MIME type of the response MUST 2021 be "application/xcap-el+xml". If the node selector identifies an XML 2022 attribute, the value of that attribute is returned in the body of the 2023 response. The MIME type of the response MUST be "application/ 2024 xcap-att+xml". If the node selector identifies a set of namespace 2025 bindings, the server computes the set of namespace bindings in scope 2026 for the element (including the default) and encodes it using the 2027 "application/xcap-ns+xml" format defined in Section 10. That 2028 document is then returned in the body of the response. 2030 GET operations can be conditional, and follow the procedures defined 2031 in [6]. 2033 8.4. DELETE Handling 2035 The semantics of DELETE are as specified in RFC 2616. This section 2036 clarifies the specific content to be deleted for a particular URI 2037 that represents an XCAP resource. 2039 If the request URI contained a namespace-selector, the server MUST 2040 reject the request with a 405 (Method Not Allowed) and MUST include 2041 an Allow header field including the GET method. 2043 If the request URI contains only a document selector, the server 2044 deletes the document specified by the URI if it exists and returns a 2045 200 OK, else returns a 404 response. 2047 If the request URI contains a node selector, the server obtains the 2048 document specified by the document selector, and if it is found, 2049 evaluates the node-selector within that document. If no document is 2050 found, or if the node-selector is a no-match or invalid (note that it 2051 will be invalid if multiple elements or attributes are selected), the 2052 server returns a 404 response. Otherwise, the server removes the 2053 specified element or attribute from the document and performs the 2054 validation checks defined in Section 8.2.5. Note that this deletion 2055 does not include any white space around the element that was deleted; 2056 the XCAP server MUST preserve surrounding whitespace. It is possible 2057 that, after deletion, the request URI selects another element in the 2058 document. If this happens the server MUST NOT perform the deletion, 2059 and MUST reject the request with a 409 response. The body of the 2060 response SHOULD contain a detailed conflict report containing the 2061 element. If the deletion will cause a failure of one 2062 of the constraints, the deletion MUST NOT take place. The server 2063 follows the procedures in Section 8.2.5 for computing the 409 2064 response. If the deletion results in a document that is still valid, 2065 the server MUST perform the deletion, process the resource 2066 interdependencies defined by the application usage, and return a 200 2067 OK response. 2069 DELETE operations can be conditional, and follow the procedures 2070 defined in [6]. 2072 Before the server returns the 200 OK response to a DELETE, it MUST 2073 process the resource interdependencies as defined in Section 8.2.7. 2075 8.5. Managing Etags 2077 An XCAP server MUST maintain entity tags for all resources that it 2078 maintains. This specification introduces the additional constraint 2079 that when one resource within a document (including the document 2080 itself) changes, that resource is assigned a new etag, and all other 2081 resources within that document MUST be assigned the same etag value. 2082 An XCAP server MUST include the Etag header field in all 200 or 201 2083 responses to PUT, GET, and DELETE, assuming the document itself still 2084 exists after the operation. In the case of a DELETE, the entity tag 2085 refers to the value of the entity tag for all other resources after 2086 the deletion of the specified resource has occurred. One way to 2087 think about this is that the server is, logically speaking, re- 2088 instantiating the resource for a brief instant, so that it can have 2089 an entity tag that can be reasonably returned in the response to 2090 DELETE. 2092 XCAP resources do not introduce new requirements on the strength of 2093 the entity tags; as in RFC 2616, weak ones MAY be used if performance 2094 constraints or other conditions make usage of strong ones untenable 2095 for some reason. 2097 As a result of this constraint, when a client makes a change to an 2098 element or attribute within a document, the response to that 2099 operation will convey the entity tag of the resource that was just 2100 affected. Since the client knows that this entity tag value is 2101 shared by all of the other resources in the document, the client can 2102 make conditional requests against other resources using that entity 2103 tag. 2105 9. Cache Control 2107 An XCAP resource is a valid HTTP resource, and therefore, it can be 2108 cached by clients and network caches. Network caches, however, will 2109 not be aware of the interdependencies between XCAP resources. As 2110 such, a change to an element in a document by a client will 2111 invalidate other XCAP resources affected by the change. For 2112 application usages contain data that is likely to be dynamic or 2113 written by clients, servers SHOULD indicate a no-cache directive. 2115 10. Namespace Binding Format 2117 A node-selector can identify a set of namespace bindings that are in 2118 scope for a particular element. In order to convey these bindings in 2119 a GET response, a way is needed to encode them. 2121 Encoding is trivially done by including a single XML element in an 2122 XML fragment body. This element has the same local-name as the 2123 element whose namespace bindings are desired, and also the same 2124 namespace-prefix. The element has an xmlns attribute identifying the 2125 default namespace in scope, and an xmlns:prefix declaration for each 2126 prefix that is in scope. 2128 For example, consider the XML document in Section 6.4. The node- 2129 selector df:foo/df2:bar/df2:baz/namespace::* will select the 2130 namespaces in scope for the element in the document, assuming 2131 the request is accompanied by a query component that contains 2132 xmlns(df=urn:test:default-namespace) and 2133 xmlns(df2=urn:test:namespace1-uri). A GET containing this node 2134 selector and namespace bindings will produce the following result: 2136 2139 It is important to note that the client does not need to know the 2140 actual namespace bindings in order to construct the URI. It does 2141 need to know the namespace URI for each element in the node-selector. 2142 The namespace bindings present in the query component are defined by 2143 the client, mapping those URI to a set of prefixes. The bindings 2144 returned by the server are the actual bindings used in the document. 2146 11. Detailed Conflict Reports 2148 In cases where the server returns a 409 error response, that response 2149 will usually include a document in the body of the response which 2150 provides further details on the nature of the error. This document 2151 is an XML document, formatted according to the schema of 2152 Section 11.2. Its MIME type, registered by this specification, is 2153 "application/xcap-error+xml". 2155 11.1. Document Structure 2157 The document structure is simple. It contains the root element 2158 . The content of this element is a specific error 2159 condition. Each error condition is represented by a different 2160 element. This allows for different error conditions to provide 2161 different data about the nature of the error. All error elements 2162 support a "phrase" attribute, which can contain text meant for 2163 rendering to a human user. 2165 The following error elements are defined by this specification: 2167 : This indicates that the body of the request was 2168 not a well-formed XML document. 2170 : This indicates that the request was supposed to 2171 contain a valid XML fragment body, but did not. Most likely this 2172 is because the XML in the body was malformed or not balanced. 2174 : This indicates that an attempt to insert a document, 2175 element, or attribute failed because the directory, document or 2176 element into which the insertion was supposed to occur does not 2177 exist. This error element can contain an optional 2178 element, which provides an HTTP URI that represents the closest 2179 parent that would be a valid point of insertion. This HTTP URI 2180 MAY be a relative URI, relative to the document itself. Because 2181 this is a valid HTTP URI, its node selector component MUST be 2182 percent-encoded. 2184 : This element indicates that the document 2185 was not compliant to the schema after the requested operation was 2186 performed. 2188 : This indicates that the request was supposed to 2189 contain a valid XML attribute value, but did not. 2191 : This indicates that the requested PUT operation 2192 could not be performed because a GET of that resource after the 2193 PUT would not yield the content of the PUT request. 2195 : This indicates that the requested DELETE operation 2196 could not be performed because it would not be idempotent. 2198 : This indicates that the requested operation 2199 would result in a document that did not meet a uniqueness 2200 constraint defined by the application usage. For each URI, 2201 element or attribute specified by the client which is not unique, 2202 an element is present as the content of the error 2203 element. Each element has a "field" attribute that 2204 contains a relative URI identifying the XML element or attribute 2205 whose value needs to be unique, but wasn't. The relative URI is 2206 relative to the document itself, and will therefore start with the 2207 root element. The query component of the URI MUST be present if 2208 the node selector portion of the URI contains namespace prefixes. 2210 Qualified elements attached with default namespace declaration are 2211 selected as described in Section 6.4. Since the "field" node 2212 selector is a valid HTTP URI, it MUST be percent-encoded. The 2213 element can optionally contain a list of 2214 elements. Each one is a suggested alternate value which does not 2215 currently exist on the server. 2217 : This indicates that the requested operation 2218 would result in a document that failed a data constraint defined 2219 by the application usage, but not enforced by the schema or a 2220 uniqueness constraint. 2222 : This indicates an error condition that is defined by an 2223 extension to XCAP. Clients which do not understand the content of 2224 the extension element MUST discard the xcap-error document and 2225 treat the error as an unqualified 409. 2227 As an example, the following document indicates that the user 2228 attempted to create an RLS service using the URI 2229 sip:friends@example.com, but that URI already exists: 2231 2232 2233 2234 2235 sip:mybuddies@example.com 2236 2237 2238 2240 11.2. XML Schema 2242 2243 2249 2251 2252 2253 Indicates the reason for the error. 2254 2255 2256 2257 2258 2259 2260 2261 2263 2264 2265 2266 2268 2269 2270 2272 2274 2275 This element indicates 2276 that the document was not compliant to the schema after the requested 2277 operation was performed. 2278 2279 2280 2281 2282 2284 2285 2286 This indicates that the request was supposed to 2287 contain a valid XML fragment body, but did not. 2288 2289 2290 2291 2292 2294 2295 2296 This indicates that an attempt to insert 2297 an element, attribute or document failed because the document or 2298 element into which the insertion was 2299 supposed to occur does not exist 2300 2301 2302 2303 2304 2305 Contains an HTTP URI that points to the 2306 element which is the closest ancestor that does exist. 2307 2308 2309 2310 2311 2312 2313 2315 2316 2317 This indicates that the requested 2318 PUT operation could not be performed because a GET of that resource 2319 after the PUT would not yield the content of the PUT request. 2320 2321 2322 2323 2324 2325 2327 2329 2330 This indicates that the 2331 request was supposed to contain a valid XML attribute value, but did 2332 not. 2333 2334 2335 2336 2337 2339 2341 2342 This indicates that the 2343 requested operation would result in a document that did not meet a 2344 uniqueness constraint defined by the application usage. 2345 2346 2347 2348 2349 2350 2351 For each URI, 2353 element or attribute specified by the client which is not unique, 2354 one of these is present. 2355 2356 2357 2358 2360 2361 An optional set of alternate values can be 2362 provided. 2363 2364 2365 2366 2367 2368 2369 2370 2371 2372 2374 2376 2377 This indicates that the body of the request was 2378 not a well-formed document. 2379 2380 2381 2382 2383 2385 2387 2388 This indicates that the 2389 requested operation would result in a document that failed a data 2390 constraint defined by the application usage, but not enforced by the 2391 schema or a uniqueness constraint. 2392 2393 2394 2395 2396 2398 2399 2400 This indicates that the requested DELETE 2402 operation could not be performed because it would not be 2403 idempotent. 2404 2405 2406 2407 2408 2410 2411 2412 This indicates that request could not be 2413 completed because it would have produced a document not 2414 encoded in UTF-8. 2415 2416 2417 2418 2419 2420 2422 12. XCAP Server Capabilities 2424 XCAP can be extended through the addition of new application usages 2425 and extensions to the core protocol. Application usages may define 2426 MIME types with XML schemas that allow new extension nodes from new 2427 namespaces. It will often be necessary for a client to determine 2428 what extensions, application usages or namespaces a server supports 2429 before making a request. To enable that, this specification defines 2430 an application usage with the AUID "xcap-caps". All XCAP servers 2431 MUST support this application usage. This usage defines a single 2432 document within the global tree which lists the capabilities of the 2433 server. Clients can read this well-known document, and therefore 2434 learn the capabilities of the server. 2436 The structure of the document is simple. The root element is . Its children are , , and . 2438 Each of these contain a list of AUIDs, extensions and namespaces 2439 supported by the server. Extensions are named by tokens defined by 2440 the extension, and typically define new selectors. Namespaces are 2441 identified by their namespace URI. Since all XCAP servers support 2442 the "xcap-caps" AUID, it MUST be listed in the element and 2443 the "urn:ietf:params:xml:ns:xcap-caps" namespace MUST be listed in 2444 the element. 2446 The following sections provide the information needed to define this 2447 application usage. 2449 12.1. Application Unique ID (AUID) 2451 This specification defines the "xcap-caps" AUID within the IETF tree, 2452 via the IANA registration in Section 15. 2454 12.2. XML Schema 2456 2457 2461 2462 2463 Root element for xcap-caps 2464 2465 2466 2467 2468 2469 List of supported AUID. 2470 2471 2472 2473 2474 2475 2476 2477 2478 2479 List of supported extensions. 2480 2481 2482 2483 2484 2485 2486 2487 2488 2489 2490 List of supported namespaces. 2491 2492 2493 2494 2495 2497 2498 2499 2500 2502 2503 2504 2505 2506 2507 AUID Type 2508 2509 2510 2511 2512 2513 Extension Type 2514 2515 2516 2517 2518 2519 Namespace type 2520 2521 2522 2523 2525 12.3. Default Namespace 2527 The default namespace used in evaluating a URI is 2528 urn:ietf:params:xml:ns:xcap-caps. 2530 12.4. MIME Type 2532 Documents conformant to this schema are known by the MIME type 2533 "application/xcap-caps+xml", registered in Section 15.2.5. 2535 12.5. Validation Constraints 2537 There are no additional validation constraints associated with this 2538 application usage. 2540 12.6. Data Semantics 2542 Data semantics are defined above. 2544 12.7. Naming Conventions 2546 A server MUST maintain a single instance of the document in the 2547 global tree, using the filename "index". There MUST NOT be an 2548 instance of this document in the users tree. 2550 12.8. Resource Interdependencies 2552 There are no resource interdependencies in this application usage 2553 beyond those defined by the schema. 2555 12.9. Authorization Policies 2557 This application usage does not change the default authorization 2558 policy defined by XCAP. 2560 13. Examples 2562 This section goes through several examples, making use of the 2563 resource-lists and rls-services [22] XCAP application usages. 2565 First, a user Bill creates a new document (see Section 7.1). This 2566 document is a new resource-list, initially with a single list, called 2567 friends, with no users in it: 2569 PUT 2570 /resource-lists/users/sip:bill@example.com/index HTTP/1.1 2571 Content-Type:application/resource-lists+xml 2572 Host: xcap.example.com 2574 2575 2576 2577 2578 2580 Next, Bill creates an RLS services document defining a single RLS 2581 service referencing this list. This service has a URI of 2582 sip:myfriends@example.com (URIs are line-folded for readability): 2584 PUT 2585 /rls-services/users/sip:bill@example.com/index HTTP/1.1 2586 Content-Type:application/rls-services+xml 2587 Host: xcap.example.com 2589 2590 2591 2592 http://xcap.example.com/resource-lists/users/ 2593 sip:bill@example.com/index/~~/resource-lists/ 2594 list%5b@name=%22friends%22%5d 2595 2596 2597 presence 2598 2599 2600 2602 Next, Bill creates an element in the resource-lists document 2603 (Section 7.4). In particular, he adds an entry to the list: 2605 PUT 2606 /resource-lists/users/sip:bill@example.com/index 2607 /~~/resource-lists/list%5b@name=%22friends%22%5d/entry HTTP/1.1 2608 Content-Type:application/xcap-el+xml 2609 Host: xcap.example.com 2611 2612 Bob Jones 2613 2615 Next, Bill fetches the document (Section 7.3): 2617 GET 2618 /resource-lists/users/sip:bill@example.com/index HTTP/1.1 2620 And the result is (note how white space text nodes appear in the 2621 document): 2623 HTTP/1.1 200 OK 2624 Etag: "wwhha" 2625 Content-Type: application/resource-lists+xml 2627 2628 2629 2630 2631 Bob Jones 2632 2633 2635 Next, Bill adds another entry to the list, which is another list that 2636 has three entries. This is another element creation (Section 7.4): 2638 PUT 2639 /resource-lists/users/sip:bill@example.com/index/~~/ 2640 resource-lists/list%5b@name=%22friends%22%5d/ 2641 list%5b@name=%22close-friends%22%5d HTTP/1.1 2642 Content-Type: application/xcap-el+xml 2643 Host: xcap.example.com 2645 2646 2647 Joe Smith 2648 2649 2650 Nancy Gross 2651 2652 2653 Petri Aukia 2654 2655 2657 Then, Bill decides he doesn't want Petri on the list, so he deletes 2658 the entry (Section 7.5): 2660 DELETE 2661 /resource-lists/users/sip:bill@example.com/index/ 2662 ~~/resource-lists/list/list/ 2663 entry%5b@uri=%22sip:petri@example.com%22%5d HTTP/1.1 2664 Host: xcap.example.com 2666 Bill decides to check on the URI for Nancy, so he fetches a 2667 particular attribute (Section 7.6): 2669 GET 2670 /resource-lists/users/sip:bill@example.com/index/ 2671 ~~/resource-lists/list/list/entry%5b2%5d/@uri HTTP/1.1 2672 Host: xcap.example.com 2674 and the server responds: 2676 HTTP/1.1 200 OK 2677 Etag: "ad88" 2678 Content-Type:application/xcap-att+xml 2680 "sip:nancy@example.com" 2682 14. Security Considerations 2684 Frequently, the data manipulated by XCAP contains sensitive 2685 information. To avoid eavesdroppers from seeing this information, it 2686 is RECOMMENDED that an admistrator hand out an https URI as the XCAP 2687 root URI. This will result in TLS-encrypted communications between 2688 the client and server, preventing any eavesdropping. 2690 Client and server authentication are also important. A client needs 2691 to be sure it is talking to the server it believes it is contacting. 2692 Otherwise, it may be given false information, which can lead to 2693 denial of service attacks against a client. To prevent this, a 2694 client SHOULD attempt to upgrade [15] any connections to TLS. 2695 Similarly, authorization of read and write operations against the 2696 data is important, and this requires client authentication. As a 2697 result, a server SHOULD challenge a client using HTTP Digest [11] to 2698 establish its identity, and this SHOULD be done over a TLS 2699 connection. 2701 Because XCAP is a usage of HTTP and not a separate protocol, it runs 2702 on the same port numbers as HTTP traffic normally does. This makes 2703 it difficult to apply port-based filtering rules in firewalls to 2704 separate the treatment of XCAP traffic from other HTTP traffic. 2705 However, this problem exists broadly today because HTTP is used to 2706 access a wide breadth of content, all on the same port, and XCAP 2707 views application configuration documents as just another type of 2708 HTTP content. As such, separate treatment of XCAP traffic from other 2709 HTTP traffic requires firewalls to examine the URL itself. There is 2710 no foolproof way to identify a URL as pointing to an XCAP resource. 2711 However, the presence of the double tilde (~~) is a strong hint that 2712 the URL points to an XML element or attribute. As always, care must 2713 be taken in looking for the double-tilde due to the breadth of ways 2714 in which a URI can be encoded on-the-wire [29] [13]. 2716 15. IANA Considerations 2718 There are several IANA considerations associated with this 2719 specification. 2721 15.1. XCAP Application Unique IDs 2723 This specification instructs IANA to create a new registry for XCAP 2724 application unique IDs (AUIDs). This registry is defined as a table 2725 that contains three colums: 2727 AUID: This will be a string provided in the IANA registrations into 2728 the registry. 2730 Description: This is text that is supplied by the IANA registration 2731 into the registry. 2733 Document: This is a reference to the RFC containing the registration. 2735 This specification instructs IANA to create this table with an 2736 initial entry. The resulting table would look like: 2738 Application Unique Description Document 2739 ID (AUID) 2740 ----------------------------------------------------------- 2742 xcap-caps Capabilities of an RFC XXXX 2743 XCAP server 2745 [[NOTE TO IANA/RFC-EDITOR: Please replace XXXX with the RFC number of 2746 this specification.]] 2748 XCAP AUIDs are registered by the IANA when they are published in 2749 standards track RFCs. The IANA Considerations section of the RFC 2750 must include the following information, which appears in the IANA 2751 registry along with the RFC number of the publication. 2753 Name of the AUID. The name MAY be of any length, but SHOULD be no 2754 more than twenty characters long. The name MUST consist of 2755 alphanum and mark [16] characters only. 2757 Descriptive text that describes the application usage. 2759 15.2. MIME Types 2761 This specification requests the registration of several new MIME 2762 types according to the procedures of RFC 2048 [8] and guidelines in 2763 RFC 3023 [9]. 2765 15.2.1. application/xcap-el+xml MIME Type 2767 MIME media type name: application 2769 MIME subtype name: xcap-el+xml 2771 Mandatory parameters: none 2773 Optional parameters: Same as charset parameter application/xml as 2774 specified in RFC 3023 [9]. 2776 Encoding considerations: Same as encoding considerations of 2777 application/xml as specified in RFC 3023 [9]. 2779 Security considerations: See Section 10 of RFC 3023 [9]. 2781 Interoperability considerations: none. 2783 Published specification: RFC XXXX [[NOTE TO RFC EDITOR: Please 2784 replace XXXX with the published RFC number of this 2785 specification.]]. 2787 Applications which use this media type: This document type has been 2788 used to support transport of XML fragment bodies in RFC XXXX 2789 [[NOTE TO RFC EDITOR: Please replace XXXX with the published RFC 2790 number of this specification.]], the XML Configuration Access 2791 Protocol (XCAP). 2793 Additional Information: 2795 Magic Number: None 2797 File Extension: .xel 2799 Macintosh file type code: "TEXT" 2801 Personal and email address for further information: Jonathan 2802 Rosenberg, jdrosen@jdrosen.net 2804 Intended usage: COMMON 2806 Author/Change controller: The IETF. 2808 15.2.2. application/xcap-att+xml MIME Type 2810 MIME media type name: application 2812 MIME subtype name: xcap-att+xml 2814 Mandatory parameters: none 2816 Optional parameters: Same as charset parameter application/xml as 2817 specified in RFC 3023 [9]. 2819 Encoding considerations: Same as encoding considerations of 2820 application/xml as specified in RFC 3023 [9]. 2822 Security considerations: See Section 10 of RFC 3023 [9]. 2824 Interoperability considerations: none. 2826 Published specification: RFC XXXX [[NOTE TO RFC EDITOR: Please 2827 replace XXXX with the published RFC number of this 2828 specification.]]. 2830 Applications which use this media type: This document type has been 2831 used to support transport of XML attribute values in RFC XXXX 2832 [[NOTE TO RFC EDITOR: Please replace XXXX with the published RFC 2833 number of this specification.]], the XML Configuration Access 2834 Protocol (XCAP). 2836 Additional Information: 2838 Magic Number: None 2840 File Extension: .xav 2842 Macintosh file type code: "TEXT" 2844 Personal and email address for further information: Jonathan 2845 Rosenberg, jdrosen@jdrosen.net 2847 Intended usage: COMMON 2849 Author/Change controller: The IETF. 2851 15.2.3. application/xcap-ns+xml MIME Type 2852 MIME media type name: application 2854 MIME subtype name: xcap-ns+xml 2856 Mandatory parameters: none 2858 Optional parameters: Same as charset parameter application/xml as 2859 specified in RFC 3023 [9]. 2861 Encoding considerations: Same as encoding considerations of 2862 application/xml as specified in RFC 3023 [9]. 2864 Security considerations: See Section 10 of RFC 3023 [9]. 2866 Interoperability considerations: none. 2868 Published specification: RFC XXXX [[NOTE TO RFC EDITOR: Please 2869 replace XXXX with the published RFC number of this 2870 specification.]]. 2872 Applications which use this media type: This document type has been 2873 used to support transport of XML fragment bodies in RFC XXXX 2874 [[NOTE TO RFC EDITOR: Please replace XXXX with the published RFC 2875 number of this specification.]], the XML Configuration Access 2876 Protocol (XCAP). 2878 Additional Information: 2880 Magic Number: None 2882 File Extension: .xns 2884 Macintosh file type code: "TEXT" 2886 Personal and email address for further information: Jonathan 2887 Rosenberg, jdrosen@jdrosen.net 2889 Intended usage: COMMON 2891 Author/Change controller: The IETF. 2893 15.2.4. application/xcap-error+xml MIME Type 2895 MIME media type name: application 2896 MIME subtype name: xcap-error+xml 2898 Mandatory parameters: none 2900 Optional parameters: Same as charset parameter application/xml as 2901 specified in RFC 3023 [9]. 2903 Encoding considerations: Same as encoding considerations of 2904 application/xml as specified in RFC 3023 [9]. 2906 Security considerations: See Section 10 of RFC 3023 [9]. 2908 Interoperability considerations: none. 2910 Published specification: RFC XXXX [[NOTE TO RFC EDITOR: Please 2911 replace XXXX with the published RFC number of this 2912 specification.]]. 2914 Applications which use this media type: This document type conveys 2915 error conditions defined in RFC XXXX. [[NOTE TO RFC EDITOR: 2916 Please replace XXXX with the published RFC number of this 2917 specification.]] 2919 Additional Information: 2921 Magic Number: None 2923 File Extension: .xer 2925 Macintosh file type code: "TEXT" 2927 Personal and email address for further information: Jonathan 2928 Rosenberg, jdrosen@jdrosen.net 2930 Intended usage: COMMON 2932 Author/Change controller: The IETF. 2934 15.2.5. application/xcap-caps+xml MIME Type 2936 MIME media type name: application 2938 MIME subtype name: xcap-caps+xml 2940 Mandatory parameters: none 2941 Optional parameters: Same as charset parameter application/xml as 2942 specified in RFC 3023 [9]. 2944 Encoding considerations: Same as encoding considerations of 2945 application/xml as specified in RFC 3023 [9]. 2947 Security considerations: See Section 10 of RFC 3023 [9]. 2949 Interoperability considerations: none. 2951 Published specification: RFC XXXX [[NOTE TO RFC EDITOR: Please 2952 replace XXXX with the published RFC number of this 2953 specification.]]. 2955 Applications which use this media type: This document type conveys 2956 capabililites of an XML Configuration Access Protocol (XCAP) 2957 server, as defined in RFC XXXX. [[NOTE TO RFC EDITOR: Please 2958 replace XXXX with the published RFC number of this 2959 specification.]] 2961 Additional Information: 2963 Magic Number: None 2965 File Extension: .xca 2967 Macintosh file type code: "TEXT" 2969 Personal and email address for further information: Jonathan 2970 Rosenberg, jdrosen@jdrosen.net 2972 Intended usage: COMMON 2974 Author/Change controller: The IETF. 2976 15.3. URN Sub-Namespace Registrations 2978 This specification registers several new XML namespaces, as per the 2979 guidelines in RFC 3688 [17]. 2981 15.3.1. urn:ietf:params:xml:ns:xcap-error 2983 URI: The URI for this namespace is urn:ietf:params:xml:ns:xcap-error 2985 Registrant Contact: IETF, SIMPLE working group, (simple@ietf.org), 2986 Jonathan Rosenberg (jdrosen@jdrosen.net). 2988 XML: 2990 BEGIN 2991 2992 2994 2995 2996 2998 XCAP Error Namespace 2999 3000 3001

Namespace for XCAP Error Documents

3002

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

3003

See RFCXXXX [[NOTE 3004 TO RFC-EDITOR/IANA: Please replace XXXX with the RFC Number of 3005 this specification]].

3006 3007 3008 END 3010 15.3.2. urn:ietf:params:xml:ns:xcap-caps 3012 URI: The URI for this namespace is urn:ietf:params:xml:ns:xcap-caps 3014 Registrant Contact: IETF, SIMPLE working group, (simple@ietf.org), 3015 Jonathan Rosenberg (jdrosen@jdrosen.net). 3017 XML: 3019 BEGIN 3020 3021 3023 3024 3025 3027 XCAP Capabilities Namespace 3028 3029 3030

Namespace for XCAP Capability Documents

3031

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

3032

See RFCXXXX [[NOTE 3033 TO RFC-EDITOR/IANA: Please replace XXXX with the RFC Number of 3034 this specification]].

3035 3036 3037 END 3039 15.4. XML Schema Registrations 3041 This section registers two XML schemas per the procedures in [17]. 3043 15.4.1. XCAP Error Schema Registration 3045 URI: urn:ietf:params:xml:schema:xcap-error 3047 Registrant Contact: IETF, SIMPLE working group, (simple@ietf.org), 3048 Jonathan Rosenberg (jdrosen@jdrosen.net). 3050 XML Schema: The XML for this schema can be found as the sole content 3051 of Section 11.2. 3053 15.4.2. XCAP Capabilities Schema Registration 3055 URI: urn:ietf:params:xml:schema:xcap-caps 3057 Registrant Contact: IETF, SIMPLE working group, (simple@ietf.org), 3058 Jonathan Rosenberg (jdrosen@jdrosen.net). 3060 XML Schema: The XML for this schema can be found as the sole content 3061 of Section 12.2. 3063 16. Acknowledgements 3065 The author would like to thank Jari Urpalainen, who has contributed 3066 many important comments and has assisted with edit passes in the 3067 document. The author would also like to thank Ben Campbell, Eva- 3068 Maria Leppanen, Hisham Khartabil, Chris Newman, Joel Halpern, , Lisa 3069 Dusseault, Tim Bray, Pete Cordell, Jeroen van Bemmel, Christian 3070 Schmidt, and Spencer Dawkins for their input and comments. A special 3071 thanks to Ted Hardie for his input and support. 3073 17. References 3075 17.1. Normative References 3077 [1] Yergeau, F., Bray, T., Paoli, J., Sperberg-McQueen, C., and E. 3078 Maler, "Extensible Markup Language (XML) 1.0 (Third Edition)", 3079 W3C REC REC-xml-20040204, February 2004. 3081 [2] Maloney, M., Beech, D., Thompson, H., and N. Mendelsohn, "XML 3082 Schema Part 1: Structures Second Edition", W3C REC REC- 3083 xmlschema-1-20041028, October 2004. 3085 [3] Bray, T., Hollander, D., and A. Layman, "Namespaces in XML", 3086 W3C REC REC-xml-names-19990114, January 1999. 3088 [4] DeRose, S., Daniel, R., Maler, E., and J. Marsh, "XPointer 3089 xmlns() Scheme", W3C REC REC-xptr-xmlns-20030325, March 2003. 3091 [5] Grosso, P., Maler, E., Marsh, J., and N. Walsh, "XPointer 3092 Framework", W3C REC REC-xptr-framework-20030325, March 2003. 3094 [6] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., 3095 Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- 3096 HTTP/1.1", RFC 2616, June 1999. 3098 [7] Bradner, S., "Key words for use in RFCs to Indicate Requirement 3099 Levels", BCP 14, RFC 2119, March 1997. 3101 [8] Freed, N., Klensin, J., and J. Postel, "Multipurpose Internet 3102 Mail Extensions (MIME) Part Four: Registration Procedures", 3103 BCP 13, RFC 2048, November 1996. 3105 [9] Murata, M., St. Laurent, S., and D. Kohn, "XML Media Types", 3106 RFC 3023, January 2001. 3108 [10] Clark, J. and S. DeRose, "XML Path Language (XPath) Version 3109 1.0", W3C REC REC-xpath-19991116, November 1999. 3111 [11] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 3112 Leach, P., Luotonen, A., and L. Stewart, "HTTP Authentication: 3114 Basic and Digest Access Authentication", RFC 2617, June 1999. 3116 [12] Crocker, D. and P. Overell, "Augmented BNF for Syntax 3117 Specifications: ABNF", RFC 4234, October 2005. 3119 [13] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3120 Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, 3121 January 2005. 3123 [14] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 3125 [15] Khare, R. and S. Lawrence, "Upgrading to TLS Within HTTP/1.1", 3126 RFC 2817, May 2000. 3128 [16] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A., 3129 Peterson, J., Sparks, R., Handley, M., and E. Schooler, "SIP: 3130 Session Initiation Protocol", RFC 3261, June 2002. 3132 [17] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 3133 January 2004. 3135 [18] Yergeau, F., "UTF-8, a transformation format of ISO 10646", 3136 STD 63, RFC 3629, November 2003. 3138 [19] Boyer, J., "Canonical XML Version 1.0", W3C REC REC-xml-c14n- 3139 20010315, March 2001. 3141 17.2. Informative References 3143 [20] Rosenberg, J., "A Presence Event Package for the Session 3144 Initiation Protocol (SIP)", RFC 3856, August 2004. 3146 [21] Roach, A., Rosenberg, J., and B. Campbell, "A Session 3147 Initiation Protocol (SIP) Event Notification Extension for 3148 Resource Lists", draft-ietf-simple-event-list-07 (work in 3149 progress), January 2005. 3151 [22] Rosenberg, J., "Extensible Markup Language (XML) Formats for 3152 Representing Resource Lists", 3153 draft-ietf-simple-xcap-list-usage-05 (work in progress), 3154 February 2005. 3156 [23] Grosso, P. and D. Veillard, "XML Fragment Interchange", W3C 3157 CR CR-xml-fragment-20010212, February 2001. 3159 [24] Berglund, A., Boag, S., Chamberlin, D., Fernandez, M., Kay, M., 3160 Robie, J., and J. Simeon, "XML Path Language (XPath) 2.0", W3C 3161 CR CR-xpath20-20051103, November 2005. 3163 [25] Newman, C. and J. Myers, "ACAP -- Application Configuration 3164 Access Protocol", RFC 2244, November 1997. 3166 [26] Day, M., Rosenberg, J., and H. Sugano, "A Model for Presence 3167 and Instant Messaging", RFC 2778, February 2000. 3169 [27] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA 3170 Considerations Section in RFCs", BCP 26, RFC 2434, 3171 October 1998. 3173 [28] Roach, A., "Session Initiation Protocol (SIP)-Specific Event 3174 Notification", RFC 3265, June 2002. 3176 [29] Duerst, M. and M. Suignard, "Internationalized Resource 3177 Identifiers (IRIs)", RFC 3987, January 2005. 3179 Author's Address 3181 Jonathan Rosenberg 3182 Cisco Systems 3183 600 Lanidex Plaza 3184 Parsippany, NJ 07054 3185 US 3187 Phone: +1 973 952-5000 3188 Email: jdrosen@cisco.com 3189 URI: http://www.jdrosen.net 3191 Intellectual Property Statement 3193 The IETF takes no position regarding the validity or scope of any 3194 Intellectual Property Rights or other rights that might be claimed to 3195 pertain to the implementation or use of the technology described in 3196 this document or the extent to which any license under such rights 3197 might or might not be available; nor does it represent that it has 3198 made any independent effort to identify any such rights. Information 3199 on the procedures with respect to rights in RFC documents can be 3200 found in BCP 78 and BCP 79. 3202 Copies of IPR disclosures made to the IETF Secretariat and any 3203 assurances of licenses to be made available, or the result of an 3204 attempt made to obtain a general license or permission for the use of 3205 such proprietary rights by implementers or users of this 3206 specification can be obtained from the IETF on-line IPR repository at 3207 http://www.ietf.org/ipr. 3209 The IETF invites any interested party to bring to its attention any 3210 copyrights, patents or patent applications, or other proprietary 3211 rights that may cover technology that may be required to implement 3212 this standard. Please address the information to the IETF at 3213 ietf-ipr@ietf.org. 3215 Disclaimer of Validity 3217 This document and the information contained herein are provided on an 3218 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 3219 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 3220 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 3221 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 3222 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 3223 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 3225 Copyright Statement 3227 Copyright (C) The Internet Society (2006). This document is subject 3228 to the rights, licenses and restrictions contained in BCP 78, and 3229 except as set forth therein, the authors retain all their rights. 3231 Acknowledgment 3233 Funding for the RFC Editor function is currently provided by the 3234 Internet Society.