idnits 2.17.1 draft-ietf-simple-xcap-03.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 3667, Section 5.1 on line 14. -- Found old boilerplate from RFC 3978, Section 5.5 on line 2342. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 2319. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 2326. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 2332. ** Found boilerplate matching RFC 3978, Section 5.4, paragraph 1 (on line 2348), which is fine, but *also* found old RFC 2026, Section 10.4C, paragraph 1 text on line 36. ** The document seems to lack an RFC 3978 Section 5.1 IPR Disclosure Acknowledgement -- however, there's a paragraph with a matching beginning. Boilerplate error? ** 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. ** The document uses RFC 3667 boilerplate or RFC 3978-like boilerplate instead of verbatim RFC 3978 boilerplate. After 6 May 2005, submission of drafts without verbatim RFC 3978 boilerplate is not accepted. The following non-3978 patterns matched text found in the document. That text should be removed or replaced: By submitting this Internet-Draft, I certify that any applicable patent or other IPR claims of which I am aware have been disclosed, or will be disclosed, and any of which I become aware will be disclosed, in accordance with RFC 3668. 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 24 instances of too long lines in the document, the longest one being 61 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 == 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: If the creation or insertion was successful, and the resource interdependcies are resolved, the server returns a 200 OK or 201 Created, as appropriate. This response 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 (July 16, 2004) is 7222 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: '19' is defined on line 2257, but no explicit reference was found in the text == Unused Reference: '20' is defined on line 2262, 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' ** Obsolete normative reference: RFC 2616 (ref. '5') (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 2048 (ref. '7') (Obsoleted by RFC 4288, RFC 4289) ** Obsolete normative reference: RFC 3023 (ref. '8') (Obsoleted by RFC 7303) -- Possible downref: Non-RFC (?) normative reference: ref. '9' ** Obsolete normative reference: RFC 2617 (ref. '10') (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) ** Obsolete normative reference: RFC 2234 (ref. '11') (Obsoleted by RFC 4234) ** Obsolete normative reference: RFC 2396 (ref. '12') (Obsoleted by RFC 3986) ** Obsolete normative reference: RFC 2818 (ref. '13') (Obsoleted by RFC 9110) == Outdated reference: A later version (-07) exists of draft-ietf-simple-event-list-04 == Outdated reference: A later version (-05) exists of draft-ietf-simple-xcap-list-usage-02 -- Obsolete informational reference (is this intentional?): RFC 2434 (ref. '27') (Obsoleted by RFC 5226) -- Obsolete informational reference (is this intentional?): RFC 3265 (ref. '28') (Obsoleted by RFC 6665) Summary: 14 errors (**), 0 flaws (~~), 8 warnings (==), 15 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 SIMPLE J. Rosenberg 2 Internet-Draft dynamicsoft 3 Expires: January 14, 2005 July 16, 2004 5 The Extensible Markup Language (XML) Configuration Access Protocol 6 (XCAP) 7 draft-ietf-simple-xcap-03 9 Status of this Memo 11 By submitting this Internet-Draft, I certify that any applicable 12 patent or other IPR claims of which I am aware have been disclosed, 13 and any of which I become aware will be disclosed, in accordance with 14 RFC 3668. 16 Internet-Drafts are working documents of the Internet Engineering 17 Task Force (IETF), its areas, and its working groups. Note that 18 other groups may also distribute working documents as 19 Internet-Drafts. 21 Internet-Drafts are draft documents valid for a maximum of six months 22 and may be updated, replaced, or obsoleted by other documents at any 23 time. It is inappropriate to use Internet-Drafts as reference 24 material or to cite them other than as "work in progress." 26 The list of current Internet-Drafts can be accessed at 27 http://www.ietf.org/ietf/1id-abstracts.txt. 29 The list of Internet-Draft Shadow Directories can be accessed at 30 http://www.ietf.org/shadow.html. 32 This Internet-Draft will expire on January 14, 2005. 34 Copyright Notice 36 Copyright (C) The Internet Society (2004). All Rights Reserved. 38 Abstract 40 This specification defines the Extensible Markup Language (XML) 41 Configuration Access Protocol (XCAP). XCAP allows a client to read, 42 write and modify application configuration data, stored in XML format 43 on a server. XCAP maps XML document sub-trees and element attributes 44 to HTTP URIs, so that these components can be directly accessed by 45 HTTP. 47 Table of Contents 49 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 50 2. Overview of Operation . . . . . . . . . . . . . . . . . . . 5 51 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . 6 52 4. Definitions . . . . . . . . . . . . . . . . . . . . . . . . 7 53 5. Application Usages . . . . . . . . . . . . . . . . . . . . . 9 54 5.1 Application Usage ID (AUID) . . . . . . . . . . . . . . . 9 55 5.2 Data Validation . . . . . . . . . . . . . . . . . . . . . 9 56 5.3 Data Semantics . . . . . . . . . . . . . . . . . . . . . . 11 57 5.4 Naming Conventions . . . . . . . . . . . . . . . . . . . . 11 58 5.5 Resource Interdependencies . . . . . . . . . . . . . . . . 11 59 5.6 Authorization Policies . . . . . . . . . . . . . . . . . . 12 60 5.7 Data Extensibility . . . . . . . . . . . . . . . . . . . . 12 61 5.8 Documenting Application Usages . . . . . . . . . . . . . . 13 62 5.9 Guidelines for Creating Application Usages . . . . . . . . 13 63 6. URI Construction . . . . . . . . . . . . . . . . . . . . . . 16 64 6.1 XCAP Root . . . . . . . . . . . . . . . . . . . . . . . . 16 65 6.2 Document Selector . . . . . . . . . . . . . . . . . . . . 16 66 6.3 Node Selector . . . . . . . . . . . . . . . . . . . . . . 18 67 7. Client Operations . . . . . . . . . . . . . . . . . . . . . 22 68 7.1 Create or Replace a Document . . . . . . . . . . . . . . . 23 69 7.2 Delete a Document . . . . . . . . . . . . . . . . . . . . 23 70 7.3 Fetch a Document . . . . . . . . . . . . . . . . . . . . . 23 71 7.4 Create or Replace an Element . . . . . . . . . . . . . . . 23 72 7.5 Delete an Element . . . . . . . . . . . . . . . . . . . . 25 73 7.6 Fetch an Element . . . . . . . . . . . . . . . . . . . . . 26 74 7.7 Create or Replace an Attribute . . . . . . . . . . . . . . 26 75 7.8 Delete an Attribute . . . . . . . . . . . . . . . . . . . 27 76 7.9 Fetch an Attribute . . . . . . . . . . . . . . . . . . . . 27 77 7.10 Conditional Operations . . . . . . . . . . . . . . . . . 27 78 8. Server Behavior . . . . . . . . . . . . . . . . . . . . . . 29 79 8.1 POST Handling . . . . . . . . . . . . . . . . . . . . . . 29 80 8.2 PUT Handling . . . . . . . . . . . . . . . . . . . . . . . 29 81 8.2.1 Locating the Parent . . . . . . . . . . . . . . . . . 30 82 8.2.2 Verifying Document Content . . . . . . . . . . . . . . 30 83 8.2.3 Creation . . . . . . . . . . . . . . . . . . . . . . . 31 84 8.2.4 Replacement . . . . . . . . . . . . . . . . . . . . . 32 85 8.2.5 Validation . . . . . . . . . . . . . . . . . . . . . . 33 86 8.2.6 Resource Interdependencies . . . . . . . . . . . . . . 33 87 8.3 GET Handling . . . . . . . . . . . . . . . . . . . . . . . 34 88 8.4 DELETE Handling . . . . . . . . . . . . . . . . . . . . . 34 89 8.5 Managing Etags . . . . . . . . . . . . . . . . . . . . . . 35 90 9. Detailed Conflict Reports . . . . . . . . . . . . . . . . . 36 91 9.1 Document Structure . . . . . . . . . . . . . . . . . . . . 36 92 9.2 XML Schema . . . . . . . . . . . . . . . . . . . . . . . . 37 93 10. XCAP Server Capabilities . . . . . . . . . . . . . . . . . . 41 94 10.1 Application Usage ID (AUID) . . . . . . . . . . . . . . 41 95 10.2 XML Schema . . . . . . . . . . . . . . . . . . . . . . . 41 96 10.3 MIME Type . . . . . . . . . . . . . . . . . . . . . . . 43 97 10.4 Validation Constraints . . . . . . . . . . . . . . . . . 43 98 10.5 Data Semantics . . . . . . . . . . . . . . . . . . . . . 43 99 10.6 Naming Conventions . . . . . . . . . . . . . . . . . . . 43 100 10.7 Resource Interdependencies . . . . . . . . . . . . . . . 43 101 10.8 Authorization Policies . . . . . . . . . . . . . . . . . 43 102 11. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 44 103 12. Security Considerations . . . . . . . . . . . . . . . . . . 47 104 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . 48 105 13.1 XCAP Application Usage IDs . . . . . . . . . . . . . . . 48 106 13.2 MIME Types . . . . . . . . . . . . . . . . . . . . . . . 48 107 13.2.1 application/xcap-el+xml MIME Type . . . . . . . . . 48 108 13.2.2 application/xcap-att+xml MIME Type . . . . . . . . . 49 109 13.2.3 application/xcap-error+xml MIME Type . . . . . . . . 50 110 13.2.4 application/xcap-caps+xml MIME Type . . . . . . . . 50 111 13.3 URN Sub-Namespace Registrations . . . . . . . . . . . . 51 112 13.3.1 urn:ietf:params:xml:ns:xcap-error . . . . . . . . . 51 113 13.3.2 urn:ietf:params:xml:ns:xcap-caps . . . . . . . . . . 51 114 13.4 XML Schema Registrations . . . . . . . . . . . . . . . . 52 115 13.4.1 XCAP Error Schema Registration . . . . . . . . . . . 52 116 13.4.2 XCAP Capabilities Schema Registration . . . . . . . 52 117 14. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 53 118 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 54 119 15.1 Normative References . . . . . . . . . . . . . . . . . . . 54 120 15.2 Informative References . . . . . . . . . . . . . . . . . . 55 121 Author's Address . . . . . . . . . . . . . . . . . . . . . . 56 122 Intellectual Property and Copyright Statements . . . . . . . 57 124 1. Introduction 126 In many communications applications, such as Voice over IP, instant 127 messaging, and presence, it is necessary for network servers to 128 access per-user information in the process of servicing a request. 129 This per-user information resides within the network, but is managed 130 by the end user themselves. Its management can be done through a 131 multiplicity of access points, including the web, a wireless handset, 132 or a PC application. 134 Examples of per-user information are presence [18] authorization 135 policy and presence lists. Presence lists are lists of users whose 136 presence is desired by a watcher [26]. One way to obtain presence 137 information for the list of is to subscribe to a resource which 138 represents that list [21]. In this case, the Resource List Server 139 (RLS) requires access to this list in order to process a SIP 140 [15]SUBSCRIBE [28] request for it. Another way to obtain presence 141 for the users on the list is for a watcher to subscribe to each user 142 individually. In that case, it is convenient to have a server store 143 the list, and when the client boots, it fetches the list from the 144 server. This would allow a user to access their resource lists from 145 different clients. 147 Requirements for manipulation of presence lists and authorization 148 policies have been specified by the SIMPLE working group [22]. 150 This specification describes a protocol that can be used to 151 manipulate this per-user data. It is called the Extensible Markup 152 Language (XML) Configuration Access Protocol (XCAP). XCAP is a set 153 of conventions for mapping XML documents and document components into 154 HTTP URIs, rules for how the modification of one resource affects 155 another, data validation constraints, and authorization policies 156 associated with access to those resources. Because of this 157 structure, normal HTTP primitives can be used to manipulate the data. 158 XCAP is based heavily on ideas borrowed from the Application 159 Configuration Access Protocol (ACAP) [25], but it is not an extension 160 of it, nor does it have any dependencies on it. Like ACAP, XCAP is 161 meant to support the configuration needs for a multiplicity of 162 applications, rather than just a single one. 164 2. Overview of Operation 166 Each application that makes use of XCAP specifies an application 167 usage (Section 5). This application usage defines the XML schema [2] 168 for the data used by the application, along with other key pieces of 169 information. The principal task of XCAP is to allow clients to read, 170 write, modify, create and delete pieces of that data. These 171 operations are supported using HTTP 1.1 [5]. An XCAP server acts as 172 a repository for collections of XML documents. There will be 173 documents stored for each application. Within each application, 174 there are documents stored for each user. Each user can have a 175 multiplicity of documents for a particular application. To access 176 some component of one of those documents, XCAP defines an algorithm 177 for constructing a URI that can be used to reference that component. 178 Components refer to any element or attribute within the document. 179 Thus, the HTTP URIs used by XCAP point a document, or to pieces of 180 information that are finer grained than the XML document itself. An 181 HTTP resource which follows the naming conventions and validation 182 constraints defined here is called an XCAP resource. 184 Since XCAP resources are also HTTP resources, they can be accessed 185 using HTTP methods. Reading an XCAP resource is accomplished with 186 HTTP GET, creating or modifying one is done with HTTP PUT, and 187 removing one of the resources is done with an HTTP DELETE. 188 Properties that HTTP associates with resources, such as entity tags, 189 also apply to XCAP resources. Indeed, entity tags are particularly 190 useful in XCAP, as they allow a number of conditional operations to 191 be performed. 193 3. Terminology 195 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 196 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 197 and "OPTIONAL" are to be interpreted as described in RFC 2119 [6] and 198 indicate requirement levels for compliant implementations. 200 4. Definitions 202 The following terms are used throughout this document: 203 XCAP Resource: An HTTP resource representing an XML document, an 204 element within an XML document, or an attribute of an element 205 within an XML document that follows the naming and validation 206 constraints of XCAP. 207 XCAP Server: An HTTP server that understands how to follow the naming 208 and validation constraints defined in this specification. 209 Application: A collection of software components within a network 210 whose operation depends on data managed and stored on an XCAP 211 server. 212 Application Usage: Detailed information on the interaction of an 213 application with the XCAP server. 214 Application Unique ID (AUID): A unique identifier that differentiates 215 XCAP resources accessed by one application from XCAP resources 216 accessed by another. 217 Naming Conventions: The part of an application usage that specifies 218 well-known URIs used by an application, or more generally, 219 specifies the URIs that are typically accessed by an application 220 during its processing. 221 XCAP User Identifier (XUI): The XUI is a string, valid as a path 222 element in an HTTP URI, that is associated with each user served 223 by the XCAP server. 224 XCAP Root: A context that contains all of the documents across all 225 application usages and users that are managed by the server. 226 Document Selector: A sequence of path segments, with each segment 227 being separated by a "/", that identify the XML document within an 228 XCAP root that is being selected. 229 Node Selector: A sequence of path segments, with each segment being 230 separated by a "/", that identify the XML node (element or 231 attribute) being selected within a document. 232 Path Separator: A single path segment equal to two tilde characters 233 (~~) that is used to separate the document selector from the node 234 selector within an HTTP URL. 235 Document URI: The HTTP URI containing the XCAP root and document 236 selector, resulting in the selection of a specific document. As a 237 result, performing a GET against the document URI would retrieve 238 the document. 239 Node URI: The HTTP URI containing the XCAP root, document selector, 240 path separator and node selector, resulting in the selection of a 241 specific XML node. 242 XCAP Root URI: An HTTP URI that representing the XCAP root. Although 243 a valid URI, the XCAP Root URI does not correspond to an actual 244 resource. 246 Global Tree: A URI that represents the parent for all global 247 documents for a particular application usage within a particular 248 XCAP root. 249 Home Directory: A URI that represents the parent for all documents 250 for a particular user for a particular application usage within a 251 particular XCAP root. 252 Positional Insertion: A PUT operation that results in the insertion 253 of a new element into a document such that its position relative 254 to other children of the same parent is set by the client. 256 5. Application Usages 258 Each XCAP resource on a server is associated with an application. In 259 order for an application to use those resources, application specific 260 conventions must be specified. Those conventions include the XML 261 schema that defines the structure and constraints of the data, well 262 known URIs to bootstrap access to the data, and so on. All of those 263 application specific conventions are defined by the application 264 usage. 266 5.1 Application Usage ID (AUID) 268 Each application usage is associated with a name, called an 269 Application Unique ID (AUID). This name uniquely identifies the 270 application usage, and is different from AUIDs used by other 271 applications. AUIDs exist in one of two namespaces. The first 272 namespace is the IETF namespace. This namespace contains a set of 273 tokens, each of which is registered with IANA. These registrations 274 occur with the publication of standards track RFCs [27] based on the 275 guidelines in Section 13. The second namespace is the 276 vendor-proprietary namespace. Each AUID in that namespace is 277 prefixed with the reverse domain name name of the organization 278 creating the AUID, followed by a period, followed by any vendor 279 defined token. As an example, the example.com domain can create an 280 AUID with the value "com.example.foo" but cannot create one with the 281 value "org.example.foo". AUIDs within the vendor namespace do not 282 need to be registered with IANA. The vendor namespace is also meant 283 to be used in lab environments where no central registry is needed. 284 The syntax for AUIDs, expressed in ABNF [11] (and using some of the 285 BNF defined in RFC 2396 [12]) is: 287 AUID = global-auid / vendor-auid 288 global-auid = auid 289 auid = alphanum / mark 290 vendor-auid = rev-hostname "." auid 291 rev-hostname = toplabel *( "." domainlabel ) 292 domainlabel = alphanum 293 / alphanum *( alphanum / "-" ) alphanum 294 toplabel = ALPHA / ALPHA *( alphanum / "-" ) alphanum 296 5.2 Data Validation 298 One of the responsibilities of an XCAP server is to validate the 299 content of each XCAP resource when an XCAP client tries to modify 300 one. This is done using two mechanisms. Firstly, all application 301 usages MUST describe their document contents using XML schema [2]. 303 The application usage MUST also identify the MIME type for documents 304 compliant to that schema. 306 Unfortunately, XML schemas cannot represent every form of data 307 constraint. As an example, one XML element may contain an integer 308 which defines the maximum number of instances of another element. 309 This constraint cannot be represented with XML schema. However, such 310 constraints may be important to the application usage. The 311 application usage defines any additional constraints beyond those in 312 the schema. 314 Of particular importance are uniqueness constraints. In many cases, 315 an application will require that there only be one instance of some 316 element or attribute within a particular scope. Each uniqueness 317 constraint needs to be specified by identifying the field, or 318 combinations of fields, that need to be unique, and then identifying 319 the scope in which that uniqueness applies. One typical scope is the 320 set of all elements of a certain name within the same parent. 321 Another typical scope is the set of all URIs valid within a 322 particular domain. In some cases these constraints can be specified 323 using XML schema, which provides the element for this 324 purpose. Other uniqueness constraints, such as URI uniqueness across 325 a domain, cannot be expressed by schema. Whether or not the schema 326 is used to express some of the uniqueness requirements, the 327 application usage MUST specify all uniqueness requirements when it 328 defines its data validation needs. 330 For example, the resource lists application usage [23] requires that 331 each element have a unique value for the "name" attribute 332 within a single parent. As another example, the RLS services 333 application usage [23] requires that the value of the "uri" attribute 334 of the element be a URI that is unique within the domain of 335 the URI. 337 Another form of constraint are URI constraints. These are 338 constraints on the scheme or structure of the scheme specific part of 339 the URI. These kinds of constraints cannot be expressed in an XML 340 schema. If these constraints are important to an application usage, 341 they need to be explicitly called out. As an example, the resource 342 lists application usage requires that the URI present in the "uri" 343 attribute of the element be either a SIP or pres URI [24]. 345 Another important data constraint is referential integrity. 346 Referential integrity is important when the name or value of an 347 element or attribute is used as a key to select another element or 348 attribute. An application usage MAY specify referential integrity 349 constraints. However, XCAP servers are not a replacement for 350 Relational Database Management Systems (RDBMS), and therefore servers 351 are never responsible for maintaining referential integrity. XCAP 352 clients are responsible for making all of the appropriate changes to 353 documents in order to maintain referential integrity. 355 The data validation information is consumed by both clients, which 356 use them to make sure they construct requests that will be accepted 357 by the server, and by servers, which validate the constraints when 358 they receive a request (with the exception of referential integrity 359 constraints, which are not validated by the server). 361 5.3 Data Semantics 363 For each application usage, the data present in the XML document has 364 a well defined semantic. The application usage defines that 365 semantic, so that a client can properly construct a document in order 366 to achieve the desired result. They are not used by the server, as 367 it is purposefully unaware of the semantics of the data it is 368 managing. The data semantics are expressed in English prose by the 369 application usage. 371 5.4 Naming Conventions 373 In addition to defining the meaning of the document in the context of 374 a particular application, an application usage has to specify how the 375 applications obtain the documents they need. In particular, it needs 376 to define any well-known URIs used for bootstrapping purposes, and 377 document any other conventions on the URIs used by an application. 378 It should also document how documents reference each other. These 379 conventions are called naming conventions. 381 As an example, the RLS services application usage allows an RLS to 382 obtain the contents of a resource list when the RLS receives a 383 SUBSCRIBE request for a SIP URI identifying an RLS service. The 384 application usage specifies that the list of service definitions is 385 present within a specific document with a specific name within the 386 global tree. This allows the RLS to perform a single XCAP request to 387 fetch the service definition for the service associated with the SIP 388 URI in a SUBSCRIBE request. 390 Naming conventions are used by XCAP clients to construct their URIs. 391 The XCAP server does not make use of them. 393 5.5 Resource Interdependencies 395 When a user modifies an XCAP resource, the content of many other 396 resources is affected. For example, when a user deletes an XML 397 element within a document, it does so by issuing a DELETE request 398 against the URI for the element resource. However, deleting this 399 element also deletes all child elements and their attributes, each of 400 which is also an XCAP resource. As such, manipulation of one 401 resource affects the state of other resources. 403 For the most part, these interdependencies are fully specified by the 404 XML schema used by the application usage. However, in some 405 application usages, there is a need for the server to relate 406 resources together, and such a relationship cannot be specified 407 through a schema. This occurs when changes in one document need to 408 affect another document. Typically, this is the case when an 409 application usage is defining a document that acts as a collection of 410 information defined in other documents. 412 As an example, when a user creates a new RLS service (that is, it 413 creates a new element within an RLS services document), the 414 server adds that element to a read-only global list of services 415 maintained by the server in the global tree. This read-only global 416 list is accessed by the RLS when processing a SIP SUBSCRIBE request. 418 Resource interdependencies are used by both XCAP clients and servers. 420 5.6 Authorization Policies 422 By default, each user is able to access (read, modify, and delete) 423 all of the documents below their home directory, and any user is able 424 to read documents within the global directory. However, only trusted 425 users, explicitly provisioned into the server, can modify global 426 documents. 428 The application usage can specify a different authorization policy 429 that applies to all documents associated with that application usage. 430 An application usage can also specify whether another application 431 usage is used to define the authorization policies. An application 432 usage for setting authorization policies can also be defined 433 subsequent to the definition of the the main application usage. In 434 such a case, the main application usage needs only to specify that 435 such a usage will be defined in the future. 437 If an application usage does not wish to change the default 438 authorization policy, it can merely state that the default policy is 439 used. 441 The authorization policies defined by the application usage are used 442 by the XCAP server during its operation. 444 5.7 Data Extensibility 446 An XCAP server MUST understand an application usage in order to 447 process an HTTP request made against a resource for that particular 448 application usage. However, it is not required for the server to 449 understand all of the contents of a document used by an application 450 usage. A server is required to understand the baseline schema 451 defined by the application usage. However, those schemas can define 452 points of extensibility where new content can be added from other 453 namespaces and corresponding schemas. Sometimes, the server will 454 understand those namespaces and therefore have access to their 455 schemas. Sometimes, it will not. 457 A server MUST allow for documents that contain elements from 458 namespaces not known to the server. In such a case, the server 459 cannot validate that such content is schema compliant; it will only 460 verify that the XML is well-formed. 462 If a client wants to verify that a server supports a particular 463 namespace before operating on a resource, it can query the server for 464 its capabilities using the XCAP Capabilities application usage, 465 discussed in Section 10. 467 5.8 Documenting Application Usages 469 Application usages are documented in specifications which convey the 470 information described above. In particular, an application usage 471 specification MUST provide the following information: 472 o Application Usage ID (AUID): If the application usage is meant for 473 general use on the Internet, the application usage MUST register 474 the AUID into the IETF tree using the IANA procedures defined in 475 Section 13. 476 o XML Schema 477 o MIME Type 478 o Validation Constraints 479 o Data Semantics 480 o Naming Conventions 481 o Resource Interdependencies 482 o Authorization Policies 484 5.9 Guidelines for Creating Application Usages 486 The primary design task when creating a new application usage is to 487 define the schema. Although XCAP can be used with any XML document, 488 intelligent schema design will improve the efficiency and utility of 489 the document when it is manipulated with XCAP. 491 XCAP provides three fundamental ways to select elements amongst a set 492 of siblings - by the name of the element, by its position, or by the 493 value of a specific attribute. Positional selection always allows a 494 client to get exactly what it wants. However, it requires a client 495 to cache a copy of the document in order to construct the predicate. 496 Furthermore, if a client performs a PUT, it requires the client to 497 reconstruct the PUT processing that a server would follow in order to 498 update its local cached copy. Otherwise, the client will be forced 499 to re-GET the document after every PUT, which is inefficient. As 500 such, it is a good idea to design schemas such that common operations 501 can be performed without requiring the client to cache a copy of the 502 document. 504 Without positional selection, a client can pick the element at each 505 step by its name or the value of an attribute. Many schemas include 506 elements that can be repeated within a parent (often, minOccurs 507 equals zero or one, and maxOccurs is unbounded). As such, all of the 508 elements have the same name. This leaves the attribute value as the 509 only way to select an element. Because of this, if an application 510 usage expects user to manipulate elements or attributes that are 511 descendants of an element which can repeat, that element SHOULD 512 include, in its schema, an attribute which can be suitably used as a 513 unique index. Furthermore, the naming conventions defined by that 514 application usage SHOULD specify this uniqueness constraint 515 explicitly. 517 URIs often make a good choice for such unique index. They have 518 fundamental uniqueness properties, and are also usually of semantic 519 significance in the application usage. However, care must be taken 520 when using a URI as an attribute value. URI equality is ususally 521 complex. However, attribute equality is performed by the server 522 using XML rules, which are based on case sensitive string comparison. 523 Thus, XCAP will match URIs based on lexical equality, not functional 524 equality. In such cases, an application usage SHOULD consider these 525 implications carefully. 527 XCAP provides the ability of a client to operate on a single element, 528 attribute or document at a time. As a result, it may be possible 529 that common operations the client might perform will require a 530 sequence of multiple requests. This is inefficient, and introduces 531 the possibility of failure conditions when another client modifies 532 the document in the middle of a sequence. In such a case, the client 533 will be forced to detect this case using entity tags (discussed below 534 in Section 7.10), and undo its previous changes. This is very 535 difficult. 537 As a result, the schemas SHOULD be defined so that common operations 538 generally require a single request to perform. Consider an example. 539 Lets say an application usage is defining permissions for users to 540 perform certain operations. The schema can be designed in two ways. 541 The top level of the tree can identify users, and within each user, 542 there can be the permissions associated with the user. In an 543 alternative design, the top level of the tree identifies each 544 permission, and within that permission, the set of users who have it. 545 If, in this application usage, it is common to change the permission 546 for a user from one value to another, the former schema design is 547 better for xcap; it will require a single PUT to make such a change. 548 In the latter case, either the entire document needs to be replaced 549 (which is a single operation), or two PUT operations need to occur - 550 one to remove the user from the old permission, and one to add the 551 user to the new permission. 553 Naming conventions form another key part of the design of an 554 application usage. The application usage should be certain that XCAP 555 clients know where to "start" to retrieve and modify documents of 556 interest. Generally, this will involve the specification of a 557 well-known document at a well-known URI. That document can contain 558 references to other documents that the client needs to read or 559 modify. 561 6. URI Construction 563 In order to manipulate an XCAP resource, the data must be represented 564 by an HTTP URI. XCAP defines a specific naming convention for 565 constructing these URIs. The URI is constructed by concatenating the 566 XCAP root with the document selector with the path separator with a 567 escape coded form of the node selector. The XCAP root is the 568 enclosing context in which all XCAP resources live. The document 569 selector is a path that identifies a document within the XCAP root. 570 The path separator is a path segment with a value of double tilde 571 (~~). It is piece of syntactic sugar that separates the document 572 selector from the node selector. The node selector is an expression 573 that identifies an XML element within a document. 575 The sections below describe these components in more detail. 577 6.1 XCAP Root 579 The root of the XCAP hierarchy is called the XCAP root. It defines 580 the context in which all other resources exist. The XCAP root is 581 represented with an HTTP URI, called the XCAP Root URI. This URI is 582 a valid HTTP URL; however, it doesnt point to any resource that 583 actually exists on the server. Its purpose is to identify the root 584 of the tree within the domain where all XCAP documents are stored. 585 It can be any valid HTTP URL, but MUST NOT contain a query string. 586 As an example, http://xcap.example.com/services might be used as the 587 XCAP root URI within the example.com domain. Typically, the XCAP 588 root URI is provisioned into client devices. A server or domain MAY 589 support multiple XCAP root URIs. In such a case, it is effectively 590 operating as if it were serving separate domains. There is never 591 information carryover or interactions between resources in different 592 XCAP root URIs. 594 6.2 Document Selector 596 Each document within the XCAP root is identified by its document 597 selector. The document selector is a sequence of path segments, 598 separated by a slash ("/"). These path segments define a 599 hierarchical structure for organizing documents within any XCAP root. 600 The first path segment MUST be the XCAP AUID. So, continuing the 601 example above, all of the documents used by the resource lists 602 application would be under 603 http://xcap.example.com/services/resource-lists. 605 It is assumed that each application will have data that is set by 606 users, and/or it will have global data that applies to all users. As 607 a result, beneath each AUID there are two sub-trees. One, called 608 "users", holds the documents that are applicable to specific users, 609 and the other, called "global", holds documents applicable to all 610 users. The subtree beneath "global" is called the global tree. The 611 path segment after the AUID MUST either be "global" or "users". 613 Within the "users" tree are zero or more sub-trees, each of which 614 identifies documents that apply to a specific user. Each user known 615 to the server is associated with a username, called the XCAP User 616 Identifier (XUI). This XUI MUST be used as the path segment beneath 617 the "users" segment. The subtree beneath an XUI for a particular 618 user is called their home directory. "User" in this context should 619 be interpreted loosely; a user might correspond to device, for 620 example. 622 XCAP does not itself define what it means for documents to "apply" to 623 a user, beyond specification of a baseline authorization policy, 624 described below in Section 8. Each application usage can specify 625 additional authorization policies which depend on data used by the 626 application itself. 628 The remainder of the document selector (the path following "global" 629 or the XUI) is not constrained by this specification. The 630 application usage MAY introduce constraints, or may allow any 631 structure to be used. 633 The final path segment in the document selector identifies the actual 634 document in the hierarchy. This is equivalent to a filename, except 635 that XCAP does not require that its document resources be stored as 636 files in a file system. However, the term "filename" is used to 637 describe the final path segment in the document selector. In 638 traditional filesystems, the filename would have a filename 639 extension, such as ".xml". There is nothing in this specification 640 that requires or prevents such extensions from being used in the 641 filename. In some cases, the application usage will specify a naming 642 convention for documents, and those naming conventions may or may not 643 specify a file extension. For example, in the RLS services 644 application usage [23], documents in the user's home directory with 645 the filename "index" will be used by the server to compute the global 646 index, which is also a document with the filename "index". 648 When the naming conventions in an application usage do not constrain 649 the filename conventions (or, more generally, the document selector), 650 an application will know the filename (or more generally, the 651 document selector) because it is included as a reference in a 652 document which is at a well known location. As another example, 653 within the index document defined by RLS services, the 654 element has a child element called whose content is a 655 URI pointing to a resource list within the users home directory. 657 As a result, if the user creates a new document, and then references 658 that document from a well-known document (such as the index document 659 above), it doesn't matter whether the user includes an extension in 660 the filename or not, as long as the user is consistent and maintains 661 referential integrity. Indeed, it doesn't even matter what the rest 662 of the filename is, independent of whether it has a filename 663 extension or not. 665 6.3 Node Selector 667 The node selector specifies specific nodes of the XML document which 668 are to be accessed. A node refers to either an XML element or an 669 attribute of an element. The node selector is an expression which 670 identifies an element or attribute. Its grammar is: 672 node-selector = element-selector ["/" attribute-selector] 673 element-selector = step *( "/" step) 674 step = by-name / by-pos / by-attr / by-pos-attr 675 by-name = NameorAny 676 by-pos = NameorAny "[" position "]" 677 position = 1*DIGIT 678 by-attr = NameorAny "[" "@" att-name "=" <"> 679 att-value <"> "]" 680 by-pos-attr = NameorAny "[" position "]" "[" "@" att-name "=" <"> 681 att-value <"> "]" 682 NameorAny = QName / "*" ; QName from XML Namespaces 683 att-name = QName 684 att-value = AttValue ; from XML specification 685 attribute-selector = "@" att-name 687 The QName grammar is defined the XML namespaces [3] specification, 688 and the AttValue grammar is defined in the XML specification XML 1.0 689 [1]. 691 Note that the left bracket, right bracket, and double quote 692 characters, which are meaningful to XCAP, cannot be directly 693 represented in the HTTP URI. As a result, they are escape coded when 694 placed within the HTTP URI. 696 Similarly, the XML specification defines the QName production for the 697 grammar for element and attribute names, and the AttValue production 698 for the attribute values. Unfortunately, the characters permitted by 699 these productions include some that are not allowed for pchar, which 700 is the production for the allowed set of characters in path segments 701 in the URI. The AttValue production allows many such characters 702 within the US-ASCII set, including the space. Those characters MUST 703 be escaped coded when placed in the URI. Furthermore, QName and 704 AttValue allow many Unicode characters, outside of US-ASCII. When 705 these characters need to be represented in the HTTP URI, they are 706 escape coded. To do this, the data should be encoded first as octets 707 according to the UTF-8 character encoding [17] and then only those 708 octets that do not correspond to characters in the unreserved set 709 should be percent-encoded. For example, the character A would be 710 represented as "A", the character LATIN CAPITAL LETTER A WITH GRAVE 711 would be represented as "%C3%80", and the character KATAKANA LETTER A 712 would be represented as "%E3%82%A2". 714 As a result, the grammar above represents the expressions processed 715 by the XCAP server internally after it has un-escape-coded the URL. 716 The on-the-wire format is dictated by RFC 2396 [12]. In the 717 discussions an examples below, the node selectors are presented in 718 their internal format prior to encoding when not part of an HTTP URL. 719 If an example includes a node selector within an HTTP URL, it is 720 presented in its escape coded form. 722 The node selector is based on the concepts in XPath [9]. Indeed, the 723 node selector expression, before it is escape coded for 724 representation in the HTTP URL, happens to be a valid XPath 725 expression. However, XPath provides a set of functionality far 726 richer than is needed here, and its breadth would introduce much 727 unneeded complexity into XCAP. 729 To determine the XML element or attribute selected by the node 730 selector, processing begins at the root of the XML document. The 731 first step in the element selector is then taken. Each step chooses 732 a single XML element within the current document context. The 733 document context is the point within the XML document from which a 734 specific step is evaluated. The document context begins at the root 735 of the document. When a step determines an element within that 736 context, that element becomes the new context for evaluation of the 737 next step. Each step can select an element by its name, by a 738 combination of name and attribute value, by name and position, or by 739 name, position and attribute. In all cases, the name can be 740 wildcarded, so that all elements get selected. 742 The selection operation operates as follows. Within the current 743 document context, the children of that context are enumerated in 744 document order. If the context is the document, its child is the 745 root element in the document. If the context is an element, its 746 children are all of the children of that element (naturally). Next, 747 those elements whose name is not a match for NameorAny are discarded. 748 An elements name is a match if NameorAny is the wildcard, or, if its 749 not a wildcard, the element name matches NameorAny. Matching is 750 discussed below. The result is an ordered list of elements. 752 The elements in the list are further filtered by the predicates, 753 which are the expressions in square brackets following NameorAny. 754 Each predicate further prunes the elements from the current ordered 755 list. These predicates are evaluated in order. If the content of 756 the content is a position, the position-th element is selected, and 757 all others are discarded. If there are fewer elements in the list 758 than the value of position, the result is a no-match. 760 If the content of the predicate is an attribute name and value, all 761 elements possessing that attribute with that value are selected, and 762 all others are discarded. Note that elements cannot be selected 763 based on any namespace attributes. That is, a step like 764 el-name[@xmlns="namespace"] will never match an element, even if 765 there is an element in the list that specifies a default namespace of 766 "namespace". If there are no elements with attributes having the 767 given name and value, the result is a no-match. 769 After the predicates have been applied, the result will be a 770 no-match, one element, or multiple elements. If the result is 771 multiple elements, the node selector is invalid. Each step in a node 772 selector MUST produce a single element to form the context for the 773 next step. This is more restrictive than general XPath expressions, 774 which allow a context to contain multiple elements. If the result is 775 a no-match, the node selector is invalid. The node selector is only 776 valid if a single element was selected. This element becomes the 777 context for the evaluation of the next step in the node selector 778 expression. 780 Once the last step is executed, if there is no attribute selector, 781 the result of the node selection is the last selected element. If 782 there is an attribute selector, the server checks to see if there is 783 an attribute with that name in the element in the current context. 784 If there is not, the result is considered a no-match. Otherwise, 785 that attribute is selected. Note that namespace attributes (such as 786 xmlns) cannot be selected. 788 As a result, once the entire node selector is evaluated against the 789 document, the result will either be a no-match, invalid, or a single 790 element or single attribute. 792 Matching of element names and attributes is performed as follows. 793 All elements and attributes are expanded as described in XML 794 namespaces [3]. The element and attribute names in the step being 795 evaluated are also expanded. This expansion form requires that any 796 namespace prefixes in the QName be expanded. This expansion is done 797 using the namespace bindings that are in scope for the current 798 context element. Like attributes, if the QName within a step has no 799 namespace prefix, the namespace URI is null. The comparisons are 800 then done against these expanded forms [[TODO: This is the rules in 801 XPath, but I dont see how they can work. Need to check up on that.]] 803 Comments, text content, and processing declarations in the XML 804 document cannot be selected by the expressions defined here. Of 805 course, if such information is present in a document, and a user 806 selects an XML element enclosing that data, that information would be 807 included in a resulting GET, for example. 809 As an example, consider the following XML document: 811 812 814 815 sip:userA@example.net 819 sip:userB@example.org 823 824 826 Example XML Document 828 Figure 3 830 The node selector "watcherinfo/watcher-list/ 831 watcher[@id="8ajksjda7s"]" would select the following XML element: 833 sip:userA@example.net 837 839 7. Client Operations 841 An XCAP client is an HTTP 1.1 compliant client. Specific data 842 manipulation tasks are accomplished by invoking the right set of HTTP 843 methods with the right set of headers on the server. This section 844 describes those in detail. 846 In all cases where the client modifies a document, by deleting or 847 inserting a document, element or attribute resource, the client 848 SHOULD verify that, if the operation were to succeed, the resulting 849 document would meet the data constraints defined by the application 850 usage, including schema validation. For example, if the client 851 performs a PUT operation to 852 http://xcap.example.com/rls-services/users/joe/mybuddies, 853 rls-services is the application unique ID, and the constraints 854 defined by it SHOULD be followed. 856 The client will know what URI to use based on the naming conventions 857 described by the application usage. 859 If the document, after modification, does not meet the data 860 constraints, the server will reject it with a 409. The 409 response 861 may contain an XML body, formatted according to the schema in Section 862 9.2, which provides further information on the nature of the error. 863 The client MAY use this information to try and alter the request so 864 that this time, it might succeed. The client SHOULD NOT simply retry 865 the request without changing some aspect of it. 867 In some cases, the application usage will dictate involve a 868 uniqueness constraint that the client cannot guarantee on its own. 869 One such example is that a URI has to be unique within a domain. 870 Typically, the client is not the owner of the domain, and so it 871 cannot be sure that a URI is unique. In such a case, the client can 872 either generate a sufficiently random identifier, or it can pick a 873 "vanity" identifier in the hopes that it is not taken. In either 874 case, if the identifier is not unique, the server will reject the 875 request with a 409 and suggest alternatives that the client can use 876 to try again. If the server does not suggest alternatives, the 877 client SHOULD attempt to use random identifiers with increasing 878 amounts of randomness. 880 HTTP also specifies that PUT and DELETE requests are idempotent. 881 This means that, if the client performs a PUT on a document and it 882 succeeds, it can perform the same PUT, and the resulting document 883 will look the same. Similarly, when a client performs a DELETE, if 884 it succeeds, a subsequent DELETE to the same URI should find the 885 resource deleted and thus have no further effect. To maintain this 886 property, the client SHOULD construct its URIs such that, after the 887 modification has taken place, the URI in the request will point to 888 the resource just inserted for PUT (i.e., the body of the request), 889 and will point to nothing for DELETE. If this property is 890 maintained, it is the case that GET to the URI in the PUT will return 891 the same content (i.e., GET(PUT(X)) == x). This property is 892 synonymous with idempotency. If the client's request does not have 893 this property, the server will reject the request with a 409 and 894 indicate a cannot-insert error condition. 896 If the result of the PUT is a 200 or 201 response, the operation was 897 successful. Other response codes to any request, such as a 898 redirection, are processed as per RFC 2616 [5]. 900 7.1 Create or Replace a Document 902 To create or replace a document, the client constructs a URI that 903 references the location where the document is to be placed. This URI 904 MUST be a document URI, and therefore contain the XCAP root and 905 document selector. The client then invokes a PUT method on that URI. 907 The MIME content type MUST be the type defined by the application 908 usage. For example, it would be "application/rls-services+xml" for 909 an RLS services [23] document, and not "application/xml". 911 If the Request-URI identifies a document that already exists in the 912 server, the PUT operation replaces that document with the content of 913 the request. If the Request-URI does not identify an existing 914 document, the document is created on the server at that specific URI. 916 7.2 Delete a Document 918 To delete a document, the client constructs a URI that references the 919 document to be deleted. This URI MUST be a document URI. The client 920 then invokes a DELETE operation on the URI to delete the document. 922 7.3 Fetch a Document 924 As one would expect, fetching a document is trivially accomplished by 925 performing an HTTP GET request with the Request URI set to the 926 document URI. 928 7.4 Create or Replace an Element 930 To create or replace an XML element within an existing document, the 931 client constructs a URI whose document selector points to the 932 document to be modified. The node selector MUST be present in the 933 URI, separated from the document selector with the path separator. 934 To create this this element within the document, the node selector is 935 constructed such that it is a no-match against the current document, 936 but if the element in the body of the request was added to the 937 document as desired by the client, the node selector would select 938 that element. To replace an element in the document, the node 939 selector is constructed so that it is a match against the element in 940 the current document to be replaced, as well as a match to the new 941 element (present in the body of the PUT request) that is to replace 942 it. 944 Oftentimes, the client will wish to insert an element into a document 945 in a certain position relative to other children of the same parent. 946 This is called a positional insertion. They often arise because the 947 schema constrains where the element can occur, or because ordering of 948 elements is significant within the schema. To accomplish this, the 949 client can use a node selector of the following form: 951 parent/*[position][unique-attribute-value] 953 Here, "parent" is an expression for the parent of the element to be 954 inserted. "position" is the position amongst the existing children 955 of this parent where the new element is to be inserted. 956 "unique-attribute-value" is an attribute name and value for the 957 element to be inserted, which is different from the current element 958 in "position". The second predicate is needed so that the overall 959 expression is a no-match when evaluated against the current children. 960 Otherwise, the PUT would replace the existing element in that 961 position. 963 Consider the example document in Figure 3. The client would like to 964 insert a new element as the second element underneath 965 . However, it cannot just PUT to a URI with the 966 watcherinfo/watcher-list/*[2] node selector; this node selector would 967 select the existing 2nd child of and replace it. 968 Thus, the PUT has to be made to a URI with watcherinfo/watcher-list/ 969 *[2][@id="hhggff"] as the node selector, where "hhggff" is the value 970 of the "id" attribute of the new element to be inserted. This 971 node-selector is a no-match against the current document, and would 972 be a match against the new element if it was inserted as the 2nd 973 child of . 975 The "*" indicates that all children of are to be 976 considered when computing the position for insertion. If, instead of 977 a *, an element name was present, the expression above would insert 978 the new element as the position-th element amongst those with the 979 same name. 981 Once the client constructs the URI, it invokes the HTTP PUT method. 983 The content in the request MUST be an XML element. Specifically, it 984 contains the element, starting with the opening bracket for the begin 985 tag for that element, including the attributes and content of that 986 element (whether it be text or other child elements), and ending with 987 the closing bracket for the end tag for that element. The MIME type 988 in the request MUST be "application/xcap-el+xml", defined in Section 989 13.2.1. If the node selector, when evaluated against the current 990 document, results in a no-match, the server performs a creation 991 operation. If the node selector, when evaluated against the current 992 document, is a match for an element in the current document, the 993 server replaces it with the content of the PUT request. This 994 replacement is complete; that is, the old element (including its 995 attributes and content) are removed, and the new one, including its 996 attributes and content, is put in its place. 998 To be certain that element insertions are idempotent, the client can 999 check that the attribute predicates in the final path segment of the 1000 URI match the attributes of the element in the body of the request. 1001 As an example of an request that would not be idempotent, consider 1002 the following PUT request: 1004 PUT 1005 http://xcap.example.com/rls-services/users/bill/index/~~/rls-services/service%5b@uri=%22sip:good-friends@example.com%5d 1006 HTTP/1.1 1007 Content-Type:application/xcap-el+xml 1009 1010 http://xcap.example.com/resource-lists/users/joe/index/~~/resource-lists/list%5b@name=%22l1%22%5d 1011 1012 1013 presence 1014 1015 1017 This request will fail with a 409. The Request URI contains a final 1018 path segment with a predicate based on attributes - 1019 @uri="sip:good-friends@example.com". However, this will not match 1020 the value of the "uri" attribute in the element in the body. 1022 When the client does not explicitly indicate a position in which to 1023 insert a new element, the server will insert that element as the last 1024 child of that parent. If this is not the desired position, the 1025 client should perform a positional insertion. 1027 7.5 Delete an Element 1029 To delete an element from a document, the client constructs a URI 1030 whose document selector points to the document containing the element 1031 to be deleted. The node selector MUST be present following the path 1032 separator, and identify the specific element to be deleted. 1034 The client then invokes the HTTP DELETE method. The server will 1035 remove the element from the document (including its attributes and 1036 its content, such as any children). 1038 7.6 Fetch an Element 1040 To fetch an element of a document, the client constructs a URI whose 1041 document selector points to the document containing the element to be 1042 fetched. The node selector MUST be present following the path 1043 separator, and must identify the element to be fetched. 1045 The client then invokes the GET method. The 200 OK response will 1046 contain that XML element. Specifically, it contains the content of 1047 the XML document, starting with the opening bracket for the begin tag 1048 for that element, and ending with the closing bracket for the end tag 1049 for that element. This will, as a result, include all attributes and 1050 child elements of that element. 1052 7.7 Create or Replace an Attribute 1054 To create or replace an attribute in an existing element of a 1055 document, the client constructs a URI whose document selector points 1056 to the document to be modified. The node selector, following the 1057 path separator, MUST be present. The node selector MUST be 1058 constructed such that, if the attribute was created or replaced as 1059 desired, the node selector would select that attribute. If the node 1060 selector, when evaluated against the current document, results in a 1061 no-match, it is a creation operation. If it matches an existing 1062 attribute, it is a replacement operation. 1064 The client then invokes the HTTP PUT method. The content defined by 1065 the request MUST be the value of the attribute, compliant to the 1066 grammar for AttValue as defined in XML 1.0. Note that, unlike when 1067 AttValue is present in the URI, there is no escape coding. Escaping 1068 only applies to URIs. This request MUST be sent with the 1069 Content-Type of "application/xcap-att+xml" as defined in Section 1070 13.2.2. The server will add that attribute such that, if the node 1071 selector is evaluated on the resulting document, it returns the 1072 attribute present in the request. 1074 To be certain that attribute insertions are idempotent, the client 1075 can check that any attribute predicate in the path segment that 1076 selects the element into which the attribute is inserted, matches a 1077 different attribute than the one being inserted by the request. As 1078 an example of a request that would not be idempotent, consider the 1079 following PUT request: 1081 PUT 1082 http://xcap.example.com/rls-services/users/bill/index/~~/rls-services/service%5b@uri=%22sip:good-friends@example.com%5d/@uri 1083 HTTP/1.1 1084 Content-Type:application/xcap-att+xml 1086 "sip:bad-friends@example.com" 1088 This request will fail with a 409. 1090 7.8 Delete an Attribute 1092 To delete attributes from the document, the client constructs a URI 1093 whose document selector points to the document containing the 1094 attributes to be deleted. The node selector MUST be present 1095 following the path separator, and evaluate to an attribute in the 1096 document to be deleted. 1098 The client then invokes the HTTP DELETE method. The server will 1099 remove the attribute from the document. 1101 7.9 Fetch an Attribute 1103 To fetch an attribute of a document, the client constructs a URI 1104 whose document selector points to the document containing the 1105 attribute to be fetched. The node selector MUST be present following 1106 the path separator, containing an expression identifying the 1107 attribute whose value is to be fetched. 1109 The client then invokes the GET method. The 200 OK response will 1110 contain an "application/xcap-att+xml" document with the specified 1111 attribute, formatted according to the grammar of AttValue as defined 1112 in the XML 1.0 specifications. 1114 7.10 Conditional Operations 1116 The HTTP specification defines several header fields that can be used 1117 by a client to make the processing of the request conditional. In 1118 particular, the If-None-Match and If-Match header fields allow a 1119 client to make them conditional on the current value of the entity 1120 tag for the resource. These conditional operations are particularly 1121 useful for XCAP resources. 1123 For example, it is anticipated that clients will frequently wish to 1124 cache the current version of a document. So, when the client starts 1125 up, it will fetch the current document from the server and store it. 1126 When it does so, the GET response will contain the entity tag for the 1127 document resource. Each resource within a document maintained by the 1128 server will share the same value of the entity tag. As a result, the 1129 entity tag returned by the server for the document resource is 1130 applicable to element and attribute resources within the document. 1132 If the client wishes to modify an element or attribute within the 1133 document, but it wants to be certain that the document hasn't been 1134 modified since the client last operated on it, it can include an 1135 If-Match header field in the request, containing the value of the 1136 entity tag known to the client for all resources within the document. 1137 If the document has changed, the server will reject this request with 1138 a 412 response. In that case, the client will need to flush its 1139 cached version, fetch the entire document, and store the new entity 1140 tag returned by the server in the 200 OK to the GET request. 1142 Its important to note that entity tags are defined for each resource 1143 in the document, even though they share the same value. As a result, 1144 if a resource does not exist in the document, there is no entity tag 1145 for it, and a PUT to such a resource with an If-Match header field 1146 will always fail with a 412. For this reason, PUT operations that 1147 insert a new element or attribute into a document cannot be 1148 conditioned on the entity tag for the document itself. If the client 1149 wishes to make sure that the document has not changed before adding 1150 the new element or attribute, the client can "pop up a level", and 1151 instead of inserting a new element or attribute, it can modify the 1152 parent of that new element and attribute such that the new value 1153 contains the new element or attribute. 1155 In another example, a client may wish to insert a new element into a 1156 document, but wants to be sure that the insertion will only take 1157 place if that element does not exist. In other words, the client 1158 wants the PUT operation to be a creation, not a replacement. To 1159 accomplish that, the client can insert the If-None-Match header field 1160 into the PUT request, with a value of *. This tells the server to 1161 reject the request with a 412 if resource exists. 1163 As another example, a when a client fetches a document, and there is 1164 an older version cached, it is useful for clients to use a 1165 conditional GET in order to reduce network usage if the cached copy 1166 is still valid. This is done by including, in the GET request, the 1167 If-None-Match header field with a value equal to the current etag 1168 held by the client for the document. The server will only generate a 1169 200 OK reponse if the etag held by the server differs than that held 1170 by the client. If it doesnt differ, the server will respond with a 1171 304 response. 1173 8. Server Behavior 1175 An XCAP server is an HTTP 1.1 compliant origin server. The behaviors 1176 mandated by this specification relate to the way in which the HTTP 1177 URI is interpreted and the content is constructed. 1179 An XCAP server MUST be explicitly aware of the application usage 1180 against which requests are being made. That is, the server must be 1181 explicitly configured to handle URIs for each specific application 1182 usage, and must be aware of the constraints imposed by that 1183 application usage. 1185 When the server receives a request, the treatment depends on the URI. 1186 If the URI refers to an application usage not understood by the 1187 server, the server MUST reject the request with a 404 (Not Found) 1188 response. If the URI refers to a user that is not recognized by the 1189 server, it MUST reject the request with a 404 (Not Found). 1191 Next, the server authenticates the request. All XCAP servers MUST 1192 implement HTTP Digest [10]. Furthermore, servers MUST implement HTTP 1193 over TLS, RFC 2818 [13]. It is RECOMMENDED that administrators use 1194 an HTTPS URI as the XCAP root URI, so that the digest client 1195 authentication occurs over TLS. 1197 Next, the server determines if the client has authorization to 1198 perform the requested operation on the resource. The application 1199 usage defines the authorization policies. An application usage may 1200 specify that the default is used. This default is described in 1201 Section 5.6. 1203 Once authorized, the specific behavior depends on the method and what 1204 the URI refers to. 1206 8.1 POST Handling 1208 XCAP resources do not represent processing scripts. As a result, 1209 POST operations to HTTP URIs representing XCAP resources are not 1210 defined. A server receiving such a request for an XCAP resource 1211 SHOULD return a 405. 1213 8.2 PUT Handling 1215 The behavior of a server in receipt of a PUT request is as specified 1216 in HTTP 1.1 Section 9.6 - the content of the request is placed at the 1217 specified location. This section serves to define the notion of 1218 "placement" and "specified location" within the context of XCAP 1219 resources. 1221 8.2.1 Locating the Parent 1223 The first step the server performs is to locate the parent, whether 1224 it is a directory or element, in which the resource is to be placed. 1225 To do that, the server removes the last path segment from the URI. 1226 The rest of the URI refers to the parent. This parent can be a 1227 document, element, or prefix of a document selector (called a 1228 directory, even though this specification does not mandate that 1229 doocuments are actually stored in a filesystem). This URI is called 1230 the parent URI. The path segment that was removed is called the 1231 target selector, and the node (element, document or attribute) it 1232 describes is called the target node. 1234 If the parent URI has no path separator, it is referring to the 1235 directory into which the document should be inserted. If this 1236 directory does not exist, the server MUST return a 409 response, and 1237 SHOULD include a detailed conflict report including the 1238 element. Detailed conflict reports are discussed in Section 9. If 1239 the directory does exist, the server checks to see if there is a 1240 document with the same filename as the target node. If there is, the 1241 operation is the replacement operation discussed in Section 8.2.4. 1242 If it does not exist, it is the creation operation, discussed in 1243 Section 8.2.4. 1245 If the parent URI has a path separator, the document selector is 1246 extracted, and that document is retrieved. If the document does not 1247 exist, the server MUST return a 409 response, and SHOULD include a 1248 detailed conflict report including the element. If it 1249 does exist, the node selector is extracted, and unescaped (recall 1250 that the node selector is escape coded). The node selector is 1251 applied to the document based on the matching operations discussed in 1252 Section 6.3. If the result is a no-match or invalid, the server MUST 1253 return a 409 response, and SHOULD include a detailed conflict report 1254 including the element. 1256 If the node-selector is valid, the server examines the target 1257 selector, and evaluates in within the context of the parent node. If 1258 the target node exists within the parent, the operation is a 1259 replacement, as described in Section 8.2.4. If it does not exist, it 1260 is the creation operation, discussed in Section 8.2.4. 1262 Before performing the replacement or creation, as determined based on 1263 the logic above, the server validates the content of the request as 1264 described in Section 8.2.2 1266 8.2.2 Verifying Document Content 1268 If the PUT request is for a document (the request URI had no path 1269 separator), the content of the request body has to be a well-formed 1270 XML document. If it is not, the server MUST reject the request with 1271 a 409 response code. That response SHOULD include a detailed 1272 conflict report including the element. If the MIME 1273 type in the Content-Type header field of the request is not equal to 1274 the MIME type defined for the application usage, the server MUST 1275 reject the request with a 415. 1277 If the PUT request is for an element, the content of the request body 1278 has to be a well-balanced region of an XML document, also known as an 1279 XML fragment body in The XML Fragment Interchange [4] specification, 1280 including only a single element. If it is not, the server MUST 1281 reject the request with a 409 response code. That response SHOULD 1282 include a detailed conflict report including the 1283 element. If the MIME type in the Content-Type header field of the 1284 request is not equal to "application/xcap-el+xml", the server MUST 1285 reject the request with a 415. 1287 If the PUT request is for an attribute, the content of the request 1288 body has to be a sequence of characters that comply with the grammar 1289 for AttValue as defined above. If it is not, the server MUST reject 1290 the request with a 409 response code. That response SHOULD include a 1291 detailed conflict report including the element. 1292 If the MIME type in the Content-Type header field of the request is 1293 not equal to "application/xcap-att+xml", the server MUST reject the 1294 request with a 415. 1296 8.2.3 Creation 1298 The steps in this sub-section are followed if the PUT request will 1299 result in the creation of a new document, element or attribute. 1301 If the PUT request is for a document, the content of the request body 1302 is placed into the directory, and its filename is associated with the 1303 target node, which is a document. 1305 If the PUT request is for an element, the server inserts the content 1306 of the request body as a new child element of the parent element 1307 selected in Section 8.2.1. The insertion is done such that, the 1308 request URI, when evaluated, would now point to the element which was 1309 inserted. If the target selector is defined by a by-name or by-attr 1310 production (in other words, there is no position indicated) the 1311 server MUST insert the element after any other siblings. If a 1312 position is indicated, the server MUST insert the element so that it 1313 is the position-th element amongst all siblings whose name matches 1314 NameorAny. 1316 It is possible that the element cannot be inserted such that the 1317 request URI, when evaluated, returns the content provided in the 1318 request. Such a request is not idempotent, and is not allowed for 1319 PUT. This happens when the element in the body is not described by 1320 the expression in the target selector. An example of this case is 1321 described in Section 7.4. If this happens the server MUST NOT 1322 perform the insertion, and MUST reject the request with a 409 1323 response. The body of the response SHOULD contain a detailed 1324 conflict report containing the element. It is 1325 important to note that schema compliance does not play a role while 1326 performing the insertion. That is, the decision of where the element 1327 gets inserted is dictated entirely by the structure of the 1328 request-URI, the current document, and the rules in this 1329 specification. 1331 If the PUT request is for an attribute, the server inserts the 1332 content of the request body as the value of the attribute. The name 1333 of the attribute is equal to the att-name from the attribute-selector 1334 in the target selector. 1336 Assuming that the insertion can be accomplished, the server verifies 1337 that the insertion results in a document that meets the constraints 1338 of the application usage. This is dicussed in Section 8.2.5. 1340 8.2.4 Replacement 1342 The steps in this sub-section are followed if the PUT request will 1343 result in the replacement of a document, element or attribute with 1344 the contents of the request. 1346 If the PUT request is for a document, the content of the request body 1347 is placed into the directory, replacing the document with the same 1348 filename. 1350 If the PUT request is for an element, the server replaces the target 1351 node with the content of the request body. As in the creation case, 1352 it is possible that, after replacement, the request URI does not 1353 select the element that was just inserted. If this happens the 1354 server MUST NOT perform the replacement, and MUST reject the request 1355 with a 409 response. The body of the response SHOULD contain a 1356 detailed conflict report containing the element. 1358 If the PUT request is for an attribute, the server sets the value of 1359 the selected attribute to the content of the request body. It is 1360 possible in the replacement case (but not in the creation case), 1361 that, after replacement of the attribute, the request URI no longer 1362 selects the attribute that was just replaced. The scenario in which 1363 this can happen is discussed in Section 7.7. If this is the case, 1364 the server MUST NOT perform the replacement, and MUST reject the 1365 request with a 409 response. The body of the response SHOULD contain 1366 a detailed conflict report containing the element. 1368 8.2.5 Validation 1370 Once the document, element or attribute has been tentatively 1371 inserted, the server needs to verify that the resulting document 1372 meets the data constraints outlined by the application usage. 1374 First, the server checks that the final document is compliant to the 1375 schema. If it is not, the server MUST NOT perform the insertion. It 1376 MUST reject the request with a 409 response. That response SHOULD 1377 contain a detailed conflict report containing the 1378 element. 1380 Next, the server checks for any uniqueness constraints identified by 1381 the application usage. If the application usage required that a 1382 particular element or attribute had a unique value within a specific 1383 scope, the server would check that this uniqueness property still 1384 exists. If the application usage required that a URI within the 1385 document was unique within the domain, the server checks whether it 1386 is the case. If any of these uniqueness constraints are not met, the 1387 server MUST NOT perform the insertion. It MUST reject the request 1388 with a 409 response. That response SHOULD contain a detailed 1389 conflict report containing the element. That 1390 element can contain suggested values that the client can retry with. 1391 These SHOULD be values that, at the time the server generates the 1392 409, would meet the uniqueness constraints. 1394 The server also checks for URI constraints and other non-schema data 1395 constraints. If the document fails one of these constraints, the 1396 server MUST NOT perform the insertion. It MUST reject the request 1397 with a 409 response. That response SHOULD contain a detailed 1398 conflict report containing the element. That 1399 element indicates that the document failed non-schema data 1400 constraints explicitly called out by the application usage. 1402 8.2.6 Resource Interdependencies 1404 Because XCAP resources include elements, attributes and documents, 1405 each of which has its own HTTP URI, the creation or modification of 1406 one resource affects the state of many others. For example, 1407 insertion of a document creates resources on the server for all of 1408 the elements and attributes within that document. After the server 1409 has performed the insertion associated with the PUT, the server MUST 1410 create and/or modify those resources affected by that PUT. The 1411 structure of the document completely defines the inter-relationship 1412 between those resources. Normally a server will not need to actually 1413 do anything to meet this requirement, since those other resources 1414 would normally be resolved dynamically when requests are made against 1415 them. 1417 However, the application usage can specify other resource 1418 inter-dependencies. The server MUST create or modify the resources 1419 specified by the application usage. 1421 If the creation or insertion was successful, and the resource 1422 interdependcies are resolved, the server returns a 200 OK or 201 1423 Created, as appropriate. This response MUST not contain any content. 1425 8.3 GET Handling 1427 The semantics of GET are as specified in RFC 2616. This section 1428 clarifies the specific content to be returned for a particular URI 1429 that represents an XCAP resource. 1431 If the request URI contains only a document selector, the server 1432 returns the document specified by the URI if it exists, else returns 1433 a 404 response. The MIME type of the body of the 200 OK response 1434 MUST be the MIME type defined by that application usage (i.e., 1435 "application/resource-lists+xml"). 1437 If the request URI contains a node selector, the server obtains the 1438 document specified by the document selector, and if it is found, 1439 evaluates the node-selector within that document. If no document is 1440 found, or if the node-selector is a no-match or invalid, the server 1441 returns a 404 response. Otherwise, the server returns a 200 OK 1442 response. If the node selector identifies an XML element, that 1443 element is returned in the 200 OK response as an XML fragment body 1444 containing the selected element. The MIME type of the response MUST 1445 be "application/xcap-el+xml". If the node selector identifies an XML 1446 attribute, the value of that attribute is returned in the body of the 1447 response. The MIME type of the response MUST be "application/ 1448 xcap-att+xml". 1450 8.4 DELETE Handling 1452 The semantics of DELETE are as specified in RFC 2616. This section 1453 clarifies the specific content to be deleted for a particular URI 1454 that represents an XCAP resource. 1456 If the request URI contains only a document selector, the server 1457 deletes the document specified by the URI if it exists and returns a 1458 200 OK, else returns a 404 response. 1460 If the request URI contains a node selector, the server obtains the 1461 document specified by the document selector, and if it is found, 1462 evaluates the node-selector within that document. If no document is 1463 found, or if the node-selector is a no-match or invalid, the server 1464 returns a 404 response. Otherwise, the server removes the specified 1465 element or attribute from the document and performs the validation 1466 checks defined in Section 8.2.2. If the deletion will cause a 1467 failure of one of the constraints, the deletion MUST NOT take place. 1468 The server follows the procedures in Section 8.2.2 for computing the 1469 409 response. If the deletion results in a document that is still 1470 valid, the server MUST perform the deletion and return a 200 OK 1471 response. 1473 Before the server returns the 200 OK response to a DELETE, it MUST 1474 process the resource interdependcies as defined in Section 8.2.6. 1476 8.5 Managing Etags 1478 An XCAP server MUST maintain entity tags for all resources that it 1479 maintains. This specification introduces the additional constraint 1480 that when one resource within a document (including the document 1481 itself) changes, that resource is assigned a new etag, and all other 1482 resources within that document MUST be assigned the same etag value. 1483 An XCAP server MUST include the Etag header field in all 200 or 201 1484 responses to PUT, GET, or DELETE [[Todo: Not sure we'll see them in 1485 DELETE responses. Need to check.]]. XCAP resources do not introduce 1486 new requirements on the strength of the entity tags; as in RFC 2616, 1487 weak ones MAY be used if performance constraints or other conditions 1488 make usage of strong ones untenable for some reason. 1490 As a result of this constraint, when a client makes a change to an 1491 element or attribute within a document, the response to that 1492 operation will convey the entity tag of the resource that was just 1493 affected. Since the client knows that this entity tag value is 1494 shared by all of the other resources in the document, the client can 1495 make conditional requests against other resources using that entity 1496 tag. 1498 9. Detailed Conflict Reports 1500 In cases where the server returns a 409 error response, that response 1501 will usually include a document in the body of the response which 1502 provides further details on the nature of the error. This document 1503 is an XML document, formatted according to the schema of Section 9.2. 1504 Its MIME type, registered by this specification, is "application/ 1505 xcap-error+xml". 1507 9.1 Document Structure 1509 The document structure is simple. It contains the root element 1510 . The content of this element is a specific error 1511 condition. Each error condition is represented by a different 1512 element. This allows for different error conditions to provide 1513 different data about the nature of the error. All error elements 1514 support a "phrase" attribute, which can contain text meant for 1515 rendering to a human user. 1517 The following error elements are defined by this specification: 1518 : This indicates that the body of the request was 1519 not a well-formed XML document. 1520 : This indicates that the request was supposed to 1521 contain a valid XML fragment body, but did not. Most likely this 1522 is because the XML in the body was malformed or not balanced. 1523 : This indicates that an attempt to insert an element, 1524 attribute or document failed because the document or element into 1525 which the insertion was supposed to occur does not exist. This 1526 error element can contain an optional element, which 1527 provides an HTTP URI of the xcap resource that identifies the 1528 closest ancestor element that does exist in the document. Because 1529 this is a valid HTTP URI, its node selector component MUST be 1530 escape encoded. 1531 : This element indicates that the document 1532 was not compliant to the schema after the requested operation was 1533 performed. 1534 : This indicates that the request was supposed to 1535 contain a valid XML attribute value, but did not. 1536 : This indicates that the requested PUT operation 1537 could not be performed because it would not be idempotent. 1538 : This indicates that the requested operation 1539 would result in a document that did not meet a uniqueness 1540 constraint defined by the application usage. For each URI, 1541 element or attribute specified by the client which is not unique, 1542 an element is present as the content of the error 1543 element. Each element has a "field" attribute that 1544 contains the node selector identifying the XML element or 1545 attribute whose value needs to be unique, but wasn't. Note that 1546 the double quote character, which is allowed in node selectors, 1547 cannot appear within the value of an attribute. As such, it MUST 1548 be represented as ". Beyond that, since the node selector is 1549 not appearing within an HTTP URL, there is no escape encoding. 1550 The element can optionally contain a list of suggested 1551 alternate values which do not currently exist on the server. 1552 : This indicates that the requested operation 1553 would result in a document that failed a data constraint defined 1554 by the application usage, but not enforced by the schema or a 1555 uniqueness constraint. 1557 Extensions to XCAP can define additional error elements. 1559 As an example, the following document indicates that the user 1560 attempted to create an RLS service using the URI 1561 sip:friends@example.com, but that URI already exists: 1563 1564 1565 1566 1567 sip:mybuddies@example.com 1568 1569 1570 1572 9.2 XML Schema 1574 1575 1580 1581 1582 1583 Indicates the reason for the error. 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 This element indicates 1594 that the document was not compliant to the schema after the requested 1595 operation was performed. 1596 1597 1598 1599 1600 1601 1602 1603 This indicates that the request was supposed to 1604 contain a valid XML fragment body, but did not. 1605 1606 1607 1608 1609 1610 1611 1612 This indicates that an attempt to insert 1613 an element, attribute or document failed because the document or 1614 element into which the insertion was 1615 supposed to occur does not exist 1616 1617 1618 1619 1620 1621 Contains an HTTP URI that points to the 1622 element which is the closest ancestor that does exist. 1623 1624 1625 1626 1627 1628 1629 1630 1631 This indicates that the requested 1632 PUT operation could not be performed because it would not be 1633 idempotent. 1634 1635 1636 1637 1638 1639 1640 1641 This indicates that the 1642 request was supposed to contain a valid XML attribute value, but did 1643 not. 1644 1645 1646 1647 1648 1649 1650 1651 This indicates that the 1652 requested operation would result in a document that did not meet a 1653 uniqueness constraint defined by the application usage. 1654 1655 1656 1657 1658 1659 For each URI, 1660 element or attribute specified by the client which is not unique, 1661 one of these is present. 1662 1663 1664 1665 1666 1667 An optional set of alternate values 1668 can be provided. 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 This indicates that the body of the request was 1682 not a well-formed document. 1683 1684 1685 1686 1687 This indicates that the 1688 requested operation would result in a document that failed a data 1689 constraint defined by the application usage, but not enforced by the 1690 schema or a uniqueness constraint. 1691 1692 1693 1695 10. XCAP Server Capabilities 1697 XCAP can be extended through the addition of new application usages 1698 and extensions to the core protocol. An XCAP server can also be 1699 extended to support new namespaces. It will often be necessary for a 1700 client to determine what extensions, application usages or namespaces 1701 a server supports before making a request. To enable that, this 1702 specification defines an application usage with the AUID "xcap-caps". 1703 All XCAP servers MUST support this application usage. This usage 1704 defines a single document within the global tree which lists the 1705 capabilities of the server. Clients can read this well-known 1706 document, and therefore learn the capabilities of the server. 1708 The structure of the document is simple. The root element is 1709 . Its children are , , and 1710 . Each of these contain a list of AUIDs, extensions and 1711 namespaces supported by the server. Extensions are named by tokens 1712 defined by the extension. Namespaces are identified by their 1713 namespace URI. Since all XCAP servers support the "xcap-caps" AUID, 1714 it MUST be listed in the element. 1716 The following sections provide the information needed to define this 1717 application usage. 1719 10.1 Application Usage ID (AUID) 1721 This specification defines the "xcap-caps" AUID within the IETF tree, 1722 via the IANA registration in Section 13. 1724 10.2 XML Schema 1726 1727 1732 1733 1734 Root element for xcap-caps 1735 1736 1737 1738 1739 1740 List of supported AUID. 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 List of supported extensions. 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 List of supported namespaces. 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 AUID Type 1775 1776 1777 1778 1779 1780 Extension Type 1781 1782 1783 1784 1785 1786 Namespace type 1787 1788 1789 1791 1793 10.3 MIME Type 1795 Documents conformant to this schema are known by the MIME type 1796 "application/xcap-caps+xml", registered in Section 13.2.4. 1798 10.4 Validation Constraints 1800 There are no additional validation constraints associated with this 1801 application usage. 1803 10.5 Data Semantics 1805 Data semantics are defined above. 1807 10.6 Naming Conventions 1809 A server MUST maintain a single instance of the document in the 1810 global tree, using the filename "index". There MUST NOT be an 1811 instance of this document in the users tree. 1813 10.7 Resource Interdependencies 1815 There are no resource interdependencies in this application usage 1816 beyond those defined by the schema. 1818 10.8 Authorization Policies 1820 This application usage does not change the default authorization 1821 policy defined by XCAP. 1823 11. Examples 1825 This section goes through several examples, making use of the 1826 resource-lists and rls-services [23] XCAP application usages. 1828 First, a user Bill creates a new document (see Section 7.1). This 1829 document is a new resource-list, initially with a single list, called 1830 friends, with no users in it: 1832 PUT 1833 http://xcap.example.com/services/resource-lists/users/bill/fr.xml HTTP/1.1 1834 Content-Type:application/resource-lists+xml 1836 1837 1838 1839 1840 1842 Next, Bill creates an RLS services document defining a single RLS 1843 service referencing this list. This service has a URI of 1844 sip:myfriends@example.com: 1846 PUT 1847 http://xcap.example.com/services/rls-services/users/bill/index HTTP/1.1 1848 Content-Type:application/rls-services+xml 1850 1851 1853 1854 http://xcap.example.com/services/resource-lists/users/bill/fr.xml/~~/resource-lists/list%5b@name=%22friends%22%5d 1855 1856 1857 presence 1858 1859 1860 1862 Next, Bill creates an element in the resource-lists document (Section 1863 7.4). In particular, he adds an entry to the list: 1865 PUT 1866 http://xcap.example.com/services/resource-lists/users/bill/fr.xml 1867 /~~/resource-lists/list%5b@name=%22friends%22%5d/entry HTTP/1.1 1868 Content-Type:application/xcap-el+xml 1870 1871 Bob Jones 1872 1874 Next, Bill fetches the document (Section 7.3): 1876 GET 1877 http://xcap.example.com/services/resource-lists/users/bill/fr.xml HTTP/1.1 1879 And the result is: 1881 HTTP/1.1 200 OK 1882 Etag: "wwhha" 1883 Content-Type: application/resource-lists+xml 1885 1886 1888 1889 1890 Bob Jones 1891 1892 1893 1895 Next, Bill adds another entry to the list, which is another list that 1896 has three entries. This is another element creation (Section 7.4): 1898 PUT 1899 http://xcap.example.com/services/resource-lists/users/bill/fr.xml/~~/ 1900 resource-lists/list%5b@name=%22friends%22%5d/list%5b@name=%22close-friends%22%5d HTTP/1.1 1901 Content-Type: application/xml-fragment-body 1903 1904 1905 Joe Smith 1906 1907 1908 Nancy Gross 1909 1910 1911 Petri Aukia 1912 1913 1915 Then, Bill decides he doesnt want Petri on the list, so he deletes 1916 the entry (Section 7.5): 1918 DELETE 1919 http://xcap.example.com/services/resource-lists/users/bill/fr.xml/ 1920 ~~/resource-lists/list/list/entry%5b@uri=%22sip:petri@example.com%22%5d HTTP/1.1 1922 Bill decides to check on the URI for Nancy, so he fetches a 1923 particular attribute (Section 7.6): 1925 GET 1926 http://xcap.example.com/services/resource-lists/users/bill/fr.xml/ 1927 ~~/resource-lists/list/list/entry%5b2%5d/@uri HTTP/1.1 1929 and the server responds: 1931 HTTP/1.1 200 OK 1932 Etag: "ad88" 1933 Content-Type:application/xcap-att+xml 1935 "sip:nancy@example.com" 1937 12. Security Considerations 1939 Frequently, the data manipulated by XCAP contains sensitive 1940 information. To avoid eavesdroppers from seeing this information, it 1941 is RECOMMENDED that an admistrator hand out an https URI as the XCAP 1942 root URI. This will result in TLS-encrypted communications between 1943 the client and server, preventing any eavesdropping. 1945 Client and server authentication are also important. A client needs 1946 to be sure it is talking to the server it believes it is contacting. 1947 Otherwise, it may be given false information, which can lead to 1948 denial of service attacks against a client. To prevent this, a 1949 client SHOULD attempt to upgrade [14] any connections to TLS. 1950 Similarly, authorization of read and write operations against the 1951 data is important, and this requires client authentication. As a 1952 result, a server SHOULD challenge a client using HTTP Digest [10] to 1953 establish its identity, and this SHOULD be done over a TLS 1954 connection. 1956 13. IANA Considerations 1958 There are several IANA considerations associated with this 1959 specification. 1961 13.1 XCAP Application Usage IDs 1963 This specification instructs IANA to create a new registry for XCAP 1964 application usage IDs (AUIDs). This registry is defined as a table 1965 that contains three colums: 1966 AUID: This will be a string provided in the IANA registrations into 1967 the registry. 1968 Description: This is text that is supplied by the IANA registration 1969 into the registry. 1970 Document: This is a reference to the RFC containing the registration. 1972 This specification instructs IANA to create this table with an 1973 initial entry. The resulting table would look like: 1975 Application Unique Description Document 1976 ID (AUID) 1977 ----------------------------------------------------------- 1979 xcap-caps Capabilities of an RFC XXXX 1980 XCAP server 1982 [[NOTE TO IANA/RFC-EDITOR: Please replace XXXX with the RFC number of 1983 this specification.]] 1985 XCAP AUIDs are registered by the IANA when they are published in 1986 standards track RFCs. The IANA Considerations section of the RFC 1987 must include the following information, which appears in the IANA 1988 registry along with the RFC number of the publication. 1989 Name of the AUID. The name MAY be of any length, but SHOULD be no 1990 more than twenty characters long. The name MUST consist of 1991 alphanum [15] characters only. 1992 Descriptive text that describes the application usage. 1994 13.2 MIME Types 1996 This specification requests the registration of several new MIME 1997 types according to the procedures of RFC 2048 [7] and guidelines in 1998 RFC 3023 [8]. 2000 13.2.1 application/xcap-el+xml MIME Type 2002 This specification registers a new MIME type according to the 2003 MIME media type name: application 2004 MIME subtype name: xcap-el+xml 2005 Mandatory parameters: none 2006 Optional parameters: Same as charset parameter application/xml as 2007 specified in RFC 3023 [8]. 2008 Encoding considerations: Same as encoding considerations of 2009 application/xml as specified in RFC 3023 [8]. 2010 Security considerations: See Section 10 of RFC 3023 [8]. 2011 Interoperability considerations: none. 2012 Published specification: RFC XXXX [[NOTE TO RFC EDITOR: Please 2013 replace XXXX with the published RFC number of this 2014 specification.]] 2015 Applications which use this media type: This document type has been 2016 used to support transport of XML fragment bodies in RFC XXXX 2017 [[NOTE TO RFC EDITOR: Please replace XXXX with the published RFC 2018 number of this specification.]], the XML Configuration Access 2019 Protocol (XCAP). 2020 Additional Information: 2021 Magic Number: None 2022 File Extension: .xel or .xml 2023 Macintosh file type code: "TEXT" 2024 Personal and email address for further information: Jonathan 2025 Rosenberg, jdrosen@jdrosen.net 2026 Intended usage: COMMON 2027 Author/Change controller: The IETF. 2029 13.2.2 application/xcap-att+xml MIME Type 2030 MIME media type name: application 2031 MIME subtype name: xcap-att+xml 2032 Mandatory parameters: none 2033 Optional parameters: Same as charset parameter application/xml as 2034 specified in RFC 3023 [8]. 2035 Encoding considerations: Same as encoding considerations of 2036 application/xml as specified in RFC 3023 [8]. 2037 Security considerations: See Section 10 of RFC 3023 [8]. 2038 Interoperability considerations: none. 2039 Published specification: RFC XXXX [[NOTE TO RFC EDITOR: Please 2040 replace XXXX with the published RFC number of this 2041 specification.]]. 2042 Applications which use this media type: This document type has been 2043 used to support transport of XML attribute values in RFC XXXX 2044 [[NOTE TO RFC EDITOR: Please replace XXXX with the published RFC 2045 number of this specification.]], the XML Configuration Access 2046 Protocol (XCAP). 2047 Additional Information: 2049 Magic Number: None 2050 File Extension: .xav 2051 Macintosh file type code: "TEXT" 2052 Personal and email address for further information: Jonathan 2053 Rosenberg, jdrosen@jdrosen.net 2054 Intended usage: COMMON 2055 Author/Change controller: The IETF. 2057 13.2.3 application/xcap-error+xml MIME Type 2058 MIME media type name: application 2059 MIME subtype name: xcap-error+xml 2060 Mandatory parameters: none 2061 Optional parameters: Same as charset parameter application/xml as 2062 specified in RFC 3023 [8]. 2063 Encoding considerations: Same as encoding considerations of 2064 application/xml as specified in RFC 3023 [8]. 2065 Security considerations: See Section 10 of RFC 3023 [8]. 2066 Interoperability considerations: none. 2067 Published specification: This specification. 2068 Applications which use this media type: This document type conveys 2069 error conditions defined in RFC XXXX. [[NOTE TO RFC EDITOR: 2070 Please replace XXXX with the published RFC number of this 2071 specification.]] 2072 Additional Information: 2073 Magic Number: None 2074 File Extension: .xe 2075 Macintosh file type code: "TEXT" 2076 Personal and email address for further information: Jonathan 2077 Rosenberg, jdrosen@jdrosen.net 2078 Intended usage: COMMON 2079 Author/Change controller: The IETF. 2081 13.2.4 application/xcap-caps+xml MIME Type 2082 MIME media type name: application 2083 MIME subtype name: xcap-caps+xml 2084 Mandatory parameters: none 2085 Optional parameters: Same as charset parameter application/xml as 2086 specified in RFC 3023 [8]. 2087 Encoding considerations: Same as encoding considerations of 2088 application/xml as specified in RFC 3023 [8]. 2089 Security considerations: See Section 10 of RFC 3023 [8]. 2090 Interoperability considerations: none. 2091 Published specification: This specification. 2092 Applications which use this media type: This document type conveys 2093 capabililites of an XML Configuration Access Protocol (XCAP) 2094 server, as defined in RFC XXXX. [[NOTE TO RFC EDITOR: Please 2095 replace XXXX with the published RFC number of this 2096 specification.]] 2098 Additional Information: 2099 Magic Number: None 2100 File Extension: .xe 2101 Macintosh file type code: "TEXT" 2102 Personal and email address for further information: Jonathan 2103 Rosenberg, jdrosen@jdrosen.net 2104 Intended usage: COMMON 2105 Author/Change controller: The IETF. 2107 13.3 URN Sub-Namespace Registrations 2109 This specification registers several new XML namespaces, as per the 2110 guidelines in RFC 3688 [16]. 2112 13.3.1 urn:ietf:params:xml:ns:xcap-error 2113 URI: The URI for this namespace is urn:ietf:params:xml:ns:xcap-error 2114 Registrant Contact: IETF, SIMPLE working group, (simple@ietf.org), 2115 Jonathan Rosenberg (jdrosen@jdrosen.net). 2116 XML: 2118 BEGIN 2119 2120 2122 2123 2124 2126 XCAP Error Namespace 2127 2128 2129

Namespace for XCAP Error Documents

2130

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

2131

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

2134 2135 2136 END 2138 13.3.2 urn:ietf:params:xml:ns:xcap-caps 2139 URI: The URI for this namespace is urn:ietf:params:xml:ns:xcap-caps 2140 Registrant Contact: IETF, SIMPLE working group, (simple@ietf.org), 2141 Jonathan Rosenberg (jdrosen@jdrosen.net). 2143 XML: 2145 BEGIN 2146 2147 2149 2150 2151 2153 XCAP Capabilities Namespace 2154 2155 2156

Namespace for XCAP Capability Documents

2157

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

2158

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

2161 2162 2163 END 2165 13.4 XML Schema Registrations 2167 This section registers two XML schemas per the procedures in [16]. 2169 13.4.1 XCAP Error Schema Registration 2170 URI: urn:ietf:params:xml:schema:xcap-error 2171 Registrant Contact: IETF, SIMPLE working group, (simple@ietf.org), 2172 Jonathan Rosenberg (jdrosen@jdrosen.net). 2173 XML Schema: The XML for this schema can be found as the sole content 2174 of Section 9.2. 2176 13.4.2 XCAP Capabilities Schema Registration 2177 URI: urn:ietf:params:xml:schema:xcap-caps 2178 Registrant Contact: IETF, SIMPLE working group, (simple@ietf.org), 2179 Jonathan Rosenberg (jdrosen@jdrosen.net). 2180 XML Schema: The XML for this schema can be found as the sole content 2181 of Section 10.2. 2183 14. Acknowledgements 2185 The author would like to thank Ben Campbell, Eva-Maria Leppanen, 2186 Hisham Khartabil, Chris Newman, Joel Halpern, Jari Urpalainen, and 2187 Lisa Dusseault for their input and comments. A special thanks to Ted 2188 Hardie for his input and support. 2190 15. References 2192 15.1 Normative References 2194 [1] Bray, T., Paoli, J., Sperberg-McQueen, C. and E. Maler, 2195 "Extensible Markup Language (XML) 1.0 (Second Edition)", W3C 2196 FirstEdition REC-xml-20001006, October 2000. 2198 [2] Thompson, H., Beech, D., Maloney, M. and N. Mendelsohn, "XML 2199 Schema Part 1: Structures", W3C REC REC-xmlschema-1-20010502, 2200 May 2001. 2202 [3] Bray, T., Hollander, D. and A. Layman, "Namespaces in XML", W3C 2203 REC REC-xml-names-19990114, January 1999. 2205 [4] Grosso, P. and D. Veillard, "XML Fragment Interchange", W3C CR 2206 CR-xml-fragment-20010212, February 2001. 2208 [5] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., 2209 Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol -- 2210 HTTP/1.1", RFC 2616, June 1999. 2212 [6] Bradner, S., "Key words for use in RFCs to Indicate Requirement 2213 Levels", BCP 14, RFC 2119, March 1997. 2215 [7] Freed, N., Klensin, J. and J. Postel, "Multipurpose Internet 2216 Mail Extensions (MIME) Part Four: Registration Procedures", BCP 2217 13, RFC 2048, November 1996. 2219 [8] Murata, M., St. Laurent, S. and D. Kohn, "XML Media Types", RFC 2220 3023, January 2001. 2222 [9] Clark, J. and S. DeRose, "XML Path Language (XPath) Version 2223 1.0", W3C REC REC-xpath-19991116, November 1999. 2225 [10] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 2226 Leach, P., Luotonen, A. and L. Stewart, "HTTP Authentication: 2227 Basic and Digest Access Authentication", RFC 2617, June 1999. 2229 [11] Crocker, D. and P. Overell, "Augmented BNF for Syntax 2230 Specifications: ABNF", RFC 2234, November 1997. 2232 [12] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform 2233 Resource Identifiers (URI): Generic Syntax", RFC 2396, August 2234 1998. 2236 [13] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 2238 [14] Khare, R. and S. Lawrence, "Upgrading to TLS Within HTTP/1.1", 2239 RFC 2817, May 2000. 2241 [15] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A., 2242 Peterson, J., Sparks, R., Handley, M. and E. Schooler, "SIP: 2243 Session Initiation Protocol", RFC 3261, June 2002. 2245 [16] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2246 January 2004. 2248 [17] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 2249 63, RFC 3629, November 2003. 2251 15.2 Informative References 2253 [18] Rosenberg, J., "A Presence Event Package for the Session 2254 Initiation Protocol (SIP)", draft-ietf-simple-presence-10 (work 2255 in progress), January 2003. 2257 [19] Rosenberg, J., "A Watcher Information Event Template-Package 2258 for the Session Initiation Protocol (SIP)", 2259 draft-ietf-simple-winfo-package-05 (work in progress), January 2260 2003. 2262 [20] Rosenberg, J., "An Extensible Markup Language (XML) Based 2263 Format for Watcher Information", 2264 draft-ietf-simple-winfo-format-04 (work in progress), January 2265 2003. 2267 [21] Roach, A., Rosenberg, J. and B. Campbell, "A Session Initiation 2268 Protocol (SIP) Event Notification Extension for Resource 2269 Lists", draft-ietf-simple-event-list-04 (work in progress), 2270 June 2003. 2272 [22] Rosenberg, J. and M. Isomaki, "Requirements for Manipulation of 2273 Data Elements in Session Initiation Protocol (SIP) for Instant 2274 Messaging and Presence Leveraging Extensions (SIMPLE) Systems", 2275 draft-ietf-simple-data-req-03 (work in progress), June 2003. 2277 [23] Rosenberg, J., "An Extensible Markup Language (XML) 2278 Configuration Access Protocol (XCAP) Usage for Presence 2279 Lists", draft-ietf-simple-xcap-list-usage-02 (work in 2280 progress), February 2004. 2282 [24] Peterson, J., "Common Profile for Presence (CPP)", 2283 draft-ietf-impp-pres-04 (work in progress), October 2003. 2285 [25] Newman, C. and J. Myers, "ACAP -- Application Configuration 2286 Access Protocol", RFC 2244, November 1997. 2288 [26] Day, M., Rosenberg, J. and H. Sugano, "A Model for Presence and 2289 Instant Messaging", RFC 2778, February 2000. 2291 [27] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA 2292 Considerations Section in RFCs", BCP 26, RFC 2434, October 2293 1998. 2295 [28] Roach, A., "Session Initiation Protocol (SIP)-Specific Event 2296 Notification", RFC 3265, June 2002. 2298 Author's Address 2300 Jonathan Rosenberg 2301 dynamicsoft 2302 600 Lanidex Plaza 2303 Parsippany, NJ 07054 2304 US 2306 Phone: +1 973 952-5000 2307 EMail: jdrosen@dynamicsoft.com 2308 URI: http://www.jdrosen.net 2310 Intellectual Property Statement 2312 The IETF takes no position regarding the validity or scope of any 2313 Intellectual Property Rights or other rights that might be claimed to 2314 pertain to the implementation or use of the technology described in 2315 this document or the extent to which any license under such rights 2316 might or might not be available; nor does it represent that it has 2317 made any independent effort to identify any such rights. Information 2318 on the procedures with respect to rights in RFC documents can be 2319 found in BCP 78 and BCP 79. 2321 Copies of IPR disclosures made to the IETF Secretariat and any 2322 assurances of licenses to be made available, or the result of an 2323 attempt made to obtain a general license or permission for the use of 2324 such proprietary rights by implementers or users of this 2325 specification can be obtained from the IETF on-line IPR repository at 2326 http://www.ietf.org/ipr. 2328 The IETF invites any interested party to bring to its attention any 2329 copyrights, patents or patent applications, or other proprietary 2330 rights that may cover technology that may be required to implement 2331 this standard. Please address the information to the IETF at 2332 ietf-ipr@ietf.org. 2334 Disclaimer of Validity 2336 This document and the information contained herein are provided on an 2337 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 2338 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 2339 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 2340 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 2341 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 2342 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 2344 Copyright Statement 2346 Copyright (C) The Internet Society (2004). This document is subject 2347 to the rights, licenses and restrictions contained in BCP 78, and 2348 except as set forth therein, the authors retain all their rights. 2350 Acknowledgment 2352 Funding for the RFC Editor function is currently provided by the 2353 Internet Society.