idnits 2.17.1 draft-ietf-simple-xcap-12.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 3306. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 3283. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 3290. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 3296. ** 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. An entity tag MUST be included in all successful responses to a PUT. -- 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 (October 13, 2006) is 6405 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' ** Obsolete normative reference: RFC 2617 (ref. '11') (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) ** 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: 9 errors (**), 0 flaws (~~), 5 warnings (==), 17 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: April 16, 2007 October 13, 2006 6 The Extensible Markup Language (XML) Configuration Access Protocol 7 (XCAP) 8 draft-ietf-simple-xcap-12 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 April 16, 2007. 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 Document Namespace . . . . . . . . . . . . . . . . 8 57 5.3. Data Validation . . . . . . . . . . . . . . . . . . . . . 9 58 5.4. Data Semantics . . . . . . . . . . . . . . . . . . . . . . 10 59 5.5. Naming Conventions . . . . . . . . . . . . . . . . . . . . 10 60 5.6. Resource Interdependencies . . . . . . . . . . . . . . . . 11 61 5.7. Authorization Policies . . . . . . . . . . . . . . . . . . 12 62 5.8. Data Extensibility . . . . . . . . . . . . . . . . . . . . 12 63 5.9. Documenting Application Usages . . . . . . . . . . . . . . 13 64 5.10. Guidelines for Creating Application Usages . . . . . . . . 13 65 6. URI Construction . . . . . . . . . . . . . . . . . . . . . . . 15 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 . . . . . . . . . . . 23 70 7. Client Operations . . . . . . . . . . . . . . . . . . . . . . 24 71 7.1. Create or Replace a Document . . . . . . . . . . . . . . . 25 72 7.2. Delete a Document . . . . . . . . . . . . . . . . . . . . 26 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 . . . . . . . . . . . . . . . . . 32 81 7.11. Conditional Operations . . . . . . . . . . . . . . . . . . 32 82 8. Server Behavior . . . . . . . . . . . . . . . . . . . . . . . 34 83 8.1. POST Handling . . . . . . . . . . . . . . . . . . . . . . 35 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 . . . . . . . . . . . . . . . . 43 91 8.2.7. Resource Interdependencies . . . . . . . . . . . . . . 44 92 8.3. GET Handling . . . . . . . . . . . . . . . . . . . . . . . 44 93 8.4. DELETE Handling . . . . . . . . . . . . . . . . . . . . . 45 94 8.5. Managing Etags . . . . . . . . . . . . . . . . . . . . . . 46 95 9. Cache Control . . . . . . . . . . . . . . . . . . . . . . . . 46 96 10. Namespace Binding Format . . . . . . . . . . . . . . . . . . . 47 97 11. Detailed Conflict Reports . . . . . . . . . . . . . . . . . . 47 98 11.1. Document Structure . . . . . . . . . . . . . . . . . . . . 48 99 11.2. XML Schema . . . . . . . . . . . . . . . . . . . . . . . . 49 100 12. XCAP Server Capabilities . . . . . . . . . . . . . . . . . . . 53 101 12.1. Application Unique ID (AUID) . . . . . . . . . . . . . . . 54 102 12.2. XML Schema . . . . . . . . . . . . . . . . . . . . . . . . 54 103 12.3. Default Document Namespace . . . . . . . . . . . . . . . . 55 104 12.4. MIME Type . . . . . . . . . . . . . . . . . . . . . . . . 55 105 12.5. Validation Constraints . . . . . . . . . . . . . . . . . . 55 106 12.6. Data Semantics . . . . . . . . . . . . . . . . . . . . . . 56 107 12.7. Naming Conventions . . . . . . . . . . . . . . . . . . . . 56 108 12.8. Resource Interdependencies . . . . . . . . . . . . . . . . 56 109 12.9. Authorization Policies . . . . . . . . . . . . . . . . . . 56 110 13. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 111 14. Security Considerations . . . . . . . . . . . . . . . . . . . 59 112 15. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 60 113 15.1. XCAP Application Unique IDs . . . . . . . . . . . . . . . 60 114 15.2. MIME Types . . . . . . . . . . . . . . . . . . . . . . . . 61 115 15.2.1. application/xcap-el+xml MIME Type . . . . . . . . . . 61 116 15.2.2. application/xcap-att+xml MIME Type . . . . . . . . . . 62 117 15.2.3. application/xcap-ns+xml MIME Type . . . . . . . . . . 63 118 15.2.4. application/xcap-error+xml MIME Type . . . . . . . . . 64 119 15.2.5. application/xcap-caps+xml MIME Type . . . . . . . . . 65 120 15.3. URN Sub-Namespace Registrations . . . . . . . . . . . . . 66 121 15.3.1. urn:ietf:params:xml:ns:xcap-error . . . . . . . . . . 66 122 15.3.2. urn:ietf:params:xml:ns:xcap-caps . . . . . . . . . . . 66 123 15.4. XML Schema Registrations . . . . . . . . . . . . . . . . . 67 124 15.4.1. XCAP Error Schema Registration . . . . . . . . . . . . 67 125 15.4.2. XCAP Capabilities Schema Registration . . . . . . . . 67 126 16. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 68 127 17. References . . . . . . . . . . . . . . . . . . . . . . . . . . 68 128 17.1. Normative References . . . . . . . . . . . . . . . . . . . 68 129 17.2. Informative References . . . . . . . . . . . . . . . . . . 70 130 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 71 131 Intellectual Property and Copyright Statements . . . . . . . . . . 72 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 (where an application refers to a use case that 175 implies a collection of data and associated semantics) that makes use 176 of XCAP specifies an application usage (Section 5). This application 177 usage defines the XML schema [2] for the data used by the 178 application, along with other key pieces of information. The 179 principal task of XCAP is to allow clients to read, write, modify, 180 create and delete pieces of that data. These operations are 181 supported using HTTP/1.1 [6]. An XCAP server acts as a repository 182 for collections of XML documents. There will be documents stored for 183 each application. Within each application, there are documents 184 stored for each user. Each user can have a multiplicity of documents 185 for a particular application. To access some component of one of 186 those documents, XCAP defines an algorithm for constructing a URI 187 that can be used to reference that component. Components refer to 188 any element or attribute within the document. Thus, the HTTP URIs 189 used by XCAP point to a document, or to pieces of information that 190 are finer grained than the XML document itself. An HTTP resource 191 which follows the naming conventions and validation constraints 192 defined here is called an XCAP resource. 194 Since XCAP resources are also HTTP resources, they can be accessed 195 using HTTP methods. Reading an XCAP resource is accomplished with 196 HTTP GET, creating or modifying one is done with HTTP PUT, and 197 removing one of the resources is done with an HTTP DELETE. XCAP 198 resources do not represent processing scripts; as a result, POST 199 operations to HTTP URIs representing XCAP resources are not defined. 200 Properties that HTTP associates with resources, such as entity tags, 201 also apply to XCAP resources. Indeed, entity tags are particularly 202 useful in XCAP, as they allow a number of conditional operations to 203 be performed. 205 XML documents which are equivalent for the purposes of many 206 applications may differ in their physical representation. With XCAP 207 resources, the canonical form with comments [19] of an XML document 208 determines the logical equivalence. In other words, the canonical 209 specification determines, how significant whitespace MUST be 210 processed and for example, that new inserted attributes may appear in 211 any order within the physical representation. 213 3. Terminology 215 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 216 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 217 and "OPTIONAL" are to be interpreted as described in RFC 2119 [7] and 218 indicate requirement levels for compliant implementations. 220 4. Definitions 222 The following terms are used throughout this document: 224 XCAP Resource: An HTTP resource representing an XML document, an 225 element within an XML document, or an attribute of an element 226 within an XML document that follows the naming and validation 227 constraints of XCAP. 229 XCAP Server: An HTTP server that understands how to follow the naming 230 and validation constraints defined in this specification. 232 XCAP Client: An HTTP client that understands how to follow the naming 233 and validation constraints defined in this specification. 235 Application: A collection of software components within a network 236 whose operation depends on data managed and stored on an XCAP 237 server. 239 Application Usage: Detailed information on the interaction of an 240 application with the XCAP server. 242 Application Unique ID (AUID): A unique identifier within the 243 namespace of application unique IDs created by this specification 244 that differentiates XCAP resources accessed by one application 245 from XCAP resources accessed by another. 247 Naming Conventions: The part of an application usage that specifies 248 well-known URIs used by an application, or more generally, 249 specifies the URIs that are typically accessed by an application 250 during its processing. 252 XCAP User Identifier (XUI): The XUI is a string, valid as a path 253 element in an HTTP URI, that is associated with each user served 254 by the XCAP server. 256 XCAP Root: A context that contains all of the documents across all 257 application usages and users that are managed by the server. 259 Document Selector: A sequence of path segments, with each segment 260 being separated by a "/", that identify the XML document within an 261 XCAP root that is being selected. 263 Node Selector: A sequence of path segments, with each segment being 264 separated by a "/", that identify the XML node (element or 265 attribute) being selected within a document. 267 Node Selector Separator: A single path segment equal to two tilde 268 characters "~~" that is used to separate the document selector 269 from the node selector within an HTTP URI. 271 Document URI: The HTTP URI containing the XCAP root and document 272 selector, resulting in the selection of a specific document. As a 273 result, performing a GET against the document URI would retrieve 274 the document. 276 Node URI: The HTTP URI containing the XCAP root, document selector, 277 node selector separator and node selector, resulting in the 278 selection of a specific XML node. 280 XCAP Root URI: An HTTP URI that representing the XCAP root. Although 281 a syntactically valid URI, the XCAP Root URI does not correspond 282 to an actual resource on an XCAP server. Actual resources are 283 created by appending additional path information to the XCAP Root 284 URI. 286 Global Tree: A URI that represents the parent for all global 287 documents for a particular application usage within a particular 288 XCAP root. 290 Home Directory: A URI that represents the parent for all documents 291 for a particular user for a particular application usage within a 292 particular XCAP root. 294 Positional Insertion: A PUT operation that results in the insertion 295 of a new element into a document such that its position relative 296 to other children of the same parent is set by the client. 298 5. Application Usages 300 Each XCAP resource on a server is associated with an application. In 301 order for an application to use those resources, application specific 302 conventions must be specified. Those conventions include the XML 303 schema that defines the structure and constraints of the data, well 304 known URIs to bootstrap access to the data, and so on. All of those 305 application specific conventions are defined by the application 306 usage. 308 5.1. Application Unique ID (AUID) 310 Each application usage is associated with a name, called an 311 Application Unique ID (AUID). This name uniquely identifies the 312 application usage within the namespace of application usages, and is 313 different from AUIDs used by other applications. AUIDs exist in one 314 of two namespaces. The first namespace is the IETF namespace. This 315 namespace contains a set of tokens, each of which is registered with 316 IANA. These registrations occur with the publication of standards 317 track RFCs [27] based on the guidelines in Section 15. The second 318 namespace is the vendor-proprietary namespace. Each AUID in that 319 namespace is prefixed with the reverse domain name of the 320 organization creating the AUID, followed by a period, followed by any 321 vendor defined token. As an example, the example.com domain can 322 create an AUID with the value "com.example.foo" but cannot create one 323 with the value "org.example.foo". AUIDs within the vendor namespace 324 do not need to be registered with IANA. The vendor namespace is also 325 meant to be used in lab environments where no central registry is 326 needed. The syntax for AUIDs, expressed in ABNF [12] (and using some 327 of the BNF defined in RFC 3986 [13]) is: 329 AUID = global-auid / vendor-auid 330 global-auid = auid 331 auid = 1*auid-char 332 vendor-auid = rev-hostname "." auid 333 rev-hostname = toplabel *( "." domainlabel ) 334 domainlabel = alphanum 335 / alphanum *( alphanum / "-" ) alphanum 336 toplabel = ALPHA / ALPHA *( alphanum / "-" ) alphanum 337 auid-char = auid-unreserved / pct-encoded / sub-delims 338 / ":" / "@" 339 auid-unreserved = ALPHA / DIGIT / "-" / "_" / "~" 341 The allowed characters for the auid production is a subset of the 342 pchar production defined in RFC3986. In particular, it omits the 343 ".", which allows for the auid to be separated from the reverse 344 hostname. 346 5.2. Default Document Namespace 348 In order for the XCAP server to match a URI to an element or 349 attribute of a document, any XML namespace prefixes used within the 350 URI must be expanded [3]. This expansion requires a namespace 351 binding context. That context maps namespace prefixes to namespace 352 URIs. It also defines a default namespace that applies to elements 353 in the URI without namespace prefixes. The namespace binding context 354 comes from two sources. Firstly, the mapping of namespace prefixes 355 to namespace URIs is obtained from the URI itself (see Section 6.4). 356 However, the default document namespace is defined by the application 357 usage itself, and applies to all URIs referencing resources within 358 that application usage. All application usages MUST define a 359 namespace URI that represents the default document namespace to be 360 used when evaluating URIs. The default document namespace does not 361 apply to elements or attributes within the documents themselves - it 362 applies only to the evaluation of URIs within that application usage. 363 Indeed, the term 'default document namespace' is distinct from the 364 term 'default namespace'. The latter has the standard meaning within 365 XML documents, and the former refers to the default used in 366 evaluation of XCAP URIs. XCAP does not change in any way the 367 mechanisms for determining the default namespace within XML 368 documents. However, if a document contains a URI representing an 369 XCAP resource, the default document namespace defined by the 370 application usage applies to that URI as well. 372 5.3. Data Validation 374 One of the responsibilities of an XCAP server is to validate the 375 content of each XCAP resource when an XCAP client tries to modify 376 one. This is done using two mechanisms. Firstly, all application 377 usages MUST describe their document contents using XML schema [2]. 378 The application usage MUST also identify the MIME type for documents 379 compliant to that schema. 381 Unfortunately, XML schemas cannot represent every form of data 382 constraint. As an example, one XML element may contain an integer 383 which defines the maximum number of instances of another element. 384 This constraint cannot be represented with XML schema. However, such 385 constraints may be important to the application usage. The 386 application usage defines any additional constraints beyond those in 387 the schema. 389 Of particular importance are uniqueness constraints. In many cases, 390 an application will require that there only be one instance of some 391 element or attribute within a particular scope. Each uniqueness 392 constraint needs to be specified by identifying the field, or 393 combinations of fields, that need to be unique, and then identifying 394 the scope in which that uniqueness applies. One typical scope is the 395 set of all elements of a certain name within the same parent. 396 Another typical scope is the set of all URIs valid within a 397 particular domain. In some cases these constraints can be specified 398 using XML schema, which provides the element for this 399 purpose. Other uniqueness constraints, such as URI uniqueness across 400 a domain, cannot be expressed by schema. Whether or not the schema 401 is used to express some of the uniqueness requirements, the 402 application usage MUST specify all uniqueness requirements when it 403 defines its data validation needs. 405 For example, the resource lists application usage [22] requires that 406 each element have a unique value for the "name" attribute 407 within a single parent. As another example, the RLS services 408 application usage [22] requires that the value of the "uri" attribute 409 of the element be a URI that is unique within the domain of 410 the URI. 412 URI constraints represent another form of constraints. These are 413 constraints on the scheme or structure of the scheme specific part of 414 the URI. These kinds of constraints cannot be expressed in an XML 415 schema. If these constraints are important to an application usage, 416 they need to be explicitly called out. 418 Another important data constraint is referential integrity. 419 Referential integrity is important when the name or value of an 420 element or attribute is used as a key to select another element or 421 attribute. An application usage MAY specify referential integrity 422 constraints. However, XCAP servers are not a replacement for 423 Relational Database Management Systems (RDBMS), and therefore clients 424 MUST NOT depend on servers to maintain referential integrity. XCAP 425 clients are responsible for making all of the appropriate changes to 426 documents in order to maintain referential integrity. 428 Another constraint is character encoding. XML allows documents to be 429 encoded using several different character sets. However, this 430 specification mandates that all documents used with XCAP MUST be 431 encoded using UTF-8. This cannot be changed by an application usage. 433 The data validation information is consumed by both clients, which 434 use them to make sure they construct requests that will be accepted 435 by the server, and by servers, which validate the constraints when 436 they receive a request (with the exception of referential integrity 437 constraints, which are not validated by the server). 439 5.4. Data Semantics 441 For each application usage, the data present in the XML document has 442 a well defined semantic. The application usage defines that 443 semantic, so that a client can properly construct a document in order 444 to achieve the desired result. They are not used by the server, as 445 it is purposefully unaware of the semantics of the data it is 446 managing. The data semantics are expressed in English prose by the 447 application usage. 449 One particularly important semantic is the base URI to be used for 450 the resolution of any relative URI references pointed to XCAP 451 resources. As discussed below, relative URI references pointing to 452 XCAP resources cannot be resolved using the retrieval URI as the base 453 URI. Therefore, it is up to the application usage to specify the 454 base URI. 456 5.5. Naming Conventions 458 In addition to defining the meaning of the document in the context of 459 a particular application, an application usage has to specify how the 460 applications obtain the documents they need. In particular, it needs 461 to define any well-known URIs used for bootstrapping purposes, and 462 document any other conventions on the URIs used by an application. 463 It should also document how documents reference each other. These 464 conventions are called naming conventions. 466 For many application usages, users need only a single document. In 467 such a case, it is RECOMMENDED that the application usage require 468 that this document be called "index" and exist within the users home 469 directory. 471 As an example, the RLS services application usage allows an RLS to 472 obtain the contents of a resource list when the RLS receives a 473 SUBSCRIBE request for a SIP URI identifying an RLS service. The 474 application usage specifies that the list of service definitions is 475 present within a specific document with a specific name within the 476 global tree. This allows the RLS to perform a single XCAP request to 477 fetch the service definition for the service associated with the SIP 478 URI in a SUBSCRIBE request. 480 Naming conventions are used by XCAP clients to construct their URIs. 481 The XCAP server does not make use of them. 483 5.6. Resource Interdependencies 485 When a user modifies an XCAP resource, the content of many other 486 resources is affected. For example, when a user deletes an XML 487 element within a document, it does so by issuing a DELETE request 488 against the URI for the element resource. However, deleting this 489 element also deletes all child elements and their attributes, each of 490 which is also an XCAP resource. As such, manipulation of one 491 resource affects the state of other resources. 493 For the most part, these interdependencies are fully specified by the 494 XML schema used by the application usage. However, in some 495 application usages, there is a need for the server to relate 496 resources together, and such a relationship cannot be specified 497 through a schema. This occurs when changes in one document will 498 affect another document. Typically, this is the case when an 499 application usage is defining a document that acts as a collection of 500 information defined in other documents. 502 As an example, when a user creates a new RLS service (that is, it 503 creates a new element within an RLS services document), the 504 server adds that element to a read-only global list of services 505 maintained by the server in the global tree. This read-only global 506 list is accessed by the RLS when processing a SIP SUBSCRIBE request. 508 Resource interdependencies are used by both XCAP clients and servers. 510 5.7. Authorization Policies 512 By default, each user is able to access (read, modify, and delete) 513 all of the documents below their home directory, and any user is able 514 to read documents within the global directory. However, only trusted 515 users, explicitly provisioned into the server, can modify global 516 documents. 518 The application usage can specify a different authorization policy 519 that applies to all documents associated with that application usage. 520 An application usage can also specify whether another application 521 usage is used to define the authorization policies. An application 522 usage for setting authorization policies can also be defined 523 subsequent to the definition of the the main application usage. In 524 such a case, the main application usage needs only to specify that 525 such a usage will be defined in the future. 527 If an application usage does not wish to change the default 528 authorization policy, it can merely state that the default policy is 529 used. 531 The authorization policies defined by the application usage are used 532 by the XCAP server during its operation. 534 5.8. Data Extensibility 536 An XCAP server MUST understand an application usage in order to 537 process an HTTP request made against a resource for that particular 538 application usage. However, it is not required for the server to 539 understand all of the contents of a document used by an application 540 usage. A server is required to understand the baseline schema 541 defined by the application usage. However, those schemas can define 542 points of extensibility where new content can be added from other 543 namespaces and corresponding schemas. Sometimes, the server will 544 understand those namespaces and therefore have access to their 545 schemas. Sometimes, it will not. 547 A server MUST allow for documents that contain elements from 548 namespaces not known to the server. In such a case, the server 549 cannot validate that such content is schema compliant; it will only 550 verify that the XML is well-formed. 552 If a client wants to verify that a server supports a particular 553 namespace before operating on a resource, it can query the server for 554 its capabilities using the XCAP Capabilities application usage, 555 discussed in Section 12. 557 5.9. Documenting Application Usages 559 Application usages are documented in specifications which convey the 560 information described above. In particular, an application usage 561 specification MUST provide the following information: 563 o Application Unique ID (AUID): If the application usage is meant 564 for general use on the Internet, the application usage MUST 565 register the AUID into the IETF tree using the IANA procedures 566 defined in Section 15. 568 o XML Schema 570 o Default Document Namespace 572 o MIME Type 574 o Validation Constraints 576 o Data Semantics 578 o Naming Conventions 580 o Resource Interdependencies 582 o Authorization Policies 584 5.10. Guidelines for Creating Application Usages 586 The primary design task when creating a new application usage is to 587 define the schema. Although XCAP can be used with any XML document, 588 intelligent schema design will improve the efficiency and utility of 589 the document when it is manipulated with XCAP. 591 XCAP provides three fundamental ways to select elements amongst a set 592 of siblings - by the expanded name of the element, by its position, 593 or by the value of a specific attribute. Positional selection always 594 allows a client to get exactly what it wants. However, it requires a 595 client to cache a copy of the document in order to construct the 596 predicate. Furthermore, if a client performs a PUT, it requires the 597 client to reconstruct the PUT processing that a server would follow 598 in order to update its local cached copy. Otherwise, the client will 599 be forced to re-GET the document after every PUT, which is 600 inefficient. As such, it is a good idea to design schemas such that 601 common operations can be performed without requiring the client to 602 cache a copy of the document. 604 Without positional selection, a client can pick the element at each 605 step by its expanded name or the value of an attribute. Many schemas 606 include elements that can be repeated within a parent (often, 607 minOccurs equals zero or one, and maxOccurs is unbounded). As such, 608 all of the elements have the same name. This leaves the attribute 609 value as the only way to select an element. Because of this, if an 610 application usage expects user to manipulate elements or attributes 611 that are descendants of an element which can repeat, that element 612 SHOULD include, in its schema, an attribute which can be suitably 613 used as a unique index. Furthermore, the naming conventions defined 614 by that application usage SHOULD specify this uniqueness constraint 615 explicitly. 617 URIs often make a good choice for such unique index. They have 618 fundamental uniqueness properties, and are also usually of semantic 619 significance in the application usage. However, care must be taken 620 when using a URI as an attribute value. URI equality is usually 621 complex. However, attribute equality is performed by the server 622 using XML rules, which are based on case sensitive string comparison. 623 Thus, XCAP will match URIs based on lexical equality, not functional 624 equality. In such cases, an application usage SHOULD consider these 625 implications carefully. 627 XCAP provides the ability of a client to operate on a single element, 628 attribute or document at a time. As a result, it may be possible 629 that common operations the client might perform will require a 630 sequence of multiple requests. This is inefficient, and introduces 631 the possibility of failure conditions when another client modifies 632 the document in the middle of a sequence. In such a case, the client 633 will be forced to detect this case using entity tags (discussed below 634 in Section 7.11), and undo its previous changes. This is very 635 difficult. 637 As a result, the schemas SHOULD be defined so that common operations 638 generally require a single request to perform. Consider an example. 639 Lets say an application usage is defining permissions for users to 640 perform certain operations. The schema can be designed in two ways. 641 The top level of the tree can identify users, and within each user, 642 there can be the permissions associated with the user. In an 643 alternative design, the top level of the tree identifies each 644 permission, and within that permission, the set of users who have it. 645 If, in this application usage, it is common to change the permission 646 for a user from one value to another, the former schema design is 647 better for xcap; it will require a single PUT to make such a change. 648 In the latter case, either the entire document needs to be replaced 649 (which is a single operation), or two PUT operations need to occur - 650 one to remove the user from the old permission, and one to add the 651 user to the new permission. 653 Naming conventions form another key part of the design of an 654 application usage. The application usage should be certain that XCAP 655 clients know where to "start" to retrieve and modify documents of 656 interest. Generally, this will involve the specification of a well- 657 known document at a well-known URI. That document can contain 658 references to other documents that the client needs to read or 659 modify. 661 6. URI Construction 663 In order to manipulate an XCAP resource, the data must be represented 664 by an HTTP URI. XCAP defines a specific naming convention for 665 constructing these URIs. The URI is constructed by concatenating the 666 XCAP root with the document selector with the node selector separator 667 with a percent-encoded form of the node selector. This is followed 668 by an optional query component that defines namespace bindings used 669 in evaluating the URI. The XCAP root is the enclosing context in 670 which all XCAP resources live. The document selector is a path that 671 identifies a document within the XCAP root. The node selector 672 separator is a path segment with a value of double tilde ("~~"), and 673 SHOULD NOT be percent-encoded, as advised in Section 2.3 of RFC 3986 674 [13]. URIs containing %7E%7E should be normalized to ~~ for 675 comparison; they are equivalent. The node selector separator is 676 piece of syntactic sugar that separates the document selector from 677 the node selector. The node selector is an expression that 678 identifies a component of the document, such as an element or 679 attribute. 681 The sections below describe these components in more detail. 683 6.1. XCAP Root 685 The root of the XCAP hierarchy is called the XCAP root. It defines 686 the context in which all other resources exist. The XCAP root is 687 represented with an HTTP URI, called the XCAP Root URI. This URI is 688 a valid HTTP URI; however, it doesn't point to any resource that 689 actually exists on the server. Its purpose is to identify the root 690 of the tree within the domain where all XCAP documents are stored. 691 It can be any valid HTTP URI, but MUST NOT contain a query component 692 (a complete XCAP URI may have a query component, but it is not part 693 of the XCAP root URI). It is RECOMMENDED that it be equal to 694 xcap.domain where domain is the domain of the provider. As an 695 example, "http://xcap.example.com" might be used as the XCAP root URI 696 within the example.com domain. Typically, the XCAP root URI is 697 provisioned into client devices. If not explicitly provisioned, 698 clients SHOULD assume the form xcap.domain where domain is the domain 699 of their service provider (for SIP, this would be the domain part of 700 their Address-of-Record (AOR)). A server or domain MAY support 701 multiple XCAP root URIs. In such a case, it is effectively operating 702 as if it were serving separate domains. There is never information 703 carryover or interactions between resources in different XCAP root 704 URIs. 706 When a client generates an HTTP request to a URI identifying an XCAP 707 resource, RFC 2616 procedures for the construction of the Request-URI 708 apply. In particular, the authority component of the URI may not be 709 present in the Request-URI if the request is sent directly to the 710 origin server. 712 The XCAP root URI can also be a relative HTTP URI. It is the 713 responsibility of the application usage to specify the base URI for 714 an HTTP URI representing an XCAP resource whenever such a URI appears 715 within a document defined by that application usage. Generally 716 speaking, it is unsafe to use the retrieval URI as the base URI. 717 This is because any URI that points to an ancestor for a particular 718 element or attribute can contain content including that element or 719 attribute. If that element or attribute contained a relative URI 720 reference, it would be resolved relative to whatever happened to be 721 used to retrieve the content, and this will often not be the base URI 722 defined by the application usage. 724 6.2. Document Selector 726 Each document within the XCAP root is identified by its document 727 selector. The document selector is a sequence of path segments, 728 separated by a slash ("/"). These path segments define a 729 hierarchical structure for organizing documents within any XCAP root. 730 The first path segment MUST be the XCAP AUID. So, continuing the 731 example above, all of the documents used by the resource lists 732 application would be under "http://xcap.example.com/resource-lists". 734 Implementors making use of HTTP servlets should be aware that XCAP 735 may require them to get authorization from the server 736 administrator to place resources within this specific subset of 737 the URI namespace. 739 It is assumed that each application will have data that is set by 740 users, and/or it will have global data that applies to all users. As 741 a result, beneath each AUID there are two sub-trees. One, called 742 "users", holds the documents that are applicable to specific users, 743 and the other, called "global", holds documents applicable to all 744 users. The subtree beneath "global" is called the global tree. The 745 path segment after the AUID MUST either be "global" or "users". 747 Within the "users" tree are zero or more sub-trees, each of which 748 identifies documents that apply to a specific user. Each user known 749 to the server is associated with a username, called the XCAP User 750 Identifier (XUI). Typically, an endpoint is provisioned with the 751 value of the XUI. For systems that support SIP applications, it is 752 RECOMMENDED that the XUI be equal to the Address-of-Record (AOR) for 753 the user (i.e., sip:joe@example.com). Since SIP endpoints generally 754 know their AOR, they will also know their XUI. As a consequence, if 755 no XUI is explicitly provisioned, a SIP UA SHOULD assume it is equal 756 to their AOR. This XUI MUST be used as the path segment beneath the 757 "users" segment. Since the SIP URI allows for characters which are 758 not permitted in HTTP URI path segments (such as the '?' and '/' 759 characters, which are permitted in the user part of the SIP URI), any 760 such characters MUST be percent encoded. The subtree beneath an XUI 761 for a particular user is called their home directory. "User" in this 762 context should be interpreted loosely; a user might correspond to 763 device, for example. 765 XCAP does not itself define what it means for documents to "apply" to 766 a user, beyond specification of a baseline authorization policy, 767 described below in Section 8. Each application usage can specify 768 additional authorization policies which depend on data used by the 769 application itself. 771 The remainder of the document selector (the path following "global" 772 or the XUI) points to specific documents for that application usage. 773 Subdirectories are permitted, but are NOT RECOMMENDED. XCAP provides 774 no way to create sub-directories or to list their contents, thus 775 limiting their utility. If subdirectories are used, there MUST not 776 be a document in a directory with the same name as a sub-directory. 778 The final path segment in the document selector identifies the actual 779 document in the hierarchy. This is equivalent to a filename, except 780 that XCAP does not require that its document resources be stored as 781 files in a file system. However, the term "filename" is used to 782 describe the final path segment in the document selector. In 783 traditional filesystems, the filename would have a filename 784 extension, such as ".xml". There is nothing in this specification 785 that requires or prevents such extensions from being used in the 786 filename. In some cases, the application usage will specify a naming 787 convention for documents, and those naming conventions may or may not 788 specify a file extension. For example, in the RLS services 789 application usage [22], documents in the user's home directory with 790 the filename "index" will be used by the server to compute the global 791 index, which is also a document with the filename "index". Barring 792 specific guidelines in the application usage, if a user has a single 793 document for a particular application usage, this SHOULD be called 794 "index". 796 When the naming conventions in an application usage do not constrain 797 the filename conventions (or, more generally, the document selector), 798 an application will know the filename (or more generally, the 799 document selector) because it is included as a reference in a 800 document which is at a well known location. As another example, 801 within the index document defined by RLS services, the 802 element has a child element called whose content is a 803 URI pointing to a resource list within the users home directory. 805 As a result, if the user creates a new document, and then references 806 that document from a well-known document (such as the index document 807 above), it doesn't matter whether the user includes an extension in 808 the filename or not, as long as the user is consistent and maintains 809 referential integrity. 811 As an example, the path segment 812 "/resource-lists/users/sip:joe@example.com/index" is a document 813 selector. Concatenating the XCAP root URI with the document selector 814 produces the HTTP URI "http://xcap.example.com/resource-lists/users/ 815 sip:joe@example.com/index". In this URI, the AUID is "resource- 816 lists", and the document is in the user tree with the XUI 817 "sip:joe@example.com" with filename "index". 819 6.3. Node Selector 821 The node selector specifies specific nodes of the XML document which 822 are to be accessed. A node refers to an XML element, an attribute of 823 an element, or a set of namespace bindings. The node selector is an 824 expression which identifies an element, attribute or set of namespace 825 bindings. Its grammar is: 827 node-selector = element-selector ["/" terminal-selector] 828 terminal-selector = attribute-selector / namespace-selector / 829 extension-selector 830 element-selector = step *( "/" step) 831 step = by-name / by-pos / by-attr / by-pos-attr / 832 extension-selector 833 by-name = NameorAny 834 by-pos = NameorAny "[" position "]" 835 position = 1*DIGIT 836 attr-test = "@" att-name "=" att-value 837 by-attr = NameorAny "[" attr-test "]" 838 by-pos-attr = NameorAny "[" position "]" "[" attr-test "]" 839 NameorAny = QName / "*" ; QName from XML Namespaces 840 att-name = QName 841 att-value = AttValue ; from XML specification 842 attribute-selector = "@" att-name 843 namespace-selector = "namespace::*" 844 extension-selector = 1*( %x00-2e / %x30-ff ) ; anything but "/" 846 The QName grammar is defined in the XML namespaces [3] specification, 847 and the AttValue grammar is defined in the XML specification XML 1.0 848 [1]. 850 The extension-selector is included for purposes of extensibility. It 851 can be composed of any character except the slash, which is the 852 delimeter amongst steps. Any characters in an extension that cannot 853 be represented in a URI MUST be percent-encoded before placement into 854 a URI. 856 Note that the double quote, left square bracket and right square 857 bracket characters, which are meaningful to XCAP, cannot be directly 858 represented in the HTTP URI. As a result, they are percent-encoded 859 when placed within the HTTP URI. In addition to these characters, an 860 apostrophe (') character can be used as a delimiter within XPath 861 expressions. Furthermore, since XML allows for non-ASCII characters, 862 the names of elements and attributes may not be directly 863 representable in a URI. Any such characters MUST be represented by 864 converting them to an octet sequence corresponding to their 865 representation in UTF-8, and then percent-encoding that sequence of 866 octets. 868 Similarly, the XML specification defines the QName production for the 869 grammar for element and attribute names, and the AttValue production 870 for the attribute values. Unfortunately, the characters permitted by 871 these productions include some that are not allowed for pchar, which 872 is the production for the allowed set of characters in path segments 873 in the URI. The AttValue production allows many such characters 874 within the US-ASCII set, including the space. Those characters MUST 875 be percent- encoded when placed in the URI. Furthermore, QName and 876 AttValue allow many Unicode characters, outside of US-ASCII. When 877 these characters need to be represented in the HTTP URI, they are 878 percent- encoded. To do this, the data should be encoded first as 879 octets according to the UTF-8 character encoding [18] and then only 880 those octets that do not correspond to characters in the pchar set 881 should be percent-encoded. For example, the character A would be 882 represented as "A", the character LATIN CAPITAL LETTER A WITH GRAVE 883 would be represented as "%C3%80", and the character KATAKANA LETTER A 884 would be represented as "%E3%82%A2". 886 As a result, the grammar above represents the expressions processed 887 by the XCAP server internally after it has decoded the URI. The on- 888 the-wire format is dictated by RFC 3986 [13]. In the discussions and 889 examples below, when the node selectors are not part of an HTTP URI, 890 they are presented in their internal format prior to encoding. If an 891 example includes a node selector within an HTTP URI, it is presented 892 in its percent-encoded form. 894 The node selector is based on the concepts in XPath [10]. Indeed, 895 the node selector expression, before it is percent-encoded for 896 representation in the HTTP URI, happens to be a valid XPath 897 expression. However, XPath provides a set of functionality far 898 richer than is needed here, and its breadth would introduce much 899 unneeded complexity into XCAP. 901 To determine the XML element, attribute or namespace bindings 902 selected by the node selector, processing begins at the root node of 903 the XML document. The first step in the element selector is then 904 taken. Each step chooses a single XML element within the current 905 document context. The document context is the point within the XML 906 document from which a specific step is evaluated. The document 907 context begins at the root node of the document. When a step 908 determines an element within that context, that element becomes the 909 new context for evaluation of the next step. Each step can select an 910 element by its name (expanded), by a combination of name and 911 attribute value, by name and position, or by name, position and 912 attribute. In all cases, the name can be wildcarded, so that all 913 elements get selected. 915 The selection operation operates as follows. Within the current 916 document context, the children of that context are enumerated in 917 document order. If the context is the root node of the document, its 918 child element is the root element of the document. If the context is 919 an element, its children are all of the children of that element 920 (naturally). Next, those elements whose name is not a match for 921 NameorAny are discarded. An element name is a match if NameorAny is 922 the wildcard, or, if its not a wildcard, the element name matches 923 NameorAny. Matching is discussed below. The result is an ordered 924 list of elements. 926 The elements in the list are further filtered by the predicates, 927 which are the expressions in square brackets following NameorAny. 928 Each predicate further prunes the elements from the current ordered 929 list. These predicates are evaluated in order. If the content of 930 the predicate is a position, the position-th element is selected 931 (that is, treat "position" as a variable, and take the element whose 932 position equals that variable), and all others are discarded. If 933 there are fewer elements in the list than the value of position, the 934 result is a no-match. 936 If the content of the predicate is an attribute name and value, all 937 elements possessing that attribute with that value are selected, and 938 all others are discarded. Note that, although a document can have 939 namespace declarations within elements, those elements cannot be 940 selected using a namespace declaration as a predicate. That is, a 941 step like "el-name[@xmlns='namespace']" will never match an element, 942 even if there is an element in the list that specifies a default 943 namespace of "namespace". In other words, a namespace node is NOT an 944 attribute. If the namespaces in scope for an element are needed, 945 they can be selected using the namespace-selector described below. 946 If there are no elements with attributes having the given name and 947 value, the result is a no-match. 949 After the predicates have been applied, the result will be a no- 950 match, one element, or multiple elements. If the result is multiple 951 elements, the node selector is invalid. Each step in a node selector 952 MUST produce a single element to form the context for the next step. 953 This is more restrictive than general XPath expressions, which allow 954 a context to contain multiple nodes. If the result is a no-match, 955 the node selector is invalid. The node selector is only valid if a 956 single element was selected. This element becomes the context for 957 the evaluation of the next step in the node selector expression. 959 The last location step is either the previously described element 960 selector or a "terminal selector". If the terminal selector is an 961 attribute selector, the server checks to see if there is an attribute 962 with the same expanded name in the current element context. If there 963 is not, the result is considered a no-match. Otherwise, that 964 attribute is selected. If the terminal selector is a namespace 965 selector, the result is equal to the set of namespace bindings in 966 scope for the element, including the possible default namespace 967 declaration. This specification defines a syntax for representing 968 namespace bindings, so they can be returned to the client in an HTTP 969 response. 971 As a result, once the entire node selector is evaluated against the 972 document, the result will either be a no-match, invalid, a single 973 element, a single attribute or a set of namespace bindings. 975 Matching of element names is performed as follows. The element being 976 compared in the step has its name expanded as described in XML 977 namespaces [3]. The element name in the step is also expanded. This 978 expansion requires that any namespace prefix is converted to its 979 namespace URI. Doing that requires a set of bindings from prefixes 980 to namespace URIs. This set of bindings is obtained from the query 981 component of the URI (see Section 6.4). If the prefix of the QName 982 of an element is empty, the corresponding URI is then the default 983 document namespace URI defined by the application usage, or null if 984 not defined. Comparisons are then performed as described in XML 985 namespaces [3]. Note that the namespace prefix expansions described 986 here are different than those specified in the XPath 1.0 987 specification, but are closer to those currently defined by the XPath 988 2.0 specification [24]. 990 Matching of attribute names proceeds in a similar way. The attribute 991 in the document has its name expanded as described in XML namespaces 992 [3]. If the attribute name in the attribute selector has a namespace 993 prefix, its name is expanded using the namespace bindings obtained 994 from the query component of the URI. An unprefixed attribute QName 995 is in no namespace. 997 Comments, text content (including whitespace), and processing 998 instructions can be present in a document, but cannot be selected by 999 the expressions defined here. Of course, if such information is 1000 present in a document, and a user selects an XML element enclosing 1001 that data, that information would be included in a resulting GET, for 1002 example. Furthermore, whitespace is respected by XCAP. If a client 1003 PUTs an element or document that contains whitespace, the server 1004 retains that whitespace, and will return the element or document back 1005 to the client with exactly the same whitespace. Similarly, when an 1006 element is inserted, no additional whitespace is added around the 1007 inserted element, and the element gets inserted in a very specific 1008 location relative to any whitespace, comments or processing 1009 instructions around it. Section 8.2.3 describes where the insertion 1010 occurs. 1012 As an example, consider the following XML document: 1014 1015 1017 1019 sip:userA@example.net 1023 sip:userB@example.org 1027 1028 1030 Figure 3: Example XML Document 1032 Assuming that the default document namespace for this application 1033 usage is "urn:ietf:params:xml:ns:watcherinfo", the node selector 1034 watcherinfo/watcher-list/watcher[@id="8ajksjda7s"] would select the 1035 following XML element: 1037 sip:userA@example.net 1042 6.4. Namespace Bindings for the Selector 1044 In order to expand the namespace prefixes used in the node selector, 1045 a set of bindings from those namespace prefixes to namespace URI must 1046 be used. Those bindings are contained in the query component of the 1047 URI. If no query component is present, it means that only the 1048 default document namespace (as identified by the application usage) 1049 is defined. The query component is formatted as a valid xpointer 1050 expression [5] after suitable URI encoding as defined in Section 4.1 1051 of the Xpointer framework. This xpointer expression SHOULD only 1052 contain expressions from the xmlns() scheme [4]. A server compliant 1053 to this specification MUST ignore any xpointer expressions not from 1054 the xmlns() scheme. The xmlns() xpointer expressions define the set 1055 of namespace bindings in use for evaluating the URI. 1057 Note that xpointer expressions were originally designed for usage 1058 within fragment identifiers of URIs. However, within XCAP, they are 1059 used within query components of URIs. 1061 The following example shows a more complex matching operation, this 1062 time including the usage of namespace bindings. Consider the 1063 following document: 1065 1066 1067 1069 1070 1071 1072 1073 1074 1075 1077 Assume that this document has a document URI of 1078 "http://xcap.example.com/test/users/sip:joe@example.com/index", where 1079 "test" is the application usage. This application usage defines a 1080 default document namespace of "urn:test:default-namespace". The XCAP 1081 URI: 1083 http://xcap.example.com/test/users/sip:joe@example.com/index/ 1084 ~~/foo/a:bar/b:baz?xmlns(a=urn:test:namespace1-uri) 1085 xmlns(b=urn:test:namespace1-uri) 1087 will select the first child element of the element in the 1088 document. The XCAP URI: 1090 http://xcap.example.com/test/users/sip:joe@example.com/index/ 1091 ~~/foo/a:bar/b:baz?xmlns(a=urn:test:namespace1-uri) 1092 xmlns(b=urn:test:namespace2-uri) 1094 will select the second child element of the element in 1095 the document. The following XCAP URI will also select the second 1096 element in the document: 1098 http://xcap.example.com/test/users/sip:joe@example.com/index/ 1099 ~~/d:foo/a:bar/b:baz?xmlns(a=urn:test:namespace1-uri) 1100 xmlns(b=urn:test:namespace2-uri) 1101 xmlns(d=urn:test:default-namespace) 1103 7. Client Operations 1105 An XCAP client is an HTTP/1.1 compliant client. Specific data 1106 manipulation tasks are accomplished by invoking the right set of HTTP 1107 methods with the right set of headers on the server. This section 1108 describes those in detail. 1110 In all cases where the client modifies a document, by deleting or 1111 inserting a document, element or attribute resource, the client 1112 SHOULD verify that, if the operation were to succeed, the resulting 1113 document would meet the data constraints defined by the application 1114 usage, including schema validation. For example, if the client 1115 performs a PUT operation to "http://xcap.example.com/rls-services/ 1116 users/sip:joe@example.com/mybuddies", rls-services is the application 1117 unique ID, and the constraints defined by it SHOULD be followed. 1119 The client will know what URI to use based on the naming conventions 1120 described by the application usage. 1122 If the document, after modification, does not meet the data 1123 constraints, the server will reject it with a 409. The 409 response 1124 may contain an XML body, formatted according to the schema in 1125 Section 11.2, which provides further information on the nature of the 1126 error. The client MAY use this information to try and alter the 1127 request so that this time, it might succeed. The client SHOULD NOT 1128 simply retry the request without changing some aspect of it. 1130 In some cases, the application usage will dictate a uniqueness 1131 constraint that the client cannot guarantee on its own. One such 1132 example is that a URI has to be unique within a domain. Typically, 1133 the client is not the owner of the domain, and so it cannot be sure 1134 that a URI is unique. In such a case, the client can either generate 1135 a sufficiently random identifier, or it can pick a "vanity" 1136 identifier in the hopes that it is not taken. In either case, if the 1137 identifier is not unique, the server will reject the request with a 1138 409 and suggest alternatives that the client can use to try again. 1139 If the server does not suggest alternatives, the client SHOULD 1140 attempt to use random identifiers with increasing amounts of 1141 randomness. 1143 HTTP also specifies that PUT and DELETE requests are idempotent. 1144 This means that, if the client performs a PUT on a document and it 1145 succeeds, it can perform the same PUT, and the resulting document 1146 will look the same. Similarly, when a client performs a DELETE, if 1147 it succeeds, a subsequent DELETE to the same URI will generate a 404; 1148 the resource no longer exists on the server since it was deleted by 1149 the previous DELETE operation. To maintain this property, the client 1150 SHOULD construct its URIs such that, after the modification has taken 1151 place, the URI in the request will point to the resource just 1152 inserted for PUT (i.e., the body of the request), and will point to 1153 nothing for DELETE. If this property is maintained, it is the case 1154 that GET to the URI in the PUT will return the same content (i.e., 1155 GET(PUT(X)) == x). This property implies idempotency. Although a 1156 request can still be idempotent if it does not possess this property, 1157 XCAP does not permit such requests. If the client's request does not 1158 have this property, the server will reject the request with a 409 and 1159 indicate a cannot-insert error condition. 1161 If the result of the PUT is a 200 or 201 response, the operation was 1162 successful. Other response codes to any request, such as a 1163 redirection, are processed as per RFC 2616 [6]. 1165 7.1. Create or Replace a Document 1167 To create or replace a document, the client constructs a URI that 1168 references the location where the document is to be placed. This URI 1169 MUST be a document URI, and therefore contain the XCAP root and 1170 document selector. The client then invokes a PUT method on that URI. 1172 The MIME content type MUST be the type defined by the application 1173 usage. For example, it would be "application/rls-services+xml" for 1174 an RLS services [22] document, and not "application/xml". 1176 If the Request-URI identifies a document that already exists in the 1177 server, the PUT operation replaces that document with the content of 1178 the request. If the Request-URI does not identify an existing 1179 document, the document is created on the server at that specific URI. 1181 7.2. Delete a Document 1183 To delete a document, the client constructs a URI that references the 1184 document to be deleted. This URI MUST be a document URI. The client 1185 then invokes a DELETE operation on the URI to delete the document. 1187 7.3. Fetch a Document 1189 As one would expect, fetching a document is trivially accomplished by 1190 performing an HTTP GET request with the Request URI set to the 1191 document URI. 1193 7.4. Create or Replace an Element 1195 To create or replace an XML element within an existing document, the 1196 client constructs a URI whose document selector points to the 1197 document to be modified. The node selector MUST be present in the 1198 URI, delimited from the document selector with the node selector 1199 separator. The query component MUST be present if the node selector 1200 makes use of namespace prefixes, in which case the xmlns() 1201 expressions in the query component MUST define those prefixes. To 1202 create this element within the document, the node selector is 1203 constructed such that it is a no-match against the current document, 1204 but if the element in the body of the request was added to the 1205 document as desired by the client, the node selector would select 1206 that element. To replace an element in the document, the node 1207 selector is constructed so that it is a match against the element in 1208 the current document to be replaced, as well as a match to the new 1209 element (present in the body of the PUT request) that is to replace 1210 it. 1212 Oftentimes, the client will wish to insert an element into a document 1213 in a certain position relative to other children of the same parent. 1214 This is called a positional insertion. They often arise because the 1215 schema constrains where the element can occur, or because ordering of 1216 elements is significant within the schema. To accomplish this, the 1217 client can use a node selector of the following form: 1219 parent/*[position][unique-attribute-value] 1221 Here, "parent" is an expression for the parent of the element to be 1222 inserted. "position" is the position amongst the existing child 1223 elements of this parent where the new element is to be inserted. 1224 "unique-attribute-value" is an attribute name and value for the 1225 element to be inserted, which is different from the current element 1226 in "position". The second predicate is needed so that the overall 1227 expression is a no-match when evaluated against the current children. 1228 Otherwise, the PUT would replace the existing element in that 1229 position. Note that in addition to wildcard "*" a QName can also be 1230 used as a node test. The insert logic is described in more detail in 1231 Section 8.2.3. 1233 Consider the example document in Figure 3. The client would like to 1234 insert a new element as the second element underneath 1235 . However, it cannot just PUT to a URI with the 1236 watcherinfo/watcher-list/*[2] node selector; this node selector would 1237 select the existing 2nd child element of and replace 1238 it. Thus, the PUT has to be made to a URI with watcherinfo/ 1239 watcher-list/*[2][@id="hhggff"] as the node selector, where "hhggff" 1240 is the value of the "id" attribute of the new element to be inserted. 1241 This node-selector is a no-match against the current document, and 1242 would be a match against the new element if it was inserted as the 1243 2nd child element of . 1245 The "*" indicates that all element children of are to 1246 be considered when computing the position for insertion. If, instead 1247 of a wildcard *, an element name (QName) was present, the expression 1248 above would insert the new element as the position-th element amongst 1249 those with the same expanded name (see Section 8.2.3 for a discussion 1250 on insertion rules). 1252 Once the client constructs the URI, it invokes the HTTP PUT method. 1253 The content in the request MUST be an XML element. Specifically, it 1254 contains the element, starting with the opening bracket for the begin 1255 tag for that element, including the attributes and content of that 1256 element (whether it be text or other child elements), and ending with 1257 the closing bracket for the end tag for that element. The MIME type 1258 in the request MUST be "application/xcap-el+xml", defined in 1259 Section 15.2.1. If the node selector, when evaluated against the 1260 current document, results in a no-match, the server performs a 1261 creation operation. If the node selector, when evaluated against the 1262 current document, is a match for an element in the current document, 1263 the server replaces it with the content of the PUT request. This 1264 replacement is complete; that is, the old element (including its 1265 attributes, namespace declarations and content: text, element, 1266 comment and processing instruction nodes) are removed, and the new 1267 one, including its attributes, namespace declarations and content, is 1268 put in its place. 1270 To be certain that element insertions have the GET(PUT(x))==x 1271 property, the client can check that the attribute predicates in the 1272 final path segment of the URI match the attributes of the element in 1273 the body of the request. As an example of an request that would not 1274 have this property and therefore not be idempotent, consider the 1275 following PUT request (URIs are line-folded for readability): 1277 PUT 1278 /rls-services/users/sip:bill@example.com/index/~~/rls-services/ 1279 service%5b@uri=%22sip:good-friends@example.com%22%5d 1280 HTTP/1.1 1281 Content-Type:application/xcap-el+xml 1282 Host: xcap.example.com 1284 1285 http://xcap.example.com/resource-lists/users 1286 /sip:joe@example.com/index/~~/resource-lists/list%5b@name=%22l1%22%5d 1287 1288 1289 presence 1290 1291 1293 This request will fail with a 409. The Request URI contains a final 1294 path segment with a predicate based on attributes - 1295 @uri="sip:good-friends@example.com". However, this will not match 1296 the value of the "uri" attribute in the element in the body 1297 (sip:mybuddies@example.com). 1299 The GET(PUT(x))==x property introduces some limitations on the types 1300 of operations possible. It will not be possible to replace an 1301 element with one that has a new value for an attribute that is the 1302 sole unique element identifier, if the URI contained a node selector 1303 which was using the previous value of that attribute for purposes of 1304 selecting the element. This is exactly the use case in the example 1305 above. To get around this limitation, the selection can be done by 1306 position instead of attribute value, or the parent of the element to 1307 be replaced can be selected, and then the body of the PUT operation 1308 would contain the parent, the child to be replaced, and all other 1309 siblings. 1311 7.5. Delete an Element 1313 To delete an element from a document, the client constructs a URI 1314 whose document selector points to the document containing the element 1315 to be deleted. The node selector MUST identify a single element. 1316 The node selector MUST be present following the node selector 1317 separator, and identify the specific element to be deleted. 1318 Furthermore, the node selector MUST match no element after the 1319 deletion of the target element. This is required to maintain the 1320 idempotency property of HTTP deletions. The query component MUST be 1321 present if the node selector makes use of namespace prefixes, in 1322 which case the xmlns() expressions in the query component MUST define 1323 those prefixes. 1325 If the client wishes to delete an element in a specific position, 1326 this is referred to as a positional deletions. Like a positional 1327 insertion, the node selector has the following form: 1329 parent/*[position][unique-attribute-value] 1331 Where "parent" is an expression for the parent of the element to be 1332 deleted, "position" is the position of the element to be deleted 1333 amongst the existing child elements of this parent, and "unique- 1334 attribute-value" is an attribute name and value for the element to be 1335 deleted, where this attribute name and value are different than any 1336 of the siblings of the element. 1338 Positional deletions without using a unique attribute name and value 1339 are possible, but only in limited cases where idempotency is 1340 guaranteed. In particular, if a DELETE operation refers to an 1341 element by name and position alone (parent/elname[n]), this is 1342 permitted only when the element to be deleted is the last element 1343 amongst all its siblings with that name. Similarly, if a DELETE 1344 operation refers to an element by position alone (parent/*[n]), this 1345 is permitted only when the elemented to be deleted is the last 1346 amongst all sibling elements, regardless of name. 1348 The client then invokes the HTTP DELETE method. The server will 1349 remove the element from the document (including its attributes, 1350 namespace declarations and its descendant nodes, such as any 1351 children). 1353 7.6. Fetch an Element 1355 To fetch an element of a document, the client constructs a URI whose 1356 document selector points to the document containing the element to be 1357 fetched. The node selector MUST be present following the node 1358 selector separator, and must identify the element to be fetched. The 1359 query component MUST be present if the node selector makes use of 1360 namespace prefixes, in which case the xmlns() expressions in the 1361 query component MUST define those prefixes. 1363 The client then invokes the GET method. The 200 OK response will 1364 contain that XML element. Specifically, it contains the content of 1365 the XML document, starting with the opening bracket for the begin tag 1366 for that element, and ending with the closing bracket for the end tag 1367 for that element. This will, as a result, include all attributes, 1368 namespace declarations and descendant nodes: elements, comments, text 1369 and processing instructions of that element. 1371 7.7. Create or Replace an Attribute 1373 To create or replace an attribute in an existing element of a 1374 document, the client constructs a URI whose document selector points 1375 to the document to be modified. The node selector, following the 1376 node selector separator, MUST be present. The node selector MUST be 1377 constructed such that, if the attribute was created or replaced as 1378 desired, the node selector would select that attribute. If the node 1379 selector, when evaluated against the current document, results in a 1380 no-match, it is a creation operation. If it matches an existing 1381 attribute, it is a replacement operation. The query component MUST 1382 be present if the node selector makes use of namespace prefixes, in 1383 which case the xmlns() expressions in the query component MUST define 1384 those prefixes. 1386 The client then invokes the HTTP PUT method. The content defined by 1387 the request MUST be the value of the attribute, compliant to the 1388 grammar for AttValue as defined in XML 1.0 [1]. Note that, unlike 1389 when AttValue is present in the URI, there is no percent-encoding 1390 which only applies to URIs. This request MUST be sent with the 1391 Content-Type of "application/xcap-att+xml" as defined in 1392 Section 15.2.2. The server will add that attribute such that, if the 1393 node selector is evaluated on the resulting document, it returns the 1394 attribute present in the request. 1396 To be certain that attribute insertions have the GET(PUT(x))==x 1397 property, the client can check that any attribute predicate in the 1398 path segment that selects the element into which the attribute is 1399 inserted, matches a different attribute than the one being inserted 1400 by the request. As an example of a request that would not have this 1401 property and therefore not be idempotent, consider the following PUT 1402 request (URIs are line folded for readability): 1404 PUT 1405 /rls-services/users/sip:bill@example.com/index/~~/rls-services 1406 /service%5b@uri=%22sip:good-friends@example.com%22%5d/@uri 1407 HTTP/1.1 1408 Content-Type:application/xcap-att+xml 1409 Host: xcap.example.com 1411 "sip:bad-friends@example.com" 1413 As with element insertions and replacements, the GET(PUT(x))==x 1414 property introduces limitations on attribute insertions and 1415 replacements. It will not be possible to replace the attribute value 1416 of an attribute, when that attribute is the sole unique element 1417 identifier, and the URI contains a node selector that uses the 1418 previous value of the attribute to select the affected element. This 1419 is the use case in the example above. Instead, the element can be 1420 selected positionally, or its entire parent replaced. 1422 This request will fail with a 409. 1424 7.8. Delete an Attribute 1426 To delete attributes from the document, the client constructs a URI 1427 whose document selector points to the document containing the 1428 attributes to be deleted. The node selector MUST be present 1429 following the node selector separator, and evaluate to an attribute 1430 in the document to be deleted. The query component MUST be present 1431 if the node selector makes use of namespace prefixes, in which case 1432 the xmlns() expressions in the query component MUST define those 1433 prefixes. 1435 The client then invokes the HTTP DELETE method. The server will 1436 remove the attribute from the document. 1438 7.9. Fetch an Attribute 1440 To fetch an attribute of a document, the client constructs a URI 1441 whose document selector points to the document containing the 1442 attribute to be fetched. The node selector MUST be present following 1443 the node selector separator, containing an expression identifying the 1444 attribute whose value is to be fetched. The query component MUST be 1445 present if the node selector makes use of namespace prefixes, in 1446 which case the xmlns() expressions in the query component MUST define 1447 those prefixes. 1449 The client then invokes the GET method. The 200 OK response will 1450 contain an "application/xcap-att+xml" document with the specified 1451 attribute, formatted according to the grammar of AttValue as defined 1452 in the XML 1.0 specifications. 1454 7.10. Fetch Namespace Bindings 1456 If a client wishes to insert an element or attribute into a document, 1457 and that element or attribute is part of a namespace declared 1458 elsewhere in the document, the client will need to know the namespace 1459 bindings in order to construct the XML content in the request. If 1460 the client has a cached copy of the document, it will know the 1461 bindings. However, if it doesn't have the whole document cached, it 1462 can be useful to fetch just the bindings that are in scope for an 1463 element, in order to construct a subsequent PUT request. 1465 To get those bindings, the client constructs a URI whose document 1466 selector points to the document containing the element whose 1467 namespace bindings are to be fetched. The node selector MUST be 1468 present following the node selector separator, containing an 1469 expression identifying the desired namespace bindings. The query 1470 component MUST be present if the node selector makes use of namespace 1471 prefixes, in which case the xmlns() expressions in the query 1472 component MUST define those prefixes. 1474 The client then invokes the GET method. The 200 OK response will 1475 contain an "application/xcap-ns+xml" document with the namespace 1476 definitions. The format for this document is defined in Section 10. 1478 A client cannot set the namespace prefixes in scope for an element. 1479 As such, a node selector that identifies namespace prefixes MUST NOT 1480 appear in a PUT or DELETE request. 1482 7.11. Conditional Operations 1484 The HTTP specification defines several header fields that can be used 1485 by a client to make the processing of the request conditional. In 1486 particular, the If-None-Match and If-Match header fields allow a 1487 client to make them conditional on the current value of the entity 1488 tag for the resource. These conditional operations are particularly 1489 useful for XCAP resources. 1491 For example, it is anticipated that clients will frequently wish to 1492 cache the current version of a document. So, when the client starts 1493 up, it will fetch the current document from the server and store it. 1494 When it does so, the GET response will contain the entity tag for the 1495 document resource. Each resource within a document maintained by the 1496 server will share the same value of the entity tag. As a result, the 1497 entity tag returned by the server for the document resource is 1498 applicable to element and attribute resources within the document. 1500 If the client wishes to insert or modify an element or attribute 1501 within the document, but it wants to be certain that the document 1502 hasn't been modified since the client last operated on it, it can 1503 include an If-Match header field in the request, containing the value 1504 of the entity tag known to the client for all resources within the 1505 document. If the document has changed, the server will reject this 1506 request with a 412 response. In that case, the client will need to 1507 flush its cached version, fetch the entire document, and store the 1508 new entity tag returned by the server in the 200 OK to the GET 1509 request. It can then retry the request, placing the new entity tag 1510 in the If-Match header field. If this succeeds, the Etag header 1511 field in the response to PUT contains the entity tag for the resource 1512 that was just inserted or modified. Because all resources in a 1513 document share the same value for their entity tag, this entity tag 1514 value can be applied to the modification of other resources. 1516 A client can also conditionally delete elements or attributes by 1517 including an If-Match header field in DELETE requests. Note that the 1518 200 OK responses to a DELETE will contain an Etag header field, 1519 containing the entity tag for all of the other resources in the 1520 document, even though the resource identified by the DELETE request 1521 no longer exists. 1523 When a client uses conditional PUT and DELETE operations, it can 1524 apply those changes to its local cached copy, and update the value of 1525 the entity tag for the locally cached copy based on the Etag header 1526 field returned in the response. As long as no other clients try to 1527 modify the document, the client will be able to perform conditional 1528 operations on the document without ever having to perform separate 1529 GET operations to synchronize the document and it's entity tags with 1530 the server. If another client tries to modify the document, this 1531 will be detected by the conditional mechanisms, and the client will 1532 need to perform a GET to resynchronize its copy unless it has some 1533 other means to learn about the change. 1535 If a client does not perform a conditional operation, but did have a 1536 cached copy of the document, that cached copy will become invalid 1537 once the operation is performed (indeed, it may have become invalid 1538 even beforehand). Unconditional operations should only be performed 1539 by clients when knowledge of the entire document is not important for 1540 the operation to succeed. 1542 In another example, a client may wish to insert a new element into a 1543 document, but wants to be sure that the insertion will only take 1544 place if that element does not exist. In other words, the client 1545 wants the PUT operation to be a creation, not a replacement. To 1546 accomplish that, the client can insert the If-None-Match header field 1547 into the PUT request, with a value of *. This tells the server to 1548 reject the request with a 412 if resource exists. 1550 As another example, a when a client fetches a document, and there is 1551 an older version cached, it is useful for clients to use a 1552 conditional GET in order to reduce network usage if the cached copy 1553 is still valid. This is done by including, in the GET request, the 1554 If-None-Match header field with a value equal to the current etag 1555 held by the client for the document. The server will only generate a 1556 200 OK reponse if the etag held by the server differs than that held 1557 by the client. If it doesn't differ, the server will respond with a 1558 304 response. 1560 8. Server Behavior 1562 An XCAP server is an HTTP/1.1 compliant origin server. The behaviors 1563 mandated by this specification relate to the way in which the HTTP 1564 URI is interpreted and the content is constructed. 1566 An XCAP server MUST be explicitly aware of the application usage 1567 against which requests are being made. That is, the server must be 1568 explicitly configured to handle URIs for each specific application 1569 usage, and must be aware of the constraints imposed by that 1570 application usage. 1572 When the server receives a request, the treatment depends on the URI. 1573 If the URI refers to an application usage not understood by the 1574 server, the server MUST reject the request with a 404 (Not Found) 1575 response. If the URI refers to a user that is not recognized by the 1576 server, it MUST reject the request with a 404 (Not Found). If the 1577 URI includes extension-selectors that the server doesn't understand, 1578 it MUST reject the request with a 404 (Not Found). 1580 Next, the server authenticates the request. All XCAP servers MUST 1581 implement HTTP Digest [11]. Furthermore, servers MUST implement HTTP 1582 over TLS, RFC 2818 [14]. It is RECOMMENDED that administrators use 1583 an HTTPS URI as the XCAP root URI, so that the digest client 1584 authentication occurs over TLS. 1586 Next, the server determines if the client has authorization to 1587 perform the requested operation on the resource. The application 1588 usage defines the authorization policies. An application usage may 1589 specify that the default is used. This default is described in 1590 Section 5.7. 1592 Next, the server makes sure that it can properly evaluate the request 1593 URI. The server MUST check the node selector in the request URI, if 1594 present. If any qualified names are present that use a namespace 1595 prefix, and that prefix is not defined in an xmlns() expression in 1596 the query component of the request URI, the server MUST reject the 1597 request with a 400 response. 1599 After checking the namespace prefix definitions, the specific 1600 behavior depends on the method and what the URI refers to. 1602 8.1. POST Handling 1604 XCAP resources do not represent processing scripts. As a result, 1605 POST operations to HTTP URIs representing XCAP resources are not 1606 defined. A server receiving such a request for an XCAP resource 1607 SHOULD return a 405. 1609 8.2. PUT Handling 1611 The behavior of a server in receipt of a PUT request is as specified 1612 in HTTP/1.1 Section 9.6 - the content of the request is placed at the 1613 specified location. This section serves to define the notion of 1614 "placement" and "specified location" within the context of XCAP 1615 resources. 1617 If the request URI contained a namespace-selector, the server MUST 1618 reject the request with a 405 (Method Not Allowed) and MUST include 1619 an Allow header field including the GET method. 1621 8.2.1. Locating the Parent 1623 The first step the server performs is to locate the parent, whether 1624 it is a directory or element, in which the resource is to be placed. 1625 To do that, the server removes the last path segment from the URI. 1626 The rest of the URI refers to the parent. This parent can be a 1627 document, element, or prefix of a document selector (called a 1628 directory, even though this specification does not mandate that 1629 documents are actually stored in a filesystem). This URI is called 1630 the parent URI. The path segment that was removed is called the 1631 target selector, and the node (element, document or attribute) it 1632 describes is called the target node. 1634 If the parent URI has no node selector separator, it is referring to 1635 the directory into which the document should be inserted. In normal 1636 XCAP operations, this will be either the users home directory or the 1637 global directory, which will always exist on the server. However, if 1638 an application usage is making use of subdirectories (despite the 1639 fact that this is not recommended), it is possible that the directory 1640 into which the document should be inserted does not exist. In this 1641 case, the server MUST return a 409 response, and SHOULD include a 1642 detailed conflict report including the element. Detailed 1643 conflict reports are discussed in Section 11. If the directory does 1644 exist, the server checks to see if there is a document with the same 1645 filename as the target node. If there is, the operation is the 1646 replacement operation discussed in Section 8.2.4. If it does not 1647 exist, it is the creation operation, discussed in Section 8.2.3. 1649 If the parent URI has a node selector separator, the document 1650 selector is extracted, and that document is retrieved. If the 1651 document does not exist, the server MUST return a 409 response, and 1652 SHOULD include a detailed conflict report including the 1653 element. If it does exist, the node selector is extracted, and 1654 decoded (recall that the node selector is percent-encoded). The node 1655 selector is applied to the document based on the matching operations 1656 discussed in Section 6.3. If the result is a no-match or invalid, 1657 the server MUST return a 409 response, and SHOULD include a detailed 1658 conflict report including the element. 1660 If the node-selector is valid, the server examines the target 1661 selector, and evaluates it within the context of the parent node. If 1662 the target node exists within the parent, the operation is a 1663 replacement, as described in Section 8.2.4. If it does not exist, it 1664 is the creation operation, discussed in Section 8.2.3. 1666 Before performing the replacement or creation, as determined based on 1667 the logic above, the server validates the content of the request as 1668 described in Section 8.2.2 1670 8.2.2. Verifying Document Content 1672 If the PUT request is for a document (the request URI had no node 1673 selector separator), the content of the request body has to be a 1674 well-formed XML document. If it is not, the server MUST reject the 1675 request with a 409 response code. That response SHOULD include a 1676 detailed conflict report including the element. If 1677 the document is well-formed but not UTF-8 encoded, the server MUST 1678 reject the request with a 409 response code. That response SHOULD 1679 include a detailed conflict report including the element. 1680 If the MIME type in the Content-Type header field of the request is 1681 not equal to the MIME type defined for the application usage, the 1682 server MUST reject the request with a 415. 1684 If the PUT request is for an element, the content of the request body 1685 has to be a well-balanced region of an XML document, also known as an 1686 XML fragment body in The XML Fragment Interchange [23] specification, 1687 including only a single element. If it is not, the server MUST 1688 reject the request with a 409 response code. That response SHOULD 1689 include a detailed conflict report including the 1690 element. If the fragment body is well-balanced but contains 1691 characters outside of the UTF-8 character set, the server MUST reject 1692 the request with a 409 response code. That response SHOULD include a 1693 detailed conflict report including the element. If the 1694 MIME type in the Content-Type header field of the request is not 1695 equal to "application/xcap-el+xml", the server MUST reject the 1696 request with a 415. 1698 If the PUT request is for an attribute, the content of the request 1699 body has to be a sequence of characters that comply with the grammar 1700 for AttValue as defined above. If it is not, the server MUST reject 1701 the request with a 409 response code. That response SHOULD include a 1702 detailed conflict report including the element. 1703 If the attribute value is valid but contains characters outside of 1704 the UTF-8 character set, the server MUST reject the request with a 1705 409 response code. That response SHOULD include a detailed conflict 1706 report including the element.If the MIME type in the 1707 Content-Type header field of the request is not equal to 1708 "application/xcap-att+xml", the server MUST reject the request with a 1709 415. 1711 8.2.3. Creation 1713 The steps in this sub-section are followed if the PUT request will 1714 result in the creation of a new document, element or attribute. 1716 If the PUT request is for a document, the content of the request body 1717 is placed into the directory, and its filename is associated with the 1718 target node, which is a document. 1720 If the PUT request is for an element, the server inserts the content 1721 of the request body as a new child element of the parent element 1722 selected in Section 8.2.1. The insertion is done such that, the 1723 request URI, when evaluated, would now point to the element which was 1724 inserted. There exist three possible ways how new elements are 1725 positioned. 1727 First, if there were no other sibling elements with the same expanded 1728 name, and the insertion is not positionally constrained, the new 1729 element is inserted such that it is the last element amongst all 1730 element siblings. Furthermore, if there were comment, text, or 1731 processing instruction nodes after the former last element, they MUST 1732 occur prior to the insertion of the new element. This case occurs 1733 when one of the following are true: 1735 o The element name in the target selector is not wildcarded. There 1736 could be an attribute selector (in which case, it would have to 1737 match an attribute of the element being inserted), and the 1738 position in the target selector will either be absent or have a 1739 value of 1 (a value greater than one would always result in 1740 rejection of the request, since this is the first element with the 1741 given name underneath the parent). 1743 o The element name in the target selector is wildcarded, but there 1744 are no other elements underneath the same parent. There could be 1745 an attribute selector (in which case, it would have to match an 1746 attribute of the element being inserted), and the position in the 1747 target selector will either be absent or have a value of 1 (a 1748 value greater than one would always result in rejection of the 1749 request, since this is the first element underneath the parent). 1751 o The element name in the target selector is wildcarded, and there 1752 are other elements underneath the same parent. However, there is 1753 an attribute selector which matches none of the attributes in the 1754 other sibling elements underneath the parent, but does match an 1755 attribute of the element to be inserted. The position in the 1756 target selector is absent. 1758 Secondly, if there were sibling elements with the same name already 1759 in the document, but the insertion is positionally unconstrained, the 1760 server MUST insert the element such that it is in the "earliest last" 1761 position. "Earliest last" means that the new element MUST be 1762 inserted so that there are no elements after it with the same 1763 expanded name, and for all insertion positions where this is true, it 1764 is inserted such that as many sibling nodes (element, comment, text 1765 or processing instruction) appear after it as possible. This case 1766 occurs when the target selector is defined by a by-name or by-attr 1767 production, and there is no position indicated. 1769 Lastly, if the element is positionally constrained, the server MUST 1770 insert the element so that it is in the "earliest nth" position. 1771 When n>1 and NameofAny is not a wildcard, the element MUST be 1772 inserted so that there are n-1 sibling elements before it with the 1773 same expanded name. If there are not n-1 sibling elements with the 1774 same expanded name, the request will fail. When n>1 and NameorAny is 1775 a wildcard, the element MUST be inserted so that there are n-1 1776 sibling elements before it, each of which can have any expanded name. 1777 If there are not n-1 sibling elements in the document, the request 1778 will fail. In both of these cases, the new element is inserted such 1779 that as many sibling nodes appear after it as possible. When n=1 and 1780 NameorAny is not a wildcard, the insertion is positionally 1781 constrained when an element with the same expanded name already 1782 appears as a child of the same parent. In this case, the new element 1783 MUST appear just before the existing first element with this same 1784 expanded name. When n=1 and NameorAny is wildcarded, the insertion 1785 is positionally constrained when there is also an attribute selector 1786 that didn't match the first sibling of the parent (if it did match, 1787 or was absent, this wouldn't have been an insertion). In this case, 1788 the new element MUST appear just before all existing elements 1789 regardless of their expanded name. 1791 In practice, this insertion logic keeps elements with the same 1792 expanded names closely together. This simplifies the application 1793 logic when the content model is described by XML schema with 1794 rules and maxOccurs="unbounded" cardinalities, like: 1796 1797 1798 1799 1800 1801 1802 1803 1805 Based on this schema, the document contains some number of 1806 elements followed by some number of elements. Either or 1807 elements may easily be added without wildcards and positional 1808 constraints. Note that if "minOccurs" cardinality of element 1809 were zero and elements don't exist yet, a positional predicate 1810 with the * wildcard must be used. 1812 The whole insert logic is best described by complete examples, 1813 consider the following document: 1815 1816 1817 1818 1819 1820 and whose node 1824 selector is root/el1[@att="third"] would result in the following 1825 document: 1827 1828 1829 1830 1831 1832 and the 1841 node selector was root/el3, it would result in the following 1842 document: 1844 1845 1846 1847 1848 1849 1852 A PUT request whose content is and whose node selector 1853 is root/el2[@att="2"] would result in the following document: 1855 1856 1857 1858 1859 1860 1861 1863 It would have been inserted in exactly the same place if the node 1864 selector had been root/el2[2][@att="2"]. However, a selector root/ 1865 *[2][@att="2"] would result in the following document: 1867 1868 1869 1870 1871 1872 1873 1875 Lastly, if the node selector had been root/el2[1][@att="2"] the 1876 result would be: 1878 1879 1880 1881 1882 1883 1884 1886 It is possible that the element cannot be inserted such that the 1887 request URI, when evaluated, returns the content provided in the 1888 request. Such a request is not allowed for PUT. This happens when 1889 the element in the body is not described by the expression in the 1890 target selector. An example of this case is described in 1891 Section 7.4. If this happens the server MUST NOT perform the 1892 insertion, and MUST reject the request with a 409 response. The body 1893 of the response SHOULD contain a detailed conflict report containing 1894 the element. It is important to note that schema 1895 compliance does not play a role while performing the insertion. That 1896 is, the decision of where the element gets inserted is dictated 1897 entirely by the structure of the request-URI, the current document, 1898 and the rules in this specification. 1900 If the element being inserted (or any of its children) contain 1901 namespace declarations, those declarations are retained when the 1902 element is inserted, even if those same declarations exist in a 1903 parent element after insertion. The XCAP server MUST NOT remove 1904 redundant namespace declarations or otherwise change the namespace 1905 declarations that were present in the element being inserted. 1907 If the PUT request is for an attribute, the server inserts the 1908 content of the request body as the value of the attribute. The name 1909 of the attribute is equal to the att-name from the attribute-selector 1910 in the target selector. 1912 Assuming that the insertion can be accomplished, the server verifies 1913 that the insertion results in a document that meets the constraints 1914 of the application usage. This is dicussed in Section 8.2.5. 1916 8.2.4. Replacement 1918 The steps in this sub-section are followed if the PUT request will 1919 result in the replacement of a document, element or attribute with 1920 the contents of the request. 1922 If the PUT request is for a document, the content of the request body 1923 is placed into the directory, replacing the document with the same 1924 filename. 1926 If the PUT request is for an element, the server replaces the target 1927 node with the content of the request body. As in the creation case, 1928 it is possible that, after replacement, the request URI does not 1929 select the element that was just inserted. If this happens the 1930 server MUST NOT perform the replacement, and MUST reject the request 1931 with a 409 response. The body of the response SHOULD contain a 1932 detailed conflict report containing the element. 1934 As with creation, replacement of an element does not result in the 1935 changing or elimination of namespace declarations within the newly 1936 modified element. 1938 If the PUT request is for an attribute, the server sets the value of 1939 the selected attribute to the content of the request body. It is 1940 possible in the replacement case (but not in the creation case), 1941 that, after replacement of the attribute, the request URI no longer 1942 selects the attribute that was just replaced. The scenario in which 1943 this can happen is discussed in Section 7.7. If this is the case, 1944 the server MUST NOT perform the replacement, and MUST reject the 1945 request with a 409 response. The body of the response SHOULD contain 1946 a detailed conflict report containing the element. 1948 8.2.5. Validation 1950 Once the document, element or attribute has been tentatively inserted 1951 the server needs to verify that the resulting document meets the data 1952 constraints outlined by the application usage. 1954 First, the server checks that the final document is compliant to the 1955 schema. If it is not, the server MUST NOT perform the insertion. It 1956 MUST reject the request with a 409 response. That response SHOULD 1957 contain a detailed conflict report containing the element. If a schema allows for elements or attributes from 1959 other namespaces, and the new document contains elements or 1960 attributes from an unknown namespace, the server MUST allow the 1961 change. In other words, it is not necessary for an XCAP server to 1962 understand the namespaces and corresponding schemas for elements and 1963 attributes within a document, as long as the schema itself allows for 1964 such elements or attributes to be included. Of course, such unknown 1965 namespaces would not be advertised by the server in its XCAP 1966 capabilities document Section 12. 1968 If the final document contains elements or attributes from a 1969 namespace that the server does understand (and has consequently 1970 advertised in its XCAP capabilities document), but the server does 1971 not have the schema for that particular element or attribute, the 1972 server MUST reject the request with a 409 response. That response 1973 SHOULD contain a detailed conflict report containing the element. 1976 Next, the server checks for any uniqueness constraints identified by 1977 the application usage. If the application usage required that a 1978 particular element or attribute had a unique value within a specific 1979 scope, the server would check that this uniqueness property still 1980 exists. If the application usage required that a URI within the 1981 document was unique within the domain, the server checks whether it 1982 is the case. If any of these uniqueness constraints are not met, the 1983 server MUST NOT perform the insertion. It MUST reject the request 1984 with a 409 response. That response SHOULD contain a detailed 1985 conflict report containing the element. That 1986 element can contain suggested values that the client can retry with. 1987 These SHOULD be values that, at the time the server generates the 1988 409, would meet the uniqueness constraints. 1990 The server also checks for URI constraints and other non-schema data 1991 constraints. If the document fails one of these constraints, the 1992 server MUST NOT perform the insertion. It MUST reject the request 1993 with a 409 response. That response SHOULD contain a detailed 1994 conflict report containing the element. That 1995 element indicates that the document failed non-schema data 1996 constraints explicitly called out by the application usage. 1998 Element or attribute removals have similar constraints. The server 1999 checks the document for schema validity and compliance to constraints 2000 defined by the application usage, and rejects the request as 2001 described above if either check fails. 2003 8.2.6. Conditional Processing 2005 A PUT request for an XCAP resource, like any other HTTP resource, can 2006 be made conditional through usage of the If-Match and If-None-Match 2007 header fields. For a replacement, these are processed as defined in 2008 [6]. For an insertion of an element or attribute, conditional 2009 operations are permitted. The entity tag that is used for the 2010 procedures in [6] is the one for all of the resources within the same 2011 document as the parent of the element or attribute being inserted. 2012 One way to think of this is that, logically speaking, on receipt of 2013 the PUT request, the XCAP server instantiates the etag for the 2014 resource referenced by the request, and then applies the processing 2015 of the request. Because of this behavior, it is not possible to 2016 perform a conditional insert on an attribute or element conditioned 2017 on the operation being an insertion and not a replacement. In other 2018 words, a conditional PUT of an element or attribute with an If-None- 2019 Match: * will always fail. 2021 8.2.7. Resource Interdependencies 2023 Because XCAP resources include elements, attributes and documents, 2024 each of which has its own HTTP URI, the creation or modification of 2025 one resource affects the state of many others. For example, 2026 insertion of a document creates resources on the server for all of 2027 the elements and attributes within that document. After the server 2028 has performed the insertion associated with the PUT, the server MUST 2029 create and/or modify those resources affected by that PUT. The 2030 structure of the document completely defines the inter-relationship 2031 between those resources. 2033 However, the application usage can specify other resource inter- 2034 dependencies. The server MUST create or modify the resources 2035 specified by the application usage. 2037 If the creation or replacement was successful, and the resource 2038 interdependencies are resolved, the server returns a 201 Created or 2039 or 200 OK, respectively. Note that a 201 Created is generated for 2040 creation of new documents, elements, or attributes. A 200 OK 2041 response to PUT MUST not contain any content. Per the 2042 recommendations of RFC 2616, the 201 can contain a Location header 2043 field and entity that identify the resource that was created. An 2044 entity tag MUST be included in all successful responses to a PUT. 2046 8.3. GET Handling 2048 The semantics of GET are as specified in RFC 2616. This section 2049 clarifies the specific content to be returned for a particular URI 2050 that represents an XCAP resource. 2052 If the request URI contains only a document selector, the server 2053 returns the document specified by the URI if it exists, else returns 2054 a 404 response. The MIME type of the body of the 200 OK response 2055 MUST be the MIME type defined by that application usage (i.e., 2056 "application/resource-lists+xml"). 2058 If the request URI contains a node selector, the server obtains the 2059 document specified by the document selector, and if it is found, 2060 evaluates the node-selector within that document. If no document is 2061 found, or if the node-selector is a no-match or invalid, the server 2062 returns a 404 response. Otherwise, the server returns a 200 OK 2063 response. If the node selector identifies an XML element, that 2064 element is returned in the 200 OK response as an XML fragment body 2065 containing the selected element. The server MUST NOT add namespace 2066 bindings representing namespaces used by the element or its children, 2067 but declared in ancestor elements; the client will either know these 2068 bindings already (since it has a cached copy of the whole document), 2069 or it can learn them by explicitly querying for the bindings. The 2070 MIME type of the response MUST be "application/xcap-el+xml". If the 2071 node selector identifies an XML attribute, the value of that 2072 attribute is returned in the body of the response. The MIME type of 2073 the response MUST be "application/xcap-att+xml". If the node 2074 selector identifies a set of namespace bindings, the server computes 2075 the set of namespace bindings in scope for the element (including the 2076 default) and encodes it using the "application/xcap-ns+xml" format 2077 defined in Section 10. That document is then returned in the body of 2078 the response. 2080 GET operations can be conditional, and follow the procedures defined 2081 in [6]. 2083 Note that the GET of a resource that was just PUT might not be octet- 2084 for-octet equivalent to what was PUT, due to XML normalization and 2085 equivalency rules. 2087 A successful response to a GET MUST include an entity tag. 2089 8.4. DELETE Handling 2091 The semantics of DELETE are as specified in RFC 2616. This section 2092 clarifies the specific content to be deleted for a particular URI 2093 that represents an XCAP resource. 2095 If the request URI contained a namespace-selector, the server MUST 2096 reject the request with a 405 (Method Not Allowed) and MUST include 2097 an Allow header field including the GET method. 2099 If the request URI contains only a document selector, the server 2100 deletes the document specified by the URI if it exists and returns a 2101 200 OK, else returns a 404 response. 2103 If the request URI contains a node selector, the server obtains the 2104 document specified by the document selector, and if it is found, 2105 evaluates the node-selector within that document. If no document is 2106 found, or if the node-selector is a no-match or invalid (note that it 2107 will be invalid if multiple elements or attributes are selected), the 2108 server returns a 404 response. Otherwise, the server removes the 2109 specified element or attribute from the document and performs the 2110 validation checks defined in Section 8.2.5. Note that this deletion 2111 does not include any white space around the element that was deleted; 2112 the XCAP server MUST preserve surrounding whitespace. It is possible 2113 that, after deletion, the request URI selects another element in the 2114 document. If this happens the server MUST NOT perform the deletion, 2115 and MUST reject the request with a 409 response. The body of the 2116 response SHOULD contain a detailed conflict report containing the 2117 element. If the deletion will cause a failure of one 2118 of the constraints, the deletion MUST NOT take place. The server 2119 follows the procedures in Section 8.2.5 for computing the 409 2120 response. If the deletion results in a document that is still valid, 2121 the server MUST perform the deletion, process the resource 2122 interdependencies defined by the application usage, and return a 200 2123 OK response. 2125 DELETE operations can be conditional, and follow the procedures 2126 defined in [6]. 2128 Before the server returns the 200 OK response to a DELETE, it MUST 2129 process the resource interdependencies as defined in Section 8.2.7. 2130 As long as the document still exists after the delete operation, any 2131 successful response to DELETE MUST include the entity tag of the 2132 document. 2134 8.5. Managing Etags 2136 An XCAP server MUST maintain entity tags for all resources that it 2137 maintains. This specification introduces the additional constraint 2138 that when one resource within a document (including the document 2139 itself) changes, that resource is assigned a new etag, and all other 2140 resources within that document MUST be assigned the same etag value. 2141 Effectively, there is a single etag for the entire document. An XCAP 2142 server MUST include the Etag header field in all 200 or 201 responses 2143 to PUT, GET, and DELETE, assuming the document itself still exists 2144 after the operation. In the case of a DELETE, the entity tag refers 2145 to the value of the entity tag for the document after the deletion of 2146 the element or attribute. 2148 XCAP resources do not introduce new requirements on the strength of 2149 the entity tags. 2151 As a result of this constraint, when a client makes a change to an 2152 element or attribute within a document, the response to that 2153 operation will convey the entity tag of the resource that was just 2154 affected. Since the client knows that this entity tag value is 2155 shared by all of the other resources in the document, the client can 2156 make conditional requests against other resources using that entity 2157 tag. 2159 9. Cache Control 2161 An XCAP resource is a valid HTTP resource, and therefore, it can be 2162 cached by clients and network caches. Network caches, however, will 2163 not be aware of the interdependencies between XCAP resources. As 2164 such, a change to an element in a document by a client will 2165 invalidate other XCAP resources affected by the change. For 2166 application usages contain data that is likely to be dynamic or 2167 written by clients, servers SHOULD indicate a no-cache directive. 2169 10. Namespace Binding Format 2171 A node-selector can identify a set of namespace bindings that are in 2172 scope for a particular element. In order to convey these bindings in 2173 a GET response, a way is needed to encode them. 2175 Encoding is trivially done by including a single XML element in an 2176 XML fragment body. This element has the same local-name as the 2177 element whose namespace bindings are desired, and also the same 2178 namespace-prefix. The element has an xmlns attribute identifying the 2179 default namespace in scope, and an xmlns:prefix declaration for each 2180 prefix that is in scope. 2182 For example, consider the XML document in Section 6.4. The node- 2183 selector df:foo/df2:bar/df2:baz/namespace::* will select the 2184 namespaces in scope for the element in the document, assuming 2185 the request is accompanied by a query component that contains 2186 xmlns(df=urn:test:default-namespace) and 2187 xmlns(df2=urn:test:namespace1-uri). A GET containing this node 2188 selector and namespace bindings will produce the following result: 2190 2193 It is important to note that the client does not need to know the 2194 actual namespace bindings in order to construct the URI. It does 2195 need to know the namespace URI for each element in the node-selector. 2196 The namespace bindings present in the query component are defined by 2197 the client, mapping those URI to a set of prefixes. The bindings 2198 returned by the server are the actual bindings used in the document. 2200 11. Detailed Conflict Reports 2202 In cases where the server returns a 409 error response, that response 2203 will usually include a document in the body of the response which 2204 provides further details on the nature of the error. This document 2205 is an XML document, formatted according to the schema of 2206 Section 11.2. Its MIME type, registered by this specification, is 2207 "application/xcap-error+xml". 2209 11.1. Document Structure 2211 The document structure is simple. It contains the root element 2212 . The content of this element is a specific error 2213 condition. Each error condition is represented by a different 2214 element. This allows for different error conditions to provide 2215 different data about the nature of the error. All error elements 2216 support a "phrase" attribute, which can contain text meant for 2217 rendering to a human user. 2219 The following error elements are defined by this specification: 2221 : This indicates that the body of the request was 2222 not a well-formed XML document. 2224 : This indicates that the request was supposed to 2225 contain a valid XML fragment body, but did not. Most likely this 2226 is because the XML in the body was malformed or not balanced. 2228 : This indicates that an attempt to insert a document, 2229 element, or attribute failed because the directory, document or 2230 element into which the insertion was supposed to occur does not 2231 exist. This error element can contain an optional 2232 element, which provides an HTTP URI that represents the closest 2233 parent that would be a valid point of insertion. This HTTP URI 2234 MAY be a relative URI, relative to the document itself. Because 2235 this is a valid HTTP URI, its node selector component MUST be 2236 percent-encoded. 2238 : This element indicates that the document 2239 was not compliant to the schema after the requested operation was 2240 performed. 2242 : This indicates that the request was supposed to 2243 contain a valid XML attribute value, but did not. 2245 : This indicates that the requested PUT operation 2246 could not be performed because a GET of that resource after the 2247 PUT would not yield the content of the PUT request. 2249 : This indicates that the requested DELETE operation 2250 could not be performed because it would not be idempotent. 2252 : This indicates that the requested operation 2253 would result in a document that did not meet a uniqueness 2254 constraint defined by the application usage. For each URI, 2255 element or attribute specified by the client which is not unique, 2256 an element is present as the content of the error 2257 element. Each element has a "field" attribute that 2258 contains a relative URI identifying the XML element or attribute 2259 whose value needs to be unique, but wasn't. The relative URI is 2260 relative to the document itself, and will therefore start with the 2261 root element. The query component of the URI MUST be present if 2262 the node selector portion of the URI contains namespace prefixes. 2263 Since the "field" node selector is a valid HTTP URI, it MUST be 2264 percent-encoded. The element can optionally contain a 2265 list of elements. Each one is a suggested alternate 2266 value which does not currently exist on the server. 2268 : This indicates that the requested operation 2269 would result in a document that failed a data constraint defined 2270 by the application usage, but not enforced by the schema or a 2271 uniqueness constraint. 2273 : This indicates an error condition that is defined by an 2274 extension to XCAP. Clients which do not understand the content of 2275 the extension element MUST discard the xcap-error document and 2276 treat the error as an unqualified 409. 2278 As an example, the following document indicates that the user 2279 attempted to create an RLS service using the URI 2280 sip:friends@example.com, but that URI already exists: 2282 2283 2284 2285 2286 sip:mybuddies@example.com 2287 2288 2289 2291 11.2. XML Schema 2293 2294 2300 2302 2303 2304 Indicates the reason for the error. 2305 2306 2307 2308 2309 2310 2311 2312 2314 2315 2316 2317 2319 2320 2321 2323 2325 2326 This element indicates 2327 that the document was not compliant to the schema after the requested 2328 operation was performed. 2329 2330 2331 2332 2333 2335 2336 2337 This indicates that the request was supposed to 2338 contain a valid XML fragment body, but did not. 2339 2340 2341 2342 2343 2345 2346 2347 This indicates that an attempt to insert 2348 an element, attribute or document failed because the document or 2349 element into which the insertion was 2350 supposed to occur does not exist 2351 2352 2353 2354 2355 2356 Contains an HTTP URI that points to the 2357 element which is the closest ancestor that does exist. 2358 2359 2360 2361 2362 2363 2364 2366 2367 2368 This indicates that the requested 2369 PUT operation could not be performed because a GET of that resource 2370 after the PUT would not yield the content of the PUT request. 2371 2372 2373 2374 2375 2376 2378 2380 2381 This indicates that the 2382 request was supposed to contain a valid XML attribute value, but did 2383 not. 2384 2385 2386 2387 2388 2390 2392 2393 This indicates that the 2394 requested operation would result in a document that did not meet a 2395 uniqueness constraint defined by the application usage. 2396 2397 2398 2399 2400 2401 2402 For each URI, 2403 element or attribute specified by the client which is not unique, 2404 one of these is present. 2405 2406 2407 2408 2410 2411 An optional set of alternate values can be 2412 provided. 2413 2414 2415 2416 2417 2418 2419 2420 2421 2422 2424 2426 2427 This indicates that the body of the request was 2428 not a well-formed document. 2429 2430 2431 2432 2433 2435 2437 2438 This indicates that the 2439 requested operation would result in a document that failed a data 2440 constraint defined by the application usage, but not enforced by the 2441 schema or a uniqueness constraint. 2442 2443 2444 2445 2446 2447 2448 2449 This indicates that the requested DELETE 2450 operation could not be performed because it would not be 2451 idempotent. 2452 2453 2454 2455 2456 2458 2459 2460 This indicates that request could not be 2461 completed because it would have produced a document not 2462 encoded in UTF-8. 2463 2464 2465 2466 2467 2468 2470 12. XCAP Server Capabilities 2472 XCAP can be extended through the addition of new application usages 2473 and extensions to the core protocol. Application usages may define 2474 MIME types with XML schemas that allow new extension nodes from new 2475 namespaces. It will often be necessary for a client to determine 2476 what extensions, application usages or namespaces a server supports 2477 before making a request. To enable that, this specification defines 2478 an application usage with the AUID "xcap-caps". All XCAP servers 2479 MUST support this application usage. This usage defines a single 2480 document within the global tree which lists the capabilities of the 2481 server. Clients can read this well-known document, and therefore 2482 learn the capabilities of the server. 2484 The structure of the document is simple. The root element is . Its children are , , and . 2486 Each of these contain a list of AUIDs, extensions and namespaces 2487 supported by the server. Extensions are named by tokens defined by 2488 the extension, and typically define new selectors. Namespaces are 2489 identified by their namespace URI. To 'support' a namespace, the 2490 server must have the schemas for all elements within that namespace, 2491 and be able to validate them if they appear within documents. Since 2492 all XCAP servers support the "xcap-caps" AUID, it MUST be listed in 2493 the element and the "urn:ietf:params:xml:ns:xcap-caps" 2494 namespace MUST be listed in the element. 2496 The following sections provide the information needed to define this 2497 application usage. 2499 12.1. Application Unique ID (AUID) 2501 This specification defines the "xcap-caps" AUID within the IETF tree, 2502 via the IANA registration in Section 15. 2504 12.2. XML Schema 2506 2507 2511 2512 2513 Root element for xcap-caps 2514 2515 2516 2517 2518 2519 List of supported AUID. 2520 2521 2522 2523 2524 2525 2526 2527 2528 2529 List of supported extensions. 2530 2531 2532 2533 2534 2535 2536 2537 2538 2539 2540 List of supported namespaces. 2541 2542 2543 2544 2545 2546 2547 2548 2549 2551 2552 2553 2554 2555 2556 AUID Type 2557 2558 2559 2560 2561 2562 Extension Type 2563 2564 2565 2566 2567 2568 Namespace type 2569 2570 2571 2572 2574 12.3. Default Document Namespace 2576 The default document namespace used in evaluating a URI is 2577 urn:ietf:params:xml:ns:xcap-caps. 2579 12.4. MIME Type 2581 Documents conformant to this schema are known by the MIME type 2582 "application/xcap-caps+xml", registered in Section 15.2.5. 2584 12.5. Validation Constraints 2586 There are no additional validation constraints associated with this 2587 application usage. 2589 12.6. Data Semantics 2591 Data semantics are defined above. 2593 12.7. Naming Conventions 2595 A server MUST maintain a single instance of the document in the 2596 global tree, using the filename "index". There MUST NOT be an 2597 instance of this document in the users tree. 2599 12.8. Resource Interdependencies 2601 There are no resource interdependencies in this application usage 2602 beyond those defined by the schema. 2604 12.9. Authorization Policies 2606 This application usage does not change the default authorization 2607 policy defined by XCAP. 2609 13. Examples 2611 This section goes through several examples, making use of the 2612 resource-lists and rls-services [22] XCAP application usages. 2614 First, a user Bill creates a new document (see Section 7.1). This 2615 document is a new resource-list, initially with a single list, called 2616 friends, with no users in it: 2618 PUT 2619 /resource-lists/users/sip:bill@example.com/index HTTP/1.1 2620 Content-Type:application/resource-lists+xml 2621 Host: xcap.example.com 2623 2624 2625 2626 2627 2629 Figure 24: New Document 2631 Next, Bill creates an RLS services document defining a single RLS 2632 service referencing this list. This service has a URI of 2633 sip:myfriends@example.com (URIs are line-folded for readability): 2635 PUT 2636 /rls-services/users/sip:bill@example.com/index HTTP/1.1 2637 Content-Type:application/rls-services+xml 2638 Host: xcap.example.com 2640 2641 2642 2643 http://xcap.example.com/resource-lists/users/ 2644 sip:bill@example.com/index/~~/resource-lists/ 2645 list%5b@name=%22friends%22%5d 2646 2647 2648 presence 2649 2650 2651 2653 Figure 25: RLS Services Example 2655 Next, Bill creates an element in the resource-lists document 2656 (Section 7.4). In particular, he adds an entry to the list: 2658 PUT 2659 /resource-lists/users/sip:bill@example.com/index 2660 /~~/resource-lists/list%5b@name=%22friends%22%5d/entry HTTP/1.1 2661 Content-Type:application/xcap-el+xml 2662 Host: xcap.example.com 2664 2665 Bob Jones 2666 2668 Figure 26: Resource Lists Document 2670 Next, Bill fetches the document (Section 7.3): 2672 GET 2673 /resource-lists/users/sip:bill@example.com/index HTTP/1.1 2675 Figure 27: Fetch Operation 2677 And the result is (note how white space text nodes appear in the 2678 document): 2680 HTTP/1.1 200 OK 2681 Etag: "wwhha" 2682 Content-Type: application/resource-lists+xml 2684 2685 2686 2687 2688 Bob Jones 2689 2690 2692 Figure 28: Results of Fetch 2694 Next, Bill adds another entry to the list, which is another list that 2695 has three entries. This is another element creation (Section 7.4): 2697 PUT 2698 /resource-lists/users/sip:bill@example.com/index/~~/ 2699 resource-lists/list%5b@name=%22friends%22%5d/ 2700 list%5b@name=%22close-friends%22%5d HTTP/1.1 2701 Content-Type: application/xcap-el+xml 2702 Host: xcap.example.com 2704 2705 2706 Joe Smith 2707 2708 2709 Nancy Gross 2710 2711 2712 Petri Aukia 2713 2714 2716 Figure 29: Adding an Entry 2718 Then, Bill decides he doesn't want Petri on the list, so he deletes 2719 the entry (Section 7.5): 2721 DELETE 2722 /resource-lists/users/sip:bill@example.com/index/ 2723 ~~/resource-lists/list/list/ 2724 entry%5b@uri=%22sip:petri@example.com%22%5d HTTP/1.1 2725 Host: xcap.example.com 2727 Figure 30: Deleting an Entry 2729 Bill decides to check on the URI for Nancy, so he fetches a 2730 particular attribute (Section 7.6): 2732 GET 2733 /resource-lists/users/sip:bill@example.com/index/ 2734 ~~/resource-lists/list/list/entry%5b2%5d/@uri HTTP/1.1 2735 Host: xcap.example.com 2737 Figure 31: Fetching an Attribute 2739 and the server responds: 2741 HTTP/1.1 200 OK 2742 Etag: "ad88" 2743 Content-Type:application/xcap-att+xml 2745 "sip:nancy@example.com" 2747 Figure 32: Results of Fetch 2749 14. Security Considerations 2751 Frequently, the data manipulated by XCAP contains sensitive 2752 information. To avoid eavesdroppers from seeing this information, it 2753 is RECOMMENDED that an admistrator hand out an https URI as the XCAP 2754 root URI. This will result in TLS-encrypted communications between 2755 the client and server, preventing any eavesdropping. Clients MUST 2756 implement TLS, assuring that such URIs will be usable by the client. 2758 Client and server authentication are also important. A client needs 2759 to be sure it is talking to the server it believes it is contacting. 2760 Otherwise, it may be given false information, which can lead to 2761 denial of service attacks against a client. To prevent this, a 2762 client SHOULD attempt to upgrade [15] any connections to TLS. 2763 Similarly, authorization of read and write operations against the 2764 data is important, and this requires client authentication. As a 2765 result, a server SHOULD challenge a client using HTTP Digest [11] to 2766 establish its identity, and this SHOULD be done over a TLS 2767 connection. Clients MUST implement digest authentication, assuring 2768 interoperability with servers which challenge the client. Servers 2769 MUST NOT perform basic authentication without a TLS connection to the 2770 client. 2772 Because XCAP is a usage of HTTP and not a separate protocol, it runs 2773 on the same port numbers as HTTP traffic normally does. This makes 2774 it difficult to apply port-based filtering rules in firewalls to 2775 separate the treatment of XCAP traffic from other HTTP traffic. 2776 However, this problem exists broadly today because HTTP is used to 2777 access a wide breadth of content, all on the same port, and XCAP 2778 views application configuration documents as just another type of 2779 HTTP content. As such, separate treatment of XCAP traffic from other 2780 HTTP traffic requires firewalls to examine the URL itself. There is 2781 no foolproof way to identify a URL as pointing to an XCAP resource. 2782 However, the presence of the double tilde (~~) is a strong hint that 2783 the URL points to an XML element or attribute. As always, care must 2784 be taken in looking for the double-tilde due to the breadth of ways 2785 in which a URI can be encoded on-the-wire [29] [13]. 2787 15. IANA Considerations 2789 There are several IANA considerations associated with this 2790 specification. 2792 15.1. XCAP Application Unique IDs 2794 This specification instructs IANA to create a new registry for XCAP 2795 application unique IDs (AUIDs). This registry is defined as a table 2796 that contains three colums: 2798 AUID: This will be a string provided in the IANA registrations into 2799 the registry. 2801 Description: This is text that is supplied by the IANA registration 2802 into the registry. 2804 Document: This is a reference to the RFC containing the registration. 2806 This specification instructs IANA to create this table with an 2807 initial entry. The resulting table would look like: 2809 Application Unique Description Document 2810 ID (AUID) 2811 ----------------------------------------------------------- 2813 xcap-caps Capabilities of an RFC XXXX 2814 XCAP server 2816 [[NOTE TO IANA/RFC-EDITOR: Please replace XXXX with the RFC number of 2817 this specification.]] 2819 XCAP AUIDs are registered by the IANA when they are published in 2820 standards track RFCs. The IANA Considerations section of the RFC 2821 must include the following information, which appears in the IANA 2822 registry along with the RFC number of the publication. 2824 Name of the AUID. The name MAY be of any length, but SHOULD be no 2825 more than twenty characters long. The name MUST consist of 2826 alphanum and mark [16] characters only. 2828 Descriptive text that describes the application usage. 2830 15.2. MIME Types 2832 This specification requests the registration of several new MIME 2833 types according to the procedures of RFC 2048 [8] and guidelines in 2834 RFC 3023 [9]. 2836 15.2.1. application/xcap-el+xml MIME Type 2838 MIME media type name: application 2840 MIME subtype name: xcap-el+xml 2842 Mandatory parameters: none 2844 Optional parameters: Same as charset parameter application/xml as 2845 specified in RFC 3023 [9]. 2847 Encoding considerations: Same as encoding considerations of 2848 application/xml as specified in RFC 3023 [9]. 2850 Security considerations: See Section 10 of RFC 3023 [9]. 2852 Interoperability considerations: none. 2854 Published specification: RFC XXXX [[NOTE TO RFC EDITOR: Please 2855 replace XXXX with the published RFC number of this 2856 specification.]]. 2858 Applications which use this media type: This document type has been 2859 used to support transport of XML fragment bodies in RFC XXXX 2860 [[NOTE TO RFC EDITOR: Please replace XXXX with the published RFC 2861 number of this specification.]], the XML Configuration Access 2862 Protocol (XCAP). 2864 Additional Information: 2866 Magic Number: None 2868 File Extension: .xel 2870 Macintosh file type code: "TEXT" 2872 Personal and email address for further information: Jonathan 2873 Rosenberg, jdrosen@jdrosen.net 2875 Intended usage: COMMON 2877 Author/Change controller: The IETF. 2879 15.2.2. application/xcap-att+xml MIME Type 2881 MIME media type name: application 2883 MIME subtype name: xcap-att+xml 2885 Mandatory parameters: none 2887 Optional parameters: Same as charset parameter application/xml as 2888 specified in RFC 3023 [9]. 2890 Encoding considerations: Same as encoding considerations of 2891 application/xml as specified in RFC 3023 [9]. 2893 Security considerations: See Section 10 of RFC 3023 [9]. 2895 Interoperability considerations: none. 2897 Published specification: RFC XXXX [[NOTE TO RFC EDITOR: Please 2898 replace XXXX with the published RFC number of this 2899 specification.]]. 2901 Applications which use this media type: This document type has been 2902 used to support transport of XML attribute values in RFC XXXX 2903 [[NOTE TO RFC EDITOR: Please replace XXXX with the published RFC 2904 number of this specification.]], the XML Configuration Access 2905 Protocol (XCAP). 2907 Additional Information: 2909 Magic Number: None 2911 File Extension: .xav 2913 Macintosh file type code: "TEXT" 2915 Personal and email address for further information: Jonathan 2916 Rosenberg, jdrosen@jdrosen.net 2918 Intended usage: COMMON 2920 Author/Change controller: The IETF. 2922 15.2.3. application/xcap-ns+xml MIME Type 2924 MIME media type name: application 2926 MIME subtype name: xcap-ns+xml 2928 Mandatory parameters: none 2930 Optional parameters: Same as charset parameter application/xml as 2931 specified in RFC 3023 [9]. 2933 Encoding considerations: Same as encoding considerations of 2934 application/xml as specified in RFC 3023 [9]. 2936 Security considerations: See Section 10 of RFC 3023 [9]. 2938 Interoperability considerations: none. 2940 Published specification: RFC XXXX [[NOTE TO RFC EDITOR: Please 2941 replace XXXX with the published RFC number of this 2942 specification.]]. 2944 Applications which use this media type: This document type has been 2945 used to support transport of XML fragment bodies in RFC XXXX 2946 [[NOTE TO RFC EDITOR: Please replace XXXX with the published RFC 2947 number of this specification.]], the XML Configuration Access 2948 Protocol (XCAP). 2950 Additional Information: 2952 Magic Number: None 2954 File Extension: .xns 2956 Macintosh file type code: "TEXT" 2958 Personal and email address for further information: Jonathan 2959 Rosenberg, jdrosen@jdrosen.net 2961 Intended usage: COMMON 2963 Author/Change controller: The IETF. 2965 15.2.4. application/xcap-error+xml MIME Type 2967 MIME media type name: application 2969 MIME subtype name: xcap-error+xml 2971 Mandatory parameters: none 2973 Optional parameters: Same as charset parameter application/xml as 2974 specified in RFC 3023 [9]. 2976 Encoding considerations: Same as encoding considerations of 2977 application/xml as specified in RFC 3023 [9]. 2979 Security considerations: See Section 10 of RFC 3023 [9]. 2981 Interoperability considerations: none. 2983 Published specification: RFC XXXX [[NOTE TO RFC EDITOR: Please 2984 replace XXXX with the published RFC number of this 2985 specification.]]. 2987 Applications which use this media type: This document type conveys 2988 error conditions defined in RFC XXXX. [[NOTE TO RFC EDITOR: 2989 Please replace XXXX with the published RFC number of this 2990 specification.]] 2992 Additional Information: 2994 Magic Number: None 2995 File Extension: .xer 2997 Macintosh file type code: "TEXT" 2999 Personal and email address for further information: Jonathan 3000 Rosenberg, jdrosen@jdrosen.net 3002 Intended usage: COMMON 3004 Author/Change controller: The IETF. 3006 15.2.5. application/xcap-caps+xml MIME Type 3008 MIME media type name: application 3010 MIME subtype name: xcap-caps+xml 3012 Mandatory parameters: none 3014 Optional parameters: Same as charset parameter application/xml as 3015 specified in RFC 3023 [9]. 3017 Encoding considerations: Same as encoding considerations of 3018 application/xml as specified in RFC 3023 [9]. 3020 Security considerations: See Section 10 of RFC 3023 [9]. 3022 Interoperability considerations: none. 3024 Published specification: RFC XXXX [[NOTE TO RFC EDITOR: Please 3025 replace XXXX with the published RFC number of this 3026 specification.]]. 3028 Applications which use this media type: This document type conveys 3029 capabililites of an XML Configuration Access Protocol (XCAP) 3030 server, as defined in RFC XXXX. [[NOTE TO RFC EDITOR: Please 3031 replace XXXX with the published RFC number of this 3032 specification.]] 3034 Additional Information: 3036 Magic Number: None 3038 File Extension: .xca 3039 Macintosh file type code: "TEXT" 3041 Personal and email address for further information: Jonathan 3042 Rosenberg, jdrosen@jdrosen.net 3044 Intended usage: COMMON 3046 Author/Change controller: The IETF. 3048 15.3. URN Sub-Namespace Registrations 3050 This specification registers several new XML namespaces, as per the 3051 guidelines in RFC 3688 [17]. 3053 15.3.1. urn:ietf:params:xml:ns:xcap-error 3055 URI: The URI for this namespace is urn:ietf:params:xml:ns:xcap-error 3057 Registrant Contact: IETF, SIMPLE working group, (simple@ietf.org), 3058 Jonathan Rosenberg (jdrosen@jdrosen.net). 3060 XML: 3062 BEGIN 3063 3064 3066 3067 3068 3070 XCAP Error Namespace 3071 3072 3073

Namespace for XCAP Error Documents

3074

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

3075

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

3078 3079 3080 END 3082 15.3.2. urn:ietf:params:xml:ns:xcap-caps 3083 URI: The URI for this namespace is urn:ietf:params:xml:ns:xcap-caps 3085 Registrant Contact: IETF, SIMPLE working group, (simple@ietf.org), 3086 Jonathan Rosenberg (jdrosen@jdrosen.net). 3088 XML: 3090 BEGIN 3091 3092 3094 3095 3096 3098 XCAP Capabilities Namespace 3099 3100 3101

Namespace for XCAP Capability Documents

3102

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

3103

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

3106 3107 3108 END 3110 15.4. XML Schema Registrations 3112 This section registers two XML schemas per the procedures in [17]. 3114 15.4.1. XCAP Error Schema Registration 3116 URI: urn:ietf:params:xml:schema:xcap-error 3118 Registrant Contact: IETF, SIMPLE working group, (simple@ietf.org), 3119 Jonathan Rosenberg (jdrosen@jdrosen.net). 3121 XML Schema: The XML for this schema can be found as the sole content 3122 of Section 11.2. 3124 15.4.2. XCAP Capabilities Schema Registration 3126 URI: urn:ietf:params:xml:schema:xcap-caps 3127 Registrant Contact: IETF, SIMPLE working group, (simple@ietf.org), 3128 Jonathan Rosenberg (jdrosen@jdrosen.net). 3130 XML Schema: The XML for this schema can be found as the sole content 3131 of Section 12.2. 3133 16. Acknowledgements 3135 The author would like to thank Jari Urpalainen, who has contributed 3136 many important comments and has assisted with edit passes in the 3137 document. The author would also like to thank Ben Campbell, Eva- 3138 Maria Leppanen, Hisham Khartabil, Chris Newman, Joel Halpern, , Lisa 3139 Dusseault, Tim Bray, Pete Cordell, Jeroen van Bemmel, Christian 3140 Schmidt, and Spencer Dawkins for their input and comments. A special 3141 thanks to Ted Hardie for his input and support. 3143 17. References 3145 17.1. Normative References 3147 [1] Sperberg-McQueen, C., Maler, E., Bray, T., Paoli, J., and F. 3148 Yergeau, "Extensible Markup Language (XML) 1.0 (Third 3149 Edition)", World Wide Web Consortium 3150 Recommendation http://www.w3.org/TR/2004/REC-xml-20040204, 3151 February 2004. 3153 [2] Beech, D., Mendelsohn, N., Maloney, M., and H. Thompson, "XML 3154 Schema Part 1: Structures Second Edition", World Wide Web 3155 Consortium Recommendation http://www.w3.org/TR/2004/ 3156 REC-xmlschema-1-20041028, October 2004. 3158 [3] Bray, T., Hollander, D., and A. Layman, "Namespaces in XML", 3159 World Wide Web Consortium 3160 Recommendation http://www.w3.org/TR/1999/ 3161 REC-xml-names-19990114, January 1999. 3163 [4] DeRose, S., Daniel, R., Maler, E., and J. Marsh, "XPointer 3164 xmlns() Scheme", World Wide Web Consortium Recommendation http: 3165 //www.w3.org/TR/2003/REC-xptr-xmlns-20030325, March 2003. 3167 [5] Marsh, J., Grosso, P., Walsh, N., and E. Maler, "XPointer 3168 Framework", World Wide Web Consortium Recommendation http:// 3169 www.w3.org/TR/2003/REC-xptr-framework-20030325, March 2003. 3171 [6] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., 3172 Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- 3173 HTTP/1.1", RFC 2616, June 1999. 3175 [7] Bradner, S., "Key words for use in RFCs to Indicate Requirement 3176 Levels", BCP 14, RFC 2119, March 1997. 3178 [8] Freed, N., Klensin, J., and J. Postel, "Multipurpose Internet 3179 Mail Extensions (MIME) Part Four: Registration Procedures", 3180 BCP 13, RFC 2048, November 1996. 3182 [9] Murata, M., St. Laurent, S., and D. Kohn, "XML Media Types", 3183 RFC 3023, January 2001. 3185 [10] Clark, J. and S. DeRose, "XML Path Language (XPath) Version 3186 1.0", World Wide Web Consortium 3187 Recommendation http://www.w3.org/TR/1999/REC-xpath-19991116, 3188 November 1999. 3190 [11] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 3191 Leach, P., Luotonen, A., and L. Stewart, "HTTP Authentication: 3192 Basic and Digest Access Authentication", RFC 2617, June 1999. 3194 [12] Crocker, D. and P. Overell, "Augmented BNF for Syntax 3195 Specifications: ABNF", RFC 4234, October 2005. 3197 [13] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3198 Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, 3199 January 2005. 3201 [14] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 3203 [15] Khare, R. and S. Lawrence, "Upgrading to TLS Within HTTP/1.1", 3204 RFC 2817, May 2000. 3206 [16] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A., 3207 Peterson, J., Sparks, R., Handley, M., and E. Schooler, "SIP: 3208 Session Initiation Protocol", RFC 3261, June 2002. 3210 [17] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 3211 January 2004. 3213 [18] Yergeau, F., "UTF-8, a transformation format of ISO 10646", 3214 STD 63, RFC 3629, November 2003. 3216 [19] Boyer, J., "Canonical XML Version 1.0", World Wide Web 3217 Consortium 3218 Recommendation http://www.w3.org/TR/2001/REC-xml-c14n-20010315, 3219 March 2001. 3221 17.2. Informative References 3223 [20] Rosenberg, J., "A Presence Event Package for the Session 3224 Initiation Protocol (SIP)", RFC 3856, August 2004. 3226 [21] Roach, A., Rosenberg, J., and B. Campbell, "A Session 3227 Initiation Protocol (SIP) Event Notification Extension for 3228 Resource Lists", draft-ietf-simple-event-list-07 (work in 3229 progress), January 2005. 3231 [22] Rosenberg, J., "Extensible Markup Language (XML) Formats for 3232 Representing Resource Lists", 3233 draft-ietf-simple-xcap-list-usage-05 (work in progress), 3234 February 2005. 3236 [23] Grosso, P. and D. Veillard, "XML Fragment Interchange", World 3237 Wide Web Consortium CR CR-xml-fragment-20010212, February 2001, 3238 . 3240 [24] Berglund, A., Boag, S., Chamberlin, D., Fernandez, M., Kay, M., 3241 Robie, J., and J. Simeon, "XML Path Language (XPath) 2.0", 3242 World Wide Web Consortium 3243 CR http://www.w3.org/TR/2005/CR-xpath20-20051103, 3244 November 2005. 3246 [25] Newman, C. and J. Myers, "ACAP -- Application Configuration 3247 Access Protocol", RFC 2244, November 1997. 3249 [26] Day, M., Rosenberg, J., and H. Sugano, "A Model for Presence 3250 and Instant Messaging", RFC 2778, February 2000. 3252 [27] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA 3253 Considerations Section in RFCs", BCP 26, RFC 2434, 3254 October 1998. 3256 [28] Roach, A., "Session Initiation Protocol (SIP)-Specific Event 3257 Notification", RFC 3265, June 2002. 3259 [29] Duerst, M. and M. Suignard, "Internationalized Resource 3260 Identifiers (IRIs)", RFC 3987, January 2005. 3262 Author's Address 3264 Jonathan Rosenberg 3265 Cisco Systems 3266 600 Lanidex Plaza 3267 Parsippany, NJ 07054 3268 US 3270 Phone: +1 973 952-5000 3271 Email: jdrosen@cisco.com 3272 URI: http://www.jdrosen.net 3274 Intellectual Property Statement 3276 The IETF takes no position regarding the validity or scope of any 3277 Intellectual Property Rights or other rights that might be claimed to 3278 pertain to the implementation or use of the technology described in 3279 this document or the extent to which any license under such rights 3280 might or might not be available; nor does it represent that it has 3281 made any independent effort to identify any such rights. Information 3282 on the procedures with respect to rights in RFC documents can be 3283 found in BCP 78 and BCP 79. 3285 Copies of IPR disclosures made to the IETF Secretariat and any 3286 assurances of licenses to be made available, or the result of an 3287 attempt made to obtain a general license or permission for the use of 3288 such proprietary rights by implementers or users of this 3289 specification can be obtained from the IETF on-line IPR repository at 3290 http://www.ietf.org/ipr. 3292 The IETF invites any interested party to bring to its attention any 3293 copyrights, patents or patent applications, or other proprietary 3294 rights that may cover technology that may be required to implement 3295 this standard. Please address the information to the IETF at 3296 ietf-ipr@ietf.org. 3298 Disclaimer of Validity 3300 This document and the information contained herein are provided on an 3301 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 3302 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 3303 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 3304 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 3305 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 3306 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 3308 Copyright Statement 3310 Copyright (C) The Internet Society (2006). This document is subject 3311 to the rights, licenses and restrictions contained in BCP 78, and 3312 except as set forth therein, the authors retain all their rights. 3314 Acknowledgment 3316 Funding for the RFC Editor function is currently provided by the 3317 Internet Society.