Tech-invite3GPPspecsGlossariesIETFRFCsGroupsSIPABNFs   Ti+   SearchTech-invite World Map Symbol

RFC 4825

Proposed STD
Pages: 71
Top     in Index     Prev     Next
in Group Index     Prev in Group     Next in Group     Group: SIMPLE

The Extensible Markup Language (XML) Configuration Access Protocol (XCAP)

Part 1 of 3, p. 1 to 24
None       Next RFC Part


Top       ToC       Page 1 
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).


   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

Top       Page 2 
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

Top      ToC       Page 3 
   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

Top      ToC       Page 4 
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.

Top      ToC       Page 5 
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

3.  Terminology

   In this document, the key words "MUST", "MUST NOT", "REQUIRED",
   and "OPTIONAL" are to be interpreted as described in RFC 2119 [7] and
   indicate requirement levels for compliant implementations.

Top      ToC       Page 6 
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

   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.

Top      ToC       Page 7 
   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

   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

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

Top      ToC       Page 8 
   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 domain can
   create an AUID with the value "" but cannot create one
   with the value "".  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

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

Top      ToC       Page 9 
   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 <unique> 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.

Top      ToC       Page 10 
   For example, the resource lists application usage [22] requires that
   each <list> 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 <service> 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

Top      ToC       Page 11 
   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

   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.

Top      ToC       Page 12 
   As an example, when a user creates a new RLS service (that is, it
   creates a new <service> 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

   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

   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

Top      ToC       Page 13 
   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

Top      ToC       Page 14 
   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

   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.

Top      ToC       Page 15 
   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

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.

Top      ToC       Page 16 
   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, "" might be used as the XCAP root URI
   within the 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 "".

   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.

Top      ToC       Page 17 
   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.,  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

Top      ToC       Page 18 
   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

   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 <service> element has a
   child element called <resource-list> 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/" is a document
   selector.  Concatenating the XCAP root URI with the document selector
   produces the HTTP URI "".  In this URI, the AUID is "resource-
   lists", and the document is in the user tree with the XUI
   "" 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 /
   element-selector       = step *( "/" step)
   step                   = by-name / by-pos / by-attr / by-pos-attr /
   by-name                = NameorAny
   by-pos                 = NameorAny "[" position "]"

Top      ToC       Page 19 
   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

   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

   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

Top      ToC       Page 20 
   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

Top      ToC       Page 21 
   (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

   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

   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

Top      ToC       Page 22 
   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

Top      ToC       Page 23 
   As an example, consider the following XML document:

   <?xml version="1.0"?>
   <watcherinfo xmlns="urn:ietf:params:xml:ns:watcherinfo"
                version="0" state="full">
     <watcher-list resource=""
       <watcher status="active"
       <watcher status="pending"
                display-name="Mr. Subscriber"

                      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:

   <watcher status="active"

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.

Top      ToC       Page 24 
   The following example shows a more complex matching operation, this
   time including the usage of namespace bindings.  Consider the
   following document:

   <?xml version="1.0"?>
   <foo xmlns="urn:test:default-namespace">
     <ns1:bar xmlns:ns1="urn:test:namespace1-uri"
       <ns2:baz xmlns:ns2="urn:test:namespace2-uri"/>
     <ns3:hi xmlns:ns3="urn:test:namespace3-uri">

   Assume that this document has a document URI of
   "", where
   "test" is the application usage.  This application usage defines a
   default document namespace of "urn:test:default-namespace".  The XCAP

   will select the first <baz> child element of the <bar> element in the
   document.  The XCAP URI:

   will select the second <baz> child element of the <bar> element in
   the document.  The following XCAP URI will also select the second
   <baz> child element of the <bar> element in the document:

(page 24 continued on part 2)

Next RFC Part