From 4bfd864f10b68b71482b35c818559068ef8d5797 Mon Sep 17 00:00:00 2001 From: Thomas Voss Date: Wed, 27 Nov 2024 20:54:24 +0100 Subject: doc: Add RFC documents --- doc/rfc/rfc4825.txt | 3979 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 3979 insertions(+) create mode 100644 doc/rfc/rfc4825.txt (limited to 'doc/rfc/rfc4825.txt') diff --git a/doc/rfc/rfc4825.txt b/doc/rfc/rfc4825.txt new file mode 100644 index 0000000..41d28eb --- /dev/null +++ b/doc/rfc/rfc4825.txt @@ -0,0 +1,3979 @@ + + + + + + +Network Working Group J. Rosenberg +Request for Comments: 4825 Cisco +Category: Standards Track May 2007 + + + The Extensible Markup Language (XML) + Configuration Access Protocol (XCAP) + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The IETF Trust (2007). + +Abstract + + This specification defines the Extensible Markup Language (XML) + Configuration Access Protocol (XCAP). XCAP allows a client to read, + write, and modify application configuration data stored in XML format + on a server. XCAP maps XML document sub-trees and element attributes + to HTTP URIs, so that these components can be directly accessed by + HTTP. + + + + + + + + + + + + + + + + + + + + + + + +Rosenberg Standards Track [Page 1] + +RFC 4825 XCAP May 2007 + + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 + 2. Overview of Operation . . . . . . . . . . . . . . . . . . . . 5 + 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 + 4. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 6 + 5. Application Usages . . . . . . . . . . . . . . . . . . . . . . 7 + 5.1. Application Unique ID (AUID) . . . . . . . . . . . . . . . 7 + 5.2. Default Document Namespace . . . . . . . . . . . . . . . . 8 + 5.3. Data Validation . . . . . . . . . . . . . . . . . . . . . 9 + 5.4. Data Semantics . . . . . . . . . . . . . . . . . . . . . . 10 + 5.5. Naming Conventions . . . . . . . . . . . . . . . . . . . . 11 + 5.6. Resource Interdependencies . . . . . . . . . . . . . . . . 11 + 5.7. Authorization Policies . . . . . . . . . . . . . . . . . . 12 + 5.8. Data Extensibility . . . . . . . . . . . . . . . . . . . . 12 + 5.9. Documenting Application Usages . . . . . . . . . . . . . . 13 + 5.10. Guidelines for Creating Application Usages . . . . . . . . 13 + 6. URI Construction . . . . . . . . . . . . . . . . . . . . . . . 15 + 6.1. XCAP Root . . . . . . . . . . . . . . . . . . . . . . . . 15 + 6.2. Document Selector . . . . . . . . . . . . . . . . . . . . 16 + 6.3. Node Selector . . . . . . . . . . . . . . . . . . . . . . 18 + 6.4. Namespace Bindings for the Selector . . . . . . . . . . . 23 + 7. Client Operations . . . . . . . . . . . . . . . . . . . . . . 24 + 7.1. Create or Replace a Document . . . . . . . . . . . . . . . 26 + 7.2. Delete a Document . . . . . . . . . . . . . . . . . . . . 26 + 7.3. Fetch a Document . . . . . . . . . . . . . . . . . . . . . 26 + 7.4. Create or Replace an Element . . . . . . . . . . . . . . . 26 + 7.5. Delete an Element . . . . . . . . . . . . . . . . . . . . 29 + 7.6. Fetch an Element . . . . . . . . . . . . . . . . . . . . . 30 + 7.7. Create or Replace an Attribute . . . . . . . . . . . . . . 30 + 7.8. Delete an Attribute . . . . . . . . . . . . . . . . . . . 31 + 7.9. Fetch an Attribute . . . . . . . . . . . . . . . . . . . . 31 + 7.10. Fetch Namespace Bindings . . . . . . . . . . . . . . . . . 32 + 7.11. Conditional Operations . . . . . . . . . . . . . . . . . . 32 + 8. Server Behavior . . . . . . . . . . . . . . . . . . . . . . . 34 + 8.1. POST Handling . . . . . . . . . . . . . . . . . . . . . . 35 + 8.2. PUT Handling . . . . . . . . . . . . . . . . . . . . . . . 35 + 8.2.1. Locating the Parent . . . . . . . . . . . . . . . . . 35 + 8.2.2. Verifying Document Content . . . . . . . . . . . . . . 36 + 8.2.3. Creation . . . . . . . . . . . . . . . . . . . . . . . 37 + 8.2.4. Replacement . . . . . . . . . . . . . . . . . . . . . 41 + 8.2.5. Validation . . . . . . . . . . . . . . . . . . . . . . 42 + 8.2.6. Conditional Processing . . . . . . . . . . . . . . . . 43 + 8.2.7. Resource Interdependencies . . . . . . . . . . . . . . 44 + 8.3. GET Handling . . . . . . . . . . . . . . . . . . . . . . . 44 + 8.4. DELETE Handling . . . . . . . . . . . . . . . . . . . . . 45 + 8.5. Managing Etags . . . . . . . . . . . . . . . . . . . . . . 46 + 9. Cache Control . . . . . . . . . . . . . . . . . . . . . . . . 47 + + + +Rosenberg Standards Track [Page 2] + +RFC 4825 XCAP May 2007 + + + 10. Namespace Binding Format . . . . . . . . . . . . . . . . . . . 47 + 11. Detailed Conflict Reports . . . . . . . . . . . . . . . . . . 47 + 11.1. Document Structure . . . . . . . . . . . . . . . . . . . . 48 + 11.2. XML Schema . . . . . . . . . . . . . . . . . . . . . . . . 50 + 12. XCAP Server Capabilities . . . . . . . . . . . . . . . . . . . 53 + 12.1. Application Unique ID (AUID) . . . . . . . . . . . . . . . 54 + 12.2. XML Schema . . . . . . . . . . . . . . . . . . . . . . . . 54 + 12.3. Default Document Namespace . . . . . . . . . . . . . . . . 56 + 12.4. MIME Type . . . . . . . . . . . . . . . . . . . . . . . . 56 + 12.5. Validation Constraints . . . . . . . . . . . . . . . . . . 56 + 12.6. Data Semantics . . . . . . . . . . . . . . . . . . . . . . 56 + 12.7. Naming Conventions . . . . . . . . . . . . . . . . . . . . 56 + 12.8. Resource Interdependencies . . . . . . . . . . . . . . . . 56 + 12.9. Authorization Policies . . . . . . . . . . . . . . . . . . 56 + 13. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 + 14. Security Considerations . . . . . . . . . . . . . . . . . . . 59 + 15. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 60 + 15.1. XCAP Application Unique IDs . . . . . . . . . . . . . . . 60 + 15.2. MIME Types . . . . . . . . . . . . . . . . . . . . . . . . 61 + 15.2.1. application/xcap-el+xml MIME Type . . . . . . . . . . 61 + 15.2.2. application/xcap-att+xml MIME Type . . . . . . . . . . 62 + 15.2.3. application/xcap-ns+xml MIME Type . . . . . . . . . . 63 + 15.2.4. application/xcap-error+xml MIME Type . . . . . . . . . 64 + 15.2.5. application/xcap-caps+xml MIME Type . . . . . . . . . 64 + 15.3. URN Sub-Namespace Registrations . . . . . . . . . . . . . 65 + 15.3.1. urn:ietf:params:xml:ns:xcap-error . . . . . . . . . . 65 + 15.3.2. urn:ietf:params:xml:ns:xcap-caps . . . . . . . . . . . 66 + 15.4. XML Schema Registrations . . . . . . . . . . . . . . . . . 67 + 15.4.1. XCAP Error Schema Registration . . . . . . . . . . . . 67 + 15.4.2. XCAP Capabilities Schema Registration . . . . . . . . 67 + 16. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 67 + 17. References . . . . . . . . . . . . . . . . . . . . . . . . . . 67 + 17.1. Normative References . . . . . . . . . . . . . . . . . . . 67 + 17.2. Informative References . . . . . . . . . . . . . . . . . . 69 + + + + + + + + + + + + + + + + + +Rosenberg Standards Track [Page 3] + +RFC 4825 XCAP May 2007 + + +1. Introduction + + In many communications applications, such as Voice over IP, instant + messaging, and presence, it is necessary for network servers to + access per-user information in the process of servicing a request. + This per-user information resides within the network, but is managed + by the end user themselves. Its management can be done through a + multiplicity of access points, including the web, a wireless handset, + or a PC application. + + There are many examples of per-user information. One is presence + [20] authorization policy, which defines rules about which watchers + are allowed to subscribe to a presentity, and what information they + are allowed to access. Another is presence lists, which are lists of + users whose presence is desired by a watcher [26]. One way to obtain + presence information for the list is to subscribe to a resource which + represents that list [21]. In this case, the Resource List Server + (RLS) requires access to this list in order to process a SIP [16] + SUBSCRIBE [28] request for it. Another way to obtain presence for + the users on the list is for a watcher to subscribe to each user + individually. In that case, it is convenient to have a server store + the list, and when the client boots, it fetches the list from the + server. This would allow a user to access their resource lists from + different clients. + + This specification describes a protocol that can be used to + manipulate this per-user data. It is called the Extensible Markup + Language (XML) Configuration Access Protocol (XCAP). XCAP is a set + of conventions for mapping XML documents and document components into + HTTP URIs, rules for how the modification of one resource affects + another, data validation constraints, and authorization policies + associated with access to those resources. Because of this + structure, normal HTTP primitives can be used to manipulate the data. + XCAP is based heavily on ideas borrowed from the Application + Configuration Access Protocol (ACAP) [25], but it is not an extension + of it, nor does it have any dependencies on it. Like ACAP, XCAP is + meant to support the configuration needs for a multiplicity of + applications, rather than just a single one. + + XCAP was not designed as a general purpose XML search protocol, XML + database update protocol, nor a general purpose, XML-based + configuration protocol for network elements. + + + + + + + + + +Rosenberg Standards Track [Page 4] + +RFC 4825 XCAP May 2007 + + +2. Overview of Operation + + Each application (where an application refers to a use case that + implies a collection of data and associated semantics) that makes use + of XCAP specifies an application usage (Section 5). This application + usage defines the XML schema [2] for the data used by the + application, along with other key pieces of information. The + principal task of XCAP is to allow clients to read, write, modify, + create, and delete pieces of that data. These operations are + supported using HTTP/1.1 [6]. An XCAP server acts as a repository + for collections of XML documents. There will be documents stored for + each application. Within each application, there are documents + stored for each user. Each user can have a multiplicity of documents + for a particular application. To access some component of one of + those documents, XCAP defines an algorithm for constructing a URI + that can be used to reference that component. Components refer to + any element or attribute within the document. Thus, the HTTP URIs + used by XCAP point to a document, or to pieces of information that + are finer grained than the XML document itself. An HTTP resource + that follows the naming conventions and validation constraints + defined here is called an XCAP resource. + + Since XCAP resources are also HTTP resources, they can be accessed + using HTTP methods. Reading an XCAP resource is accomplished with + HTTP GET, creating or modifying one is done with HTTP PUT, and + removing one of the resources is done with an HTTP DELETE. XCAP + resources do not represent processing scripts; as a result, POST + operations to HTTP URIs representing XCAP resources are not defined. + Properties that HTTP associates with resources, such as entity tags, + also apply to XCAP resources. Indeed, entity tags are particularly + useful in XCAP, as they allow a number of conditional operations to + be performed. + + XML documents that are equivalent for the purposes of many + applications may differ in their physical representation. With XCAP + resources, the canonical form with comments [19] of an XML document + determines the logical equivalence. In other words, the canonical + specification determines how significant whitespace MUST be + processed. It also implies that, for example, new inserted + attributes may appear in any order within the physical + representation. + +3. Terminology + + In this document, the key words "MUST", "MUST NOT", "REQUIRED", + "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", + and "OPTIONAL" are to be interpreted as described in RFC 2119 [7] and + indicate requirement levels for compliant implementations. + + + +Rosenberg Standards Track [Page 5] + +RFC 4825 XCAP May 2007 + + +4. Definitions + + The following terms are used throughout this document: + + XCAP Resource: An HTTP resource representing an XML document, an + element within an XML document, or an attribute of an element + within an XML document that follows the naming and validation + constraints of XCAP. + + XCAP Server: An HTTP server that understands how to follow the + naming and validation constraints defined in this specification. + + XCAP Client: An HTTP client that understands how to follow the + naming and validation constraints defined in this specification. + + Application: A collection of software components within a network + whose operation depends on data managed and stored on an XCAP + server. + + Application Usage: Detailed information on the interaction of an + application with the XCAP server. + + Application Unique ID (AUID): A unique identifier within the + namespace of application unique IDs created by this specification + that differentiates XCAP resources accessed by one application + from XCAP resources accessed by another. + + Naming Conventions: The part of an application usage that specifies + well-known URIs used by an application, or more generally, + specifies the URIs that are typically accessed by an application + during its processing. + + XCAP User Identifier (XUI): The XUI is a string, valid as a path + element in an HTTP URI, that is associated with each user served + by the XCAP server. + + XCAP Root: A context that contains all the documents across all + application usages and users that are managed by the server. + + Document Selector: A sequence of path segments, with each segment + being separated by a "/", that identify the XML document within an + XCAP root that is being selected. + + Node Selector: A sequence of path segments, with each segment being + separated by a "/", that identify the XML node (element or + attribute) being selected within a document. + + + + + +Rosenberg Standards Track [Page 6] + +RFC 4825 XCAP May 2007 + + + Node Selector Separator: A single path segment equal to two tilde + characters "~~" that is used to separate the document selector + from the node selector within an HTTP URI. + + Document URI: The HTTP URI containing the XCAP root and document + selector, resulting in the selection of a specific document. As a + result, performing a GET against the document URI would retrieve + the document. + + Node URI: The HTTP URI containing the XCAP root, document selector, + node selector separator, and node selector, resulting in the + selection of a specific XML node. + + XCAP Root URI: An HTTP URI that represents the XCAP root. Although + a syntactically valid URI, the XCAP Root URI does not correspond + to an actual resource on an XCAP server. Actual resources are + created by appending additional path information to the XCAP Root + URI. + + Global Tree: A URI that represents the parent for all global + documents for a particular application usage within a particular + XCAP root. + + Home Directory: A URI that represents the parent for all documents + for a particular user for a particular application usage within a + particular XCAP root. + + Positional Insertion: A PUT operation that results in the insertion + of a new element into a document such that its position, relative + to other children of the same parent, is set by the client. + +5. Application Usages + + Each XCAP resource on a server is associated with an application. In + order for an application to use those resources, application specific + conventions must be specified. Those conventions include the XML + schema that defines the structure and constraints of the data, well- + known URIs to bootstrap access to the data, and so on. All of those + application specific conventions are defined by the application + usage. + +5.1. Application Unique ID (AUID) + + Each application usage is associated with a name, called an + Application Unique ID (AUID). This name uniquely identifies the + application usage within the namespace of application usages, and is + different from AUIDs used by other applications. AUIDs exist in one + of two namespaces. The first namespace is the IETF namespace. This + + + +Rosenberg Standards Track [Page 7] + +RFC 4825 XCAP May 2007 + + + namespace contains a set of tokens, each of which is registered with + IANA. These registrations occur with the publication of standards + track RFCs [27], based on the guidelines in Section 15. The second + namespace is the vendor-proprietary namespace. Each AUID in that + namespace is prefixed with the reverse domain name of the + organization creating the AUID, followed by a period, followed by any + vendor defined token. As an example, the example.com domain can + create an AUID with the value "com.example.foo" but cannot create one + with the value "org.example.foo". AUIDs within the vendor namespace + do not need to be registered with IANA. The vendor namespace is also + meant to be used in lab environments where no central registry is + needed. The syntax for AUIDs, expressed in ABNF [12] (and using some + of the BNF defined in RFC 3986 [13]), is: + + AUID = global-a-uid / vendor-a-uid + global-a-uid = a-uid + a-uid = 1*a-uid-char + vendor-a-uid = rev-hostname "." a-uid + rev-hostname = toplabel *( "." domainlabel ) + domainlabel = alphanum + / alphanum *( alphanum / "-" ) alphanum + toplabel = ALPHA / ALPHA *( alphanum / "-" ) alphanum + a-uid-char = a-uid-unreserved / pct-encoded / sub-delims + / ":" / "@" + ;pct-encoded from RFC 3986 + ;sub-delims from RFC 3986 + alphanum = ALPHA / DIGIT + ;DIGIT from RFC 4234 + ;ALPHA from RFC 4234 + a-uid-unreserved = ALPHA / DIGIT / "-" / "_" / "~" + + The allowed characters for the auid production is a subset of the + pchar production defined in RFC 3986. In particular, it omits the + ".", which allows for the auid to be separated from the reverse + hostname. + +5.2. Default Document Namespace + + In order for the XCAP server to match a URI to an element or + attribute of a document, any XML namespace prefixes used within the + URI must be expanded [3]. This expansion requires a namespace + binding context. That context maps namespace prefixes to namespace + URIs. It also defines a default namespace that applies to elements + in the URI without namespace prefixes. The namespace binding context + comes from two sources. First, the mapping of namespace prefixes to + namespace URIs is obtained from the URI itself (see Section 6.4). + However, the default document namespace is defined by the application + usage itself, and applies to all URIs referencing resources within + + + +Rosenberg Standards Track [Page 8] + +RFC 4825 XCAP May 2007 + + + that application usage. All application usages MUST define a + namespace URI that represents the default document namespace to be + used when evaluating URIs. The default document namespace does not + apply to elements or attributes within the documents themselves -- it + applies only to the evaluation of URIs within that application usage. + Indeed, the term 'default document namespace' is distinct from the + term 'default namespace'. The latter has the standard meaning within + XML documents, and the former refers to the default used in + evaluation of XCAP URIs. XCAP does not change in any way the + mechanisms for determining the default namespace within XML + documents. However, if a document contains a URI representing an + XCAP resource, the default document namespace defined by the + application usage applies to that URI as well. + +5.3. Data Validation + + One of the responsibilities of an XCAP server is to validate the + content of each XCAP resource when an XCAP client tries to modify + one. This is done using two mechanisms. Firstly, all application + usages MUST describe their document contents using XML schema [2]. + The application usage MUST also identify the MIME type for documents + compliant to that schema. + + Unfortunately, XML schemas cannot represent every form of data + constraint. As an example, one XML element may contain an integer + that defines the maximum number of instances of another element. + This constraint cannot be represented with XML schema. However, such + constraints may be important to the application usage. The + application usage defines any additional constraints beyond those in + the schema. + + Of particular importance are uniqueness constraints. In many cases, + an application will require that there be only one instance of some + element or attribute within a particular scope. Each uniqueness + constraint needs to be specified by identifying the field, or + combinations of fields, that need to be unique, and then identifying + the scope in which that uniqueness applies. One typical scope is the + set of all elements of a certain name within the same parent. + Another typical scope is the set of all URIs valid within a + particular domain. In some cases, these constraints can be specified + using XML schema, which provides the element for this + purpose. Other uniqueness constraints, such as URI uniqueness across + a domain, cannot be expressed by schema. Whether or not the schema + is used to express some of the uniqueness requirements, the + application usage MUST specify all uniqueness requirements when it + defines its data validation needs. + + + + + +Rosenberg Standards Track [Page 9] + +RFC 4825 XCAP May 2007 + + + For example, the resource lists application usage [22] requires that + each element have a unique value for the "name" attribute + within a single parent. As another example, the RLS services + application usage [22] requires that the value of the "uri" attribute + of the element be a URI that is unique within the domain of + the URI. + + URI constraints represent another form of constraints. These are + constraints on the scheme or structure of the scheme-specific part of + the URI. These kinds of constraints cannot be expressed in an XML + schema. If these constraints are important to an application usage, + they need to be explicitly called out. + + Another important data constraint is referential integrity. + Referential integrity is important when the name or value of an + element or attribute is used as a key to select another element or + attribute. An application usage MAY specify referential integrity + constraints. However, XCAP servers are not a replacement for + Relational Database Management Systems (RDBMS), and therefore clients + MUST NOT depend on servers to maintain referential integrity. XCAP + clients are responsible for making all the appropriate changes to + documents in order to maintain referential integrity. + + Another constraint is character encoding. XML allows documents to be + encoded using several different character sets. However, this + specification mandates that all documents used with XCAP MUST be + encoded using UTF-8. This cannot be changed by an application usage. + + The data validation information is consumed by both clients, which + use them to make sure they construct requests that will be accepted + by the server, and by servers, which validate the constraints when + they receive a request (with the exception of referential integrity + constraints, which are not validated by the server). + +5.4. Data Semantics + + For each application usage, the data present in the XML document has + a well-defined semantic. The application usage defines that + semantic, so that a client can properly construct a document in order + to achieve the desired result. They are not used by the server, as + it is purposefully unaware of the semantics of the data it is + managing. The data semantics are expressed in English prose by the + application usage. + + One particularly important semantic is the base URI that is to be + used for the resolution of any relative URI references pointed to + XCAP resources. As discussed below, relative URI references pointing + to XCAP resources cannot be resolved using the retrieval URI as the + + + +Rosenberg Standards Track [Page 10] + +RFC 4825 XCAP May 2007 + + + base URI. Therefore, it is up to the application usage to specify + the base URI. + +5.5. Naming Conventions + + In addition to defining the meaning of the document in the context of + a particular application, an application usage has to specify how the + applications obtain the documents they need. In particular, it needs + to define any well-known URIs used for bootstrapping purposes, and + document any other conventions on the URIs used by an application. + It should also document how documents reference each other. These + conventions are called naming conventions. + + For many application usages, users need only a single document. In + such a case, it is RECOMMENDED that the application usage require + that this document be called "index" and exist within the user's home + directory. + + As an example, the RLS services application usage allows an RLS to + obtain the contents of a resource list when the RLS receives a + SUBSCRIBE request for a SIP URI identifying an RLS service. The + application usage specifies that the list of service definitions is + present within a specific document with a specific name within the + global tree. This allows the RLS to perform a single XCAP request to + fetch the service definition for the service associated with the SIP + URI in a SUBSCRIBE request. + + Naming conventions are used by XCAP clients to construct their URIs. + The XCAP server does not make use of them. + +5.6. Resource Interdependencies + + When a user modifies an XCAP resource, the content of many other + resources is affected. For example, when a user deletes an XML + element within a document, it does so by issuing a DELETE request + against the URI for the element resource. However, deleting this + element also deletes all child elements and their attributes, each of + which is also an XCAP resource. As such, manipulation of one + resource affects the state of other resources. + + For the most part, these interdependencies are fully specified by the + XML schema used by the application usage. However, in some + application usages, there is a need for the server to relate + resources together, and such a relationship cannot be specified + through a schema. This occurs when changes in one document will + affect another document. Typically, this is the case when an + application usage is defining a document that acts as a collection of + information defined in other documents. + + + +Rosenberg Standards Track [Page 11] + +RFC 4825 XCAP May 2007 + + + As an example, when a user creates a new RLS service (that is, it + creates a new element within an RLS services document), the + server adds that element to a read-only global list of services + maintained by the server in the global tree. This read-only global + list is accessed by the RLS when processing a SIP SUBSCRIBE request. + + Resource interdependencies are used by both XCAP clients and servers. + +5.7. Authorization Policies + + By default, each user is able to access (read, modify, and delete) + all the documents below their home directory, and any user is able to + read documents within the global directory. However, only trusted + users, explicitly provisioned into the server, can modify global + documents. + + The application usage can specify a different authorization policy + that applies to all documents associated with that application usage. + An application usage can also specify whether another application + usage is used to define the authorization policies. An application + usage for setting authorization policies can also be defined + subsequent to the definition of the main application usage. In such + a case, the main application usage needs only to specify that such a + usage will be defined in the future. + + If an application usage does not wish to change the default + authorization policy, it can merely state that the default policy is + used. + + The authorization policies defined by the application usage are used + by the XCAP server during its operation. + +5.8. Data Extensibility + + An XCAP server MUST understand an application usage in order to + process an HTTP request made against a resource for that particular + application usage. However, it is not required for the server to + understand all of the contents of a document used by an application + usage. A server is required to understand the baseline schema + defined by the application usage. However, those schemas can define + points of extensibility where new content can be added from other + namespaces and corresponding schemas. Sometimes, the server will + understand those namespaces and therefore have access to their + schemas. Sometimes, it will not. + + A server MUST allow for documents that contain elements from + namespaces not known to the server. In such a case, the server + + + + +Rosenberg Standards Track [Page 12] + +RFC 4825 XCAP May 2007 + + + cannot validate that such content is schema compliant; it will only + verify that the XML is well-formed. + + If a client wants to verify that a server supports a particular + namespace before operating on a resource, it can query the server for + its capabilities using the XCAP Capabilities application usage, + discussed in Section 12. + +5.9. Documenting Application Usages + + Application usages are documented in specifications that convey the + information described above. In particular, an application usage + specification MUST provide the following information: + + o Application Unique ID (AUID): If the application usage is meant + for general use on the Internet, the application usage MUST + register the AUID into the IETF tree using the IANA procedures + defined in Section 15. + + o XML Schema + + o Default Document Namespace + + o MIME Type + + o Validation Constraints + + o Data Semantics + + o Naming Conventions + + o Resource Interdependencies + + o Authorization Policies + +5.10. Guidelines for Creating Application Usages + + The primary design task when creating a new application usage is to + define the schema. Although XCAP can be used with any XML document, + intelligent schema design will improve the efficiency and utility of + the document when it is manipulated with XCAP. + + XCAP provides three fundamental ways to select elements amongst a set + of siblings: by the expanded name of the element, by its position, or + by the value of a specific attribute. Positional selection always + allows a client to get exactly what it wants. However, it requires a + client to cache a copy of the document in order to construct the + predicate. Furthermore, if a client performs a PUT, it requires the + + + +Rosenberg Standards Track [Page 13] + +RFC 4825 XCAP May 2007 + + + client to reconstruct the PUT processing that a server would follow + in order to update its local cached copy. Otherwise, the client will + be forced to re-GET the document after every PUT, which is + inefficient. As such, it is a good idea to design schemas such that + common operations can be performed without requiring the client to + cache a copy of the document. + + Without positional selection, a client can pick the element at each + step by its expanded name or the value of an attribute. Many schemas + include elements that can be repeated within a parent (often, + minOccurs equals zero or one, and maxOccurs is unbounded). As such, + all of the elements have the same name. This leaves the attribute + value as the only way to select an element. Because of this, if an + application usage expects the user to manipulate elements or + attributes that are descendants of an element that can repeat, that + element SHOULD include, in its schema, an attribute that can be + suitably used as a unique index. Furthermore, the naming conventions + defined by that application usage SHOULD specify this uniqueness + constraint explicitly. + + URIs often make a good choice for such a unique index. They have + fundamental uniqueness properties, and are also usually of semantic + significance in the application usage. However, care must be taken + when using a URI as an attribute value. URI equality is usually + complex. However, attribute equality is performed by the server + using XML rules, which are based on case sensitive string comparison. + Thus, XCAP will match URIs based on lexical equality, not functional + equality. In such cases, an application usage SHOULD consider these + implications carefully. + + XCAP provides the ability of a client to operate on a single element, + attribute, or document at a time. As a result, it may be possible + that common operations the client might perform will require a + sequence of multiple requests. This is inefficient, and introduces + the possibility of failure conditions when another client modifies + the document in the middle of a sequence. In such a case, the client + will be forced to detect this case using entity tags (discussed below + in Section 7.11), and undo its previous changes. This is very + difficult. + + As a result, the schemas SHOULD be defined so that common operations + generally require a single request to perform. Consider an example. + Let's say an application usage is defining permissions for users to + perform certain operations. The schema can be designed in two ways. + The top level of the tree can identify users, and within each user, + there can be the permissions associated with the user. In an + alternative design, the top level of the tree identifies each + permission, and within that permission, the set of users who have it. + + + +Rosenberg Standards Track [Page 14] + +RFC 4825 XCAP May 2007 + + + If, in this application usage, it is common to change the permission + for a user from one value to another, the former schema design is + better for xcap; it will require a single PUT to make such a change. + In the latter case, either the entire document needs to be replaced + (which is a single operation), or two PUT operations need to occur -- + one to remove the user from the old permission, and one to add the + user to the new permission. + + Naming conventions form another key part of the design of an + application usage. The application usage should be certain that XCAP + clients know where to "start" to retrieve and modify documents of + interest. Generally, this will involve the specification of a well- + known document at a well-known URI. That document can contain + references to other documents that the client needs to read or + modify. + +6. URI Construction + + In order to manipulate an XCAP resource, the data must be represented + by an HTTP URI. XCAP defines a specific naming convention for + constructing these URIs. The URI is constructed by concatenating the + XCAP root with the document selector with the node selector separator + with a percent-encoded form of the node selector. This is followed + by an optional query component that defines namespace bindings used + in evaluating the URI. The XCAP root is the enclosing context in + which all XCAP resources live. The document selector is a path that + identifies a document within the XCAP root. The node selector + separator is a path segment with a value of double tilde ("~~"), and + SHOULD NOT be percent-encoded, as advised in Section 2.3 of RFC 3986 + [13]. URIs containing %7E%7E should be normalized to ~~ for + comparison; they are equivalent. The node selector separator is a + piece of syntactic sugar that separates the document selector from + the node selector. The node selector is an expression that + identifies a component of the document, such as an element or + attribute. It is possible that a "~~" appears as part of the node + selector itself; in such a case, the first "~~" in the URI is the + node selector separator. + + The sections below describe these components in more detail. + +6.1. XCAP Root + + The root of the XCAP hierarchy is called the XCAP root. It defines + the context in which all other resources exist. The XCAP root is + represented with an HTTP URI, called the XCAP Root URI. This URI is + a valid HTTP URI; however, it doesn't point to any resource that + actually exists on the server. Its purpose is to identify the root + of the tree within the domain where all XCAP documents are stored. + + + +Rosenberg Standards Track [Page 15] + +RFC 4825 XCAP May 2007 + + + It can be any valid HTTP URI, but MUST NOT contain a query component + (a complete XCAP URI may have a query component, but it is not part + of the XCAP root URI). It is RECOMMENDED that it be equal to + xcap.domain, where domain is the domain of the provider. As an + example, "http://xcap.example.com" might be used as the XCAP root URI + within the example.com domain. Typically, the XCAP root URI is + provisioned into client devices. If not explicitly provisioned, + clients SHOULD assume the form xcap.domain, where domain is the + domain of their service provider (for SIP, this would be the domain + part of their Address-of-Record (AOR)). A server or domain MAY + support multiple XCAP root URIs. In such a case, it is effectively + operating as if it were serving separate domains. There is never + information carryover or interactions between resources in different + XCAP root URIs. + + When a client generates an HTTP request to a URI identifying an XCAP + resource, RFC 2616 procedures for the construction of the Request-URI + apply. In particular, the authority component of the URI may not be + present in the Request-URI if the request is sent directly to the + origin server. + + The XCAP root URI can also be a relative HTTP URI. It is the + responsibility of the application usage to specify the base URI for + an HTTP URI representing an XCAP resource whenever such a URI appears + within a document defined by that application usage. Generally + speaking, it is unsafe to use the retrieval URI as the base URI. + This is because any URI that points to an ancestor for a particular + element or attribute can contain content including that element or + attribute. If that element or attribute contained a relative URI + reference, it would be resolved relative to whatever happened to be + used to retrieve the content, and this will often not be the base URI + defined by the application usage. + +6.2. Document Selector + + Each document within the XCAP root is identified by its document + selector. The document selector is a sequence of path segments, + separated by a slash ("/"). These path segments define a + hierarchical structure for organizing documents within any XCAP root. + The first path segment MUST be the XCAP AUID. So, continuing the + example above, all of the documents used by the resource lists + application would be under "http://xcap.example.com/resource-lists". + + o Implementors making use of HTTP servlets should be aware that XCAP + may require them to get authorization from the server + administrator to place resources within this specific subset of + the URI namespace. + + + + +Rosenberg Standards Track [Page 16] + +RFC 4825 XCAP May 2007 + + + It is assumed that each application will have data that is set by + users, and/or it will have global data that applies to all users. As + a result, beneath each AUID, there are two sub-trees. One, called + "users", holds the documents that are applicable to specific users, + and the other, called "global", holds documents applicable to all + users. The sub-tree beneath "global" is called the global tree. The + path segment after the AUID MUST either be "global" or "users". + + Within the "users" tree are zero or more sub-trees, each of which + identifies documents that apply to a specific user. Each user known + to the server is associated with a username, called the XCAP User + Identifier (XUI). Typically, an endpoint is provisioned with the + value of the XUI. For systems that support SIP applications, it is + RECOMMENDED that the XUI be equal to the Address-of-Record (AOR) for + the user (i.e., sip:joe@example.com). Since SIP endpoints generally + know their AOR, they will also know their XUI. As a consequence, if + no XUI is explicitly provisioned, a SIP User Agent SHOULD assume it + is equal to their AOR. This XUI MUST be used as the path segment + beneath the "users" segment. Since the SIP URI allows for characters + that are not permitted in HTTP URI path segments (such as the '?' and + '/' characters, which are permitted in the user part of the SIP URI), + any such characters MUST be percent encoded. The sub-tree beneath an + XUI for a particular user is called their home directory. "User" in + this context should be interpreted loosely; a user might correspond + to a device, for example. + + XCAP does not itself define what it means for documents to "apply" to + a user, beyond specification of a baseline authorization policy, + described below in Section 8. Each application usage can specify + additional authorization policies that depend on data used by the + application itself. + + The remainder of the document selector (the path following "global" + or the XUI) points to specific documents for that application usage. + Subdirectories are permitted, but are NOT RECOMMENDED. XCAP provides + no way to create sub-directories or to list their contents, thus + limiting their utility. If subdirectories are used, there MUST NOT + be a document in a directory with the same name as a sub-directory. + + The final path segment in the document selector identifies the actual + document in the hierarchy. This is equivalent to a filename, except + that XCAP does not require that its document resources be stored as + files in a file system. However, the term "filename" is used to + describe the final path segment in the document selector. In + traditional filesystems, the filename would have a filename + extension, such as ".xml". There is nothing in this specification + that requires or prevents such extensions from being used in the + filename. In some cases, the application usage will specify a naming + + + +Rosenberg Standards Track [Page 17] + +RFC 4825 XCAP May 2007 + + + convention for documents, and those naming conventions may or may not + specify a file extension. For example, in the RLS services + application usage [22], documents in the user's home directory with + the filename "index" will be used by the server to compute the global + index, which is also a document with the filename "index". Barring + specific guidelines in the application usage, if a user has a single + document for a particular application usage, this SHOULD be called + "index". + + When the naming conventions in an application usage do not constrain + the filename conventions (or, more generally, the document selector), + an application will know the filename (or more generally, the + document selector) because it is included as a reference in a + document accessed by the client. As another example, within the + index document defined by RLS services, the element has a + child element called whose content is a URI pointing + to a resource list within the users home directory. + + As a result, if the user creates a new document, and then references + that document from a well-known document (such as the index document + above), it doesn't matter whether or not the user includes an + extension in the filename, as long as the user is consistent and + maintains referential integrity. + + As an example, the path segment + "/resource-lists/users/sip:joe@example.com/index" is a document + selector. Concatenating the XCAP root URI with the document selector + produces the HTTP URI "http://xcap.example.com/resource-lists/users/ + sip:joe@example.com/index". In this URI, the AUID is "resource- + lists", and the document is in the user tree with the XUI + "sip:joe@example.com" with filename "index". + +6.3. Node Selector + + The node selector specifies specific nodes of the XML document that + are to be accessed. A node refers to an XML element, an attribute of + an element, or a set of namespace bindings. The node selector is an + expression that identifies an element, attribute, or set of namespace + bindings. Its grammar is: + + node-selector = element-selector ["/" terminal-selector] + terminal-selector = attribute-selector / namespace-selector / + extension-selector + element-selector = step *( "/" step) + step = by-name / by-pos / by-attr / by-pos-attr / + extension-selector + by-name = NameorAny + by-pos = NameorAny "[" position "]" + + + +Rosenberg Standards Track [Page 18] + +RFC 4825 XCAP May 2007 + + + position = 1*DIGIT + attr-test = "@" att-name "=" att-value + by-attr = NameorAny "[" attr-test "]" + by-pos-attr = NameorAny "[" position "]" "[" attr-test "]" + NameorAny = QName / "*" ; QName from XML Namespaces + att-name = QName + att-value = AttValue ; from XML specification + attribute-selector = "@" att-name + namespace-selector = "namespace::*" + extension-selector = 1*( %x00-2e / %x30-ff ) ; anything but "/" + + The QName grammar is defined in the XML namespaces [3] specification, + and the AttValue grammar is defined in the XML specification XML 1.0 + [1]. + + The extension-selector is included for purposes of extensibility. It + can be composed of any character except the slash, which is the + delimiter amongst steps. Any characters in an extension that cannot + be represented in a URI MUST be percent-encoded before placement into + a URI. + + Note that the double quote, left square bracket and right square + bracket characters, which are meaningful to XCAP, cannot be directly + represented in the HTTP URI. As a result, they are percent-encoded + when placed within the HTTP URI. In addition to these characters, an + apostrophe (') character can be used as a delimiter within XPath + expressions. Furthermore, since XML allows for non-ASCII characters, + the names of elements and attributes may not be directly + representable in a URI. Any such characters MUST be represented by + converting them to an octet sequence corresponding to their + representation in UTF-8, and then percent-encoding that sequence of + octets. + + Similarly, the XML specification defines the QName production for the + grammar for element and attribute names, and the AttValue production + for the attribute values. Unfortunately, the characters permitted by + these productions include some that are not allowed for pchar, which + is the production for the allowed set of characters in path segments + in the URI. The AttValue production allows many such characters + within the US-ASCII set, including the space. Those characters MUST + be percent-encoded when placed in the URI. Furthermore, QName and + AttValue allow many Unicode characters, outside of US-ASCII. When + these characters need to be represented in the HTTP URI, they are + percent-encoded. To do this, the data should be encoded first as + octets according to the UTF-8 character encoding [18], and then only + those octets that do not correspond to characters in the pchar set + should be percent-encoded. For example, the character A would be + represented as "A", the character LATIN CAPITAL LETTER A WITH GRAVE + + + +Rosenberg Standards Track [Page 19] + +RFC 4825 XCAP May 2007 + + + would be represented as "%C3%80", and the character KATAKANA LETTER A + would be represented as "%E3%82%A2". + + As a result, the grammar above represents the expressions processed + by the XCAP server internally after it has decoded the URI. The on- + the-wire format is dictated by RFC 3986 [13]. In the discussions and + examples below, when the node selectors are not part of an HTTP URI, + they are presented in their internal format prior to encoding. If an + example includes a node selector within an HTTP URI, it is presented + in its percent-encoded form. + + The node selector is based on the concepts in XPath [10]. Indeed, + the node selector expression, before it is percent-encoded for + representation in the HTTP URI, happens to be a valid XPath + expression. However, XPath provides a set of functionality far + richer than is needed here, and its breadth would introduce much + unneeded complexity into XCAP. + + To determine the XML element, attribute, or namespace bindings + selected by the node selector, processing begins at the root node of + the XML document. The first step in the element selector is then + taken. Each step chooses a single XML element within the current + document context. The document context is the point within the XML + document from which a specific step is evaluated. The document + context begins at the root node of the document. When a step + determines an element within that context, that element becomes the + new context for evaluation of the next step. Each step can select an + element by its name (expanded), by a combination of name and + attribute value, by name and position, or by name, position and + attribute. In all cases, the name can be wildcarded, so that all + elements get selected. + + The selection operation operates as follows. Within the current + document context, the children of that context are enumerated in + document order. If the context is the root node of the document, its + child element is the root element of the document. If the context is + an element, its children are all of the children of that element + (naturally). Next, those elements whose name is not a match for + NameorAny are discarded. An element name is a match if NameorAny is + the wildcard, or if it is not a wildcard, the element name matches + NameorAny. Matching is discussed below. The result is an ordered + list of elements. + + The elements in the list are further filtered by the predicates, + which are the expressions in square brackets following NameorAny. + Each predicate further prunes the elements from the current ordered + list. These predicates are evaluated in order. If the content of + the predicate is a position, the position-th element is selected + + + +Rosenberg Standards Track [Page 20] + +RFC 4825 XCAP May 2007 + + + (that is, treat "position" as a variable, and take the element whose + position equals that variable), and all others are discarded. If + there are fewer elements in the list than the value of position, the + result is a no-match. + + If the content of the predicate is an attribute name and value, all + elements possessing an attribute with that name and value are + selected, and all others are discarded. Note that, although a + document can have namespace declarations within elements, those + elements cannot be selected using a namespace declaration as a + predicate. That is, a step like "el-name[@xmlns='namespace']" will + never match an element, even if there is an element in the list that + specifies a default namespace of "namespace". In other words, a + namespace node is NOT an attribute. If the namespaces in scope for + an element are needed, they can be selected using the namespace- + selector described below. If there are no elements with attributes + having the given name and value, the result is a no-match. + + After the predicates have been applied, the result will be a + no-match, one element, or multiple elements. If the result is + multiple elements, the node selector is invalid. Each step in a node + selector MUST produce a single element to form the context for the + next step. This is more restrictive than general XPath expressions, + which allow a context to contain multiple nodes. If the result is a + no-match, the node selector is invalid. The node selector is only + valid if a single element was selected. This element becomes the + context for the evaluation of the next step in the node selector + expression. + + The last location step is either the previously described element + selector or a "terminal selector". If the terminal selector is an + attribute selector, the server checks to see if there is an attribute + with the same expanded name in the current element context. If there + is not, the result is considered a no-match. Otherwise, that + attribute is selected. If the terminal selector is a namespace + selector, the result is equal to the set of namespace bindings in + scope for the element, including the possible default namespace + declaration. This specification defines a syntax for representing + namespace bindings, so they can be returned to the client in an HTTP + response. + + As a result, once the entire node selector is evaluated against the + document, the result will either be a no-match, invalid, a single + element, a single attribute, or a set of namespace bindings. + + Matching of element names is performed as follows. The element being + compared in the step has its name expanded as described in XML + namespaces [3]. The element name in the step is also expanded. This + + + +Rosenberg Standards Track [Page 21] + +RFC 4825 XCAP May 2007 + + + expansion requires that any namespace prefix is converted to its + namespace URI. Doing that requires a set of bindings from prefixes + to namespace URIs. This set of bindings is obtained from the query + component of the URI (see Section 6.4). If the prefix of the QName + of an element is empty, the corresponding URI is then the default + document namespace URI defined by the application usage, or null if + not defined. Comparisons are then performed as described in XML + namespaces [3]. Note that the namespace prefix expansions described + here are different than those specified in the XPath 1.0 + specification, but are closer to those currently defined by the XPath + 2.0 specification [24]. + + Matching of attribute names proceeds in a similar way. The attribute + in the document has its name expanded as described in XML namespaces + [3]. If the attribute name in the attribute selector has a namespace + prefix, its name is expanded using the namespace bindings obtained + from the query component of the URI. An unprefixed attribute QName + is in no namespace. + + Comments, text content (including whitespace), and processing + instructions can be present in a document, but cannot be selected by + the expressions defined here. Of course, if such information is + present in a document, and a user selects an XML element enclosing + that data, that information would be included in a resulting GET, for + example. Furthermore, whitespace is respected by XCAP. If a client + PUTs an element or document that contains whitespace, the server + retains that whitespace, and will return the element or document back + to the client with exactly the same whitespace. Similarly, when an + element is inserted, no additional whitespace is added around the + inserted element, and the element gets inserted in a very specific + location relative to any whitespace, comments, or processing + instructions around it. Section 8.2.3 describes where the insertion + occurs. + + + + + + + + + + + + + + + + + + +Rosenberg Standards Track [Page 22] + +RFC 4825 XCAP May 2007 + + + As an example, consider the following XML document: + + + + + sip:userA@example.net + sip:userB@example.org + + + + Figure 3: Example XML Document + + Assuming that the default document namespace for this application + usage is "urn:ietf:params:xml:ns:watcherinfo", the node selector + watcherinfo/watcher-list/watcher[@id="8ajksjda7s"] would select the + following XML element: + + sip:userA@example.net + +6.4. Namespace Bindings for the Selector + + In order to expand the namespace prefixes used in the node selector, + a set of bindings from those namespace prefixes to namespace URI must + be used. Those bindings are contained in the query component of the + URI. If no query component is present, it means that only the + default document namespace (as identified by the application usage) + is defined. The query component is formatted as a valid xpointer + expression [5] after suitable URI encoding as defined in Section 4.1 + of the Xpointer framework. This xpointer expression SHOULD only + contain expressions from the xmlns() scheme [4]. A server compliant + to this specification MUST ignore any xpointer expressions not from + the xmlns() scheme. The xmlns() xpointer expressions define the set + of namespace bindings in use for evaluating the URI. + + Note that xpointer expressions were originally designed for usage + within fragment identifiers of URIs. However, within XCAP, they are + used within query components of URIs. + + + +Rosenberg Standards Track [Page 23] + +RFC 4825 XCAP May 2007 + + + The following example shows a more complex matching operation, this + time including the usage of namespace bindings. Consider the + following document: + + + + + + + + + + + + + Assume that this document has a document URI of + "http://xcap.example.com/test/users/sip:joe@example.com/index", where + "test" is the application usage. This application usage defines a + default document namespace of "urn:test:default-namespace". The XCAP + URI: + + http://xcap.example.com/test/users/sip:joe@example.com/index/ + ~~/foo/a:bar/b:baz?xmlns(a=urn:test:namespace1-uri) + xmlns(b=urn:test:namespace1-uri) + + will select the first child element of the element in the + document. The XCAP URI: + + http://xcap.example.com/test/users/sip:joe@example.com/index/ + ~~/foo/a:bar/b:baz?xmlns(a=urn:test:namespace1-uri) + xmlns(b=urn:test:namespace2-uri) + + will select the second child element of the element in + the document. The following XCAP URI will also select the second + child element of the element in the document: + + http://xcap.example.com/test/users/sip:joe@example.com/index/ + ~~/d:foo/a:bar/b:baz?xmlns(a=urn:test:namespace1-uri) + xmlns(b=urn:test:namespace2-uri) + xmlns(d=urn:test:default-namespace) + +7. Client Operations + + An XCAP client is an HTTP/1.1 compliant client. Specific data + manipulation tasks are accomplished by invoking the right set of HTTP + methods with the right set of headers on the server. This section + describes those in detail. + + + +Rosenberg Standards Track [Page 24] + +RFC 4825 XCAP May 2007 + + + In all cases where the client modifies a document, by deleting or + inserting a document, element or attribute resource, the client + SHOULD verify that, if the operation were to succeed, the resulting + document would meet the data constraints defined by the application + usage, including schema validation. For example, if the client + performs a PUT operation to "http://xcap.example.com/rls-services/ + users/sip:joe@example.com/mybuddies", rls-services is the application + unique ID, and the constraints defined by it SHOULD be followed. + + The client will know what URI to use based on the naming conventions + described by the application usage. + + If the document, after modification, does not meet the data + constraints, the server will reject it with a 409. The 409 response + may contain an XML body, formatted according to the schema in + Section 11.2, which provides further information on the nature of the + error. The client MAY use this information to try and alter the + request so that, this time, it might succeed. The client SHOULD NOT + simply retry the request without changing some aspect of it. + + In some cases, the application usage will dictate a uniqueness + constraint that the client cannot guarantee on its own. One such + example is that a URI has to be unique within a domain. Typically, + the client is not the owner of the domain, and so it cannot be sure + that a URI is unique. In such a case, the client can either generate + a sufficiently random identifier, or it can pick a "vanity" + identifier in the hopes that it is not taken. In either case, if the + identifier is not unique, the server will reject the request with a + 409 and suggest alternatives that the client can use to try again. + If the server does not suggest alternatives, the client SHOULD + attempt to use random identifiers with increasing amounts of + randomness. + + HTTP also specifies that PUT and DELETE requests are idempotent. + This means that, if the client performs a PUT on a document and it + succeeds, it can perform the same PUT, and the resulting document + will look the same. Similarly, when a client performs a DELETE, if + it succeeds, a subsequent DELETE to the same URI will generate a 404; + the resource no longer exists on the server since it was deleted by + the previous DELETE operation. To maintain this property, the client + SHOULD construct its URIs such that, after the modification has taken + place, the URI in the request will point to the resource just + inserted for PUT (i.e., the body of the request), and will point to + nothing for DELETE. If this property is maintained, it is the case + that GET to the URI in the PUT will return the same content (i.e., + GET(PUT(X)) == x). This property implies idempotency. Although a + request can still be idempotent if it does not possess this property, + XCAP does not permit such requests. If the client's request does not + + + +Rosenberg Standards Track [Page 25] + +RFC 4825 XCAP May 2007 + + + have this property, the server will reject the request with a 409 and + indicate a cannot-insert error condition. + + If the result of the PUT is a 200 or 201 response, the operation was + successful. Other response codes to any request, such as a + redirection, are processed as per RFC 2616 [6]. + +7.1. Create or Replace a Document + + To create or replace a document, the client constructs a URI that + references the location where the document is to be placed. This URI + MUST be a document URI, and therefore contain the XCAP root and + document selector. The client then invokes a PUT method on that URI. + + The MIME content type MUST be the type defined by the application + usage. For example, it would be "application/rls-services+xml" for + an RLS services [22] document, and not "application/xml". + + If the Request-URI identifies a document that already exists in the + server, the PUT operation replaces that document with the content of + the request. If the Request-URI does not identify an existing + document, the document is created on the server at that specific URI. + +7.2. Delete a Document + + To delete a document, the client constructs a URI that references the + document to be deleted. This URI MUST be a document URI. The client + then invokes a DELETE operation on the URI to delete the document. + +7.3. Fetch a Document + + As one would expect, fetching a document is trivially accomplished by + performing an HTTP GET request with the Request URI set to the + document URI. + +7.4. Create or Replace an Element + + To create or replace an XML element within an existing document, the + client constructs a URI whose document selector points to the + document to be modified. The node selector MUST be present in the + URI, delimited from the document selector with the node selector + separator. The query component MUST be present if the node selector + makes use of namespace prefixes, in which case, the xmlns() + expressions in the query component MUST define those prefixes. To + create this element within the document, the node selector is + constructed such that it is a no-match against the current document, + but if the element in the body of the request was added to the + document as desired by the client, the node selector would select + + + +Rosenberg Standards Track [Page 26] + +RFC 4825 XCAP May 2007 + + + that element. To replace an element in the document, the node + selector is constructed so that it is a match against the element in + the current document to be replaced, as well as a match to the new + element (present in the body of the PUT request) that is to replace + it. + + Oftentimes, the client will wish to insert an element into a document + in a certain position relative to other children of the same parent. + This is called a positional insertion. They often arise because the + schema constrains where the element can occur, or because ordering of + elements is significant within the schema. To accomplish this, the + client can use a node selector of the following form: + + parent/*[position][unique-attribute-value] + + Here, "parent" is an expression for the parent of the element to be + inserted. "position" is the position amongst the existing child + elements of this parent where the new element is to be inserted. + "unique-attribute-value" is an attribute name and value for the + element to be inserted, which is different from the current element + in "position". The second predicate is needed so that the overall + expression is a no-match when evaluated against the current children. + Otherwise, the PUT would replace the existing element in that + position. Note that in addition to wildcard "*" a QName can also be + used as a node test. The insert logic is described in more detail in + Section 8.2.3. + + Consider the example document in Figure 3. The client would like to + insert a new element as the second element underneath + . However, it cannot just PUT to a URI with the + watcherinfo/watcher-list/*[2] node selector; this node selector would + select the existing second child element of and + replace it. Thus, the PUT has to be made to a URI with watcherinfo/ + watcher-list/*[2][@id="hhggff"] as the node selector, where "hhggff" + is the value of the "id" attribute of the new element to be inserted. + This node-selector is a no-match against the current document, and + would be a match against the new element if it was inserted as the + second child element of . + + The "*" indicates that all element children of are to + be considered when computing the position for insertion. If, instead + of a wildcard *, an element name (QName) was present, the expression + above would insert the new element as the position-th element amongst + those with the same expanded name (see Section 8.2.3 for a discussion + on insertion rules). + + Once the client constructs the URI, it invokes the HTTP PUT method. + The content in the request MUST be an XML element. Specifically, it + + + +Rosenberg Standards Track [Page 27] + +RFC 4825 XCAP May 2007 + + + contains the element, starting with the opening bracket for the begin + tag for that element, including the attributes and content of that + element (whether it be text or other child elements), and ending with + the closing bracket for the end tag for that element. The MIME type + in the request MUST be "application/xcap-el+xml", defined in + Section 15.2.1. If the node selector, when evaluated against the + current document, results in a no-match, the server performs a + creation operation. If the node selector, when evaluated against the + current document, is a match for an element in the current document, + the server replaces it with the content of the PUT request. This + replacement is complete; that is, the old element (including its + attributes, namespace declarations and content: text, element, + comment and processing instruction nodes) are removed, and the new + one, including its attributes, namespace declarations and content, is + put in its place. + + To be certain that element insertions have the GET(PUT(x))==x + property, the client can check that the attribute predicates in the + final path segment of the URI match the attributes of the element in + the body of the request. As an example of a request that would not + have this property, and therefore would not be idempotent, consider + the following PUT request (URIs are line-folded for readability): + + PUT + /rls-services/users/sip:bill@example.com/index/~~/rls-services/ + service%5b@uri=%22sip:good-friends@example.com%22%5d + HTTP/1.1 + Content-Type:application/xcap-el+xml + Host: xcap.example.com + + + http://xcap.example.com/resource-lists/users + /sip:joe@example.com/index/~~/resource-lists/list%5b@name=%22l1%22%5d + + + presence + + + + This request will fail with a 409. The Request URI contains a final + path segment with a predicate based on attributes: + @uri="sip:good-friends@example.com". However, this will not match + the value of the "uri" attribute in the element in the body + (sip:mybuddies@example.com). + + The GET(PUT(x))==x property introduces some limitations on the types + of operations possible. It will not be possible to replace an + element with one that has a new value for an attribute that is the + + + +Rosenberg Standards Track [Page 28] + +RFC 4825 XCAP May 2007 + + + sole unique element identifier, if the URI contained a node selector + that was using the previous value of that attribute for purposes of + selecting the element. This is exactly the use case in the example + above. To get around this limitation, the selection can be done by + position instead of attribute value, or the parent of the element to + be replaced can be selected, and then the body of the PUT operation + would contain the parent, the child to be replaced, and all other + siblings. + +7.5. Delete an Element + + To delete an element from a document, the client constructs a URI + whose document selector points to the document containing the element + to be deleted. The node selector MUST identify a single element. + The node selector MUST be present following the node selector + separator, and identify the specific element to be deleted. + Furthermore, the node selector MUST match no element after the + deletion of the target element. This is required to maintain the + idempotency property of HTTP deletions. The query component MUST be + present if the node selector makes use of namespace prefixes, in + which case the xmlns() expressions in the query component MUST define + those prefixes. + + If the client wishes to delete an element in a specific position, + this is referred to as a positional deletion. Like a positional + insertion, the node selector has the following form: + + parent/*[position][unique-attribute-value] + + Where "parent" is an expression for the parent of the element to be + deleted, "position" is the position of the element to be deleted + amongst the existing child elements of this parent, and "unique- + attribute-value" is an attribute name and value for the element to be + deleted, where this attribute name and value are different than any + of the siblings of the element. + + Positional deletions without using a unique attribute name and value + are possible, but only in limited cases where idempotency is + guaranteed. In particular, if a DELETE operation refers to an + element by name and position alone (parent/elname[n]), this is + permitted only when the element to be deleted is the last element + amongst all its siblings with that name. Similarly, if a DELETE + operation refers to an element by position alone (parent/*[n]), this + is permitted only when the element to be deleted is the last amongst + all sibling elements, regardless of name. + + The client then invokes the HTTP DELETE method. The server will + remove the element from the document (including its attributes, + + + +Rosenberg Standards Track [Page 29] + +RFC 4825 XCAP May 2007 + + + namespace declarations, and its descendant nodes, such as any + children). + +7.6. Fetch an Element + + To fetch an element of a document, the client constructs a URI whose + document selector points to the document containing the element to be + fetched. The node selector MUST be present following the node + selector separator, and must identify the element to be fetched. The + query component MUST be present if the node selector makes use of + namespace prefixes, in which case the xmlns() expressions in the + query component MUST define those prefixes. + + The client then invokes the GET method. The 200 OK response will + contain that XML element. Specifically, it contains the content of + the XML document, starting with the opening bracket for the begin tag + for that element, and ending with the closing bracket for the end tag + for that element. This will, as a result, include all attributes, + namespace declarations and descendant nodes: elements, comments, + text, and processing instructions of that element. + +7.7. Create or Replace an Attribute + + To create or replace an attribute in an existing element of a + document, the client constructs a URI whose document selector points + to the document to be modified. The node selector, following the + node selector separator, MUST be present. The node selector MUST be + constructed such that, if the attribute was created or replaced as + desired, the node selector would select that attribute. If the node + selector, when evaluated against the current document, results in a + no-match, it is a creation operation. If it matches an existing + attribute, it is a replacement operation. The query component MUST + be present if the node selector makes use of namespace prefixes, in + which case the xmlns() expressions in the query component MUST define + those prefixes. + + The client then invokes the HTTP PUT method. The content defined by + the request MUST be the value of the attribute, compliant to the + grammar for AttValue as defined in XML 1.0 [1]. Note that, unlike + when AttValue is present in the URI, there is no percent-encoding of + the body. This request MUST be sent with the Content-Type of + "application/xcap-att+xml" as defined in Section 15.2.2. The server + will add the attribute such that, if the node selector is evaluated + on the resulting document, it will return the attribute present in + the request. + + To be certain that attribute insertions have the GET(PUT(x))==x + property, the client can check that any attribute predicate in the + + + +Rosenberg Standards Track [Page 30] + +RFC 4825 XCAP May 2007 + + + path segment that selects the element into which the attribute is + inserted, matches a different attribute than the one being inserted + by the request. As an example of a request that would not have this + property, and therefore would not be idempotent, consider the + following PUT request (URIs are line-folded for readability): + + PUT + /rls-services/users/sip:bill@example.com/index/~~/rls-services + /service%5b@uri=%22sip:good-friends@example.com%22%5d/@uri + HTTP/1.1 + Content-Type:application/xcap-att+xml + Host: xcap.example.com + + "sip:bad-friends@example.com" + + This request will fail with a 409. + + As with element insertions and replacements, the GET(PUT(x))==x + property introduces limitations on attribute replacements. It will + not be possible to replace the attribute value of an attribute, when + that attribute is the sole unique element identifier, and the URI + contains a node selector that uses the previous value of the + attribute to select the affected element. This is the use case in + the example above. Instead, the element can be selected + positionally, or its entire parent replaced. + +7.8. Delete an Attribute + + To delete an attribute from the document, the client constructs a URI + whose document selector points to the document containing the + attribute to be deleted. The node selector MUST be present following + the node selector separator, and evaluate to an attribute in the + document to be deleted. The query component MUST be present if the + node selector makes use of namespace prefixes, in which case the + xmlns() expressions in the query component MUST define those + prefixes. + + The client then invokes the HTTP DELETE method. The server will + remove the attribute from the document. + +7.9. Fetch an Attribute + + To fetch an attribute of a document, the client constructs a URI + whose document selector points to the document containing the + attribute to be fetched. The node selector MUST be present following + the node selector separator, containing an expression identifying the + attribute whose value is to be fetched. The query component MUST be + present if the node selector makes use of namespace prefixes, in + + + +Rosenberg Standards Track [Page 31] + +RFC 4825 XCAP May 2007 + + + which case the xmlns() expressions in the query component MUST define + those prefixes. + + The client then invokes the GET method. The 200 OK response will + contain an "application/xcap-att+xml" document with the specified + attribute, formatted according to the grammar of AttValue as defined + in the XML 1.0 specifications. + +7.10. Fetch Namespace Bindings + + If a client wishes to insert an element or attribute into a document, + and that element or attribute is part of a namespace declared + elsewhere in the document, the client will need to know the namespace + bindings in order to construct the XML content in the request. If + the client has a cached copy of the document, it will know the + bindings. However, if it doesn't have the whole document cached, it + can be useful to fetch just the bindings that are in scope for an + element, in order to construct a subsequent PUT request. + + To get those bindings, the client constructs a URI whose document + selector points to the document containing the element whose + namespace bindings are to be fetched. The node selector MUST be + present following the node selector separator, containing an + expression identifying the desired namespace bindings. The query + component MUST be present if the node selector makes use of namespace + prefixes, in which case the xmlns() expressions in the query + component MUST define those prefixes. + + The client then invokes the GET method. The 200 OK response will + contain an "application/xcap-ns+xml" document with the namespace + definitions. The format for this document is defined in Section 10. + + A client cannot set the namespace prefixes in scope for an element. + As such, a node selector that identifies namespace prefixes MUST NOT + appear in a PUT or DELETE request. + +7.11. Conditional Operations + + The HTTP specification defines several header fields that can be used + by a client to make the processing of the request conditional. In + particular, the If-None-Match and If-Match header fields allow a + client to make them conditional on the current value of the entity + tag for the resource. These conditional operations are particularly + useful for XCAP resources. + + For example, it is anticipated that clients will frequently wish to + cache the current version of a document. So, when the client starts + up, it will fetch the current document from the server and store it. + + + +Rosenberg Standards Track [Page 32] + +RFC 4825 XCAP May 2007 + + + When it does so, the GET response will contain the entity tag for the + document resource. Each resource within a document maintained by the + server will share the same value of the entity tag. As a result, the + entity tag returned by the server for the document resource is + applicable to element and attribute resources within the document. + + If the client wishes to insert or modify an element or attribute + within the document, but it wants to be certain that the document + hasn't been modified since the client last operated on it, it can + include an If-Match header field in the request, containing the value + of the entity tag known to the client for all resources within the + document. If the document has changed, the server will reject this + request with a 412 response. In that case, the client will need to + flush its cached version, fetch the entire document, and store the + new entity tag returned by the server in the 200 OK to the GET + request. It can then retry the request, placing the new entity tag + in the If-Match header field. If this succeeds, the Etag header + field in the response to PUT contains the entity tag for the resource + that was just inserted or modified. Because all resources in a + document share the same value for their entity tag, this entity tag + value can be applied to the modification of other resources. + + A client can also conditionally delete elements or attributes by + including an If-Match header field in DELETE requests. Note that the + 200 OK responses to a DELETE will contain an Etag header field, + containing the entity tag for all of the other resources in the + document, even though the resource identified by the DELETE request + no longer exists. + + When a client uses conditional PUT and DELETE operations, it can + apply those changes to its local cached copy, and update the value of + the entity tag for the locally cached copy based on the Etag header + field returned in the response. As long as no other clients try to + modify the document, the client will be able to perform conditional + operations on the document without ever having to perform separate + GET operations to synchronize the document and its entity tags with + the server. If another client tries to modify the document, this + will be detected by the conditional mechanisms, and the client will + need to perform a GET to resynchronize its copy unless it has some + other means to learn about the change. + + If a client does not perform a conditional operation, but did have a + cached copy of the document, that cached copy will become invalid + once the operation is performed (indeed, it may have become invalid + even beforehand). Unconditional operations should only be performed + by clients when knowledge of the entire document is not important for + the operation to succeed. + + + + +Rosenberg Standards Track [Page 33] + +RFC 4825 XCAP May 2007 + + + As another example, a when a client fetches a document, and there is + an older version cached, it is useful for clients to use a + conditional GET in order to reduce network usage if the cached copy + is still valid. This is done by including, in the GET request, the + If-None-Match header field with a value equal to the current etag + held by the client for the document. The server will only generate a + 200 OK response if the etag held by the server differs than that held + by the client. If it doesn't differ, the server will respond with a + 304 response. + +8. Server Behavior + + An XCAP server is an HTTP/1.1 compliant origin server. The behaviors + mandated by this specification relate to the way in which the HTTP + URI is interpreted and the content is constructed. + + An XCAP server MUST be explicitly aware of the application usage + against which requests are being made. That is, the server must be + explicitly configured to handle URIs for each specific application + usage, and must be aware of the constraints imposed by that + application usage. + + When the server receives a request, the treatment depends on the URI. + If the URI refers to an application usage not understood by the + server, the server MUST reject the request with a 404 (Not Found) + response. If the URI refers to a user (identified by an XUI) that is + not recognized by the + server, it MUST reject the request with a 404 (Not Found). If the + URI includes extension-selectors that the server doesn't understand, + it MUST reject the request with a 404 (Not Found). + + Next, the server authenticates the request. All XCAP servers MUST + implement HTTP Digest [11]. Furthermore, servers MUST implement HTTP + over TLS, RFC 2818 [14]. It is RECOMMENDED that administrators use + an HTTPS URI as the XCAP root URI, so that the digest client + authentication occurs over TLS. + + Next, the server determines if the client has authorization to + perform the requested operation on the resource. The application + usage defines the authorization policies. An application usage may + specify that the default is used. This default is described in + Section 5.7. + + Next, the server makes sure that it can properly evaluate the request + URI. The server MUST separate the document selector from the node + selector, by splitting the URI at the first instance of the node + selector separator ("~~"). The server MUST check the node selector + in the request URI, if present. If any qualified names are present + + + +Rosenberg Standards Track [Page 34] + +RFC 4825 XCAP May 2007 + + + that use a namespace prefix, and that prefix is not defined in an + xmlns() expression in the query component of the request URI, the + server MUST reject the request with a 400 response. + + After checking the namespace prefix definitions, the specific + behavior depends on the method and what the URI refers to. + +8.1. POST Handling + + XCAP resources do not represent processing scripts. As a result, + POST operations to HTTP URIs representing XCAP resources are not + defined. A server receiving such a request for an XCAP resource + SHOULD return a 405. + +8.2. PUT Handling + + The behavior of a server in receipt of a PUT request is as specified + in HTTP/1.1, Section 9.6 -- the content of the request is placed at + the specified location. This section serves to define the notion of + "placement" and "specified location" within the context of XCAP + resources. + + If the request URI contained a namespace-selector, the server MUST + reject the request with a 405 (Method Not Allowed) and MUST include + an Allow header field including the GET method. + +8.2.1. Locating the Parent + + The first step the server performs is to locate the parent, whether + it is a directory or element, in which the resource is to be placed. + To do that, the server removes the last path segment from the URI. + The rest of the URI refers to the parent. This parent can be a + document, element, or prefix of a document selector (called a + directory, even though this specification does not mandate that + documents are actually stored in a filesystem). This URI is called + the parent URI. The path segment that was removed is called the + target selector, and the node (element, document, or attribute) it + describes is called the target node. + + If the parent URI has no node selector separator, it is referring to + the directory into which the document should be inserted. In normal + XCAP operations, this will be either the user's home directory or the + global directory, which will always exist on the server. However, if + an application usage is making use of subdirectories (despite the + fact that this is not recommended), it is possible that the directory + into which the document should be inserted does not exist. In this + case, the server MUST return a 409 response, and SHOULD include a + detailed conflict report including the element. Detailed + + + +Rosenberg Standards Track [Page 35] + +RFC 4825 XCAP May 2007 + + + conflict reports are discussed in Section 11. If the directory does + exist, the server checks to see if there is a document with the same + filename as the target node. If there is, the operation is the + replacement operation, discussed in Section 8.2.4. If it does not + exist, it is the creation operation discussed in Section 8.2.3. + + If the parent URI has a node selector separator, the document + selector is extracted, and that document is retrieved. If the + document does not exist, the server MUST return a 409 response, and + SHOULD include a detailed conflict report including the + element. If it does exist, the node selector is extracted and + decoded (recall that the node selector is percent-encoded). The node + selector is applied to the document based on the matching operations + discussed in Section 6.3. If the result is a no-match or invalid, + the server MUST return a 409 response, and SHOULD include a detailed + conflict report including the element. + + If the node-selector is valid, the server examines the target + selector, and evaluates it within the context of the parent node. If + the target node exists within the parent, the operation is a + replacement, as described in Section 8.2.4. If it does not exist, it + is the creation operation, discussed in Section 8.2.3. + + Before performing the replacement or creation, as determined based on + the logic above, the server validates the content of the request as + described in Section 8.2.2. + +8.2.2. Verifying Document Content + + If the PUT request is for a document (the request URI had no node + selector separator), the content of the request body has to be a + well-formed XML document. If it is not, the server MUST reject the + request with a 409 response code. That response SHOULD include a + detailed conflict report including the element. If + the document is well-formed but not UTF-8 encoded, the server MUST + reject the request with a 409 response code. That response SHOULD + include a detailed conflict report including the element. + If the MIME type in the Content-Type header field of the request is + not equal to the MIME type defined for the application usage, the + server MUST reject the request with a 415. + + If the PUT request is for an element, the content of the request body + has to be a well-balanced region of an XML document, also known as an + XML fragment body in The XML Fragment Interchange [23] specification, + including only a single element. If it is not, the server MUST + reject the request with a 409 response code. That response SHOULD + include a detailed conflict report including the + element. If the fragment body is well-balanced but contains + + + +Rosenberg Standards Track [Page 36] + +RFC 4825 XCAP May 2007 + + + characters outside of the UTF-8 character set, the server MUST reject + the request with a 409 response code. That response SHOULD include a + detailed conflict report including the element. If the + MIME type in the Content-Type header field of the request is not + equal to "application/xcap-el+xml", the server MUST reject the + request with a 415. + + If the PUT request is for an attribute, the content of the request + body has to be a sequence of characters that comply with the grammar + for AttValue as defined above. If it is not, the server MUST reject + the request with a 409 response code. That response SHOULD include a + detailed conflict report including the element. + If the attribute value is valid but contains characters outside of + the UTF-8 character set, the server MUST reject the request with a + 409 response code. That response SHOULD include a detailed conflict + report including the element.If the MIME type in the + Content-Type header field of the request is not equal to + "application/xcap-att+xml", the server MUST reject the request with a + 415. + +8.2.3. Creation + + The steps in this sub-section are followed if the PUT request will + result in the creation of a new document, element, or attribute. + + If the PUT request is for a document, the content of the request body + is placed into the directory, and its filename is associated with the + target node, which is a document. + + If the PUT request is for an element, the server inserts the content + of the request body as a new child element of the parent element + selected in Section 8.2.1. The insertion is done such that the + request URI, when evaluated, would now point to the element that was + inserted. There exist three possible ways in which new elements are + positioned. + + First, if there were no other sibling elements with the same expanded + name, and the insertion is not positionally constrained, the new + element is inserted such that it is the last element amongst all + element siblings. Furthermore, if there were comment, text, or + processing instruction nodes after the former last element, they MUST + occur prior to the insertion of the new element. This case occurs + when one of the following are true: + + o The element name in the target selector is not wildcarded. There + could be an attribute selector (in which case, it would have to + match an attribute of the element being inserted), and the + position in the target selector will either be absent or have a + + + +Rosenberg Standards Track [Page 37] + +RFC 4825 XCAP May 2007 + + + value of 1 (a value greater than 1 would always result in + rejection of the request, since this is the first element with the + given name underneath the parent). + + o The element name in the target selector is wildcarded, but there + are no other elements underneath the same parent. There could be + an attribute selector (in which case, it would have to match an + attribute of the element being inserted), and the position in the + target selector will either be absent or have a value of 1 (a + value greater than 1 would always result in rejection of the + request, since this is the first element underneath the parent). + + o The element name in the target selector is wildcarded, and there + are other elements underneath the same parent. However, there is + an attribute selector that matches none of the attributes in the + other sibling elements underneath the parent, but does match an + attribute of the element to be inserted. The position in the + target selector is absent. + + Secondly, if there were sibling elements with the same name already + in the document, but the insertion is positionally unconstrained, the + server MUST insert the element such that it is in the "earliest last" + position. "Earliest last" means that the new element MUST be + inserted so that there are no elements after it with the same + expanded name, and for all insertion positions where this is true, it + is inserted such that as many sibling nodes (element, comment, text, + or processing instruction) appear after it as possible. This case + occurs when the target selector is defined by a by-name or by-attr + production, and there is no position indicated. + + Lastly, if the element is positionally constrained, the server MUST + insert the element so that it is in the "earliest nth" position. + When n>1 and NameofAny is not a wildcard, the element MUST be + inserted so that there are n-1 sibling elements before it with the + same expanded name. If there are not n-1 sibling elements with the + same expanded name, the request will fail. When n>1 and NameorAny is + a wildcard, the element MUST be inserted so that there are n-1 + sibling elements before it, each of which can have any expanded name. + If there are not n-1 sibling elements in the document, the request + will fail. In both of these cases, the new element is inserted such + that as many sibling nodes appear after it as possible. When n=1 and + + NameorAny is not a wildcard, the insertion is positionally + constrained when an element with the same expanded name already + appears as a child of the same parent. In this case, the new element + MUST appear just before the existing first element with this same + expanded name. When n=1 and NameorAny is wildcarded, the insertion + is positionally constrained when there is also an attribute selector + + + +Rosenberg Standards Track [Page 38] + +RFC 4825 XCAP May 2007 + + + that didn't match the first sibling of the parent (if it did match, + or was absent, this wouldn't have been an insertion). In this case, + the new element MUST appear just before all existing elements, + regardless of their expanded name. + + In practice, this insertion logic keeps elements with the same + expanded names closely together. This simplifies the application + logic when the content model is described by XML schema with + rules and maxOccurs="unbounded" cardinalities, like: + + + + + + + + + + + Based on this schema, the document contains some number of + elements followed by some number of elements. Either or + elements may easily be added without wildcards and positional + constraints. Note that if "minOccurs" cardinality of element + were zero and elements do not yet exist, a positional predicate + with the * wildcard must be used. + + The whole insert logic is best described by complete examples. + Consider the following document: + + + + + + + + + + A PUT request whose content is and whose node + selector is root/el1[@att="third"] would result in the following + document: + + + + + + + + + + + +Rosenberg Standards Track [Page 39] + +RFC 4825 XCAP May 2007 + + + Notice how it has been inserted as the third element in the + document, and just before the comment and whitespace nodes. It would + have been inserted in exactly the same place if the node selector had + been root/el1[3][@att="third"] or root/*[3][@att="third"]. + + If the content of the request had been and the + node selector was root/el3, it would result in the following + document: + + + + + + + + + + A PUT request whose content is and whose node selector + is root/el2[@att="2"] would result in the following document: + + + + + + + + + + It would have been inserted in exactly the same place if the node + selector had been root/el2[2][@att="2"]. However, a selector root/ + *[2][@att="2"] would result in the following document: + + + + + + + + + + + + + + + + + + + + +Rosenberg Standards Track [Page 40] + +RFC 4825 XCAP May 2007 + + + Lastly, if the node selector had been root/el2[1][@att="2"] the + result would be: + + + + + + + + + + It is possible that the element cannot be inserted such that the + request URI, when evaluated, returns the content provided in the + request. Such a request is not allowed for PUT. This happens when + the element in the body is not described by the expression in the + target selector. An example of this case is described in + Section 7.4. If this happens, the server MUST NOT perform the + insertion, and MUST reject the request with a 409 response. The body + of the response SHOULD contain a detailed conflict report containing + the element. It is important to note that schema + compliance does not play a role while performing the insertion. That + is, the decision of where the element gets inserted is dictated + entirely by the structure of the request-URI, the current document, + and the rules in this specification. + + If the element being inserted (or any of its children) contain + namespace declarations, those declarations are retained when the + element is inserted, even if those same declarations exist in a + parent element after insertion. The XCAP server MUST NOT remove + redundant namespace declarations or otherwise change the namespace + declarations that were present in the element being inserted. + + If the PUT request is for an attribute, the server inserts the + content of the request body as the value of the attribute. The name + of the attribute is equal to the att-name from the attribute-selector + in the target selector. + + Assuming that the insertion can be accomplished, the server verifies + that the insertion results in a document that meets the constraints + of the application usage. This is discussed in Section 8.2.5. + +8.2.4. Replacement + + The steps in this sub-section are followed if the PUT request will + result in the replacement of a document, element, or attribute with + the contents of the request. + + + + + +Rosenberg Standards Track [Page 41] + +RFC 4825 XCAP May 2007 + + + If the PUT request is for a document, the content of the request body + is placed into the directory, replacing the document with the same + filename. + + If the PUT request is for an element, the server replaces the target + node with the content of the request body. As in the creation case, + it is possible that, after replacement, the request URI does not + select the element that was just inserted. If this happens, the + server MUST NOT perform the replacement, and MUST reject the request + with a 409 response. The body of the response SHOULD contain a + detailed conflict report containing the element. + + As with creation, replacement of an element does not result in the + changing or elimination of namespace declarations within the newly + modified element. + + If the PUT request is for an attribute, the server sets the value of + the selected attribute to the content of the request body. It is + possible in the replacement case (but not in the creation case), + that, after replacement of the attribute, the request URI no longer + selects the attribute that was just replaced. The scenario in which + this can happen is discussed in Section 7.7. If this is the case, + the server MUST NOT perform the replacement, and MUST reject the + request with a 409 response. The body of the response SHOULD contain + a detailed conflict report containing the element. + +8.2.5. Validation + + Once the document, element, or attribute has been tentatively + inserted, the server needs to verify that the resulting document + meets the data constraints outlined by the application usage. + + First, the server checks that the final document is compliant with + the schema. If it is not, the server MUST NOT perform the insertion. + It MUST reject the request with a 409 response. That response SHOULD + contain a detailed conflict report containing the element. If a schema allows for elements or attributes from + other namespaces, and the new document contains elements or + attributes from an unknown namespace, the server MUST allow the + change. In other words, it is not necessary for an XCAP server to + understand the namespaces and corresponding schemas for elements and + attributes within a document, as long as the schema itself allows for + such elements or attributes to be included. Of course, such unknown + namespaces would not be advertised by the server in its XCAP + capabilities document, discussed in Section 12. + + If the final document contains elements or attributes from a + namespace that the server does understand (and has consequently + + + +Rosenberg Standards Track [Page 42] + +RFC 4825 XCAP May 2007 + + + advertised in its XCAP capabilities document), but the server does + not have the schema for that particular element or attribute, the + server MUST reject the request with a 409 response. That response + SHOULD contain a detailed conflict report containing the element. + + Next, the server checks for any uniqueness constraints identified by + the application usage. If the application usage required that a + particular element or attribute had a unique value within a specific + scope, the server would check that this uniqueness property still + exists. If the application usage required that a URI within the + document was unique within the domain, the server checks whether it + is the case. If any of these uniqueness constraints are not met, the + server MUST NOT perform the insertion. It MUST reject the request + with a 409 response. That response SHOULD contain a detailed + conflict report containing the element. That + element can contain suggested values that the client can use to + retry. These SHOULD be values that, at the time the server generates + the 409, would meet the uniqueness constraints. + + The server also checks for URI constraints and other non-schema data + constraints. If the document fails one of these constraints, the + server MUST NOT perform the insertion. It MUST reject the request + with a 409 response. That response SHOULD contain a detailed + conflict report containing the element. That + element indicates that the document failed non-schema data + constraints explicitly called out by the application usage. + + Element or attribute removals have similar constraints. The server + checks the document for schema validity and compliance to constraints + defined by the application usage, and rejects the request as + described above, if either check fails. + +8.2.6. Conditional Processing + + A PUT request for an XCAP resource, like any other HTTP resource, can + be made conditional through usage of the If-Match and If-None-Match + header fields. For a replacement, these are processed as defined in + [6]. For an insertion of an element or attribute, conditional + operations are permitted. The entity tag that is used for the + procedures in [6] is the one for all of the resources within the same + document as the parent of the element or attribute being inserted. + One way to think of this is that, logically speaking, upon receipt of + the PUT request, the XCAP server instantiates the etag for the + resource referenced by the request, and then applies the processing + of the request. Because of this behavior, it is not possible to + perform a conditional insert on an attribute or element that is + conditioned on the operation being an insertion and not a + + + +Rosenberg Standards Track [Page 43] + +RFC 4825 XCAP May 2007 + + + replacement. In other words, a conditional PUT of an element or + attribute with an If-None-Match: * will always fail. + +8.2.7. Resource Interdependencies + + Because XCAP resources include elements, attributes, and documents, + each of which has its own HTTP URI, the creation or modification of + one resource affects the state of many others. For example, + insertion of a document creates resources on the server for all of + the elements and attributes within that document. After the server + has performed the insertion associated with the PUT, the server MUST + create and/or modify those resources affected by that PUT. The + structure of the document completely defines the inter-relationship + between those resources. + + However, the application usage can specify other resource inter- + dependencies. The server MUST create or modify the resources + specified by the application usage. + + If the creation or replacement was successful, and the resource + interdependencies are resolved, the server returns a 201 Created or + 200 OK, respectively. Note that a 201 Created is generated for + creation of new documents, elements, or attributes. A 200 OK + response to PUT MUST not contain any content. Per the + recommendations of RFC 2616, the 201 can contain a Location header + field and entity that identify the resource that was created. An + entity tag MUST be included in all successful responses to a PUT. + +8.3. GET Handling + + The semantics of GET are as specified in RFC 2616. This section + clarifies the specific content to be returned for a particular URI + that represents an XCAP resource. + + If the request URI contains only a document selector, the server + returns the document specified by the URI if it exists, else returns + a 404 response. The MIME type of the body of the 200 OK response + MUST be the MIME type defined by that application usage (i.e., + "application/resource-lists+xml"). + + If the request URI contains a node selector, the server obtains the + document specified by the document selector, and if it is found, + evaluates the node-selector within that document. If no document is + found, or if the node-selector is a no-match or invalid, the server + returns a 404 response. Otherwise, the server returns a 200 OK + response. If the node selector identifies an XML element, that + element is returned in the 200 OK response as an XML fragment body + containing the selected element. The server MUST NOT add namespace + + + +Rosenberg Standards Track [Page 44] + +RFC 4825 XCAP May 2007 + + + bindings representing namespaces used by the element or its children, + but declared in ancestor elements; the client will either know these + bindings already (since it has a cached copy of the whole document), + or it can learn them by explicitly querying for the bindings. The + MIME type of the response MUST be "application/xcap-el+xml". If the + node selector identifies an XML attribute, the value of that + attribute is returned in the body of the response. The MIME type of + the response MUST be "application/xcap-att+xml". If the node + selector identifies a set of namespace bindings, the server computes + the set of namespace bindings in scope for the element (including the + default) and encodes it using the "application/xcap-ns+xml" format + defined in Section 10. That document is then returned in the body of + the response. + + GET operations can be conditional, and follow the procedures defined + in [6]. + + Note that the GET of a resource that was just PUT might not be octet- + for-octet equivalent to what was PUT, due to XML normalization and + equivalency rules. + + A successful response to a GET MUST include an entity tag. + +8.4. DELETE Handling + + The semantics of DELETE are as specified in RFC 2616. This section + clarifies the specific content to be deleted for a particular URI + that represents an XCAP resource. + + If the request URI contained a namespace-selector, the server MUST + reject the request with a 405 (Method Not Allowed) and MUST include + an Allow header field including the GET method. + + If the request URI contains only a document selector, the server + deletes the document specified by the URI if it exists and returns a + 200 OK, else returns a 404 response. + + If the request URI contains a node selector, the server obtains the + document specified by the document selector, and if it is found, + evaluates the node-selector within that document. If no document is + found, or if the node-selector is a no-match or invalid (note that it + will be invalid if multiple elements or attributes are selected), the + server returns a 404 response. Otherwise, the server removes the + specified element or attribute from the document and performs the + validation checks defined in Section 8.2.5. Note that this deletion + does not include any white space around the element that was deleted; + the XCAP server MUST preserve surrounding whitespace. It is possible + that, after deletion, the request URI selects another element in the + + + +Rosenberg Standards Track [Page 45] + +RFC 4825 XCAP May 2007 + + + document. If this happens, the server MUST NOT perform the deletion, + and MUST reject the request with a 409 response. The body of the + response SHOULD contain a detailed conflict report containing the + element. If the deletion will cause a failure of one + of the constraints, the deletion MUST NOT take place. The server + follows the procedures in Section 8.2.5 for computing the 409 + response. If the deletion results in a document that is still valid, + the server MUST perform the deletion, process the resource + interdependencies defined by the application usage, and return a 200 + OK response. + + DELETE operations can be conditional, and follow the procedures + defined in [6]. + + Before the server returns the 200 OK response to a DELETE, it MUST + process the resource interdependencies as defined in Section 8.2.7. + As long as the document still exists after the delete operation, any + successful response to DELETE MUST include the entity tag of the + document. + +8.5. Managing Etags + + An XCAP server MUST maintain entity tags for all resources that it + maintains. This specification introduces the additional constraint + that when one resource within a document (including the document + itself) changes, that resource is assigned a new etag, and all other + resources within that document MUST be assigned the same etag value. + Effectively, there is a single etag for the entire document. An XCAP + server MUST include the Etag header field in all 200 or 201 responses + to PUT, GET, and DELETE, assuming the document itself still exists + after the operation. In the case of a DELETE, the entity tag refers + to the value of the entity tag for the document after the deletion of + the element or attribute. + + XCAP resources do not introduce new requirements on the strength of + the entity tags. + + As a result of this constraint, when a client makes a change to an + element or attribute within a document, the response to that + operation will convey the entity tag of the resource that was just + affected. Since the client knows that this entity tag value is + shared by all of the other resources in the document, the client can + make conditional requests against other resources using that entity + tag. + + + + + + + +Rosenberg Standards Track [Page 46] + +RFC 4825 XCAP May 2007 + + +9. Cache Control + + An XCAP resource is a valid HTTP resource, and therefore, it can be + cached by clients and network caches. Network caches, however, will + not be aware of the interdependencies between XCAP resources. As + such, a change to an element in a document by a client will + invalidate other XCAP resources affected by the change. For + application usages containing data that is likely to be dynamic or + written by clients, servers SHOULD indicate a no-cache directive. + +10. Namespace Binding Format + + A node-selector can identify a set of namespace bindings that are in + scope for a particular element. In order to convey these bindings in + a GET response, a way is needed to encode them. + + Encoding is trivially done by including a single XML element in an + XML fragment body. This element has the same local-name as the + element whose namespace bindings are desired, and also the same + namespace-prefix. The element has an xmlns attribute identifying the + default namespace in scope, and an xmlns:prefix declaration for each + prefix that is in scope. + + For example, consider the XML document in Section 6.4. The node- + selector df:foo/df2:bar/df2:baz/namespace::* will select the + namespaces in scope for the element in the document, assuming + the request is accompanied by a query component that contains + xmlns(df=urn:test:default-namespace) and + xmlns(df2=urn:test:namespace1-uri). A GET containing this node + selector and namespace bindings will produce the following result: + + + + It is important to note that the client does not need to know the + actual namespace bindings in order to construct the URI. It does + need to know the namespace URI for each element in the node-selector. + The namespace bindings present in the query component are defined by + the client, mapping those URIs to a set of prefixes. The bindings + returned by the server are the actual bindings used in the document. + +11. Detailed Conflict Reports + + In cases where the server returns a 409 error response, that response + will usually include a document in the body of the response which + provides further details on the nature of the error. This document + is an XML document, formatted according to the schema of + + + + +Rosenberg Standards Track [Page 47] + +RFC 4825 XCAP May 2007 + + + Section 11.2. Its MIME type, registered by this specification, is + "application/xcap-error+xml". + +11.1. Document Structure + + The document structure is simple. It contains the root element + . The content of this element is a specific error + condition. Each error condition is represented by a different + element. This allows for different error conditions to provide + different data about the nature of the error. All error elements + support a "phrase" attribute, which can contain text meant for + rendering to a human user. + + The following error elements are defined by this specification: + + : This indicates that the body of the request was + not a well-formed XML document. + + : This indicates that the request was supposed to + contain a valid XML fragment body, but did not. Most likely this + is because the XML in the body was malformed or not balanced. + + : This indicates that an attempt to insert a document, + element, or attribute failed because the directory, document, or + element into which the insertion was supposed to occur does not + exist. This error element can contain an optional + element, which provides an HTTP URI that represents the closest + parent that would be a valid point of insertion. This HTTP URI + MAY be a relative URI, relative to the document itself. Because + this is a valid HTTP URI, its node selector component MUST be + percent-encoded. + + : This element indicates that the document + was not compliant to the schema after the requested operation was + performed. + + : This indicates that the request was supposed to + contain a valid XML attribute value, but did not. + + : This indicates that the requested PUT operation + could not be performed because a GET of that resource after the + PUT would not yield the content of the PUT request. + + : This indicates that the requested DELETE operation + could not be performed because it would not be idempotent. + + + + + + +Rosenberg Standards Track [Page 48] + +RFC 4825 XCAP May 2007 + + + : This indicates that the requested operation + would result in a document that did not meet a uniqueness + constraint defined by the application usage. For each URI, + element, or attribute specified by the client that is not unique, + an element is present as the content of the error + element. Each element has a "field" attribute that + contains a relative URI identifying the XML element or attribute + whose value needs to be unique, but wasn't. The relative URI is + relative to the document itself, and will therefore start with the + root element. The query component of the URI MUST be present if + the node selector portion of the URI contains namespace prefixes. + Since the "field" node selector is a valid HTTP URI, it MUST be + percent-encoded. The element can optionally contain a + list of elements. Each one is a suggested alternate + value that does not currently exist on the server. + + : This indicates that the requested operation + would result in a document that failed a data constraint defined + by the application usage, but not enforced by the schema or a + uniqueness constraint. + + : This indicates an error condition that is defined by an + extension to XCAP. Clients that do not understand the content of + the extension element MUST discard the xcap-error document and + treat the error as an unqualified 409. + + : This indicates that the request could not be completed + because it would have produced a document not encoded in UTF-8. + + As an example, the following document indicates that the user + attempted to create an RLS service using the URI + sip:friends@example.com, but that URI already exists: + + + + + + sip:mybuddies@example.com + + + + + + + + + + + + + +Rosenberg Standards Track [Page 49] + +RFC 4825 XCAP May 2007 + + +11.2. XML Schema + + + + + + + + Indicates the reason for the error. + + + + + + + + + + + + + + + + + + + + This element indicates + that the document was not compliant to the schema after the requested + operation was performed. + + + + + + + + + This indicates that the request was supposed to + contain a valid XML fragment body, but did not. + + + + +Rosenberg Standards Track [Page 50] + +RFC 4825 XCAP May 2007 + + + + + + + + + + This indicates that an attempt to insert + an element, attribute, or document failed because the document or + element into which the insertion was + supposed to occur does not exist. + + + + + + Contains an HTTP URI that points to the + element that is the closest ancestor that does exist. + + + + + + + + + + + This indicates that the requested + PUT operation could not be performed because a GET of that resource + after the PUT would not yield the content of the PUT request. + + + + + + + + + + This indicates that the + request was supposed to contain a valid XML attribute value, but did + not. + + + + + + + +Rosenberg Standards Track [Page 51] + +RFC 4825 XCAP May 2007 + + + + + + + This indicates that the + requested operation would result in a document that did not meet a + uniqueness constraint defined by the application usage. + + + + + + + For each URI, + element, or attribute specified by the client that is not unique, + one of these is present. + + + + + + An optional set of alternate values can be + provided. + + + + + + + + + + + + + + This indicates that the body of the request was + not a well-formed document. + + + + + + + + + + +Rosenberg Standards Track [Page 52] + +RFC 4825 XCAP May 2007 + + + + + This indicates that the + requested operation would result in a document that failed a data + constraint defined by the application usage, but not enforced by the + schema or a uniqueness constraint. + + + + + + + + + This indicates that the requested DELETE + operation could not be performed because it would not be + idempotent. + + + + + + + + + This indicates that the request could not be + completed because it would have produced a document not + encoded in UTF-8. + + + + + + + + +12. XCAP Server Capabilities + + XCAP can be extended through the addition of new application usages + and extensions to the core protocol. Application usages may define + MIME types with XML schemas that allow new extension nodes from new + namespaces. It will often be necessary for a client to determine + what extensions, application usages, or namespaces a server supports + before making a request. To enable that, this specification defines + an application usage with the AUID "xcap-caps". All XCAP servers + MUST support this application usage. This usage defines a single + + + + +Rosenberg Standards Track [Page 53] + +RFC 4825 XCAP May 2007 + + + document within the global tree that lists the capabilities of the + server. Clients can read this well-known document, and therefore + learn the capabilities of the server. + + The structure of the document is simple. The root element is . Its children are , , and . + Each of these contain a list of AUIDs, extensions, and namespaces + supported by the server. Extensions are named by tokens defined by + the extension, and typically define new selectors. Namespaces are + identified by their namespace URI. To 'support' a namespace, the + server must have the schemas for all elements within that namespace, + and be able to validate them if they appear within documents. Since + all XCAP servers support the "xcap-caps" AUID, it MUST be listed in + the element, and the "urn:ietf:params:xml:ns:xcap-caps" + namespace MUST be listed in the element. + + The following sections provide the information needed to define this + application usage. + +12.1. Application Unique ID (AUID) + + This specification defines the "xcap-caps" AUID within the IETF tree, + via the IANA registration in Section 15. + +12.2. XML Schema + + + + + + Root element for xcap-caps + + + + + + List of supported AUID. + + + + + + + + + + + +Rosenberg Standards Track [Page 54] + +RFC 4825 XCAP May 2007 + + + + List of supported extensions. + + + + + + + + + + + List of supported namespaces. + + + + + + + + + + + + + + + AUID Type + + + + + + Extension Type + + + + + + Namespace type + + + + + + + + + + +Rosenberg Standards Track [Page 55] + +RFC 4825 XCAP May 2007 + + +12.3. Default Document Namespace + + The default document namespace used in evaluating a URI is + urn:ietf:params:xml:ns:xcap-caps. + +12.4. MIME Type + + Documents conformant to this schema are known by the MIME type + "application/xcap-caps+xml", registered in Section 15.2.5. + +12.5. Validation Constraints + + There are no additional validation constraints associated with this + application usage. + +12.6. Data Semantics + + Data semantics are defined above. + +12.7. Naming Conventions + + A server MUST maintain a single instance of the document in the + global tree, using the filename "index". There MUST NOT be an + instance of this document in the user's tree. + +12.8. Resource Interdependencies + + There are no resource interdependencies in this application usage + beyond those defined by the schema. + +12.9. Authorization Policies + + This application usage does not change the default authorization + policy defined by XCAP. + +13. Examples + + This section goes through several examples, making use of the + resource-lists and rls-services [22] XCAP application usages. + + First, a user Bill creates a new document (see Section 7.1). This + document is a new resource-list, initially with a single list, called + friends, with no users in it: + + PUT + /resource-lists/users/sip:bill@example.com/index HTTP/1.1 + Content-Type:application/resource-lists+xml + Host: xcap.example.com + + + +Rosenberg Standards Track [Page 56] + +RFC 4825 XCAP May 2007 + + + + + + + + + Figure 24: New Document + + Next, Bill creates an RLS services document defining a single RLS + service referencing this list. This service has a URI of + sip:myfriends@example.com (URIs are line-folded for readability): + + PUT + /rls-services/users/sip:bill@example.com/index HTTP/1.1 + Content-Type:application/rls-services+xml + Host: xcap.example.com + + + + + http://xcap.example.com/resource-lists/users/ + sip:bill@example.com/index/~~/resource-lists/ + list%5b@name=%22friends%22%5d + + + presence + + + + + Figure 25: RLS Services Example + + Next, Bill creates an element in the resource-lists document + (Section 7.4). In particular, he adds an entry to the list: + + PUT + /resource-lists/users/sip:bill@example.com/index + /~~/resource-lists/list%5b@name=%22friends%22%5d/entry HTTP/1.1 + Content-Type:application/xcap-el+xml + Host: xcap.example.com + + + Bob Jones + + + Figure 26: Resource Lists Document + + + + + +Rosenberg Standards Track [Page 57] + +RFC 4825 XCAP May 2007 + + + Next, Bill fetches the document (Section 7.3): + + GET + /resource-lists/users/sip:bill@example.com/index HTTP/1.1 + + Figure 27: Fetch Operation + + And the result is (note how white space text nodes appear in the + document): + + HTTP/1.1 200 OK + Etag: "wwhha" + Content-Type: application/resource-lists+xml + + + + + + Bob Jones + + + + Figure 28: Results of Fetch + + Next, Bill adds another entry to the list, which is another list that + has three entries. This is another element creation (Section 7.4): + + PUT + /resource-lists/users/sip:bill@example.com/index/~~/ + resource-lists/list%5b@name=%22friends%22%5d/ + list%5b@name=%22close-friends%22%5d HTTP/1.1 + Content-Type: application/xcap-el+xml + Host: xcap.example.com + + + + Joe Smith + + + Nancy Gross + + + Petri Aukia + + + + Figure 29: Adding an Entry + + + + +Rosenberg Standards Track [Page 58] + +RFC 4825 XCAP May 2007 + + + Then, Bill decides he doesn't want Petri on the list, so he deletes + the entry (Section 7.5): + + DELETE + /resource-lists/users/sip:bill@example.com/index/ + ~~/resource-lists/list/list/ + entry%5b@uri=%22sip:petri@example.com%22%5d HTTP/1.1 + Host: xcap.example.com + + Figure 30: Deleting an Entry + + Bill decides to check on the URI for Nancy, so he fetches a + particular attribute (Section 7.6): + + GET + /resource-lists/users/sip:bill@example.com/index/ + ~~/resource-lists/list/list/entry%5b2%5d/@uri HTTP/1.1 + Host: xcap.example.com + + Figure 31: Fetching an Attribute + + and the server responds: + + HTTP/1.1 200 OK + Etag: "ad88" + Content-Type:application/xcap-att+xml + + "sip:nancy@example.com" + + Figure 32: Results of Fetch + +14. Security Considerations + + Frequently, the data manipulated by XCAP contains sensitive + information. To avoid eavesdroppers from seeing this information, it + is RECOMMENDED that an administrator hand out an HTTPS URI as the + XCAP root URI. This will result in TLS-encrypted communications + between the client and server, preventing any eavesdropping. Clients + MUST implement TLS, assuring that such URIs will be usable by the + client. + + Client and server authentication are also important. A client needs + to be sure it is talking to the server it believes it is contacting. + Otherwise, it may be given false information, which can lead to + denial-of-service attacks against a client. To prevent this, a + client SHOULD attempt to upgrade [15] any connections to TLS. + Similarly, authorization of read and write operations against the + data is important, and this requires client authentication. As a + + + +Rosenberg Standards Track [Page 59] + +RFC 4825 XCAP May 2007 + + + result, a server SHOULD challenge a client using HTTP Digest [11] to + establish its identity, and this SHOULD be done over a TLS + connection. Clients MUST implement digest authentication, assuring + interoperability with servers that challenge the client. Servers + MUST NOT perform basic authentication without a TLS connection to the + client. + + Because XCAP is a usage of HTTP and not a separate protocol, it runs + on the same port numbers as HTTP traffic normally does. This makes + it difficult to apply port-based filtering rules in firewalls to + separate the treatment of XCAP traffic from other HTTP traffic. + + However, this problem exists broadly today because HTTP is used to + access a wide breadth of content, all on the same port, and XCAP + views application configuration documents as just another type of + HTTP content. As such, separate treatment of XCAP traffic from other + HTTP traffic requires firewalls to examine the URL itself. There is + no foolproof way to identify a URL as pointing to an XCAP resource. + However, the presence of the double tilde (~~) is a strong hint that + the URL points to an XML element or attribute. As always, care must + be taken in looking for the double-tilde due to the breadth of ways + in which a URI can be encoded on-the-wire [29] [13]. + +15. IANA Considerations + + There are several IANA considerations associated with this + specification. + +15.1. XCAP Application Unique IDs + + Per this specification's instructions, IANA created a new registry + for XCAP application unique IDs (AUIDs). This registry is defined as + a table that contains three columns: + + AUID: This will be a string provided in the IANA registrations into + the registry. + + Description: This is text that is supplied by the IANA registration + into the registry. + + Reference: This is a reference to the RFC containing the + registration. + + + + + + + + + +Rosenberg Standards Track [Page 60] + +RFC 4825 XCAP May 2007 + + + Per this specification's instructions, IANA created this table with + an initial entry. The resulting table looks like: + + Application Unique + ID (AUID) Description Reference + -------------------- ------------------------------- --------- + xcap-caps Capabilities of an XCAP server RFC 4825 + + XCAP AUIDs are registered by the IANA when they are published in + standards track RFCs. The IANA Considerations section of the RFC + must include the following information, which appears in the IANA + registry along with the RFC number of the publication. + + o Name of the AUID. The name MAY be of any length, but SHOULD be no + more than 20 characters long. The name MUST consist of alphanum + and mark [16] characters only. + + o Descriptive text that describes the application usage. + +15.2. MIME Types + + This specification requests the registration of several new MIME + types according to the procedures of RFC 4288 [8] and guidelines in + RFC 3023 [9]. + +15.2.1. application/xcap-el+xml MIME Type + + MIME media type name: application + + MIME subtype name: xcap-el+xml + + Mandatory parameters: none + + Optional parameters: Same as charset parameter application/xml as + specified in RFC 3023 [9]. + + Encoding considerations: Same as encoding considerations of + application/xml as specified in RFC 3023 [9]. + + Security considerations: See Section 10 of RFC 3023 [9]. + + Interoperability considerations: none + + Published specification: RFC 4825 + + + + + + + +Rosenberg Standards Track [Page 61] + +RFC 4825 XCAP May 2007 + + + Applications that use this media type: This document type has been + used to support transport of XML fragment bodies in RFC 4825, the + XML Configuration Access Protocol (XCAP). + + Additional Information: + + Magic Number: none + + File Extension: .xel + + Macintosh file type code: "TEXT" + + Personal and email address for further information: + Jonathan Rosenberg, jdrosen@jdrosen.net + + Intended usage: COMMON + + Author/Change controller: The IETF. + +15.2.2. application/xcap-att+xml MIME Type + + MIME media type name: application + + MIME subtype name: xcap-att+xml + + Mandatory parameters: none + + Optional parameters: Same as charset parameter application/xml as + specified in RFC 3023 [9]. + + Encoding considerations: Same as encoding considerations of + application/xml as specified in RFC 3023 [9]. + + Security considerations: See Section 10 of RFC 3023 [9]. + + Interoperability considerations: none + + Published specification: RFC 4825 + + Applications that use this media type: This document type has been + used to support transport of XML attribute values in RFC 4825, the + XML Configuration Access Protocol (XCAP). + + Additional Information: + + Magic Number: none + + File Extension: .xav + + + +Rosenberg Standards Track [Page 62] + +RFC 4825 XCAP May 2007 + + + Macintosh file type code: "TEXT" + + Personal and email address for further information: + Jonathan Rosenberg, jdrosen@jdrosen.net + + Intended usage: COMMON + + Author/Change controller: The IETF. + +15.2.3. application/xcap-ns+xml MIME Type + + MIME media type name: application + + MIME subtype name: xcap-ns+xml + + Mandatory parameters: none + + Optional parameters: Same as charset parameter application/xml as + specified in RFC 3023 [9]. + + Encoding considerations: Same as encoding considerations of + application/xml as specified in RFC 3023 [9]. + + Security considerations: See Section 10 of RFC 3023 [9]. + + Interoperability considerations: none + + Published specification: RFC 4825 + + Applications that use this media type: This document type has been + used to support transport of XML fragment bodies in RFC 4825, the + XML Configuration Access Protocol (XCAP). + + Additional Information: + + Magic Number: none + + File Extension: .xns + + Macintosh file type code: "TEXT" + + Personal and email address for further information: + Jonathan Rosenberg, jdrosen@jdrosen.net + + Intended usage: COMMON + + Author/Change controller: The IETF. + + + + +Rosenberg Standards Track [Page 63] + +RFC 4825 XCAP May 2007 + + +15.2.4. application/xcap-error+xml MIME Type + + MIME media type name: application + + MIME subtype name: xcap-error+xml + + Mandatory parameters: none + + Optional parameters: Same as charset parameter application/xml as + specified in RFC 3023 [9]. + + Encoding considerations: Same as encoding considerations of + application/xml as specified in RFC 3023 [9]. + + Security considerations: See Section 10 of RFC 3023 [9]. + + Interoperability considerations: none + + Published specification: RFC 4825 + + Applications that use this media type: This document type conveys + error conditions defined in RFC 4825 + + Additional Information: + + Magic Number: none + + File Extension: .xer + + Macintosh file type code: "TEXT" + + Personal and email address for further information: + Jonathan Rosenberg, jdrosen@jdrosen.net + + Intended usage: COMMON + + Author/Change controller: The IETF. + +15.2.5. application/xcap-caps+xml MIME Type + + MIME media type name: application + + MIME subtype name: xcap-caps+xml + + Mandatory parameters: none + + Optional parameters: Same as charset parameter application/xml as + specified in RFC 3023 [9]. + + + +Rosenberg Standards Track [Page 64] + +RFC 4825 XCAP May 2007 + + + Encoding considerations: Same as encoding considerations of + application/xml as specified in RFC 3023 [9]. + + Security considerations: See Section 10 of RFC 3023 [9]. + + Interoperability considerations: none + + Published specification: RFC 4825 + + Applications that use this media type: This document type conveys + capabilities of an XML Configuration Access Protocol (XCAP) + server, as defined in RFC 4825. + + Additional Information: + + Magic Number: none + + File Extension: .xca + + Macintosh file type code: "TEXT" + + Personal and email address for further information: + Jonathan Rosenberg, jdrosen@jdrosen.net + + Intended usage: COMMON + + Author/Change controller: The IETF. + +15.3. URN Sub-Namespace Registrations + + This specification registers several new XML namespaces, as per the + guidelines in RFC 3688 [17]. + +15.3.1. urn:ietf:params:xml:ns:xcap-error + + URI: The URI for this namespace is urn:ietf:params:xml:ns:xcap-error + + Registrant Contact: IETF, SIMPLE working group, (simple@ietf.org), + Jonathan Rosenberg (jdrosen@jdrosen.net). + + + + + + + + + + + + +Rosenberg Standards Track [Page 65] + +RFC 4825 XCAP May 2007 + + +XML: + BEGIN + + + + + + XCAP Error Namespace + + +

