idnits 2.17.1 draft-ietf-simple-xcap-08.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 3038. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 3015. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 3022. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 3028. ** 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 : ---------------------------------------------------------------------------- ** There are 14 instances of too long lines in the document, the longest one being 85 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 2906 has weird spacing: '...Changes in XM...' == 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. As a consequence, the remainder of the document selector will normally be a name for the document itself. If a user has a single document for a particular application usage, this SHOULD be called "index". 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 OK or 200, respectively. Note that a 201 Created is generated for creation of new documents, elements, or attributes. If the client included "application/xcap-diff+xml" in an Accept header in the PUT request, and the request was an insertion resulting in a 201 response, the server SHOULD include an XCAP diff document in the response [6]. The XCAP diff document SHOULD contain a single element. It SHOULD indicate the entity tag for the document resource prior to the insertion in the "previous-etag" attribute, and the entity tag for the document after insertion in the "new-etag" attribute. A 200 OK response to PUT MUST not contain any content. -- 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 24, 2005) is 6752 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) == Unused Reference: '23' is defined on line 2968, but no explicit reference was found in the text -- 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' == Outdated reference: A later version (-14) exists of draft-ietf-simple-xcap-diff-01 ** Obsolete normative reference: RFC 2616 (ref. '7') (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 2048 (ref. '9') (Obsoleted by RFC 4288, RFC 4289) ** Obsolete normative reference: RFC 3023 (ref. '10') (Obsoleted by RFC 7303) -- Possible downref: Non-RFC (?) normative reference: ref. '11' ** Obsolete normative reference: RFC 2617 (ref. '12') (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) ** Obsolete normative reference: RFC 2234 (ref. '13') (Obsoleted by RFC 4234) ** Obsolete normative reference: RFC 2818 (ref. '15') (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 2434 (ref. '28') (Obsoleted by RFC 5226) -- Obsolete informational reference (is this intentional?): RFC 3265 (ref. '29') (Obsoleted by RFC 6665) Summary: 10 errors (**), 0 flaws (~~), 8 warnings (==), 16 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 27, 2006 October 24, 2005 6 The Extensible Markup Language (XML) Configuration Access Protocol 7 (XCAP) 8 draft-ietf-simple-xcap-08 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 27, 2006. 35 Copyright Notice 37 Copyright (C) The Internet Society (2005). 39 Abstract 41 This specification defines the Extensible Markup Language (XML) 42 Configuration Access Protocol (XCAP). XCAP allows a client to read, 43 write and modify application configuration data, stored in XML format 44 on a server. XCAP maps XML document sub-trees and element attributes 45 to HTTP URIs, so that these components can be directly accessed by 46 HTTP. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 51 2. Overview of Operation . . . . . . . . . . . . . . . . . . . 4 52 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . 5 53 4. Definitions . . . . . . . . . . . . . . . . . . . . . . . . 5 54 5. Application Usages . . . . . . . . . . . . . . . . . . . . . 7 55 5.1 Application Unique ID (AUID) . . . . . . . . . . . . . . . 7 56 5.2 Default Namespace Binding . . . . . . . . . . . . . . . . 8 57 5.3 Data Validation . . . . . . . . . . . . . . . . . . . . . 8 58 5.4 Data Semantics . . . . . . . . . . . . . . . . . . . . . . 10 59 5.5 Naming Conventions . . . . . . . . . . . . . . . . . . . . 10 60 5.6 Resource Interdependencies . . . . . . . . . . . . . . . . 10 61 5.7 Authorization Policies . . . . . . . . . . . . . . . . . . 11 62 5.8 Data Extensibility . . . . . . . . . . . . . . . . . . . . 12 63 5.9 Documenting Application Usages . . . . . . . . . . . . . . 12 64 5.10 Guidelines for Creating Application Usages . . . . . . . 13 65 6. URI Construction . . . . . . . . . . . . . . . . . . . . . . 14 66 6.1 XCAP Root . . . . . . . . . . . . . . . . . . . . . . . . 15 67 6.2 Document Selector . . . . . . . . . . . . . . . . . . . . 16 68 6.3 Node Selector . . . . . . . . . . . . . . . . . . . . . . 17 69 6.4 Namespace Bindings for the Selector . . . . . . . . . . . 22 70 7. Client Operations . . . . . . . . . . . . . . . . . . . . . 23 71 7.1 Create or Replace a Document . . . . . . . . . . . . . . . 25 72 7.2 Delete a Document . . . . . . . . . . . . . . . . . . . . 25 73 7.3 Fetch a Document . . . . . . . . . . . . . . . . . . . . . 25 74 7.4 Create or Replace an Element . . . . . . . . . . . . . . . 25 75 7.5 Delete an Element . . . . . . . . . . . . . . . . . . . . 28 76 7.6 Fetch an Element . . . . . . . . . . . . . . . . . . . . . 28 77 7.7 Create or Replace an Attribute . . . . . . . . . . . . . . 29 78 7.8 Delete an Attribute . . . . . . . . . . . . . . . . . . . 30 79 7.9 Fetch an Attribute . . . . . . . . . . . . . . . . . . . . 30 80 7.10 Fetch Namespace Bindings . . . . . . . . . . . . . . . . 30 81 7.11 Conditional Operations . . . . . . . . . . . . . . . . . 31 82 8. Server Behavior . . . . . . . . . . . . . . . . . . . . . . 33 83 8.1 POST Handling . . . . . . . . . . . . . . . . . . . . . . 34 84 8.2 PUT Handling . . . . . . . . . . . . . . . . . . . . . . . 34 85 8.2.1 Locating the Parent . . . . . . . . . . . . . . . . . 34 86 8.2.2 Verifying Document Content . . . . . . . . . . . . . . 35 87 8.2.3 Creation . . . . . . . . . . . . . . . . . . . . . . . 36 88 8.2.4 Replacement . . . . . . . . . . . . . . . . . . . . . 39 89 8.2.5 Validation . . . . . . . . . . . . . . . . . . . . . . 39 90 8.2.6 Resource Interdependencies . . . . . . . . . . . . . . 40 91 8.3 GET Handling . . . . . . . . . . . . . . . . . . . . . . . 40 92 8.4 DELETE Handling . . . . . . . . . . . . . . . . . . . . . 41 93 8.5 Managing Etags . . . . . . . . . . . . . . . . . . . . . . 42 94 9. Cache Control . . . . . . . . . . . . . . . . . . . . . . . 42 95 10. Namespace Binding Format . . . . . . . . . . . . . . . . . . 43 96 11. Detailed Conflict Reports . . . . . . . . . . . . . . . . . 43 97 11.1 Document Structure . . . . . . . . . . . . . . . . . . . 44 98 11.2 XML Schema . . . . . . . . . . . . . . . . . . . . . . . 45 99 12. XCAP Server Capabilities . . . . . . . . . . . . . . . . . . 48 100 12.1 Application Unique ID (AUID) . . . . . . . . . . . . . . 49 101 12.2 XML Schema . . . . . . . . . . . . . . . . . . . . . . . 49 102 12.3 Default Namespace . . . . . . . . . . . . . . . . . . . 51 103 12.4 MIME Type . . . . . . . . . . . . . . . . . . . . . . . 51 104 12.5 Validation Constraints . . . . . . . . . . . . . . . . . 51 105 12.6 Data Semantics . . . . . . . . . . . . . . . . . . . . . 51 106 12.7 Naming Conventions . . . . . . . . . . . . . . . . . . . 51 107 12.8 Resource Interdependencies . . . . . . . . . . . . . . . 51 108 12.9 Authorization Policies . . . . . . . . . . . . . . . . . 51 109 13. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 51 110 14. Security Considerations . . . . . . . . . . . . . . . . . . 54 111 15. IANA Considerations . . . . . . . . . . . . . . . . . . . . 55 112 15.1 XCAP Application Unique IDs . . . . . . . . . . . . . . 55 113 15.2 MIME Types . . . . . . . . . . . . . . . . . . . . . . . 56 114 15.2.1 application/xcap-el+xml MIME Type . . . . . . . . . 56 115 15.2.2 application/xcap-att+xml MIME Type . . . . . . . . . 57 116 15.2.3 application/xcap-ns+xml MIME Type . . . . . . . . . 58 117 15.2.4 application/xcap-error+xml MIME Type . . . . . . . . 59 118 15.2.5 application/xcap-caps+xml MIME Type . . . . . . . . 60 119 15.3 URN Sub-Namespace Registrations . . . . . . . . . . . . 61 120 15.3.1 urn:ietf:params:xml:ns:xcap-error . . . . . . . . . 61 121 15.3.2 urn:ietf:params:xml:ns:xcap-caps . . . . . . . . . . 61 122 15.4 XML Schema Registrations . . . . . . . . . . . . . . . . 62 123 15.4.1 XCAP Error Schema Registration . . . . . . . . . . . 62 124 15.4.2 XCAP Capabilities Schema Registration . . . . . . . 62 125 16. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 63 126 17. References . . . . . . . . . . . . . . . . . . . . . . . . . 63 127 17.1 Normative References . . . . . . . . . . . . . . . . . . 63 128 17.2 Informative References . . . . . . . . . . . . . . . . . 64 129 Author's Address . . . . . . . . . . . . . . . . . . . . . . 65 130 Intellectual Property and Copyright Statements . . . . . . . 66 132 1. Introduction 134 In many communications applications, such as Voice over IP, instant 135 messaging, and presence, it is necessary for network servers to 136 access per-user information in the process of servicing a request. 137 This per-user information resides within the network, but is managed 138 by the end user themselves. Its management can be done through a 139 multiplicity of access points, including the web, a wireless handset, 140 or a PC application. 142 There are many examples of per-user information. One is presence 143 [20] authorization policy, which defines rules about which watchers 144 are allowed to subscribe to a presentity, and what information they 145 are allowed to access. Another is presence lists, which are lists of 146 users whose presence is desired by a watcher [27]. One way to obtain 147 presence information for the list is to subscribe to a resource which 148 represents that list [21]. In this case, the Resource List Server 149 (RLS) requires access to this list in order to process a SIP [17] 150 SUBSCRIBE [29] request for it. Another way to obtain presence for 151 the users on the list is for a watcher to subscribe to each user 152 individually. In that case, it is convenient to have a server store 153 the list, and when the client boots, it fetches the list from the 154 server. This would allow a user to access their resource lists from 155 different clients. 157 This specification describes a protocol that can be used to 158 manipulate this per-user data. It is called the Extensible Markup 159 Language (XML) Configuration Access Protocol (XCAP). XCAP is a set 160 of conventions for mapping XML documents and document components into 161 HTTP URIs, rules for how the modification of one resource affects 162 another, data validation constraints, and authorization policies 163 associated with access to those resources. Because of this 164 structure, normal HTTP primitives can be used to manipulate the data. 165 XCAP is based heavily on ideas borrowed from the Application 166 Configuration Access Protocol (ACAP) [26], but it is not an extension 167 of it, nor does it have any dependencies on it. Like ACAP, XCAP is 168 meant to support the configuration needs for a multiplicity of 169 applications, rather than just a single one. 171 2. Overview of Operation 173 Each application that makes use of XCAP specifies an application 174 usage (Section 5). This application usage defines the XML schema [2] 175 for the data used by the application, along with other key pieces of 176 information. The principal task of XCAP is to allow clients to read, 177 write, modify, create and delete pieces of that data. These 178 operations are supported using HTTP/1.1 [7]. An XCAP server acts as 179 a repository for collections of XML documents. There will be 180 documents stored for each application. Within each application, 181 there are documents stored for each user. Each user can have a 182 multiplicity of documents for a particular application. To access 183 some component of one of those documents, XCAP defines an algorithm 184 for constructing a URI that can be used to reference that component. 185 Components refer to any element or attribute within the document. 186 Thus, the HTTP URIs used by XCAP point to a document, or to pieces of 187 information that are finer grained than the XML document itself. An 188 HTTP resource which follows the naming conventions and validation 189 constraints defined here is called an XCAP resource. 191 Since XCAP resources are also HTTP resources, they can be accessed 192 using HTTP methods. Reading an XCAP resource is accomplished with 193 HTTP GET, creating or modifying one is done with HTTP PUT, and 194 removing one of the resources is done with an HTTP DELETE. XCAP 195 resources do not represent processing scripts; as a result, POST 196 operations to HTTP URIs representing XCAP resources are not defined. 197 Properties that HTTP associates with resources, such as entity tags, 198 also apply to XCAP resources. Indeed, entity tags are particularly 199 useful in XCAP, as they allow a number of conditional operations to 200 be performed. 202 3. Terminology 204 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 205 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 206 and "OPTIONAL" are to be interpreted as described in RFC 2119 [8] and 207 indicate requirement levels for compliant implementations. 209 4. Definitions 211 The following terms are used throughout this document: 213 XCAP Resource: An HTTP resource representing an XML document, an 214 element within an XML document, or an attribute of an element 215 within an XML document that follows the naming and validation 216 constraints of XCAP. 218 XCAP Server: An HTTP server that understands how to follow the naming 219 and validation constraints defined in this specification. 221 XCAP Client: An HTTP client that understands how to follow the naming 222 and validation constraints defined in this specification. 224 Application: A collection of software components within a network 225 whose operation depends on data managed and stored on an XCAP 226 server. 228 Application Usage: Detailed information on the interaction of an 229 application with the XCAP server. 231 Application Unique ID (AUID): A unique identifier within the 232 namespace of application unique IDs created by this specification 233 that differentiates XCAP resources accessed by one application 234 from XCAP resources accessed by another. 236 Naming Conventions: The part of an application usage that specifies 237 well-known URIs used by an application, or more generally, 238 specifies the URIs that are typically accessed by an application 239 during its processing. 241 XCAP User Identifier (XUI): The XUI is a string, valid as a path 242 element in an HTTP URI, that is associated with each user served 243 by the XCAP server. 245 XCAP Root: A context that contains all of the documents across all 246 application usages and users that are managed by the server. 248 Document Selector: A sequence of path segments, with each segment 249 being separated by a "/", that identify the XML document within an 250 XCAP root that is being selected. 252 Node Selector: A sequence of path segments, with each segment being 253 separated by a "/", that identify the XML node (element or 254 attribute) being selected within a document. 256 Path Separator: A single path segment equal to two tilde characters 257 "~~" that is used to separate the document selector from the node 258 selector within an HTTP URI. 260 Document URI: The HTTP URI containing the XCAP root and document 261 selector, resulting in the selection of a specific document. As a 262 result, performing a GET against the document URI would retrieve 263 the document. 265 Node URI: The HTTP URI containing the XCAP root, document selector, 266 path separator and node selector, resulting in the selection of a 267 specific XML node. 269 XCAP Root URI: An HTTP URI that representing the XCAP root. Although 270 a syntactically valid URI, the XCAP Root URI does not correspond 271 to an actual resource on an XCAP server. Actual resources are 272 created by appending additional path information to the XCAP Root 273 URI. 275 Global Tree: A URI that represents the parent for all global 276 documents for a particular application usage within a particular 277 XCAP root. 279 Home Directory: A URI that represents the parent for all documents 280 for a particular user for a particular application usage within a 281 particular XCAP root. 283 Positional Insertion: A PUT operation that results in the insertion 284 of a new element into a document such that its position relative 285 to other children of the same parent is set by the client. 287 5. Application Usages 289 Each XCAP resource on a server is associated with an application. In 290 order for an application to use those resources, application specific 291 conventions must be specified. Those conventions include the XML 292 schema that defines the structure and constraints of the data, well 293 known URIs to bootstrap access to the data, and so on. All of those 294 application specific conventions are defined by the application 295 usage. 297 5.1 Application Unique ID (AUID) 299 Each application usage is associated with a name, called an 300 Application Unique ID (AUID). This name uniquely identifies the 301 application usage within the namespace of application usages, and is 302 different from AUIDs used by other applications. AUIDs exist in one 303 of two namespaces. The first namespace is the IETF namespace. This 304 namespace contains a set of tokens, each of which is registered with 305 IANA. These registrations occur with the publication of standards 306 track RFCs [28] based on the guidelines in Section 15. The second 307 namespace is the vendor-proprietary namespace. Each AUID in that 308 namespace is prefixed with the reverse domain name of the 309 organization creating the AUID, followed by a period, followed by any 310 vendor defined token. As an example, the example.com domain can 311 create an AUID with the value "com.example.foo" but cannot create one 312 with the value "org.example.foo". AUIDs within the vendor namespace 313 do not need to be registered with IANA. The vendor namespace is also 314 meant to be used in lab environments where no central registry is 315 needed. The syntax for AUIDs, expressed in ABNF [13] (and using some 316 of the BNF defined in RFC 3986 [14]) is: 318 AUID = global-auid / vendor-auid 319 global-auid = auid 320 auid = 1*pchar 321 vendor-auid = rev-hostname "." auid 322 rev-hostname = toplabel *( "." domainlabel ) 323 domainlabel = alphanum 324 / alphanum *( alphanum / "-" ) alphanum 325 toplabel = ALPHA / ALPHA *( alphanum / "-" ) alphanum 327 5.2 Default Namespace Binding 329 In order for the XCAP server to match a URI to an element or 330 attribute of a document, any XML namespace prefixes used within the 331 URI must be expanded [3]. This expansion requires a namespace 332 binding context. That context maps namespace prefixes to namespace 333 URIs. It also defines a default namespace that applies to elements 334 without namespace prefixes. The namespace binding context comes from 335 two sources. Firstly, the mapping of namespace prefixes to namespace 336 URIs is obtained from the URI itself (see Section 6.4). However, the 337 default namespace URI is defined by the application usage itself, and 338 applies to all URIs referencing resources within that application 339 usage. All application usages MUST define a namespace URI that 340 represents the default namespace to be used when evaluating URIs. 341 The default namespace does not apply to elements or attributes within 342 the documents themselves. However, if a document contains a URI 343 representing an XCAP resource, the default namespace defined by the 344 application usage applies to that URI as well. 346 5.3 Data Validation 348 One of the responsibilities of an XCAP server is to validate the 349 content of each XCAP resource when an XCAP client tries to modify 350 one. This is done using two mechanisms. Firstly, all application 351 usages MUST describe their document contents using XML schema [2]. 352 The application usage MUST also identify the MIME type for documents 353 compliant to that schema. 355 Unfortunately, XML schemas cannot represent every form of data 356 constraint. As an example, one XML element may contain an integer 357 which defines the maximum number of instances of another element. 358 This constraint cannot be represented with XML schema. However, such 359 constraints may be important to the application usage. The 360 application usage defines any additional constraints beyond those in 361 the schema. 363 Of particular importance are uniqueness constraints. In many cases, 364 an application will require that there only be one instance of some 365 element or attribute within a particular scope. Each uniqueness 366 constraint needs to be specified by identifying the field, or 367 combinations of fields, that need to be unique, and then identifying 368 the scope in which that uniqueness applies. One typical scope is the 369 set of all elements of a certain name within the same parent. 370 Another typical scope is the set of all URIs valid within a 371 particular domain. In some cases these constraints can be specified 372 using XML schema, which provides the element for this 373 purpose. Other uniqueness constraints, such as URI uniqueness across 374 a domain, cannot be expressed by schema. Whether or not the schema 375 is used to express some of the uniqueness requirements, the 376 application usage MUST specify all uniqueness requirements when it 377 defines its data validation needs. 379 For example, the resource lists application usage [22] requires that 380 each element have a unique value for the "name" attribute 381 within a single parent. As another example, the RLS services 382 application usage [22] requires that the value of the "uri" attribute 383 of the element be a URI that is unique within the domain of 384 the URI. 386 URI constraints represent another form of constraints. These are 387 constraints on the scheme or structure of the scheme specific part of 388 the URI. These kinds of constraints cannot be expressed in an XML 389 schema. If these constraints are important to an application usage, 390 they need to be explicitly called out. 392 Another important data constraint is referential integrity. 393 Referential integrity is important when the name or value of an 394 element or attribute is used as a key to select another element or 395 attribute. An application usage MAY specify referential integrity 396 constraints. However, XCAP servers are not a replacement for 397 Relational Database Management Systems (RDBMS), and therefore servers 398 are never responsible for maintaining referential integrity. XCAP 399 clients are responsible for making all of the appropriate changes to 400 documents in order to maintain referential integrity. 402 Another constraint is character encoding. XML allows documents to be 403 encoded using several different character sets. However, this 404 specification mandates that all documents used with XCAP MUST be 405 encoded using UTF-8. This cannot be changed by an application usage. 407 The data validation information is consumed by both clients, which 408 use them to make sure they construct requests that will be accepted 409 by the server, and by servers, which validate the constraints when 410 they receive a request (with the exception of referential integrity 411 constraints, which are not validated by the server). 413 5.4 Data Semantics 415 For each application usage, the data present in the XML document has 416 a well defined semantic. The application usage defines that 417 semantic, so that a client can properly construct a document in order 418 to achieve the desired result. They are not used by the server, as 419 it is purposefully unaware of the semantics of the data it is 420 managing. The data semantics are expressed in English prose by the 421 application usage. 423 One particularly important semantic is the base URI to be used for 424 the resolution of any relative URI references pointed to XCAP 425 resources. As discussed below, relative URI references pointing to 426 XCAP resources cannot be resolved using the retrieval URI as the base 427 URI. Therefore, it is up to the application usage to specify the 428 base URI. 430 5.5 Naming Conventions 432 In addition to defining the meaning of the document in the context of 433 a particular application, an application usage has to specify how the 434 applications obtain the documents they need. In particular, it needs 435 to define any well-known URIs used for bootstrapping purposes, and 436 document any other conventions on the URIs used by an application. 437 It should also document how documents reference each other. These 438 conventions are called naming conventions. 440 For many application usages, users need only a single document. In 441 such a case, it is RECOMMENDED that the application usage require 442 that this document be called "index" and exist within the users home 443 directory. 445 As an example, the RLS services application usage allows an RLS to 446 obtain the contents of a resource list when the RLS receives a 447 SUBSCRIBE request for a SIP URI identifying an RLS service. The 448 application usage specifies that the list of service definitions is 449 present within a specific document with a specific name within the 450 global tree. This allows the RLS to perform a single XCAP request to 451 fetch the service definition for the service associated with the SIP 452 URI in a SUBSCRIBE request. 454 Naming conventions are used by XCAP clients to construct their URIs. 455 The XCAP server does not make use of them. 457 5.6 Resource Interdependencies 459 When a user modifies an XCAP resource, the content of many other 460 resources is affected. For example, when a user deletes an XML 461 element within a document, it does so by issuing a DELETE request 462 against the URI for the element resource. However, deleting this 463 element also deletes all child elements and their attributes, each of 464 which is also an XCAP resource. As such, manipulation of one 465 resource affects the state of other resources. 467 For the most part, these interdependencies are fully specified by the 468 XML schema used by the application usage. However, in some 469 application usages, there is a need for the server to relate 470 resources together, and such a relationship cannot be specified 471 through a schema. This occurs when changes in one document will 472 affect another document. Typically, this is the case when an 473 application usage is defining a document that acts as a collection of 474 information defined in other documents. 476 As an example, when a user creates a new RLS service (that is, it 477 creates a new element within an RLS services document), the 478 server adds that element to a read-only global list of services 479 maintained by the server in the global tree. This read-only global 480 list is accessed by the RLS when processing a SIP SUBSCRIBE request. 482 Resource interdependencies are used by both XCAP clients and servers. 484 5.7 Authorization Policies 486 By default, each user is able to access (read, modify, and delete) 487 all of the documents below their home directory, and any user is able 488 to read documents within the global directory. However, only trusted 489 users, explicitly provisioned into the server, can modify global 490 documents. 492 The application usage can specify a different authorization policy 493 that applies to all documents associated with that application usage. 494 An application usage can also specify whether another application 495 usage is used to define the authorization policies. An application 496 usage for setting authorization policies can also be defined 497 subsequent to the definition of the the main application usage. In 498 such a case, the main application usage needs only to specify that 499 such a usage will be defined in the future. 501 If an application usage does not wish to change the default 502 authorization policy, it can merely state that the default policy is 503 used. 505 The authorization policies defined by the application usage are used 506 by the XCAP server during its operation. 508 5.8 Data Extensibility 510 An XCAP server MUST understand an application usage in order to 511 process an HTTP request made against a resource for that particular 512 application usage. However, it is not required for the server to 513 understand all of the contents of a document used by an application 514 usage. A server is required to understand the baseline schema 515 defined by the application usage. However, those schemas can define 516 points of extensibility where new content can be added from other 517 namespaces and corresponding schemas. Sometimes, the server will 518 understand those namespaces and therefore have access to their 519 schemas. Sometimes, it will not. 521 A server MUST allow for documents that contain elements from 522 namespaces not known to the server. In such a case, the server 523 cannot validate that such content is schema compliant; it will only 524 verify that the XML is well-formed. 526 If a client wants to verify that a server supports a particular 527 namespace before operating on a resource, it can query the server for 528 its capabilities using the XCAP Capabilities application usage, 529 discussed in Section 12. 531 5.9 Documenting Application Usages 533 Application usages are documented in specifications which convey the 534 information described above. In particular, an application usage 535 specification MUST provide the following information: 537 o Application Unique ID (AUID): If the application usage is meant 538 for general use on the Internet, the application usage MUST 539 register the AUID into the IETF tree using the IANA procedures 540 defined in Section 15. 542 o XML Schema 544 o Default Namespace 546 o MIME Type 548 o Validation Constraints 550 o Data Semantics 552 o Naming Conventions 554 o Resource Interdependencies 555 o Authorization Policies 557 5.10 Guidelines for Creating Application Usages 559 The primary design task when creating a new application usage is to 560 define the schema. Although XCAP can be used with any XML document, 561 intelligent schema design will improve the efficiency and utility of 562 the document when it is manipulated with XCAP. 564 XCAP provides three fundamental ways to select elements amongst a set 565 of siblings - by the name of the element, by its position, or by the 566 value of a specific attribute. Positional selection always allows a 567 client to get exactly what it wants. However, it requires a client 568 to cache a copy of the document in order to construct the predicate. 569 Furthermore, if a client performs a PUT, it requires the client to 570 reconstruct the PUT processing that a server would follow in order to 571 update its local cached copy. Otherwise, the client will be forced 572 to re-GET the document after every PUT, which is inefficient. As 573 such, it is a good idea to design schemas such that common operations 574 can be performed without requiring the client to cache a copy of the 575 document. 577 Without positional selection, a client can pick the element at each 578 step by its name or the value of an attribute. Many schemas include 579 elements that can be repeated within a parent (often, minOccurs 580 equals zero or one, and maxOccurs is unbounded). As such, all of the 581 elements have the same name. This leaves the attribute value as the 582 only way to select an element. Because of this, if an application 583 usage expects user to manipulate elements or attributes that are 584 descendants of an element which can repeat, that element SHOULD 585 include, in its schema, an attribute which can be suitably used as a 586 unique index. Furthermore, the naming conventions defined by that 587 application usage SHOULD specify this uniqueness constraint 588 explicitly. 590 URIs often make a good choice for such unique index. They have 591 fundamental uniqueness properties, and are also usually of semantic 592 significance in the application usage. However, care must be taken 593 when using a URI as an attribute value. URI equality is usually 594 complex. However, attribute equality is performed by the server 595 using XML rules, which are based on case sensitive string comparison. 596 Thus, XCAP will match URIs based on lexical equality, not functional 597 equality. In such cases, an application usage SHOULD consider these 598 implications carefully. 600 XCAP provides the ability of a client to operate on a single element, 601 attribute or document at a time. As a result, it may be possible 602 that common operations the client might perform will require a 603 sequence of multiple requests. This is inefficient, and introduces 604 the possibility of failure conditions when another client modifies 605 the document in the middle of a sequence. In such a case, the client 606 will be forced to detect this case using entity tags (discussed below 607 in Section 7.11), and undo its previous changes. This is very 608 difficult. 610 As a result, the schemas SHOULD be defined so that common operations 611 generally require a single request to perform. Consider an example. 612 Lets say an application usage is defining permissions for users to 613 perform certain operations. The schema can be designed in two ways. 614 The top level of the tree can identify users, and within each user, 615 there can be the permissions associated with the user. In an 616 alternative design, the top level of the tree identifies each 617 permission, and within that permission, the set of users who have it. 618 If, in this application usage, it is common to change the permission 619 for a user from one value to another, the former schema design is 620 better for xcap; it will require a single PUT to make such a change. 621 In the latter case, either the entire document needs to be replaced 622 (which is a single operation), or two PUT operations need to occur - 623 one to remove the user from the old permission, and one to add the 624 user to the new permission. 626 Naming conventions form another key part of the design of an 627 application usage. The application usage should be certain that XCAP 628 clients know where to "start" to retrieve and modify documents of 629 interest. Generally, this will involve the specification of a well- 630 known document at a well-known URI. That document can contain 631 references to other documents that the client needs to read or 632 modify. 634 6. URI Construction 636 In order to manipulate an XCAP resource, the data must be represented 637 by an HTTP URI. XCAP defines a specific naming convention for 638 constructing these URIs. The URI is constructed by concatenating the 639 XCAP root with the document selector with the path separator with a 640 escape coded form of the node selector. This is followed by an 641 optional query component that defines namespace bindings used in 642 evaluating the URI. The XCAP root is the enclosing context in which 643 all XCAP resources live. The document selector is a path that 644 identifies a document within the XCAP root. The path separator is a 645 path segment with a value of double tilde ("~~"), and SHOULD NOT be 646 percent-encoded, as advised in Section 2.3 of RFC 3986 [14]. URIs 647 containing %7E%7E should be normalized to ~~ for comparison; they are 648 equivalent. The path separator is piece of syntactic sugar that 649 separates the document selector from the node selector. The node 650 selector is an expression that identifies an XML element within a 651 document. 653 The sections below describe these components in more detail. 655 6.1 XCAP Root 657 The root of the XCAP hierarchy is called the XCAP root. It defines 658 the context in which all other resources exist. The XCAP root is 659 represented with an HTTP URI, called the XCAP Root URI. This URI is 660 a valid HTTP URI; however, it doesn't point to any resource that 661 actually exists on the server. Its purpose is to identify the root 662 of the tree within the domain where all XCAP documents are stored. 663 It can be any valid HTTP URI, but MUST NOT contain a query component 664 (a complete XCAP URI may have a query component, but it is not part 665 of the XCAP root URI). It is RECOMMENDED that it be equal to 666 xcap.domain where domain is the domain of the provider. As an 667 example, http://xcap.example.com might be used as the XCAP root URI 668 within the example.com domain. Typically, the XCAP root URI is 669 provisioned into client devices. If not explicitly provisioned, 670 clients SHOULD assume the form xcap.domain where domain is the domain 671 of their service provider (for SIP, this would be the domain part of 672 their Address-of-Record (AOR)). A server or domain MAY support 673 multiple XCAP root URIs. In such a case, it is effectively operating 674 as if it were serving separate domains. There is never information 675 carryover or interactions between resources in different XCAP root 676 URIs. 678 When a client generates an HTTP request to a URI identifying an XCAP 679 resource, RFC 2616 procedures for the construction of the Request-URI 680 apply. In particular, the authority component of the URI may not be 681 present in the Request-URI if the request is sent directly to the 682 origin server. 684 The XCAP root URI can also be a relative HTTP URI. It is the 685 responsibility of the application usage to specify the base URI for 686 an HTTP URI representing an XCAP resource whenever such a URI appears 687 within a document defined by that application usage. Generally 688 speaking, it is unsafe to use the retrieval URI as the base URI. 689 This is because any URI that points to an ancestor for a particular 690 element or attribute can contain content including that element or 691 attribute. If that element or attribute contained a relative URI 692 reference, it would be resolved relative to whatever happened to be 693 used to retrieve the content, and this will often not be the base URI 694 defined by the application usage. 696 6.2 Document Selector 698 Each document within the XCAP root is identified by its document 699 selector. The document selector is a sequence of path segments, 700 separated by a slash ("/"). These path segments define a 701 hierarchical structure for organizing documents within any XCAP root. 702 The first path segment MUST be the XCAP AUID. So, continuing the 703 example above, all of the documents used by the resource lists 704 application would be under 705 http://xcap.example.com/services/resource-lists. 707 It is assumed that each application will have data that is set by 708 users, and/or it will have global data that applies to all users. As 709 a result, beneath each AUID there are two sub-trees. One, called 710 "users", holds the documents that are applicable to specific users, 711 and the other, called "global", holds documents applicable to all 712 users. The subtree beneath "global" is called the global tree. The 713 path segment after the AUID MUST either be "global" or "users". 715 Within the "users" tree are zero or more sub-trees, each of which 716 identifies documents that apply to a specific user. Each user known 717 to the server is associated with a username, called the XCAP User 718 Identifier (XUI). Typically, an endpoint is provisioned with the 719 value of the XUI. For systems that support SIP applications, it is 720 RECOMMENDED that the XUI be equal to the Address-of-Record (AOR) for 721 the user. Since SIP endpoints generally know their AOR, they will 722 also know their XUI. As a consequence, if no XUI is explicitly 723 provisioned, a SIP UA SHOULD assume it is equal to their AOR. This 724 XUI MUST be used as the path segment beneath the "users" segment. 725 The subtree beneath an XUI for a particular user is called their home 726 directory. "User" in this context should be interpreted loosely; a 727 user might correspond to device, for example. 729 XCAP does not itself define what it means for documents to "apply" to 730 a user, beyond specification of a baseline authorization policy, 731 described below in Section 8. Each application usage can specify 732 additional authorization policies which depend on data used by the 733 application itself. 735 The remainder of the document selector (the path following "global" 736 or the XUI) points to specific documents for that application usage. 737 Subdirectories are permitted, but are NOT RECOMMENDED. XCAP provides 738 no way to create sub-directories or to list their contents, thus 739 limiting their utility. As a consequence, the remainder of the 740 document selector will normally be a name for the document itself. 741 If a user has a single document for a particular application usage, 742 this SHOULD be called "index". If subdirectories are used, there 743 MUST not be a document in a directory with the same name as a sub- 744 directory. 746 The final path segment in the document selector identifies the actual 747 document in the hierarchy. This is equivalent to a filename, except 748 that XCAP does not require that its document resources be stored as 749 files in a file system. However, the term "filename" is used to 750 describe the final path segment in the document selector. In 751 traditional filesystems, the filename would have a filename 752 extension, such as ".xml". There is nothing in this specification 753 that requires or prevents such extensions from being used in the 754 filename. In some cases, the application usage will specify a naming 755 convention for documents, and those naming conventions may or may not 756 specify a file extension. For example, in the RLS services 757 application usage [22], documents in the user's home directory with 758 the filename "index" will be used by the server to compute the global 759 index, which is also a document with the filename "index". 761 When the naming conventions in an application usage do not constrain 762 the filename conventions (or, more generally, the document selector), 763 an application will know the filename (or more generally, the 764 document selector) because it is included as a reference in a 765 document which is at a well known location. As another example, 766 within the index document defined by RLS services, the 767 element has a child element called whose content is a 768 URI pointing to a resource list within the users home directory. 770 As a result, if the user creates a new document, and then references 771 that document from a well-known document (such as the index document 772 above), it doesn't matter whether the user includes an extension in 773 the filename or not, as long as the user is consistent and maintains 774 referential integrity. 776 As an example, the HTTP URI 777 http://xcap.example.com/resource-lists/users/joe/index represents a 778 document selector where the AUID is "resource-lists", and the 779 document is in the user tree with the XUI "joe" with filename 780 "index". 782 6.3 Node Selector 784 The node selector specifies specific nodes of the XML document which 785 are to be accessed. A node refers to an XML element, an attribute of 786 an element, or a set of namespace bindings. The node selector is an 787 expression which identifies an element, attribute or set of namespace 788 bindings. Its grammar is: 790 node-selector = element-selector ["/" terminal-selector] 791 terminal-selector = attribute-selector / namespace-selector / 792 extension-selector 793 element-selector = step *( "/" step) 794 step = by-name / by-pos / by-attr / by-pos-attr 795 / extension-selector 796 by-name = NameorAny 797 by-pos = NameorAny "[" position "]" 798 position = 1*DIGIT 799 by-attr = NameorAny "[" "@" att-name "=" <"> 800 att-value <"> "]" 801 by-pos-attr = NameorAny "[" position "]" "[" "@" 802 att-name "=" <"> att-value <"> "]" 803 NameorAny = QName / "*" ; QName from XML Namespaces 804 att-name = QName 805 att-value = AttValue ; from XML specification 806 attribute-selector = "@" att-name 807 namespace-selector = "namespace::*" 808 extension-selector = %x00-2e / %x30-ff ; anything but "/" 810 The QName grammar is defined in the XML namespaces [3] specification, 811 and the AttValue grammar is defined in the XML specification XML 1.0 812 [1]. 814 The extension-selector is included for purposes of extensibility. It 815 can be composed of any character except the slash, which is the 816 delimeter amongst steps. Any characters in an extension that cannot 817 be represented in a URI MUST be escape coded before placement into a 818 URI. 820 Note that the left bracket, right bracket, and double quote 821 characters, which are meaningful to XCAP, cannot be directly 822 represented in the HTTP URI. As a result, they are escape coded when 823 placed within the HTTP URI. Furthermore, since XML allows for non- 824 ASCII characters, the names of elements and attributes may not be 825 directly representable in a URI. Any such characters MUST be 826 represented by converting them to an octet sequence corresponding to 827 their representation in UTF-8, and then escape-coding that sequence 828 of octets. 830 Similarly, the XML specification defines the QName production for the 831 grammar for element and attribute names, and the AttValue production 832 for the attribute values. Unfortunately, the characters permitted by 833 these productions include some that are not allowed for pchar, which 834 is the production for the allowed set of characters in path segments 835 in the URI. The AttValue production allows many such characters 836 within the US-ASCII set, including the space. Those characters MUST 837 be escaped coded when placed in the URI. Furthermore, QName and 838 AttValue allow many Unicode characters, outside of US-ASCII. When 839 these characters need to be represented in the HTTP URI, they are 840 escape coded. To do this, the data should be encoded first as octets 841 according to the UTF-8 character encoding [19] and then only those 842 octets that do not correspond to characters in the unreserved set 843 should be percent-encoded. For example, the character A would be 844 represented as "A", the character LATIN CAPITAL LETTER A WITH GRAVE 845 would be represented as "%C3%80", and the character KATAKANA LETTER A 846 would be represented as "%E3%82%A2". 848 As a result, the grammar above represents the expressions processed 849 by the XCAP server internally after it has un-escape-coded the URI. 850 The on-the-wire format is dictated by RFC 3986 [14]. In the 851 discussions and examples below, when the node selectors are not part 852 of an HTTP URI, they are presented in their internal format prior to 853 encoding. If an example includes a node selector within an HTTP URI, 854 it is presented in its escape coded form. 856 The node selector is based on the concepts in XPath [11]. Indeed, 857 the node selector expression, before it is escape coded for 858 representation in the HTTP URI, happens to be a valid XPath 859 expression. However, XPath provides a set of functionality far 860 richer than is needed here, and its breadth would introduce much 861 unneeded complexity into XCAP. 863 To determine the XML element, attribute or namespace bindings 864 selected by the node selector, processing begins at the root of the 865 XML document. The first step in the element selector is then taken. 866 Each step chooses a single XML element within the current document 867 context. The document context is the point within the XML document 868 from which a specific step is evaluated. The document context begins 869 at the root of the document. When a step determines an element 870 within that context, that element becomes the new context for 871 evaluation of the next step. Each step can select an element by its 872 name, by a combination of name and attribute value, by name and 873 position, or by name, position and attribute. In all cases, the name 874 can be wildcarded, so that all elements get selected. 876 The selection operation operates as follows. Within the current 877 document context, the children of that context are enumerated in 878 document order. If the context is the document, its child is the 879 root element in the document. If the context is an element, its 880 children are all of the children of that element (naturally). Next, 881 those elements whose name is not a match for NameorAny are discarded. 882 An element name is a match if NameorAny is the wildcard, or, if its 883 not a wildcard, the element name matches NameorAny. Matching is 884 discussed below. The result is an ordered list of elements. 886 The elements in the list are further filtered by the predicates, 887 which are the expressions in square brackets following NameorAny. 888 Each predicate further prunes the elements from the current ordered 889 list. These predicates are evaluated in order. If the content of 890 the predicate is a position, the position-th element is selected 891 (that is, treat "position" as a variable, and take the element whose 892 position equals that variable), and all others are discarded. If 893 there are fewer elements in the list than the value of position, the 894 result is a no-match. 896 If the content of the predicate is an attribute name and value, all 897 elements possessing that attribute with that value are selected, and 898 all others are discarded. Note that, although a document can have 899 elements with namespace attributes, those elements cannot be selected 900 using a namespace attribute as a predicate. That is, a step like el- 901 name[@xmlns="namespace"] will never match an element, even if there 902 is an element in the list that specifies a default namespace of 903 "namespace". If the namespaces in scope for an element are needed, 904 they can be selected using the namespace-selector described below. 905 If there are no elements with attributes having the given name and 906 value, the result is a no-match. 908 After the predicates have been applied, the result will be a no- 909 match, one element, or multiple elements. If the result is multiple 910 elements, the node selector is invalid. Each step in a node selector 911 MUST produce a single element to form the context for the next step. 912 This is more restrictive than general XPath expressions, which allow 913 a context to contain multiple elements. If the result is a no-match, 914 the node selector is invalid. The node selector is only valid if a 915 single element was selected. This element becomes the context for 916 the evaluation of the next step in the node selector expression. 918 Once the last step is executed, if there is no terminal selector, the 919 result of the node selection is the last selected element. If the 920 terminal selector is an attribute selector, the server checks to see 921 if there is an attribute with that name in the element in the current 922 context. If there is not, the result is considered a no-match. 923 Otherwise, that attribute is selected. If the terminal selector is a 924 namespace selector, the result is always a match, and it is equal to 925 the set of namespace bindings in scope for the element, including the 926 default. This specification defines a syntax for representing 927 namespace bindings, so they can be returned to the client in an HTTP 928 response. 930 As a result, once the entire node selector is evaluated against the 931 document, the result will either be a no-match, invalid, a single 932 element, a single attribute or a set of namespace bindings. 934 Matching of element names is performed as follows. The element being 935 compared in the step has its name expanded as described in XML 936 namespaces [3]. The element name in the step is also expanded. This 937 expansion requires that any namespace prefix is converted to its 938 namespace URI. Doing that requires a set of bindings from prefixes 939 to namespace URIs. This set of bindings is obtained from the query 940 component of the URI (see Section 6.4). If the element name in the 941 step is not qualified, it is expanded using the default namespace 942 defined by the application usage. Comparisons are then performed as 943 described in XML namespaces [3]. Note that the namespace prefix 944 expansions described here are different than those specified in the 945 XPath 1.0 specification, but are compatible with those currently 946 defined by the XPath 2.0 specification [25]. 948 Matching of attribute names proceeds in a similar way. The attribute 949 in the document has its name expanded as described in XML namespaces 950 [3]. Note that the default namespace for attributes is null. If the 951 attribute name in the attribute selector has a namespace prefix, its 952 name expanded using the namespace bindings obtained from the query 953 component of the URI. If the attribute name in the attribute 954 selector does not have a namespace prefix, the default namespace is 955 null. 957 Comments, text content (including whitespace), and processing 958 declarations can be present in a document, but cannot be selected by 959 the expressions defined here. This is consistent with the XPath 960 treatment of these components. Of course, if such information is 961 present in a document, and a user selects an XML element enclosing 962 that data, that information would be included in a resulting GET, for 963 example. Furthermore, whitespace is respected by XCAP. If a client 964 PUTs an element or document that contains whitespace, the server 965 retains that whitespace, and will return the element or document back 966 to the client with exactly the same whitespace. Similarly, when an 967 element is inserted, no additional whitespace is added around the 968 inserted element, and the element gets inserted in a very specific 969 location relative to any whitespace, comments or processing 970 instructions around it (namely, after any such content, as described 971 in Section 8.2.3). 973 As an example, consider the following XML document: 975 976 978 980 sip:userA@example.net 984 sip:userB@example.org 988 989 991 Figure 3: Example XML Document 993 Assuming that the default namespace URI for this application usage is 994 urn:ietf:params:xml:ns:watcherinfo, the node selector "watcherinfo/ 995 watcher-list/watcher[@id="8ajksjda7s"]" would select the following 996 XML element: 998 sip:userA@example.net 1003 6.4 Namespace Bindings for the Selector 1005 In order to expand the namespace prefixes used in the document 1006 selector, a set of bindings from those namespace prefixes to 1007 namespace URI must be used. Those bindings are contained in the 1008 query component of the URI. If no query component is present, it 1009 means that only the default namespace URI (as identified by the 1010 application usage) is defined. The query component is formatted as a 1011 valid xpointer expression [5] after suitable URI encoding as defined 1012 in Section 4.1 of the Xpointer framework. This xpointer expression 1013 SHOULD only contain expressions from the xmlns() scheme [4]. A 1014 server compliant to this specification MUST ignore any xpointer 1015 expressions not from the xmlns() scheme. The xmlns() xpointer 1016 expressions define the set of namespace bindings in use for 1017 evaluating the URI. 1019 Note that xpointer expressions were originally designed for usage 1020 within fragment identifiers of URIs. However, within XCAP, they are 1021 used within query components of URIs. 1023 The following example shows a more complex matching operation, this 1024 time including the usage of namespace bindings. Consider the 1025 following document: 1027 1028 1030 1031 1032 1033 1034 1035 1036 1038 Assume that this document has a document URI of 1039 http://xcap.example.com/test/users/joe/index, where "test" is the 1040 application usage. This application usage defines a default 1041 namespace URI of "urn:test:default-namespace". The XCAP URI: 1043 http://xcap.example.com/test/users/joe/index/~~/foo/a:bar/b:baz? 1044 xmlns(a=%22urn:test:namespace1-uri%22)xml 1045 ns(b=%22urn:test:namespace1-uri%22) 1047 will select the first element in the document. The XCAP URI: 1049 http://xcap.example.com/test/users/joe/index/~~/foo/a:bar/b:baz? 1050 xmlns(a=%22urn:test:namespace1-uri%22)xml 1051 ns(b=%22urn:test:namespace2-uri%22) 1053 will select the second element in the document. The following 1054 XCAP URI will also select the second element in the document: 1056 http://xcap.example.com/test/users/joe/index/~~/d:foo/a:bar/b:baz? 1057 xmlns(a=%22urn:test:namespace1-uri%22)xml 1058 ns(b=%22urn:test:namespace2-uri%22)xmlns(d=%22urn:test: 1059 default-namespace%22) 1061 7. Client Operations 1063 An XCAP client is an HTTP/1.1 compliant client. Specific data 1064 manipulation tasks are accomplished by invoking the right set of HTTP 1065 methods with the right set of headers on the server. This section 1066 describes those in detail. 1068 In all cases where the client modifies a document, by deleting or 1069 inserting a document, element or attribute resource, the client 1070 SHOULD verify that, if the operation were to succeed, the resulting 1071 document would meet the data constraints defined by the application 1072 usage, including schema validation. For example, if the client 1073 performs a PUT operation to 1074 http://xcap.example.com/rls-services/users/joe/mybuddies, rls- 1075 services is the application unique ID, and the constraints defined by 1076 it SHOULD be followed. 1078 The client will know what URI to use based on the naming conventions 1079 described by the application usage. 1081 If the document, after modification, does not meet the data 1082 constraints, the server will reject it with a 409. The 409 response 1083 may contain an XML body, formatted according to the schema in 1084 Section 11.2, which provides further information on the nature of the 1085 error. The client MAY use this information to try and alter the 1086 request so that this time, it might succeed. The client SHOULD NOT 1087 simply retry the request without changing some aspect of it. 1089 In some cases, the application usage will dictate a uniqueness 1090 constraint that the client cannot guarantee on its own. One such 1091 example is that a URI has to be unique within a domain. Typically, 1092 the client is not the owner of the domain, and so it cannot be sure 1093 that a URI is unique. In such a case, the client can either generate 1094 a sufficiently random identifier, or it can pick a "vanity" 1095 identifier in the hopes that it is not taken. In either case, if the 1096 identifier is not unique, the server will reject the request with a 1097 409 and suggest alternatives that the client can use to try again. 1098 If the server does not suggest alternatives, the client SHOULD 1099 attempt to use random identifiers with increasing amounts of 1100 randomness. 1102 HTTP also specifies that PUT and DELETE requests are idempotent. 1103 This means that, if the client performs a PUT on a document and it 1104 succeeds, it can perform the same PUT, and the resulting document 1105 will look the same. Similarly, when a client performs a DELETE, if 1106 it succeeds, a subsequent DELETE to the same URI will generate a 404; 1107 the resource no longer exists on the server since it was deleted by 1108 the previous DELETE operation. To maintain this property, the client 1109 SHOULD construct its URIs such that, after the modification has taken 1110 place, the URI in the request will point to the resource just 1111 inserted for PUT (i.e., the body of the request), and will point to 1112 nothing for DELETE. If this property is maintained, it is the case 1113 that GET to the URI in the PUT will return the same content (i.e., 1114 GET(PUT(X)) == x). This property implies idempotency. Although a 1115 request can still be idempotent if it does not possess this property, 1116 XCAP does not permit such requests. If the client's request does not 1117 have this property, the server will reject the request with a 409 and 1118 indicate a cannot-insert error condition. 1120 If the result of the PUT is a 200 or 201 response, the operation was 1121 successful. Other response codes to any request, such as a 1122 redirection, are processed as per RFC 2616 [7]. 1124 7.1 Create or Replace a Document 1126 To create or replace a document, the client constructs a URI that 1127 references the location where the document is to be placed. This URI 1128 MUST be a document URI, and therefore contain the XCAP root and 1129 document selector. The client then invokes a PUT method on that URI. 1131 The MIME content type MUST be the type defined by the application 1132 usage. For example, it would be "application/rls-services+xml" for 1133 an RLS services [22] document, and not "application/xml". 1135 If the Request-URI identifies a document that already exists in the 1136 server, the PUT operation replaces that document with the content of 1137 the request. If the Request-URI does not identify an existing 1138 document, the document is created on the server at that specific URI. 1140 7.2 Delete a Document 1142 To delete a document, the client constructs a URI that references the 1143 document to be deleted. This URI MUST be a document URI. The client 1144 then invokes a DELETE operation on the URI to delete the document. 1146 7.3 Fetch a Document 1148 As one would expect, fetching a document is trivially accomplished by 1149 performing an HTTP GET request with the Request URI set to the 1150 document URI. 1152 7.4 Create or Replace an Element 1154 To create or replace an XML element within an existing document, the 1155 client constructs a URI whose document selector points to the 1156 document to be modified. The node selector MUST be present in the 1157 URI, separated from the document selector with the path separator. 1158 The query component MUST be present if the node selector makes use of 1159 namespace prefixes, in which case the xmlns() expressions in the 1160 query component MUST define those prefixes. To create this this 1161 element within the document, the node selector is constructed such 1162 that it is a no-match against the current document, but if the 1163 element in the body of the request was added to the document as 1164 desired by the client, the node selector would select that element. 1165 To replace an element in the document, the node selector is 1166 constructed so that it is a match against the element in the current 1167 document to be replaced, as well as a match to the new element 1168 (present in the body of the PUT request) that is to replace it. 1170 Oftentimes, the client will wish to insert an element into a document 1171 in a certain position relative to other children of the same parent. 1172 This is called a positional insertion. They often arise because the 1173 schema constrains where the element can occur, or because ordering of 1174 elements is significant within the schema. To accomplish this, the 1175 client can use a node selector of the following form: 1177 parent/*[position][unique-attribute-value] 1179 Here, "parent" is an expression for the parent of the element to be 1180 inserted. "position" is the position amongst the existing children of 1181 this parent where the new element is to be inserted. "unique- 1182 attribute-value" is an attribute name and value for the element to be 1183 inserted, which is different from the current element in "position". 1184 The second predicate is needed so that the overall expression is a 1185 no-match when evaluated against the current children. Otherwise, the 1186 PUT would replace the existing element in that position. 1188 Consider the example document in Figure 3. The client would like to 1189 insert a new element as the second element underneath 1190 . However, it cannot just PUT to a URI with the 1191 watcherinfo/watcher-list/*[2] node selector; this node selector would 1192 select the existing 2nd child of and replace it. 1193 Thus, the PUT has to be made to a URI with watcherinfo/watcher-list/ 1194 *[2][@id="hhggff"] as the node selector, where "hhggff" is the value 1195 of the "id" attribute of the new element to be inserted. This node- 1196 selector is a no-match against the current document, and would be a 1197 match against the new element if it was inserted as the 2nd child of 1198 . 1200 The "*" indicates that all element children of are to 1201 be considered when computing the position for insertion. If, instead 1202 of a *, an element name was present, the expression above would 1203 insert the new element as the position-th element amongst those with 1204 the same name. 1206 Once the client constructs the URI, it invokes the HTTP PUT method. 1208 If the client is creating a new element, it SHOULD include 1209 "application/xcap-diff+xml" in the Accept header field of the 1210 request. This allows the server to return an XCAP Diff document in a 1211 201 response code, and is useful for subsequent conditional 1212 operations, as described in Section 7.11. The content in the request 1213 MUST be an XML element. Specifically, it contains the element, 1214 starting with the opening bracket for the begin tag for that element, 1215 including the attributes and content of that element (whether it be 1216 text or other child elements), and ending with the closing bracket 1217 for the end tag for that element. The MIME type in the request MUST 1218 be "application/xcap-el+xml", defined in Section 15.2.1. If the node 1219 selector, when evaluated against the current document, results in a 1220 no-match, the server performs a creation operation. If the node 1221 selector, when evaluated against the current document, is a match for 1222 an element in the current document, the server replaces it with the 1223 content of the PUT request. This replacement is complete; that is, 1224 the old element (including its attributes and content) are removed, 1225 and the new one, including its attributes and content, is put in its 1226 place. 1228 To be certain that element insertions have the GET(PUT(x))==x 1229 property, the client can check that the attribute predicates in the 1230 final path segment of the URI match the attributes of the element in 1231 the body of the request. As an example of an request that would not 1232 have this property and therefore not be idempotent, consider the 1233 following PUT request (URIs are line-folded for readability): 1235 PUT 1236 /rls-services/users/bill/index/~~/rls-services/ 1237 service%5b@uri=%22sip:good-friends@example.com%5d 1238 HTTP/1.1 1239 Content-Type:application/xcap-el+xml 1240 Host: xcap.example.com 1242 1243 http://xcap.example.com/resource-lists/users/joe 1244 /index/~~/resource-lists/list%5b@name=%22l1%22%5d 1245 1246 1247 presence 1248 1249 1251 This request will fail with a 409. The Request URI contains a final 1252 path segment with a predicate based on attributes - 1253 @uri="sip:good-friends@example.com". However, this will not match 1254 the value of the "uri" attribute in the element in the body. 1256 7.5 Delete an Element 1258 To delete an element from a document, the client constructs a URI 1259 whose document selector points to the document containing the element 1260 to be deleted. The node selector MUST identify a single element. 1261 The node selector MUST be present following the path separator, and 1262 identify the specific element to be deleted. Furthermore, the node 1263 selector MUST match no element after the deletion of the target 1264 element. This is required to maintain the idempotency property of 1265 HTTP deletions. The query component MUST be present if the node 1266 selector makes use of namespace prefixes, in which case the xmlns() 1267 expressions in the query component MUST define those prefixes. 1269 If the client wishes to delete an element in a specific position, 1270 this is referred to as a positional deletions. Like a positional 1271 insertion, the node selector has the following form: 1273 parent/*[position][unique-attribute-value] 1275 Where "parent" is an expression for the parent of the element to be 1276 deleted, "position" is the position of the element to be deleted 1277 amongst the existing children of this parent, and "unique-attribute- 1278 value" is an attribute name and value for the element to be deleted, 1279 where this attribute name and value are different than the siblings 1280 of the element. 1282 The client then invokes the HTTP DELETE method. If the client plans 1283 on performing conditional operations using If-Match or If-None-Match, 1284 it SHOULD include "application/xcap-diff+xml" in an Accept header 1285 field in the DELETE request. This will allow the server to send an 1286 XCAP Diff document in the response. The server will remove the 1287 element from the document (including its attributes and its content, 1288 such as any children). 1290 7.6 Fetch an Element 1292 To fetch an element of a document, the client constructs a URI whose 1293 document selector points to the document containing the element to be 1294 fetched. The node selector MUST be present following the path 1295 separator, and must identify the element to be fetched. The query 1296 component MUST be present if the node selector makes use of namespace 1297 prefixes, in which case the xmlns() expressions in the query 1298 component MUST define those prefixes. 1300 The client then invokes the GET method. The 200 OK response will 1301 contain that XML element. Specifically, it contains the content of 1302 the XML document, starting with the opening bracket for the begin tag 1303 for that element, and ending with the closing bracket for the end tag 1304 for that element. This will, as a result, include all attributes, 1305 child elements, comments and CDATA of that element. 1307 7.7 Create or Replace an Attribute 1309 To create or replace an attribute in an existing element of a 1310 document, the client constructs a URI whose document selector points 1311 to the document to be modified. The node selector, following the 1312 path separator, MUST be present. The node selector MUST be 1313 constructed such that, if the attribute was created or replaced as 1314 desired, the node selector would select that attribute. If the node 1315 selector, when evaluated against the current document, results in a 1316 no-match, it is a creation operation. If it matches an existing 1317 attribute, it is a replacement operation. The query component MUST 1318 be present if the node selector makes use of namespace prefixes, in 1319 which case the xmlns() expressions in the query component MUST define 1320 those prefixes. 1322 The client then invokes the HTTP PUT method. If the client is 1323 creating a new attribute, it SHOULD include "application/ 1324 xcap-diff+xml" in the Accept header field of the request. This 1325 allows the server to return an XCAP Diff document in a 201 response 1326 code, and is useful for subsequent conditional operations, as 1327 described in Section 7.11. The content defined by the request MUST 1328 be the value of the attribute, compliant to the grammar for AttValue 1329 as defined in XML 1.0 [1]. Note that, unlike when AttValue is 1330 present in the URI, there is no escape coding. Escaping only applies 1331 to URIs. This request MUST be sent with the Content-Type of 1332 "application/xcap-att+xml" as defined in Section 15.2.2. The server 1333 will add that attribute such that, if the node selector is evaluated 1334 on the resulting document, it returns the attribute present in the 1335 request. 1337 To be certain that attribute insertions have the GET(PUT(x))==x 1338 property, the client can check that any attribute predicate in the 1339 path segment that selects the element into which the attribute is 1340 inserted, matches a different attribute than the one being inserted 1341 by the request. As an example of a request that would not have this 1342 property and therefore not be idempotent, consider the following PUT 1343 request (URIs are line folded for readability): 1345 PUT 1346 /rls-services/users/bill/index/~~/ 1347 rls-services/service%5b@uri=%22sip:good-friends@example.com%5d/@uri 1348 HTTP/1.1 1349 Content-Type:application/xcap-att+xml 1350 Host: xcap.example.com 1352 "sip:bad-friends@example.com" 1354 This request will fail with a 409. 1356 7.8 Delete an Attribute 1358 To delete attributes from the document, the client constructs a URI 1359 whose document selector points to the document containing the 1360 attributes to be deleted. The node selector MUST be present 1361 following the path separator, and evaluate to an attribute in the 1362 document to be deleted. The query component MUST be present if the 1363 node selector makes use of namespace prefixes, in which case the 1364 xmlns() expressions in the query component MUST define those 1365 prefixes. 1367 The client then invokes the HTTP DELETE method. The server will 1368 remove the attribute from the document. 1370 7.9 Fetch an Attribute 1372 To fetch an attribute of a document, the client constructs a URI 1373 whose document selector points to the document containing the 1374 attribute to be fetched. The node selector MUST be present following 1375 the path separator, containing an expression identifying the 1376 attribute whose value is to be fetched. The query component MUST be 1377 present if the node selector makes use of namespace prefixes, in 1378 which case the xmlns() expressions in the query component MUST define 1379 those prefixes. 1381 The client then invokes the GET method. The 200 OK response will 1382 contain an "application/xcap-att+xml" document with the specified 1383 attribute, formatted according to the grammar of AttValue as defined 1384 in the XML 1.0 specifications. 1386 7.10 Fetch Namespace Bindings 1388 If a client wishes to insert an element or attribute into a document, 1389 and that element or attribute are part of a namespace declared 1390 elsewhere in the document, the client will need to know the namespace 1391 bindings in order to construct the XML content in the request. If 1392 the client has a cached copy of the document, it will know the 1393 bindings. However, if it doesnt have the whole document cached, it 1394 can be useful to fetch just the bindings that are in scope for an 1395 element, in order to construct a subsequent PUT request. 1397 To get those bindings, the client constructs a URI whose document 1398 selector points to the document containing the element whose 1399 namespace bindings are to be fetched. The node selector MUST be 1400 present following the path separator, containing an expression 1401 identifying the desired namespace bindings. The query component MUST 1402 be present if the node selector makes use of namespace prefixes, in 1403 which case the xmlns() expressions in the query component MUST define 1404 those prefixes. 1406 The client then invokes the GET method. The 200 OK response will 1407 contain an "application/xcap-ns+xml" document with the namespace 1408 definitions. The format for this document is defined in Section 10. 1410 A client cannot set the namespace prefixes in scope for an element. 1411 As such, a node selector that identifies namespace prefixes MUST NOT 1412 appear in a PUT or DELETE request. 1414 7.11 Conditional Operations 1416 The HTTP specification defines several header fields that can be used 1417 by a client to make the processing of the request conditional. In 1418 particular, the If-None-Match and If-Match header fields allow a 1419 client to make them conditional on the current value of the entity 1420 tag for the resource. These conditional operations are particularly 1421 useful for XCAP resources. 1423 For example, it is anticipated that clients will frequently wish to 1424 cache the current version of a document. So, when the client starts 1425 up, it will fetch the current document from the server and store it. 1426 When it does so, the GET response will contain the entity tag for the 1427 document resource. Each resource within a document maintained by the 1428 server will share the same value of the entity tag. As a result, the 1429 entity tag returned by the server for the document resource is 1430 applicable to element and attribute resources within the document. 1432 If the client wishes to modify an element or attribute within the 1433 document, but it wants to be certain that the document hasn't been 1434 modified since the client last operated on it, it can include an If- 1435 Match header field in the request, containing the value of the entity 1436 tag known to the client for all resources within the document. If 1437 the document has changed, the server will reject this request with a 1438 412 response. In that case, the client will need to flush its cached 1439 version, fetch the entire document, and store the new entity tag 1440 returned by the server in the 200 OK to the GET request. It can then 1441 retry the request, placing the new entity tag in the If-Match header 1442 field. If this succeeds, the Etag header field in the response to 1443 PUT contains the entity tag for the resource that was just modified. 1444 Because all resources in a document share the same value for their 1445 entity tag, this entity tag value can be applied to the modification 1446 of other resources. 1448 A client can also conditionally delete elements or attributes by 1449 including an If-Match header field in DELETE requests. However, the 1450 200 OK response to a DELETE will not contain an Etag header field, 1451 since the resource no longer exists. However, if the client included 1452 "application/xcap-diff+xml" in the Accept header field of its DELETE 1453 request, a 200 OK response will contain an XCAP Diff document, 1454 indicating the entity tag for the document in which the deleted 1455 element resided. 1457 Unfortunately, the same conditional operation cannot be directly 1458 performed for insertions of elements or attributes. That is, if the 1459 client wishes to insert a new element or attribute into a document, 1460 and it wants to be sure that the document hasn't been modified since 1461 the client last operated on it, it cannot do that directly. This is 1462 because the If-Match header field applies to the resource in the 1463 request URI. For an insertion, this resource does not yet exist, and 1464 the If-Match will fail. Because of this, if a client wishes to 1465 conditionally insert an attribute or element, it should turn this 1466 into an update operation by modifying the enclosing element, such 1467 that its new value includes the element or attribute that the client 1468 wishes to insert. 1470 When a client uses conditional PUT and DELETE operations, it can 1471 apply those changes to its local cached copy, and update the value of 1472 the entity tag for the locally cached copy based on the Etag header 1473 field or the XCAP diff document returned in the response. As long as 1474 no other clients try to modify the document, the client will be able 1475 to perform conditional operations on the document without ever having 1476 to perform separate GET operations to synchronize the document and 1477 it's entity tags with the server. If another client tries to modify 1478 the document, this will be detected by the conditional mechanisms, 1479 and the client will need to perform a GET to resynchronize its copy 1480 unless it has some other means to learn about the change. 1482 If a client does not perform a conditional operation, but did have a 1483 cached copy of the document, that cached copy will become invalid 1484 once the operation is performed (indeed, it may have become invalid 1485 even beforehand). To allow the client to keep its version in sync 1486 with the server in cases where no other clients happen to be 1487 modifying the document, the client has to rely on the XCAP diff 1488 documents returned in a successful 200 OK to a PUT or DELETE. The 1489 diff document indicates the entity tags for the entire document (and 1490 thus all resources within it) prior to, and after, the operation. If 1491 the entity tag prior to the operation matches the one cached by the 1492 client, the client can know that the document was unmodified prior to 1493 the operation. If the entity tag does not match, the client knows it 1494 had been modified. In that case, the client should fetch the entire 1495 document to resynchronize, unless it is using some other mechanism to 1496 discover the changes made to the document. 1498 In another example, a client may wish to insert a new element into a 1499 document, but wants to be sure that the insertion will only take 1500 place if that element does not exist. In other words, the client 1501 wants the PUT operation to be a creation, not a replacement. To 1502 accomplish that, the client can insert the If-None-Match header field 1503 into the PUT request, with a value of *. This tells the server to 1504 reject the request with a 412 if resource exists. 1506 As another example, a when a client fetches a document, and there is 1507 an older version cached, it is useful for clients to use a 1508 conditional GET in order to reduce network usage if the cached copy 1509 is still valid. This is done by including, in the GET request, the 1510 If-None-Match header field with a value equal to the current etag 1511 held by the client for the document. The server will only generate a 1512 200 OK reponse if the etag held by the server differs than that held 1513 by the client. If it doesn't differ, the server will respond with a 1514 304 response. 1516 8. Server Behavior 1518 An XCAP server is an HTTP/1.1 compliant origin server. The behaviors 1519 mandated by this specification relate to the way in which the HTTP 1520 URI is interpreted and the content is constructed. 1522 An XCAP server MUST be explicitly aware of the application usage 1523 against which requests are being made. That is, the server must be 1524 explicitly configured to handle URIs for each specific application 1525 usage, and must be aware of the constraints imposed by that 1526 application usage. 1528 When the server receives a request, the treatment depends on the URI. 1529 If the URI refers to an application usage not understood by the 1530 server, the server MUST reject the request with a 404 (Not Found) 1531 response. If the URI refers to a user that is not recognized by the 1532 server, it MUST reject the request with a 404 (Not Found). If the 1533 URI includes extension-selectors that the server doesnt understand, 1534 it MUST reject the request with a 404 (Not Found). 1536 Next, the server authenticates the request. All XCAP servers MUST 1537 implement HTTP Digest [12]. Furthermore, servers MUST implement HTTP 1538 over TLS, RFC 2818 [15]. It is RECOMMENDED that administrators use 1539 an HTTPS URI as the XCAP root URI, so that the digest client 1540 authentication occurs over TLS. 1542 Next, the server determines if the client has authorization to 1543 perform the requested operation on the resource. The application 1544 usage defines the authorization policies. An application usage may 1545 specify that the default is used. This default is described in 1546 Section 5.7. 1548 Next, the server makes sure that it can properly evaluate the request 1549 URI. The server MUST check the node selector in the request URI, if 1550 present. If any qualified names are present that use a namespace 1551 prefix, and that prefix is not defined in an xmlns() expression in 1552 the query component of the request URI, the server MUST reject the 1553 request with a 400 response. 1555 After checking the namespace prefix definitions, the specific 1556 behavior depends on the method and what the URI refers to. 1558 8.1 POST Handling 1560 XCAP resources do not represent processing scripts. As a result, 1561 POST operations to HTTP URIs representing XCAP resources are not 1562 defined. A server receiving such a request for an XCAP resource 1563 SHOULD return a 405. 1565 8.2 PUT Handling 1567 The behavior of a server in receipt of a PUT request is as specified 1568 in HTTP/1.1 Section 9.6 - the content of the request is placed at the 1569 specified location. This section serves to define the notion of 1570 "placement" and "specified location" within the context of XCAP 1571 resources. 1573 If the request URI contained a namespace-selector, the server MUST 1574 reject the request with a 405 (Method Not Allowed) and MUST include 1575 an Allow header field including the GET method. 1577 8.2.1 Locating the Parent 1579 The first step the server performs is to locate the parent, whether 1580 it is a directory or element, in which the resource is to be placed. 1581 To do that, the server removes the last path segment from the URI. 1582 The rest of the URI refers to the parent. This parent can be a 1583 document, element, or prefix of a document selector (called a 1584 directory, even though this specification does not mandate that 1585 documents are actually stored in a filesystem). This URI is called 1586 the parent URI. The path segment that was removed is called the 1587 target selector, and the node (element, document or attribute) it 1588 describes is called the target node. 1590 If the parent URI has no path separator, it is referring to the 1591 directory into which the document should be inserted. If this 1592 directory does not exist, the server MUST return a 409 response, and 1593 SHOULD include a detailed conflict report including the 1594 element. Detailed conflict reports are discussed in Section 11. If 1595 the directory does exist, the server checks to see if there is a 1596 document with the same filename as the target node. If there is, the 1597 operation is the replacement operation discussed in Section 8.2.4. 1598 If it does not exist, it is the creation operation, discussed in 1599 Section 8.2.4. 1601 If the parent URI has a path separator, the document selector is 1602 extracted, and that document is retrieved. If the document does not 1603 exist, the server MUST return a 409 response, and SHOULD include a 1604 detailed conflict report including the element. If it 1605 does exist, the node selector is extracted, and unescaped (recall 1606 that the node selector is escape coded). The node selector is 1607 applied to the document based on the matching operations discussed in 1608 Section 6.3. If the result is a no-match or invalid, the server MUST 1609 return a 409 response, and SHOULD include a detailed conflict report 1610 including the element. 1612 If the node-selector is valid, the server examines the target 1613 selector, and evaluates it within the context of the parent node. If 1614 the target node exists within the parent, the operation is a 1615 replacement, as described in Section 8.2.4. If it does not exist, it 1616 is the creation operation, discussed in Section 8.2.4. 1618 Before performing the replacement or creation, as determined based on 1619 the logic above, the server validates the content of the request as 1620 described in Section 8.2.2 1622 8.2.2 Verifying Document Content 1624 If the PUT request is for a document (the request URI had no path 1625 separator), the content of the request body has to be a well-formed 1626 XML document. If it is not, the server MUST reject the request with 1627 a 409 response code. That response SHOULD include a detailed 1628 conflict report including the element. If the 1629 document is well-formed but not UTF-8 encoded, the server MUST reject 1630 the request with a 409 response code. That response SHOULD include a 1631 detailed conflict report including the element. If the 1632 MIME type in the Content-Type header field of the request is not 1633 equal to the MIME type defined for the application usage, the server 1634 MUST reject the request with a 415. 1636 If the PUT request is for an element, the content of the request body 1637 has to be a well-balanced region of an XML document, also known as an 1638 XML fragment body in The XML Fragment Interchange [24] specification, 1639 including only a single element. If it is not, the server MUST 1640 reject the request with a 409 response code. That response SHOULD 1641 include a detailed conflict report including the 1642 element. If the fragment body is well-balanced but contains 1643 characters outside of the UTF-8 character set, the server MUST reject 1644 the request with a 409 response code. That response SHOULD include a 1645 detailed conflict report including the element. If the 1646 MIME type in the Content-Type header field of the request is not 1647 equal to "application/xcap-el+xml", the server MUST reject the 1648 request with a 415. 1650 If the PUT request is for an attribute, the content of the request 1651 body has to be a sequence of characters that comply with the grammar 1652 for AttValue as defined above. If it is not, the server MUST reject 1653 the request with a 409 response code. That response SHOULD include a 1654 detailed conflict report including the element. 1655 If the attribute value is valid but contains characters outside of 1656 the UTF-8 character set, the server MUST reject the request with a 1657 409 response code. That response SHOULD include a detailed conflict 1658 report including the element.If the MIME type in the 1659 Content-Type header field of the request is not equal to 1660 "application/xcap-att+xml", the server MUST reject the request with a 1661 415. 1663 8.2.3 Creation 1665 The steps in this sub-section are followed if the PUT request will 1666 result in the creation of a new document, element or attribute. 1668 If the PUT request is for a document, the content of the request body 1669 is placed into the directory, and its filename is associated with the 1670 target node, which is a document. 1672 If the PUT request is for an element, the server inserts the content 1673 of the request body as a new child element of the parent element 1674 selected in Section 8.2.1. The insertion is done such that, the 1675 request URI, when evaluated, would now point to the element which was 1676 inserted. If the target selector is defined by a by-name or by-attr 1677 production (in other words, there is no position indicated) the 1678 server MUST insert the element such that it is in the "earliest last" 1679 position. "Earliest last" means that it MUST be inserted so that 1680 there are no elements after it with the same element name, and for 1681 all insertion positions where this is true, it is inserted such that 1682 as many sibling elements appear after it as possible. Furthermore, 1683 if there were comment, whitespace, or processing instructions after 1684 the last element with the same name, they MUST occur prior to the 1685 insertion of the new element. In other words, it appears just after 1686 the last element with that name, but before any comments, whitespace 1687 or processing instructions. If there were no other sibling elements 1688 with the same element name, the new element is inserted such that it 1689 is the last element amongst all element siblings. Furthermore, if 1690 there were comment, whitespace, or processing instructions after the 1691 former last element, they MUST occur prior to the insertion of the 1692 new element. 1694 If a position is indicated, the server MUST insert the element so 1695 that it is in the "earliest nth" position. Earliest nth position 1696 means that it MUST be inserted so that there are n-1 elements before 1697 it with the same element name, and for all insertion positions where 1698 this is true, it is inserted such that as many sibling elements 1699 appear after it as possible. Furthermore, if there were comment, 1700 whitespace, or processing instructions after the previous element 1701 with the same name, they MUST occur prior to the insertion of the new 1702 element. If there were no other sibling elements with the same 1703 element name, a positional insertion is only possible if the position 1704 was 1. In such a case, the new element is inserted such that it is 1705 the last element amongst all element siblings. Furthermore, if there 1706 were comment, whitespace, or processing instructions after the former 1707 last element, they MUST occur prior to the insertion of the new 1708 element. 1710 For example, consider the following document: 1712 1713 1714 1715 1716 and whose node 1721 selector is root/el1[@att="third"] would result in the following 1722 document: 1724 1725 1726 1727 1728 and the node 1737 selector was root/el3, it would result in the following document: 1739 1740 1741 1742 1743 1745
1747 It is possible that the element cannot be inserted such that the 1748 request URI, when evaluated, returns the content provided in the 1749 request. Such a request is not allowed for PUT. This happens when 1750 the element in the body is not described by the expression in the 1751 target selector. An example of this case is described in 1752 Section 7.4. If this happens the server MUST NOT perform the 1753 insertion, and MUST reject the request with a 409 response. The body 1754 of the response SHOULD contain a detailed conflict report containing 1755 the element. It is important to note that schema 1756 compliance does not play a role while performing the insertion. That 1757 is, the decision of where the element gets inserted is dictated 1758 entirely by the structure of the request-URI, the current document, 1759 and the rules in this specification. 1761 If the PUT request is for an attribute, the server inserts the 1762 content of the request body as the value of the attribute. The name 1763 of the attribute is equal to the att-name from the attribute-selector 1764 in the target selector. 1766 Assuming that the insertion can be accomplished, the server verifies 1767 that the insertion results in a document that meets the constraints 1768 of the application usage. This is dicussed in Section 8.2.5. 1770 8.2.4 Replacement 1772 The steps in this sub-section are followed if the PUT request will 1773 result in the replacement of a document, element or attribute with 1774 the contents of the request. 1776 If the PUT request is for a document, the content of the request body 1777 is placed into the directory, replacing the document with the same 1778 filename. 1780 If the PUT request is for an element, the server replaces the target 1781 node with the content of the request body. As in the creation case, 1782 it is possible that, after replacement, the request URI does not 1783 select the element that was just inserted. If this happens the 1784 server MUST NOT perform the replacement, and MUST reject the request 1785 with a 409 response. The body of the response SHOULD contain a 1786 detailed conflict report containing the element. 1788 If the PUT request is for an attribute, the server sets the value of 1789 the selected attribute to the content of the request body. It is 1790 possible in the replacement case (but not in the creation case), 1791 that, after replacement of the attribute, the request URI no longer 1792 selects the attribute that was just replaced. The scenario in which 1793 this can happen is discussed in Section 7.7. If this is the case, 1794 the server MUST NOT perform the replacement, and MUST reject the 1795 request with a 409 response. The body of the response SHOULD contain 1796 a detailed conflict report containing the element. 1798 8.2.5 Validation 1800 Once the document, element or attribute has been tentatively 1801 inserted, the server needs to verify that the resulting document 1802 meets the data constraints outlined by the application usage. 1804 First, the server checks that the final document is compliant to the 1805 schema. If it is not, the server MUST NOT perform the insertion. It 1806 MUST reject the request with a 409 response. That response SHOULD 1807 contain a detailed conflict report containing the element. 1810 Next, the server checks for any uniqueness constraints identified by 1811 the application usage. If the application usage required that a 1812 particular element or attribute had a unique value within a specific 1813 scope, the server would check that this uniqueness property still 1814 exists. If the application usage required that a URI within the 1815 document was unique within the domain, the server checks whether it 1816 is the case. If any of these uniqueness constraints are not met, the 1817 server MUST NOT perform the insertion. It MUST reject the request 1818 with a 409 response. That response SHOULD contain a detailed 1819 conflict report containing the element. That 1820 element can contain suggested values that the client can retry with. 1821 These SHOULD be values that, at the time the server generates the 1822 409, would meet the uniqueness constraints. 1824 The server also checks for URI constraints and other non-schema data 1825 constraints. If the document fails one of these constraints, the 1826 server MUST NOT perform the insertion. It MUST reject the request 1827 with a 409 response. That response SHOULD contain a detailed 1828 conflict report containing the element. That 1829 element indicates that the document failed non-schema data 1830 constraints explicitly called out by the application usage. 1832 8.2.6 Resource Interdependencies 1834 Because XCAP resources include elements, attributes and documents, 1835 each of which has its own HTTP URI, the creation or modification of 1836 one resource affects the state of many others. For example, 1837 insertion of a document creates resources on the server for all of 1838 the elements and attributes within that document. After the server 1839 has performed the insertion associated with the PUT, the server MUST 1840 create and/or modify those resources affected by that PUT. The 1841 structure of the document completely defines the inter-relationship 1842 between those resources. 1844 However, the application usage can specify other resource inter- 1845 dependencies. The server MUST create or modify the resources 1846 specified by the application usage. 1848 If the creation or replacement was successful, and the resource 1849 interdependencies are resolved, the server returns a 201 Created or 1850 OK or 200, respectively. Note that a 201 Created is generated for 1851 creation of new documents, elements, or attributes. If the client 1852 included "application/xcap-diff+xml" in an Accept header in the PUT 1853 request, and the request was an insertion resulting in a 201 1854 response, the server SHOULD include an XCAP diff document in the 1855 response [6]. The XCAP diff document SHOULD contain a single 1856 element. It SHOULD indicate the entity tag for the 1857 document resource prior to the insertion in the "previous-etag" 1858 attribute, and the entity tag for the document after insertion in the 1859 "new-etag" attribute. A 200 OK response to PUT MUST not contain any 1860 content. 1862 8.3 GET Handling 1864 The semantics of GET are as specified in RFC 2616. This section 1865 clarifies the specific content to be returned for a particular URI 1866 that represents an XCAP resource. 1868 If the request URI contains only a document selector, the server 1869 returns the document specified by the URI if it exists, else returns 1870 a 404 response. The MIME type of the body of the 200 OK response 1871 MUST be the MIME type defined by that application usage (i.e., 1872 "application/resource-lists+xml"). 1874 If the request URI contains a node selector, the server obtains the 1875 document specified by the document selector, and if it is found, 1876 evaluates the node-selector within that document. If no document is 1877 found, or if the node-selector is a no-match or invalid, the server 1878 returns a 404 response. Otherwise, the server returns a 200 OK 1879 response. If the node selector identifies an XML element, that 1880 element is returned in the 200 OK response as an XML fragment body 1881 containing the selected element. The MIME type of the response MUST 1882 be "application/xcap-el+xml". If the node selector identifies an XML 1883 attribute, the value of that attribute is returned in the body of the 1884 response. The MIME type of the response MUST be "application/ 1885 xcap-att+xml". If the node selector identifies a set of namespace 1886 bindings, the server computes the set of namespace bindings in scope 1887 for the element (including the default) and encodes it using the 1888 "application/xcap-ns+xml" format defined in Section 10. That 1889 document is then returned in the body of the response. 1891 8.4 DELETE Handling 1893 The semantics of DELETE are as specified in RFC 2616. This section 1894 clarifies the specific content to be deleted for a particular URI 1895 that represents an XCAP resource. 1897 If the request URI contained a namespace-selector, the server MUST 1898 reject the request with a 405 (Method Not Allowed) and MUST include 1899 an Allow header field including the GET method. 1901 If the request URI contains only a document selector, the server 1902 deletes the document specified by the URI if it exists and returns a 1903 200 OK, else returns a 404 response. 1905 If the request URI contains a node selector, the server obtains the 1906 document specified by the document selector, and if it is found, 1907 evaluates the node-selector within that document. If no document is 1908 found, or if the node-selector is a no-match or invalid (note that it 1909 will be invalid if multiple elements or attributes are selected), the 1910 server returns a 404 response. Otherwise, the server removes the 1911 specified element or attribute from the document and performs the 1912 validation checks defined in Section 8.2.5. Note that this deletion 1913 does not include any white space around the element that was deleted; 1914 the XCAP server MUST preserve surrounding whitespace. It is possible 1915 that, after deletion, the request URI selects another element in the 1916 document. If this happens the server MUST NOT perform the deletion, 1917 and MUST reject the request with a 409 response. The body of the 1918 response SHOULD contain a detailed conflict report containing the 1919 element. If the deletion will cause a failure of one 1920 of the constraints, the deletion MUST NOT take place. The server 1921 follows the procedures in Section 8.2.5 for computing the 409 1922 response. If the deletion results in a document that is still valid, 1923 the server MUST perform the deletion, process the resource 1924 interdependencies defined by the application usage, and return a 200 1925 OK response. 1927 Before the server returns the 200 OK response to a DELETE, it MUST 1928 process the resource interdependencies as defined in Section 8.2.6. 1929 Furthermore, if the client included "application/xcap-diff+xml" in an 1930 Accept header in the DELETE request, and the request deleted an 1931 element or attribute in the document, the server SHOULD include an 1932 XCAP diff document in the response [6]. The XCAP diff document 1933 SHOULD contain a single element. It SHOULD indicate the 1934 entity tag for the document resource prior to the deletion in the 1935 "previous-etag" attribute, and the entity tag for the document after 1936 deletion in the "new-etag" attribute. 1938 8.5 Managing Etags 1940 An XCAP server MUST maintain entity tags for all resources that it 1941 maintains. This specification introduces the additional constraint 1942 that when one resource within a document (including the document 1943 itself) changes, that resource is assigned a new etag, and all other 1944 resources within that document MUST be assigned the same etag value. 1945 An XCAP server MUST include the Etag header field in all 200 or 201 1946 responses to PUT and GET. XCAP resources do not introduce new 1947 requirements on the strength of the entity tags; as in RFC 2616, weak 1948 ones MAY be used if performance constraints or other conditions make 1949 usage of strong ones untenable for some reason. 1951 As a result of this constraint, when a client makes a change to an 1952 element or attribute within a document, the response to that 1953 operation will convey the entity tag of the resource that was just 1954 affected. Since the client knows that this entity tag value is 1955 shared by all of the other resources in the document, the client can 1956 make conditional requests against other resources using that entity 1957 tag. 1959 9. Cache Control 1961 An XCAP resource is a valid HTTP resource, and therefore, it can be 1962 cached by clients and network caches. Network caches, however, will 1963 not be aware of the interdependencies between XCAP resources. As 1964 such, a change to an element in a document by a client will 1965 invalidate other XCAP resources affected by the change. For 1966 application usages contain data that is likely to be dynamic or 1967 written by clients, servers SHOULD indicate a no-cache directive. 1969 10. Namespace Binding Format 1971 A node-selector can identify a set of namespace bindings that are in 1972 scope for a particular element. In order to convey these bindings in 1973 a GET response, a way is needed to encode them. 1975 Encoding is trivially done by including a single XML element element 1976 in an XML fragment body. This element has the same local-name as the 1977 element whose namespace bindings are desired, and also the same 1978 namespace-prefix. The element has an xmlns attribute identifying the 1979 default namespace in scope, and an xmlns:prefix attribute for each 1980 prefix that is in scope. 1982 For example, consider the XML document in Section 6.4. The node- 1983 selector df:foo/df2:bar/df2:baz/namespace::* will select the 1984 namespaces in scope for the element in the document, assuming 1985 the request is accompanied by a query component that contains 1986 xmlns(df="urn:test:default-namespace") and 1987 xmlns(df2="urn:test:namespace1-uri"). A GET containing this node 1988 selector and namespace bindings will produce the following result: 1990 1993 It is important to note that the client does not need to know the 1994 actual namespace bindings in order to construct the URI. It does 1995 need to know the namespace URI for each element in the node-selector. 1996 The namespace bindings present in the query component are defined by 1997 the client, mapping those URI to a set prefixes. The bindings 1998 returned by the server are the actual bindings used in the document. 2000 11. Detailed Conflict Reports 2002 In cases where the server returns a 409 error response, that response 2003 will usually include a document in the body of the response which 2004 provides further details on the nature of the error. This document 2005 is an XML document, formatted according to the schema of 2006 Section 11.2. Its MIME type, registered by this specification, is 2007 "application/xcap-error+xml". 2009 11.1 Document Structure 2011 The document structure is simple. It contains the root element 2012 . The content of this element is a specific error 2013 condition. Each error condition is represented by a different 2014 element. This allows for different error conditions to provide 2015 different data about the nature of the error. All error elements 2016 support a "phrase" attribute, which can contain text meant for 2017 rendering to a human user. 2019 The following error elements are defined by this specification: 2021 : This indicates that the body of the request was 2022 not a well-formed XML document. 2024 : This indicates that the request was supposed to 2025 contain a valid XML fragment body, but did not. Most likely this 2026 is because the XML in the body was malformed or not balanced. 2028 : This indicates that an attempt to insert an element, 2029 attribute or document failed because the document or element into 2030 which the insertion was supposed to occur does not exist. This 2031 error element can contain an optional element, which 2032 provides an HTTP URI of the xcap resource that identifies the 2033 closest ancestor element that does exist in the document. This 2034 HTTP URI MAY be a relative URI, relative to the document itself. 2035 Because this is a valid HTTP URI, its node selector component MUST 2036 be escape encoded. 2038 : This element indicates that the document 2039 was not compliant to the schema after the requested operation was 2040 performed. 2042 : This indicates that the request was supposed to 2043 contain a valid XML attribute value, but did not. 2045 : This indicates that the requested PUT operation 2046 could not be performed because a GET of that resource after the 2047 PUT would not yield the content of the PUT request. 2049 : This indicates that the requested DELETE operation 2050 could not be performed because it would not be idempotent. 2052 : This indicates that the requested operation 2053 would result in a document that did not meet a uniqueness 2054 constraint defined by the application usage. For each URI, 2055 element or attribute specified by the client which is not unique, 2056 an element is present as the content of the error 2057 element. Each element has a "field" attribute that 2058 contains a relative URI identifying the XML element or attribute 2059 whose value needs to be unique, but wasn't. The relative URI is 2060 relative to the document itself, and will therefore start with the 2061 root element. The query component of the URI MUST be present if 2062 the node selector portion of the URI contains namespace prefixes. 2063 Note that the double quote character, which is allowed in node 2064 selectors, cannot appear within the value of an attribute. As 2065 such, it MUST be represented as ". Since the node selector is 2066 a valid HTTP URI, it MUST be escape coded. The element 2067 can optionally contain a list of elements. Each one 2068 is a suggested alternate value which does not currently exist on 2069 the server. 2071 : This indicates that the requested operation 2072 would result in a document that failed a data constraint defined 2073 by the application usage, but not enforced by the schema or a 2074 uniqueness constraint. 2076 Extensions to XCAP can define additional error elements. 2078 As an example, the following document indicates that the user 2079 attempted to create an RLS service using the URI 2080 sip:friends@example.com, but that URI already exists: 2082 2083 2084 2085 2086 sip:mybuddies@example.com 2087 2088 2089 2091 11.2 XML Schema 2093 2094 2099 2100 2101 2102 Indicates the reason for the error. 2103 2104 2105 2106 2107 2108 2109 2110 2112 2113 This element indicates 2114 that the document was not compliant to the schema after the requested 2115 operation was performed. 2116 2117 2118 2119 2120 2121 2122 2123 This indicates that the request was supposed to 2124 contain a valid XML fragment body, but did not. 2125 2126 2127 2128 2129 2130 2131 2132 This indicates that an attempt to insert 2133 an element, attribute or document failed because the document or 2134 element into which the insertion was 2135 supposed to occur does not exist 2136 2137 2138 2139 2140 2141 Contains an HTTP URI that points to the 2142 element which is the closest ancestor that does exist. 2143 2144 2145 2146 2147 2148 2149 2150 2151 This indicates that the requested 2152 PUT operation could not be performed because a GET of that resource 2153 after the PUT would not yield the content of the PUT request. 2154 2155 2156 2157 2158 2159 2160 2161 2162 This indicates that the 2163 request was supposed to contain a valid XML attribute value, but did 2164 not. 2165 2166 2167 2168 2169 2170 2171 2172 This indicates that the 2173 requested operation would result in a document that did not meet a 2174 uniqueness constraint defined by the application usage. 2175 2176 2177 2178 2179 2180 For each URI, 2181 element or attribute specified by the client which is not unique, 2182 one of these is present. 2183 2184 2185 2186 2187 2188 An optional set of alternate values can be 2189 provided. 2190 2191 2192 2193 2194 2195 2196 2197 2199 2200 2201 2202 2203 This indicates that the body of the request was 2204 not a well-formed document. 2205 2206 2207 2208 2209 2210 2211 2212 This indicates that the 2213 requested operation would result in a document that failed a data 2214 constraint defined by the application usage, but not enforced by the 2215 schema or a uniqueness constraint. 2216 2217 2218 2219 2220 2221 2222 2223 This indicates that the requested DELETE 2224 operation could not be performed because it would not be 2225 idempotent. 2226 2227 2228 2229 2230 2231 2232 2233 This indicates that request could not be completed because it would have produced a document not encoded in UTF-8. 2234 2235 2236 2237 2238 2239 2241 12. XCAP Server Capabilities 2243 XCAP can be extended through the addition of new application usages 2244 and extensions to the core protocol. An XCAP server can also be 2245 extended to support new namespaces. It will often be necessary for a 2246 client to determine what extensions, application usages or namespaces 2247 a server supports before making a request. To enable that, this 2248 specification defines an application usage with the AUID "xcap-caps". 2249 All XCAP servers MUST support this application usage. This usage 2250 defines a single document within the global tree which lists the 2251 capabilities of the server. Clients can read this well-known 2252 document, and therefore learn the capabilities of the server. 2254 The structure of the document is simple. The root element is . Its children are , , and . 2256 Each of these contain a list of AUIDs, extensions and namespaces 2257 supported by the server. Extensions are named by tokens defined by 2258 the extension, and typically define new selectors. Namespaces are 2259 identified by their namespace URI. Since all XCAP servers support 2260 the "xcap-caps" AUID, it MUST be listed in the element. 2262 The following sections provide the information needed to define this 2263 application usage. 2265 12.1 Application Unique ID (AUID) 2267 This specification defines the "xcap-caps" AUID within the IETF tree, 2268 via the IANA registration in Section 15. 2270 12.2 XML Schema 2272 2273 2278 2279 2280 Root element for xcap-caps 2281 2282 2283 2284 2285 2286 List of supported AUID. 2287 2288 2289 2290 2291 2293 2294 2295 2296 2297 List of supported extensions. 2298 2299 2300 2301 2302 2303 2304 2305 2306 2307 List of supported namespaces. 2308 2309 2310 2311 2312 2313 2314 2315 2316 2317 2318 2319 2320 2321 AUID Type 2322 2323 2324 2325 2326 2327 Extension Type 2328 2329 2330 2331 2332 2333 Namespace type 2334 2335 2336 2337 2339 12.3 Default Namespace 2341 The default namespace used in evaluating a URI is 2342 urn:ietf:params:xml:ns:xcap-caps. 2344 12.4 MIME Type 2346 Documents conformant to this schema are known by the MIME type 2347 "application/xcap-caps+xml", registered in Section 15.2.5. 2349 12.5 Validation Constraints 2351 There are no additional validation constraints associated with this 2352 application usage. 2354 12.6 Data Semantics 2356 Data semantics are defined above. 2358 12.7 Naming Conventions 2360 A server MUST maintain a single instance of the document in the 2361 global tree, using the filename "index". There MUST NOT be an 2362 instance of this document in the users tree. 2364 12.8 Resource Interdependencies 2366 There are no resource interdependencies in this application usage 2367 beyond those defined by the schema. 2369 12.9 Authorization Policies 2371 This application usage does not change the default authorization 2372 policy defined by XCAP. 2374 13. Examples 2376 This section goes through several examples, making use of the 2377 resource-lists and rls-services [22] XCAP application usages. 2379 First, a user Bill creates a new document (see Section 7.1). This 2380 document is a new resource-list, initially with a single list, called 2381 friends, with no users in it: 2383 PUT 2384 /services/resource-lists/users/bill/fr.xml HTTP/1.1 2385 Content-Type:application/resource-lists+xml 2386 Host: xcap.example.com 2388 2389 2390 2391 2392 2394 Next, Bill creates an RLS services document defining a single RLS 2395 service referencing this list. This service has a URI of 2396 sip:myfriends@example.com (URIs are line-folded for readability): 2398 PUT 2399 /services/rls-services/users/bill/index HTTP/1.1 2400 Content-Type:application/rls-services+xml 2401 Host: xcap.example.com 2403 2404 2405 2406 http://xcap.example.com/services/resource-lists/users/bill/ 2407 fr.xml/~~/resource-lists/list%5b@name=%22friends%22%5d 2408 2409 2410 presence 2411 2412 2413 2415 Next, Bill creates an element in the resource-lists document 2416 (Section 7.4). In particular, he adds an entry to the list: 2418 PUT 2419 /services/resource-lists/users/bill/fr.xml 2420 /~~/resource-lists/list%5b@name=%22friends%22%5d/entry HTTP/1.1 2421 Content-Type:application/xcap-el+xml 2422 Host: xcap.example.com 2424 2425 Bob Jones 2426 2428 Next, Bill fetches the document (Section 7.3): 2430 GET 2431 /services/resource-lists/users/bill/fr.xml HTTP/1.1 2433 And the result is: 2435 HTTP/1.1 200 OK 2436 Etag: "wwhha" 2437 Content-Type: application/resource-lists+xml 2439 2440 2441 2442 2443 Bob Jones 2444 2445 2446 2448 Next, Bill adds another entry to the list, which is another list that 2449 has three entries. This is another element creation (Section 7.4): 2451 PUT 2452 /services/resource-lists/users/bill/fr.xml/~~/ 2453 resource-lists/list%5b@name=%22friends%22%5d/ 2454 list%5b@name=%22close-friends%22%5d HTTP/1.1 2455 Content-Type: application/xcap-el+xml 2456 Host: xcap.example.com 2458 2459 2460 Joe Smith 2461 2462 2463 Nancy Gross 2464 2465 2466 Petri Aukia 2467 2468 2470 Then, Bill decides he doesn't want Petri on the list, so he deletes 2471 the entry (Section 7.5): 2473 DELETE 2474 /services/resource-lists/users/bill/fr.xml/ 2475 ~~/resource-lists/list/list/ 2476 entry%5b@uri=%22sip:petri@example.com%22%5d HTTP/1.1 2477 Host: xcap.example.com 2479 Bill decides to check on the URI for Nancy, so he fetches a 2480 particular attribute (Section 7.6): 2482 GET 2483 /services/resource-lists/users/bill/fr.xml/ 2484 ~~/resource-lists/list/list/entry%5b2%5d/@uri HTTP/1.1 2485 Host: xcap.example.com 2487 and the server responds: 2489 HTTP/1.1 200 OK 2490 Etag: "ad88" 2491 Content-Type:application/xcap-att+xml 2493 "sip:nancy@example.com" 2495 14. Security Considerations 2497 Frequently, the data manipulated by XCAP contains sensitive 2498 information. To avoid eavesdroppers from seeing this information, it 2499 is RECOMMENDED that an admistrator hand out an https URI as the XCAP 2500 root URI. This will result in TLS-encrypted communications between 2501 the client and server, preventing any eavesdropping. 2503 Client and server authentication are also important. A client needs 2504 to be sure it is talking to the server it believes it is contacting. 2505 Otherwise, it may be given false information, which can lead to 2506 denial of service attacks against a client. To prevent this, a 2507 client SHOULD attempt to upgrade [16] any connections to TLS. 2508 Similarly, authorization of read and write operations against the 2509 data is important, and this requires client authentication. As a 2510 result, a server SHOULD challenge a client using HTTP Digest [12] to 2511 establish its identity, and this SHOULD be done over a TLS 2512 connection. 2514 Because XCAP is a usage of HTTP and not a separate protocol, it runs 2515 on the same port numbers as HTTP traffic normally does. This makes 2516 it difficult to apply port-based filtering rules in firewalls to 2517 separate the treatment of XCAP traffic from other HTTP traffic. 2519 However, this problem exists broadly today because HTTP is used to 2520 access a wide breadth of content, all on the same port, and XCAP 2521 views application configuration documents as just another type of 2522 HTTP content. As such, separate treatment of XCAP traffic from other 2523 HTTP traffic requires firewalls to examine the URL itself. There is 2524 no foolproof way to identify a URL as pointing to an XCAP resource. 2525 However, the presence of the double tilde (~~) is a strong hint that 2526 the URL points to an XML element or attribute. As always, care must 2527 be taken in looking for the double-tilde due to the breadth of ways 2528 in which a URI can be encoded on-the-wire [30] [14]. 2530 15. IANA Considerations 2532 There are several IANA considerations associated with this 2533 specification. 2535 15.1 XCAP Application Unique IDs 2537 This specification instructs IANA to create a new registry for XCAP 2538 application unique IDs (AUIDs). This registry is defined as a table 2539 that contains three colums: 2541 AUID: This will be a string provided in the IANA registrations into 2542 the registry. 2544 Description: This is text that is supplied by the IANA registration 2545 into the registry. 2547 Document: This is a reference to the RFC containing the registration. 2549 This specification instructs IANA to create this table with an 2550 initial entry. The resulting table would look like: 2552 Application Unique Description Document 2553 ID (AUID) 2554 ----------------------------------------------------------- 2556 xcap-caps Capabilities of an RFC XXXX 2557 XCAP server 2559 [[NOTE TO IANA/RFC-EDITOR: Please replace XXXX with the RFC number of 2560 this specification.]] 2562 XCAP AUIDs are registered by the IANA when they are published in 2563 standards track RFCs. The IANA Considerations section of the RFC 2564 must include the following information, which appears in the IANA 2565 registry along with the RFC number of the publication. 2567 Name of the AUID. The name MAY be of any length, but SHOULD be no 2568 more than twenty characters long. The name MUST consist of 2569 alphanum and mark [17] characters only. 2571 Descriptive text that describes the application usage. 2573 15.2 MIME Types 2575 This specification requests the registration of several new MIME 2576 types according to the procedures of RFC 2048 [9] and guidelines in 2577 RFC 3023 [10]. 2579 15.2.1 application/xcap-el+xml MIME Type 2581 MIME media type name: application 2583 MIME subtype name: xcap-el+xml 2585 Mandatory parameters: none 2587 Optional parameters: Same as charset parameter application/xml as 2588 specified in RFC 3023 [10]. 2590 Encoding considerations: Same as encoding considerations of 2591 application/xml as specified in RFC 3023 [10]. 2593 Security considerations: See Section 10 of RFC 3023 [10]. 2595 Interoperability considerations: none. 2597 Published specification: RFC XXXX [[NOTE TO RFC EDITOR: Please 2598 replace XXXX with the published RFC number of this 2599 specification.]]. 2601 Applications which use this media type: This document type has been 2602 used to support transport of XML fragment bodies in RFC XXXX 2603 [[NOTE TO RFC EDITOR: Please replace XXXX with the published RFC 2604 number of this specification.]], the XML Configuration Access 2605 Protocol (XCAP). 2607 Additional Information: 2609 Magic Number: None 2610 File Extension: .xel 2612 Macintosh file type code: "TEXT" 2614 Personal and email address for further information: Jonathan 2615 Rosenberg, jdrosen@jdrosen.net 2617 Intended usage: COMMON 2619 Author/Change controller: The IETF. 2621 15.2.2 application/xcap-att+xml MIME Type 2623 MIME media type name: application 2625 MIME subtype name: xcap-att+xml 2627 Mandatory parameters: none 2629 Optional parameters: Same as charset parameter application/xml as 2630 specified in RFC 3023 [10]. 2632 Encoding considerations: Same as encoding considerations of 2633 application/xml as specified in RFC 3023 [10]. 2635 Security considerations: See Section 10 of RFC 3023 [10]. 2637 Interoperability considerations: none. 2639 Published specification: RFC XXXX [[NOTE TO RFC EDITOR: Please 2640 replace XXXX with the published RFC number of this 2641 specification.]]. 2643 Applications which use this media type: This document type has been 2644 used to support transport of XML attribute values in RFC XXXX 2645 [[NOTE TO RFC EDITOR: Please replace XXXX with the published RFC 2646 number of this specification.]], the XML Configuration Access 2647 Protocol (XCAP). 2649 Additional Information: 2651 Magic Number: None 2653 File Extension: .xav 2654 Macintosh file type code: "TEXT" 2656 Personal and email address for further information: Jonathan 2657 Rosenberg, jdrosen@jdrosen.net 2659 Intended usage: COMMON 2661 Author/Change controller: The IETF. 2663 15.2.3 application/xcap-ns+xml MIME Type 2665 MIME media type name: application 2667 MIME subtype name: xcap-ns+xml 2669 Mandatory parameters: none 2671 Optional parameters: Same as charset parameter application/xml as 2672 specified in RFC 3023 [10]. 2674 Encoding considerations: Same as encoding considerations of 2675 application/xml as specified in RFC 3023 [10]. 2677 Security considerations: See Section 10 of RFC 3023 [10]. 2679 Interoperability considerations: none. 2681 Published specification: RFC XXXX [[NOTE TO RFC EDITOR: Please 2682 replace XXXX with the published RFC number of this 2683 specification.]]. 2685 Applications which use this media type: This document type has been 2686 used to support transport of XML fragment bodies in RFC XXXX 2687 [[NOTE TO RFC EDITOR: Please replace XXXX with the published RFC 2688 number of this specification.]], the XML Configuration Access 2689 Protocol (XCAP). 2691 Additional Information: 2693 Magic Number: None 2695 File Extension: .xns 2697 Macintosh file type code: "TEXT" 2698 Personal and email address for further information: Jonathan 2699 Rosenberg, jdrosen@jdrosen.net 2701 Intended usage: COMMON 2703 Author/Change controller: The IETF. 2705 15.2.4 application/xcap-error+xml MIME Type 2707 MIME media type name: application 2709 MIME subtype name: xcap-error+xml 2711 Mandatory parameters: none 2713 Optional parameters: Same as charset parameter application/xml as 2714 specified in RFC 3023 [10]. 2716 Encoding considerations: Same as encoding considerations of 2717 application/xml as specified in RFC 3023 [10]. 2719 Security considerations: See Section 10 of RFC 3023 [10]. 2721 Interoperability considerations: none. 2723 Published specification: RFC XXXX [[NOTE TO RFC EDITOR: Please 2724 replace XXXX with the published RFC number of this 2725 specification.]]. 2727 Applications which use this media type: This document type conveys 2728 error conditions defined in RFC XXXX. [[NOTE TO RFC EDITOR: 2729 Please replace XXXX with the published RFC number of this 2730 specification.]] 2732 Additional Information: 2734 Magic Number: None 2736 File Extension: .xer 2738 Macintosh file type code: "TEXT" 2740 Personal and email address for further information: Jonathan 2741 Rosenberg, jdrosen@jdrosen.net 2743 Intended usage: COMMON 2745 Author/Change controller: The IETF. 2747 15.2.5 application/xcap-caps+xml MIME Type 2749 MIME media type name: application 2751 MIME subtype name: xcap-caps+xml 2753 Mandatory parameters: none 2755 Optional parameters: Same as charset parameter application/xml as 2756 specified in RFC 3023 [10]. 2758 Encoding considerations: Same as encoding considerations of 2759 application/xml as specified in RFC 3023 [10]. 2761 Security considerations: See Section 10 of RFC 3023 [10]. 2763 Interoperability considerations: none. 2765 Published specification: RFC XXXX [[NOTE TO RFC EDITOR: Please 2766 replace XXXX with the published RFC number of this 2767 specification.]]. 2769 Applications which use this media type: This document type conveys 2770 capabililites of an XML Configuration Access Protocol (XCAP) 2771 server, as defined in RFC XXXX. [[NOTE TO RFC EDITOR: Please 2772 replace XXXX with the published RFC number of this 2773 specification.]] 2775 Additional Information: 2777 Magic Number: None 2779 File Extension: .xca 2781 Macintosh file type code: "TEXT" 2783 Personal and email address for further information: Jonathan 2784 Rosenberg, jdrosen@jdrosen.net 2786 Intended usage: COMMON 2787 Author/Change controller: The IETF. 2789 15.3 URN Sub-Namespace Registrations 2791 This specification registers several new XML namespaces, as per the 2792 guidelines in RFC 3688 [18]. 2794 15.3.1 urn:ietf:params:xml:ns:xcap-error 2796 URI: The URI for this namespace is urn:ietf:params:xml:ns:xcap-error 2798 Registrant Contact: IETF, SIMPLE working group, (simple@ietf.org), 2799 Jonathan Rosenberg (jdrosen@jdrosen.net). 2801 XML: 2803 BEGIN 2804 2805 2807 2808 2809 2811 XCAP Error Namespace 2812 2813 2814

Namespace for XCAP Error Documents

2815

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

2816

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

2819 2820 2821 END 2823 15.3.2 urn:ietf:params:xml:ns:xcap-caps 2825 URI: The URI for this namespace is urn:ietf:params:xml:ns:xcap-caps 2827 Registrant Contact: IETF, SIMPLE working group, (simple@ietf.org), 2828 Jonathan Rosenberg (jdrosen@jdrosen.net). 2830 XML: 2832 BEGIN 2833 2834 2836 2837 2838 2840 XCAP Capabilities Namespace 2841 2842 2843

Namespace for XCAP Capability Documents

2844

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

2845

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

2848 2849 2850 END 2852 15.4 XML Schema Registrations 2854 This section registers two XML schemas per the procedures in [18]. 2856 15.4.1 XCAP Error Schema Registration 2858 URI: urn:ietf:params:xml:schema:xcap-error 2860 Registrant Contact: IETF, SIMPLE working group, (simple@ietf.org), 2861 Jonathan Rosenberg (jdrosen@jdrosen.net). 2863 XML Schema: The XML for this schema can be found as the sole content 2864 of Section 11.2. 2866 15.4.2 XCAP Capabilities Schema Registration 2868 URI: urn:ietf:params:xml:schema:xcap-caps 2870 Registrant Contact: IETF, SIMPLE working group, (simple@ietf.org), 2871 Jonathan Rosenberg (jdrosen@jdrosen.net). 2873 XML Schema: The XML for this schema can be found as the sole content 2874 of Section 12.2. 2876 16. Acknowledgements 2878 The author would like to thank Ben Campbell, Eva-Maria Leppanen, 2879 Hisham Khartabil, Chris Newman, Joel Halpern, Jari Urpalainen, Lisa 2880 Dusseault, Tim Bray, Pete Cordell and Spencer Dawkins for their input 2881 and comments. A special thanks to Ted Hardie for his input and 2882 support. 2884 17. References 2886 17.1 Normative References 2888 [1] Yergeau, F., Bray, T., Paoli, J., Sperberg-McQueen, C., and E. 2889 Maler, "Extensible Markup Language (XML) 1.0 (Third Edition)", 2890 W3C REC REC-xml-20040204, February 2004. 2892 [2] Maloney, M., Beech, D., Mendelsohn, N., and H. Thompson, "XML 2893 Schema Part 1: Structures", W3C REC REC-xmlschema-1-20010502, 2894 May 2001. 2896 [3] Bray, T., Hollander, D., and A. Layman, "Namespaces in XML", 2897 W3C REC REC-xml-names-19990114, January 1999. 2899 [4] DeRose, S., Daniel, R., Maler, E., and J. Marsh, "XPointer 2900 xmlns() Scheme", W3C REC REC-xptr-xmlns-20030325, March 2003. 2902 [5] Grosso, P., Maler, E., Marsh, J., and N. Walsh, "XPointer 2903 Framework", W3C REC REC-xptr-framework-20030325, March 2003. 2905 [6] Rosenberg, J., "An Extensible Markup Language (XML) Document 2906 Format for Indicating Changes in XML Configuration Access 2907 Protocol (XCAP) Resources", draft-ietf-simple-xcap-diff-01 2908 (work in progress), July 2005. 2910 [7] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., 2911 Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- 2912 HTTP/1.1", RFC 2616, June 1999. 2914 [8] Bradner, S., "Key words for use in RFCs to Indicate Requirement 2915 Levels", BCP 14, RFC 2119, March 1997. 2917 [9] Freed, N., Klensin, J., and J. Postel, "Multipurpose Internet 2918 Mail Extensions (MIME) Part Four: Registration Procedures", 2919 BCP 13, RFC 2048, November 1996. 2921 [10] Murata, M., St. Laurent, S., and D. Kohn, "XML Media Types", 2922 RFC 3023, January 2001. 2924 [11] Clark, J. and S. DeRose, "XML Path Language (XPath) Version 2925 1.0", W3C REC REC-xpath-19991116, November 1999. 2927 [12] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 2928 Leach, P., Luotonen, A., and L. Stewart, "HTTP Authentication: 2929 Basic and Digest Access Authentication", RFC 2617, June 1999. 2931 [13] Crocker, D. and P. Overell, "Augmented BNF for Syntax 2932 Specifications: ABNF", RFC 2234, November 1997. 2934 [14] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2935 Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, 2936 January 2005. 2938 [15] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 2940 [16] Khare, R. and S. Lawrence, "Upgrading to TLS Within HTTP/1.1", 2941 RFC 2817, May 2000. 2943 [17] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A., 2944 Peterson, J., Sparks, R., Handley, M., and E. Schooler, "SIP: 2945 Session Initiation Protocol", RFC 3261, June 2002. 2947 [18] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2948 January 2004. 2950 [19] Yergeau, F., "UTF-8, a transformation format of ISO 10646", 2951 STD 63, RFC 3629, November 2003. 2953 17.2 Informative References 2955 [20] Rosenberg, J., "A Presence Event Package for the Session 2956 Initiation Protocol (SIP)", RFC 3856, August 2004. 2958 [21] Roach, A., Rosenberg, J., and B. Campbell, "A Session 2959 Initiation Protocol (SIP) Event Notification Extension for 2960 Resource Lists", draft-ietf-simple-event-list-07 (work in 2961 progress), January 2005. 2963 [22] Rosenberg, J., "Extensible Markup Language (XML) Formats for 2964 Representing Resource Lists", 2965 draft-ietf-simple-xcap-list-usage-05 (work in progress), 2966 February 2005. 2968 [23] Peterson, J., "Common Profile for Presence (CPP)", RFC 3859, 2969 August 2004. 2971 [24] Grosso, P. and D. Veillard, "XML Fragment Interchange", W3C 2972 CR CR-xml-fragment-20010212, February 2001. 2974 [25] Berglund, A., Chamberlin, D., Boag, S., FernA!ndez, M., Kay, 2975 M., Robie, J., and J. SimA(C)on, "XML Path Language (XPath) 2976 2.0", W3C WD WD-xpath20-20041029, October 2004. 2978 [26] Newman, C. and J. Myers, "ACAP -- Application Configuration 2979 Access Protocol", RFC 2244, November 1997. 2981 [27] Day, M., Rosenberg, J., and H. Sugano, "A Model for Presence 2982 and Instant Messaging", RFC 2778, February 2000. 2984 [28] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA 2985 Considerations Section in RFCs", BCP 26, RFC 2434, 2986 October 1998. 2988 [29] Roach, A., "Session Initiation Protocol (SIP)-Specific Event 2989 Notification", RFC 3265, June 2002. 2991 [30] Duerst, M. and M. Suignard, "Internationalized Resource 2992 Identifiers (IRIs)", RFC 3987, January 2005. 2994 Author's Address 2996 Jonathan Rosenberg 2997 Cisco Systems 2998 600 Lanidex Plaza 2999 Parsippany, NJ 07054 3000 US 3002 Phone: +1 973 952-5000 3003 Email: jdrosen@cisco.com 3004 URI: http://www.jdrosen.net 3006 Intellectual Property Statement 3008 The IETF takes no position regarding the validity or scope of any 3009 Intellectual Property Rights or other rights that might be claimed to 3010 pertain to the implementation or use of the technology described in 3011 this document or the extent to which any license under such rights 3012 might or might not be available; nor does it represent that it has 3013 made any independent effort to identify any such rights. Information 3014 on the procedures with respect to rights in RFC documents can be 3015 found in BCP 78 and BCP 79. 3017 Copies of IPR disclosures made to the IETF Secretariat and any 3018 assurances of licenses to be made available, or the result of an 3019 attempt made to obtain a general license or permission for the use of 3020 such proprietary rights by implementers or users of this 3021 specification can be obtained from the IETF on-line IPR repository at 3022 http://www.ietf.org/ipr. 3024 The IETF invites any interested party to bring to its attention any 3025 copyrights, patents or patent applications, or other proprietary 3026 rights that may cover technology that may be required to implement 3027 this standard. Please address the information to the IETF at 3028 ietf-ipr@ietf.org. 3030 Disclaimer of Validity 3032 This document and the information contained herein are provided on an 3033 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 3034 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 3035 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 3036 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 3037 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 3038 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 3040 Copyright Statement 3042 Copyright (C) The Internet Society (2005). This document is subject 3043 to the rights, licenses and restrictions contained in BCP 78, and 3044 except as set forth therein, the authors retain all their rights. 3046 Acknowledgment 3048 Funding for the RFC Editor function is currently provided by the 3049 Internet Society.