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.

   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

   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

   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 <watcher> element as the second element underneath
   <watcher-list>.  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 <watcher-list> 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 <watcher-list>.

   The "*" indicates that all element children of <watcher-info> 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

   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

   <service uri="sip:mybuddies@example.com">
     <resource-list>http://xcap.example.com/resource-lists/users
   /sip:joe@example.com/index/~~/resource-lists/list%5b@name=%22l1%22%5d
   </resource-list>
     <packages>
      <package>presence</package>
     </packages>
   </service>

   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

   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,

   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

   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

   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.

   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.

   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

   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 <no-parent> element.  Detailed

   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 <no-parent>
   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 <no-parent> 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 <not-well-formed> 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 <not-utf-8> 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 <not-xml-frag>
   element.  If the fragment body is well-balanced 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 <not-utf-8> 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 <not-xml-att-value> 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 <not-utf-8> 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

      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

   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
   <sequence> rules and maxOccurs="unbounded" cardinalities, like:

   <xs:element name="foobar">
     <xs:complexType>
       <xs:sequence>
         <xs:element ref="foo" maxOccurs="unbounded" />
         <xs:element ref="bar" maxOccurs="unbounded" />
       </xs:sequence>
     </xs:complexType>
   </xs:element>

   Based on this schema, the document contains some number of <foo>
   elements followed by some number of <bar> elements.  Either <bar> or
   <foo> elements may easily be added without wildcards and positional
   constraints.  Note that if "minOccurs" cardinality of <foo> element
   were zero and <foo> 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:

   <?xml version="1.0"?>
   <root>
    <el1 att="first"/>
    <el1 att="second"/>
    <!-- comment -->
    <el2 att="first"/>
   </root>

   A PUT request whose content is <el1 att="third"/> and whose node
   selector is root/el1[@att="third"] would result in the following
   document:

   <?xml version="1.0"?>
   <root>
    <el1 att="first"/>
    <el1 att="second"/><el1 att="third"/>
    <!-- comment -->
    <el2 att="first"/>
   </root>

   Notice how it has been inserted as the third <el1> 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 <el3 att="first"/> and the
   node selector was root/el3, it would result in the following
   document:

   <?xml version="1.0"?>
   <root>
    <el1 att="first"/>
    <el1 att="second"/>
    <!-- comment -->
    <el2 att="first"/>
   <el3 att="first"/></root>

   A PUT request whose content is <el2 att="2"/> and whose node selector
   is root/el2[@att="2"] would result in the following document:

   <?xml version="1.0"?>
   <root>
    <el1 att="first"/>
    <el1 att="second"/>
    <!-- comment -->
    <el2 att="first"/><el2 att="2"/>
   </root>

   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:

   <?xml version="1.0"?>
   <root>
    <el1 att="first"/><el2 att="2"/>
    <el1 att="second"/>
    <!-- comment -->
    <el2 att="first"/>
   </root>

   Lastly, if the node selector had been root/el2[1][@att="2"] the
   result would be:

   <?xml version="1.0"?>
   <root>
    <el1 att="first"/>
    <el1 att="second"/>
    <!-- comment -->
    <el2 att="2"/><el2 att="first"/>
   </root>

   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 <cannot-insert> 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.

   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 <cannot-insert> 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 <cannot-insert> 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 <schema-validation-
   error> 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

   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 <schema-
   validation-error> 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 <uniqueness-failure> 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 <constraint-failure> 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

   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

   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

   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
   <cannot-delete> 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.