Namespace for XCAP Error Documents

+

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

+

See + RFC4825

+ + + END + +15.3.2. urn:ietf:params:xml:ns:xcap-caps + + URI: The URI for this namespace is urn:ietf:params:xml:ns:xcap-caps + + Registrant Contact: IETF, SIMPLE working group, (simple@ietf.org), + Jonathan Rosenberg (jdrosen@jdrosen.net). + +XML: + BEGIN + + + + + + XCAP Capabilities Namespace + + +

Namespace for XCAP Capability Documents

+

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

+

See + RFC4825

+ + + END + + + + + +Rosenberg Standards Track [Page 66] + +RFC 4825 XCAP May 2007 + + +15.4. XML Schema Registrations + + This section registers two XML schemas per the procedures in [17]. + +15.4.1. XCAP Error Schema Registration + + URI: urn:ietf:params:xml:schema:xcap-error + + Registrant Contact: IETF, SIMPLE working group, (simple@ietf.org), + Jonathan Rosenberg (jdrosen@jdrosen.net). + + XML Schema: The XML for this schema can be found as the sole content + of Section 11.2. + +15.4.2. XCAP Capabilities Schema Registration + + URI: urn:ietf:params:xml:schema:xcap-caps + + Registrant Contact: IETF, SIMPLE working group, (simple@ietf.org), + Jonathan Rosenberg (jdrosen@jdrosen.net). + + XML Schema: The XML for this schema can be found as the sole content + of Section 12.2. + +16. Acknowledgements + + The author would like to thank Jari Urpalainen, who has contributed + many important comments and has assisted with edit passes in the + document. The author would also like to thank Ben Campbell, + Eva-Maria Leppanen, Hisham Khartabil, Chris Newman, Joel Halpern, + Lisa Dusseault, Tim Bray, Pete Cordell, Jeroen van Bemmel, Christian + Schmidt, and Spencer Dawkins for their input and comments. A special + thanks to Ted Hardie for his input and support. + +17. References + +17.1. Normative References + + [1] Maler, E., Yergeau, F., Paoli, J., Bray, T., and C. Sperberg- + McQueen, "Extensible Markup Language (XML) 1.0 (Third + Edition)", World Wide Web Consortium FirstEdition REC-xml- + 20040204, February 2004, + . + + + + + + + + +Rosenberg Standards Track [Page 67] + +RFC 4825 XCAP May 2007 + + + [2] Thompson, H., Maloney, M., Mendelsohn, N., and D. Beech, "XML + Schema Part 1: Structures Second Edition", World Wide Web + Consortium Recommendation REC-xmlschema-1-20041028, + October 2004, + . + + [3] Layman, A., Hollander, D., and T. Bray, "Namespaces in XML", + World Wide Web Consortium FirstEdition REC-xml-names-19990114, + January 1999, + . + + [4] Daniel, R., DeRose, S., Maler, E., and J. Marsh, "XPointer + xmlns() Scheme", World Wide Web Consortium Recommendation REC- + xptr-xmlns-20030325, March 2003, + . + + [5] Grosso, P., Marsh, J., Maler, E., and N. Walsh, "XPointer + Framework", World Wide Web Consortium Recommendation REC-xptr- + framework-20030325, March 2003, + . + + [6] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., + Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- + HTTP/1.1", RFC 2616, June 1999. + + [7] Bradner, S., "Key words for use in RFCs to Indicate Requirement + Levels", BCP 14, RFC 2119, March 1997. + + [8] Freed, N. and J. Klensin, "Media Type Specifications and + Registration Procedures", BCP 13, RFC 4288, December 2005. + + [9] Murata, M., St. Laurent, S., and D. Kohn, "XML Media Types", + RFC 3023, January 2001. + + [10] Clark, J. and S. DeRose, "XML Path Language (XPath) Version + 1.0", World Wide Web Consortium Recommendation REC-xpath- + 19991116, November 1999, + . + + [11] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., + Leach, P., Luotonen, A., and L. Stewart, "HTTP Authentication: + Basic and Digest Access Authentication", RFC 2617, June 1999. + + [12] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", RFC 4234, October 2005. + + + + + + +Rosenberg Standards Track [Page 68] + +RFC 4825 XCAP May 2007 + + + [13] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform + Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, + January 2005. + + [14] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. + + [15] Khare, R. and S. Lawrence, "Upgrading to TLS Within HTTP/1.1", + RFC 2817, May 2000. + + [16] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A., + Peterson, J., Sparks, R., Handley, M., and E. Schooler, "SIP: + Session Initiation Protocol", RFC 3261, June 2002. + + [17] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, + January 2004. + + [18] Yergeau, F., "UTF-8, a transformation format of ISO 10646", + STD 63, RFC 3629, November 2003. + + [19] Boyer, J., "Canonical XML Version 1.0", World Wide Web + Consortium Recommendation REC-xml-c14n-20010315, March 2001, + . + +17.2. Informative References + + [20] Rosenberg, J., "A Presence Event Package for the Session + Initiation Protocol (SIP)", RFC 3856, August 2004. + + [21] Roach, A., Campbell, B., and J. Rosenberg, "A Session + Initiation Protocol (SIP) Event Notification Extension for + Resource Lists", RFC 4662, August 2006. + + [22] Rosenberg, J., "Extensible Markup Language (XML) Formats for + Representing Resource Lists", RFC 4826, May 2007. + + [23] Grosso, P. and D. Veillard, "XML Fragment Interchange", World + Wide Web Consortium CR CR-xml-fragment-20010212, February 2001, + . + + [24] Berglund, A., Boag, S., Chamberlin, D., Fernandez, M., Kay, M., + Robie, J., and J. Simeon, "XML Path Language (XPath) 2.0", + World Wide Web Consortium + CR http://www.w3.org/TR/2005/CR-xpath20-20051103, + November 2005. + + [25] Newman, C. and J. Myers, "ACAP -- Application Configuration + Access Protocol", RFC 2244, November 1997. + + + + +Rosenberg Standards Track [Page 69] + +RFC 4825 XCAP May 2007 + + + [26] Day, M., Rosenberg, J., and H. Sugano, "A Model for Presence + and Instant Messaging", RFC 2778, February 2000. + + [27] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA + Considerations Section in RFCs", BCP 26, RFC 2434, + October 1998. + + [28] Roach, A., "Session Initiation Protocol (SIP)-Specific Event + Notification", RFC 3265, June 2002. + + [29] Duerst, M. and M. Suignard, "Internationalized Resource + Identifiers (IRIs)", RFC 3987, January 2005. + +Author's Address + + Jonathan Rosenberg + Cisco + Edison, NJ + US + + EMail: jdrosen@cisco.com + URI: http://www.jdrosen.net + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Rosenberg Standards Track [Page 70] + +RFC 4825 XCAP May 2007 + + +Full Copyright Statement + + Copyright (C) The IETF Trust (2007). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND + THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS + OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF + THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + +Rosenberg Standards Track [Page 71] + -- cgit v1.2.3