< draft-ietf-simple-xcap-04.txt   draft-ietf-simple-xcap-05.txt >
SIMPLE J. Rosenberg SIMPLE J. Rosenberg
Internet-Draft Cisco Systems Internet-Draft Cisco Systems
Expires: April 22, 2005 October 22, 2004 Expires: May 17, 2005 November 16, 2004
The Extensible Markup Language (XML) Configuration Access Protocol The Extensible Markup Language (XML) Configuration Access Protocol
(XCAP) (XCAP)
draft-ietf-simple-xcap-04 draft-ietf-simple-xcap-05
Status of this Memo Status of this Memo
By submitting this Internet-Draft, I certify that any applicable This document is an Internet-Draft and is subject to all provisions
patent or other IPR claims of which I am aware have been disclosed, of section 3 of RFC 3667. By submitting this Internet-Draft, each
and any of which I become aware will be disclosed, in accordance with author represents that any applicable patent or other IPR claims of
which he or she is aware have been or will be disclosed, and any of
which he or she become aware will be disclosed, in accordance with
RFC 3668. RFC 3668.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as other groups may also distribute working documents as
Internet-Drafts. Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt. http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
This Internet-Draft will expire on April 22, 2005. This Internet-Draft will expire on May 17, 2005.
Copyright Notice Copyright Notice
Copyright (C) The Internet Society (2004). All Rights Reserved. Copyright (C) The Internet Society (2004).
Abstract Abstract
This specification defines the Extensible Markup Language (XML) This specification defines the Extensible Markup Language (XML)
Configuration Access Protocol (XCAP). XCAP allows a client to read, Configuration Access Protocol (XCAP). XCAP allows a client to read,
write and modify application configuration data, stored in XML format write and modify application configuration data, stored in XML format
on a server. XCAP maps XML document sub-trees and element attributes on a server. XCAP maps XML document sub-trees and element attributes
to HTTP URLs, so that these components can be directly accessed by to HTTP URLs, so that these components can be directly accessed by
HTTP. HTTP.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Overview of Operation . . . . . . . . . . . . . . . . . . . 4 2. Overview of Operation . . . . . . . . . . . . . . . . . . . 4
3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . 5 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . 5
4. Definitions . . . . . . . . . . . . . . . . . . . . . . . . 5 4. Definitions . . . . . . . . . . . . . . . . . . . . . . . . 5
5. Application Usages . . . . . . . . . . . . . . . . . . . . . 7 5. Application Usages . . . . . . . . . . . . . . . . . . . . . 7
5.1 Application Usage ID (AUID) . . . . . . . . . . . . . . . 7 5.1 Application Unique ID (AUID) . . . . . . . . . . . . . . . 7
5.2 Data Validation . . . . . . . . . . . . . . . . . . . . . 8 5.2 Data Validation . . . . . . . . . . . . . . . . . . . . . 8
5.3 Data Semantics . . . . . . . . . . . . . . . . . . . . . . 9 5.3 Data Semantics . . . . . . . . . . . . . . . . . . . . . . 9
5.4 Naming Conventions . . . . . . . . . . . . . . . . . . . . 9 5.4 Naming Conventions . . . . . . . . . . . . . . . . . . . . 9
5.5 Resource Interdependencies . . . . . . . . . . . . . . . . 10 5.5 Resource Interdependencies . . . . . . . . . . . . . . . . 10
5.6 Authorization Policies . . . . . . . . . . . . . . . . . . 10 5.6 Authorization Policies . . . . . . . . . . . . . . . . . . 10
5.7 Data Extensibility . . . . . . . . . . . . . . . . . . . . 11 5.7 Data Extensibility . . . . . . . . . . . . . . . . . . . . 11
5.8 Documenting Application Usages . . . . . . . . . . . . . . 11 5.8 Documenting Application Usages . . . . . . . . . . . . . . 11
5.9 Guidelines for Creating Application Usages . . . . . . . . 12 5.9 Guidelines for Creating Application Usages . . . . . . . . 12
6. URL Construction . . . . . . . . . . . . . . . . . . . . . . 13 6. URL Construction . . . . . . . . . . . . . . . . . . . . . . 13
6.1 XCAP Root . . . . . . . . . . . . . . . . . . . . . . . . 14 6.1 XCAP Root . . . . . . . . . . . . . . . . . . . . . . . . 14
6.2 Document Selector . . . . . . . . . . . . . . . . . . . . 14 6.2 Document Selector . . . . . . . . . . . . . . . . . . . . 14
6.3 Node Selector . . . . . . . . . . . . . . . . . . . . . . 15 6.3 Node Selector . . . . . . . . . . . . . . . . . . . . . . 15
7. Client Operations . . . . . . . . . . . . . . . . . . . . . 20 7. Client Operations . . . . . . . . . . . . . . . . . . . . . 20
7.1 Create or Replace a Document . . . . . . . . . . . . . . . 21 7.1 Create or Replace a Document . . . . . . . . . . . . . . . 22
7.2 Delete a Document . . . . . . . . . . . . . . . . . . . . 22 7.2 Delete a Document . . . . . . . . . . . . . . . . . . . . 22
7.3 Fetch a Document . . . . . . . . . . . . . . . . . . . . . 22 7.3 Fetch a Document . . . . . . . . . . . . . . . . . . . . . 22
7.4 Create or Replace an Element . . . . . . . . . . . . . . . 22 7.4 Create or Replace an Element . . . . . . . . . . . . . . . 22
7.5 Delete an Element . . . . . . . . . . . . . . . . . . . . 24 7.5 Delete an Element . . . . . . . . . . . . . . . . . . . . 24
7.6 Fetch an Element . . . . . . . . . . . . . . . . . . . . . 25 7.6 Fetch an Element . . . . . . . . . . . . . . . . . . . . . 25
7.7 Create or Replace an Attribute . . . . . . . . . . . . . . 25 7.7 Create or Replace an Attribute . . . . . . . . . . . . . . 25
7.8 Delete an Attribute . . . . . . . . . . . . . . . . . . . 26 7.8 Delete an Attribute . . . . . . . . . . . . . . . . . . . 26
7.9 Fetch an Attribute . . . . . . . . . . . . . . . . . . . . 26 7.9 Fetch an Attribute . . . . . . . . . . . . . . . . . . . . 27
7.10 Conditional Operations . . . . . . . . . . . . . . . . . 27 7.10 Conditional Operations . . . . . . . . . . . . . . . . . 27
8. Server Behavior . . . . . . . . . . . . . . . . . . . . . . 29 8. Server Behavior . . . . . . . . . . . . . . . . . . . . . . 29
8.1 POST Handling . . . . . . . . . . . . . . . . . . . . . . 29 8.1 POST Handling . . . . . . . . . . . . . . . . . . . . . . 29
8.2 PUT Handling . . . . . . . . . . . . . . . . . . . . . . . 29 8.2 PUT Handling . . . . . . . . . . . . . . . . . . . . . . . 30
8.2.1 Locating the Parent . . . . . . . . . . . . . . . . . 30 8.2.1 Locating the Parent . . . . . . . . . . . . . . . . . 30
8.2.2 Verifying Document Content . . . . . . . . . . . . . . 31 8.2.2 Verifying Document Content . . . . . . . . . . . . . . 31
8.2.3 Creation . . . . . . . . . . . . . . . . . . . . . . . 31 8.2.3 Creation . . . . . . . . . . . . . . . . . . . . . . . 31
8.2.4 Replacement . . . . . . . . . . . . . . . . . . . . . 32 8.2.4 Replacement . . . . . . . . . . . . . . . . . . . . . 32
8.2.5 Validation . . . . . . . . . . . . . . . . . . . . . . 33 8.2.5 Validation . . . . . . . . . . . . . . . . . . . . . . 33
8.2.6 Resource Interdependencies . . . . . . . . . . . . . . 33 8.2.6 Resource Interdependencies . . . . . . . . . . . . . . 34
8.3 GET Handling . . . . . . . . . . . . . . . . . . . . . . . 34 8.3 GET Handling . . . . . . . . . . . . . . . . . . . . . . . 34
8.4 DELETE Handling . . . . . . . . . . . . . . . . . . . . . 35 8.4 DELETE Handling . . . . . . . . . . . . . . . . . . . . . 35
8.5 Managing Etags . . . . . . . . . . . . . . . . . . . . . . 35 8.5 Managing Etags . . . . . . . . . . . . . . . . . . . . . . 36
9. Cache Control . . . . . . . . . . . . . . . . . . . . . . . 36 9. Cache Control . . . . . . . . . . . . . . . . . . . . . . . 36
10. Detailed Conflict Reports . . . . . . . . . . . . . . . . . 36 10. Detailed Conflict Reports . . . . . . . . . . . . . . . . . 36
10.1 Document Structure . . . . . . . . . . . . . . . . . . . 36 10.1 Document Structure . . . . . . . . . . . . . . . . . . . 36
10.2 XML Schema . . . . . . . . . . . . . . . . . . . . . . . 38 10.2 XML Schema . . . . . . . . . . . . . . . . . . . . . . . 38
11. XCAP Server Capabilities . . . . . . . . . . . . . . . . . . 41 11. XCAP Server Capabilities . . . . . . . . . . . . . . . . . . 41
11.1 Application Usage ID (AUID) . . . . . . . . . . . . . . 41 11.1 Application Usage ID (AUID) . . . . . . . . . . . . . . 41
11.2 XML Schema . . . . . . . . . . . . . . . . . . . . . . . 41 11.2 XML Schema . . . . . . . . . . . . . . . . . . . . . . . 41
11.3 MIME Type . . . . . . . . . . . . . . . . . . . . . . . 43 11.3 MIME Type . . . . . . . . . . . . . . . . . . . . . . . 43
11.4 Validation Constraints . . . . . . . . . . . . . . . . . 43 11.4 Validation Constraints . . . . . . . . . . . . . . . . . 43
11.5 Data Semantics . . . . . . . . . . . . . . . . . . . . . 43 11.5 Data Semantics . . . . . . . . . . . . . . . . . . . . . 43
11.6 Naming Conventions . . . . . . . . . . . . . . . . . . . 43 11.6 Naming Conventions . . . . . . . . . . . . . . . . . . . 43
11.7 Resource Interdependencies . . . . . . . . . . . . . . . 43 11.7 Resource Interdependencies . . . . . . . . . . . . . . . 43
11.8 Authorization Policies . . . . . . . . . . . . . . . . . 43 11.8 Authorization Policies . . . . . . . . . . . . . . . . . 43
12. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 43 12. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 44
13. Security Considerations . . . . . . . . . . . . . . . . . . 46 13. Security Considerations . . . . . . . . . . . . . . . . . . 46
14. IANA Considerations . . . . . . . . . . . . . . . . . . . . 46 14. IANA Considerations . . . . . . . . . . . . . . . . . . . . 47
14.1 XCAP Application Usage IDs . . . . . . . . . . . . . . . 46 14.1 XCAP Application Usage IDs . . . . . . . . . . . . . . . 47
14.2 MIME Types . . . . . . . . . . . . . . . . . . . . . . . 47 14.2 MIME Types . . . . . . . . . . . . . . . . . . . . . . . 48
14.2.1 application/xcap-el+xml MIME Type . . . . . . . . . 47 14.2.1 application/xcap-el+xml MIME Type . . . . . . . . . 48
14.2.2 application/xcap-att+xml MIME Type . . . . . . . . . 48 14.2.2 application/xcap-att+xml MIME Type . . . . . . . . . 49
14.2.3 application/xcap-error+xml MIME Type . . . . . . . . 49 14.2.3 application/xcap-error+xml MIME Type . . . . . . . . 50
14.2.4 application/xcap-caps+xml MIME Type . . . . . . . . 50 14.2.4 application/xcap-caps+xml MIME Type . . . . . . . . 51
14.3 URN Sub-Namespace Registrations . . . . . . . . . . . . 51 14.3 URN Sub-Namespace Registrations . . . . . . . . . . . . 52
14.3.1 urn:ietf:params:xml:ns:xcap-error . . . . . . . . . 51 14.3.1 urn:ietf:params:xml:ns:xcap-error . . . . . . . . . 52
14.3.2 urn:ietf:params:xml:ns:xcap-caps . . . . . . . . . . 52 14.3.2 urn:ietf:params:xml:ns:xcap-caps . . . . . . . . . . 52
14.4 XML Schema Registrations . . . . . . . . . . . . . . . . 53 14.4 XML Schema Registrations . . . . . . . . . . . . . . . . 53
14.4.1 XCAP Error Schema Registration . . . . . . . . . . . 53 14.4.1 XCAP Error Schema Registration . . . . . . . . . . . 53
14.4.2 XCAP Capabilities Schema Registration . . . . . . . 53 14.4.2 XCAP Capabilities Schema Registration . . . . . . . 53
15. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 53 15. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 54
16. References . . . . . . . . . . . . . . . . . . . . . . . . . 53 16. References . . . . . . . . . . . . . . . . . . . . . . . . . 54
16.1 Normative References . . . . . . . . . . . . . . . . . . . 53 16.1 Normative References . . . . . . . . . . . . . . . . . . . 54
16.2 Informative References . . . . . . . . . . . . . . . . . . 55 16.2 Informative References . . . . . . . . . . . . . . . . . . 55
Author's Address . . . . . . . . . . . . . . . . . . . . . . 56 Author's Address . . . . . . . . . . . . . . . . . . . . . . 56
Intellectual Property and Copyright Statements . . . . . . . 57 Intellectual Property and Copyright Statements . . . . . . . 57
1. Introduction 1. Introduction
In many communications applications, such as Voice over IP, instant In many communications applications, such as Voice over IP, instant
messaging, and presence, it is necessary for network servers to messaging, and presence, it is necessary for network servers to
access per-user information in the process of servicing a request. access per-user information in the process of servicing a request.
This per-user information resides within the network, but is managed This per-user information resides within the network, but is managed
skipping to change at page 7, line 23 skipping to change at page 7, line 23
5. Application Usages 5. Application Usages
Each XCAP resource on a server is associated with an application. In Each XCAP resource on a server is associated with an application. In
order for an application to use those resources, application specific order for an application to use those resources, application specific
conventions must be specified. Those conventions include the XML conventions must be specified. Those conventions include the XML
schema that defines the structure and constraints of the data, well schema that defines the structure and constraints of the data, well
known URLs to bootstrap access to the data, and so on. All of those known URLs to bootstrap access to the data, and so on. All of those
application specific conventions are defined by the application application specific conventions are defined by the application
usage. usage.
5.1 Application Usage ID (AUID) 5.1 Application Unique ID (AUID)
Each application usage is associated with a name, called an Each application usage is associated with a name, called an
Application Unique ID (AUID). This name uniquely identifies the Application Unique ID (AUID). This name uniquely identifies the
application usage, and is different from AUIDs used by other application usage, and is different from AUIDs used by other
applications. AUIDs exist in one of two namespaces. The first applications. AUIDs exist in one of two namespaces. The first
namespace is the IETF namespace. This namespace contains a set of namespace is the IETF namespace. This namespace contains a set of
tokens, each of which is registered with IANA. These registrations tokens, each of which is registered with IANA. These registrations
occur with the publication of standards track RFCs [26] based on the occur with the publication of standards track RFCs [26] based on the
guidelines in Section 14. The second namespace is the guidelines in Section 14. The second namespace is the
vendor-proprietary namespace. Each AUID in that namespace is vendor-proprietary namespace. Each AUID in that namespace is
skipping to change at page 7, line 46 skipping to change at page 7, line 46
As an example, the example.com domain can create an AUID with the As an example, the example.com domain can create an AUID with the
value "com.example.foo" but cannot create one with the value value "com.example.foo" but cannot create one with the value
"org.example.foo". AUIDs within the vendor namespace do not need to "org.example.foo". AUIDs within the vendor namespace do not need to
be registered with IANA. The vendor namespace is also meant to be be registered with IANA. The vendor namespace is also meant to be
used in lab environments where no central registry is needed. The used in lab environments where no central registry is needed. The
syntax for AUIDs, expressed in ABNF [11] (and using some of the BNF syntax for AUIDs, expressed in ABNF [11] (and using some of the BNF
defined in RFC 2396 [12]) is: defined in RFC 2396 [12]) is:
AUID = global-auid / vendor-auid AUID = global-auid / vendor-auid
global-auid = auid global-auid = auid
auid = alphanum / mark auid = 1*(alphanum / mark)
vendor-auid = rev-hostname "." auid vendor-auid = rev-hostname "." auid
rev-hostname = toplabel *( "." domainlabel ) rev-hostname = toplabel *( "." domainlabel )
domainlabel = alphanum domainlabel = alphanum
/ alphanum *( alphanum / "-" ) alphanum / alphanum *( alphanum / "-" ) alphanum
toplabel = ALPHA / ALPHA *( alphanum / "-" ) alphanum toplabel = ALPHA / ALPHA *( alphanum / "-" ) alphanum
5.2 Data Validation 5.2 Data Validation
One of the responsibilities of an XCAP server is to validate the One of the responsibilities of an XCAP server is to validate the
skipping to change at page 11, line 39 skipping to change at page 11, line 39
namespace before operating on a resource, it can query the server for namespace before operating on a resource, it can query the server for
its capabilities using the XCAP Capabilities application usage, its capabilities using the XCAP Capabilities application usage,
discussed in Section 11. discussed in Section 11.
5.8 Documenting Application Usages 5.8 Documenting Application Usages
Application usages are documented in specifications which convey the Application usages are documented in specifications which convey the
information described above. In particular, an application usage information described above. In particular, an application usage
specification MUST provide the following information: specification MUST provide the following information:
o Application Usage ID (AUID): If the application usage is meant for o Application Unique ID (AUID): If the application usage is meant
general use on the Internet, the application usage MUST register for general use on the Internet, the application usage MUST
the AUID into the IETF tree using the IANA procedures defined in register the AUID into the IETF tree using the IANA procedures
Section 14. defined in Section 14.
o XML Schema o XML Schema
o MIME Type o MIME Type
o Validation Constraints o Validation Constraints
o Data Semantics o Data Semantics
o Naming Conventions o Naming Conventions
skipping to change at page 19, line 48 skipping to change at page 19, line 48
event="approved" >sip:userA@example.net</watcher> event="approved" >sip:userA@example.net</watcher>
<watcher status="pending" <watcher status="pending"
id="hh8juja87s997-ass7" id="hh8juja87s997-ass7"
display-name="Mr. Subscriber" display-name="Mr. Subscriber"
event="subscribe">sip:userB@example.org</watcher> event="subscribe">sip:userB@example.org</watcher>
</watcher-list> </watcher-list>
</watcherinfo> </watcherinfo>
Figure 4: Example XML Document Figure 4: Example XML Document
The node selector "watcherinfo/watcher-list/ The node selector
watcher[@id="8ajksjda7s"]" would select the following XML element: "watcherinfo/watcher-list/watcher[@id="8ajksjda7s"]" would select the
following XML element:
<watcher status="active" <watcher status="active"
id="8ajksjda7s" id="8ajksjda7s"
duration-subscribed="509" duration-subscribed="509"
event="approved" >sip:userA@example.net event="approved" >sip:userA@example.net
</watcher> </watcher>
As another example, consider the following document: As another example, consider the following document:
<foo xmlns="default-namespace"> <foo xmlns="default-namespace">
skipping to change at page 21, line 41 skipping to change at page 21, line 41
succeeds, it can perform the same PUT, and the resulting document succeeds, it can perform the same PUT, and the resulting document
will look the same. Similarly, when a client performs a DELETE, if will look the same. Similarly, when a client performs a DELETE, if
it succeeds, a subsequent DELETE to the same URL will generate a 404; it succeeds, a subsequent DELETE to the same URL will generate a 404;
the resource no longer exists on the server since it was deleted by the resource no longer exists on the server since it was deleted by
the previous DELETE operation. To maintain this property, the client the previous DELETE operation. To maintain this property, the client
SHOULD construct its URLs such that, after the modification has taken SHOULD construct its URLs such that, after the modification has taken
place, the URL in the request will point to the resource just place, the URL in the request will point to the resource just
inserted for PUT (i.e., the body of the request), and will point to 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 nothing for DELETE. If this property is maintained, it is the case
that GET to the URL in the PUT will return the same content (i.e., that GET to the URL in the PUT will return the same content (i.e.,
GET(PUT(X)) == x). This property is synonymous with idempotency. If GET(PUT(X)) == x). This property implies idempotency. Although a
the client's request does not have this property, the server will request can still be idempotent if it does not possess this property,
reject the request with a 409 and indicate a cannot-insert error XCAP does not permit such requests. If the client's request does not
condition. 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 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 successful. Other response codes to any request, such as a
redirection, are processed as per RFC 2616 [5]. redirection, are processed as per RFC 2616 [5].
7.1 Create or Replace a Document 7.1 Create or Replace a Document
To create or replace a document, the client constructs a URL that To create or replace a document, the client constructs a URL that
references the location where the document is to be placed. This URL references the location where the document is to be placed. This URL
MUST be a document URL, and therefore contain the XCAP root and MUST be a document URL, and therefore contain the XCAP root and
skipping to change at page 23, line 22 skipping to change at page 23, line 24
in "position". The second predicate is needed so that the overall in "position". The second predicate is needed so that the overall
expression is a no-match when evaluated against the current children. expression is a no-match when evaluated against the current children.
Otherwise, the PUT would replace the existing element in that Otherwise, the PUT would replace the existing element in that
position. position.
Consider the example document in Figure 4. The client would like to Consider the example document in Figure 4. The client would like to
insert a new <watcher> element as the second element underneath insert a new <watcher> element as the second element underneath
<watcher-list>. However, it cannot just PUT to a URL with the <watcher-list>. However, it cannot just PUT to a URL with the
watcherinfo/watcher-list/*[2] node selector; this node selector would watcherinfo/watcher-list/*[2] node selector; this node selector would
select the existing 2nd child of <watcher-list> and replace it. select the existing 2nd child of <watcher-list> and replace it.
Thus, the PUT has to be made to a URL with watcherinfo/watcher-list/ Thus, the PUT has to be made to a URL with
*[2][@id="hhggff"] as the node selector, where "hhggff" is the value watcherinfo/watcher-list/*[2][@id="hhggff"] as the node selector,
of the "id" attribute of the new element to be inserted. This where "hhggff" is the value of the "id" attribute of the new element
node-selector is a no-match against the current document, and would to be inserted. This node-selector is a no-match against the current
be a match against the new element if it was inserted as the 2nd document, and would be a match against the new element if it was
child of <watcher-list>. inserted as the 2nd child of <watcher-list>.
The "*" indicates that all children of <watcher-info> are to be The "*" indicates that all children of <watcher-info> are to be
considered when computing the position for insertion. If, instead of considered when computing the position for insertion. If, instead of
a *, an element name was present, the expression above would insert a *, an element name was present, the expression above would insert
the new element as the position-th element amongst those with the the new element as the position-th element amongst those with the
same name. same name.
Once the client constructs the URL, it invokes the HTTP PUT method. Once the client constructs the URL, it invokes the HTTP PUT method.
If the client is creating a new element, it SHOULD include If the client is creating a new element, it SHOULD include
"application/xcap-diff+xml" in the Accept header field of the "application/xcap-diff+xml" in the Accept header field of the
skipping to change at page 24, line 7 skipping to change at page 24, line 11
be "application/xcap-el+xml", defined in Section 14.2.1. If the node be "application/xcap-el+xml", defined in Section 14.2.1. If the node
selector, when evaluated against the current document, results in a selector, when evaluated against the current document, results in a
no-match, the server performs a creation operation. If the node no-match, the server performs a creation operation. If the node
selector, when evaluated against the current document, is a match for selector, when evaluated against the current document, is a match for
an element in the current document, the server replaces it with the an element in the current document, the server replaces it with the
content of the PUT request. This replacement is complete; that is, content of the PUT request. This replacement is complete; that is,
the old element (including its attributes and content) are removed, the old element (including its attributes and content) are removed,
and the new one, including its attributes and content, is put in its and the new one, including its attributes and content, is put in its
place. place.
To be certain that element insertions are idempotent, the client can To be certain that element insertions have the GET(PUT(x))==x
check that the attribute predicates in the final path segment of the property, the client can check that the attribute predicates in the
URL match the attributes of the element in the body of the request. final path segment of the URL match the attributes of the element in
As an example of an request that would not be idempotent, consider the body of the request. As an example of an request that would not
the following PUT request (URLs are line-folded for readability): have this property and therefore not be idempotent, consider the
following PUT request (URLs are line-folded for readability):
PUT PUT
http://xcap.example.com/rls-services/users/bill/index/~~/rls-services/ http://xcap.example.com/rls-services/users/bill/index/~~/rls-services/
service%5b@uri=%22sip:good-friends@example.com%5d service%5b@uri=%22sip:good-friends@example.com%5d
HTTP/1.1 HTTP/1.1
Content-Type:application/xcap-el+xml Content-Type:application/xcap-el+xml
<service uri="sip:mybuddies@example.com"> <service uri="sip:mybuddies@example.com">
<resource-list>http://xcap.example.com/resource-lists/users/joe <resource-list>http://xcap.example.com/resource-lists/users/joe
/index/~~/resource-lists/list%5b@name=%22l1%22%5d /index/~~/resource-lists/list%5b@name=%22l1%22%5d
skipping to change at page 25, line 50 skipping to change at page 26, line 8
document, the client constructs a URL whose document selector points document, the client constructs a URL whose document selector points
to the document to be modified. The node selector, following the to the document to be modified. The node selector, following the
path separator, MUST be present. The node selector MUST be path separator, MUST be present. The node selector MUST be
constructed such that, if the attribute was created or replaced as constructed such that, if the attribute was created or replaced as
desired, the node selector would select that attribute. If the node desired, the node selector would select that attribute. If the node
selector, when evaluated against the current document, results in a selector, when evaluated against the current document, results in a
no-match, it is a creation operation. If it matches an existing no-match, it is a creation operation. If it matches an existing
attribute, it is a replacement operation. attribute, it is a replacement operation.
The client then invokes the HTTP PUT method. If the client is The client then invokes the HTTP PUT method. If the client is
creating a new attribute, it SHOULD include "application/ creating a new attribute, it SHOULD include
xcap-diff+xml" in the Accept header field of the request. This "application/xcap-diff+xml" in the Accept header field of the
allows the server to return an XCAP Diff document in a 201 response request. This allows the server to return an XCAP Diff document in a
code, and is useful for subsequent conditional operations, as 201 response code, and is useful for subsequent conditional
described in Section 7.10. The content defined by the request MUST operations, as described in Section 7.10. The content defined by the
be the value of the attribute, compliant to the grammar for AttValue request MUST be the value of the attribute, compliant to the grammar
as defined in XML 1.0 [1]. Note that, unlike when AttValue is for AttValue as defined in XML 1.0 [1]. Note that, unlike when
present in the URL, there is no escape coding. Escaping only applies AttValue is present in the URL, there is no escape coding. Escaping
to URLs. This request MUST be sent with the Content-Type of only applies to URLs. This request MUST be sent with the
"application/xcap-att+xml" as defined in Section 14.2.2. The server Content-Type of "application/xcap-att+xml" as defined in Section
will add that attribute such that, if the node selector is evaluated 14.2.2. The server will add that attribute such that, if the node
on the resulting document, it returns the attribute present in the selector is evaluated on the resulting document, it returns the
request. attribute present in the request.
To be certain that attribute insertions are idempotent, the client To be certain that attribute insertions have the GET(PUT(x))==x
can check that any attribute predicate in the path segment that property, the client can check that any attribute predicate in the
selects the element into which the attribute is inserted, matches a path segment that selects the element into which the attribute is
different attribute than the one being inserted by the request. As inserted, matches a different attribute than the one being inserted
an example of a request that would not be idempotent, consider the by the request. As an example of a request that would not have this
following PUT request (URLs are line folded for readability): property and therefore not be idempotent, consider the following PUT
request (URLs are line folded for readability):
PUT PUT
http://xcap.example.com/rls-services/users/bill/index/~~/ http://xcap.example.com/rls-services/users/bill/index/~~/
rls-services/service%5b@uri=%22sip:good-friends@example.com%5d/@uri rls-services/service%5b@uri=%22sip:good-friends@example.com%5d/@uri
HTTP/1.1 HTTP/1.1
Content-Type:application/xcap-att+xml Content-Type:application/xcap-att+xml
"sip:bad-friends@example.com" "sip:bad-friends@example.com"
This request will fail with a 409. This request will fail with a 409.
skipping to change at page 28, line 6 skipping to change at page 28, line 12
Unfortunately, the same conditional operation cannot be performed for Unfortunately, the same conditional operation cannot be performed for
insertions of elements or attributes. That is, if the client wishes insertions of elements or attributes. That is, if the client wishes
to insert a new element or attribute into a document, and it wants to to insert a new element or attribute into a document, and it wants to
be sure that the document hasn't been modified since the client last be sure that the document hasn't been modified since the client last
operated on it, it cannot do that. This is because the If-Match operated on it, it cannot do that. This is because the If-Match
header field applies to the resource in the request URI. For an header field applies to the resource in the request URI. For an
insertion, this resource does not yet exist, and the If-Match will insertion, this resource does not yet exist, and the If-Match will
fail. Fortunately, the client can at least detect, after the fail. Fortunately, the client can at least detect, after the
insertion is performed, whether or not the document had been modified insertion is performed, whether or not the document had been modified
prior to the insertion. If the client placed "application/ prior to the insertion. If the client placed
xcap-diff+xml" into the Accept header field of the request, the "application/xcap-diff+xml" into the Accept header field of the
server will return an XCAP diff document to the client, indicating request, the server will return an XCAP diff document to the client,
the entity tags for the entire document (and thus all resources indicating the entity tags for the entire document (and thus all
within it) prior to, and after, the insertion. If the entity tag resources within it) prior to, and after, the insertion. If the
prior to the insertion matches the one cached by the client, the entity tag prior to the insertion matches the one cached by the
client can know that the document was unmodified prior to insertion. client, the client can know that the document was unmodified prior to
If the entity tag does not match, the client knows it had been insertion. If the entity tag does not match, the client knows it had
modified. This specification does not provide a way to tell the been modified. This specification does not provide a way to tell the
server to roll back. As such, the client can fetch the current server to roll back. As such, the client can fetch the current
document, or PUT the entire document to the desired value. However, document, or PUT the entire document to the desired value. However,
the best way to handle this case is to avoid it entirely. If a the best way to handle this case is to avoid it entirely. If a
condition insertion is truly needed (and often they are not), the condition insertion is truly needed (and often they are not), the
client can instead just modify the parent of the element that is to client can instead just modify the parent of the element that is to
be inserted, setting it to the current value of that element along be inserted, setting it to the current value of that element along
with the newly inserted child. with the newly inserted child.
If the client deletes a resource with DELETE, the resource will no If the client deletes a resource with DELETE, the resource will no
longer exist, and the HTTP response will not contain an Etag header longer exist, and the HTTP response will not contain an Etag header
skipping to change at page 32, line 8 skipping to change at page 32, line 15
request URI, when evaluated, would now point to the element which was request URI, when evaluated, would now point to the element which was
inserted. If the target selector is defined by a by-name or by-attr inserted. If the target selector is defined by a by-name or by-attr
production (in other words, there is no position indicated) the production (in other words, there is no position indicated) the
server MUST insert the element after any other siblings. If a server MUST insert the element after any other siblings. If a
position is indicated, the server MUST insert the element so that it position is indicated, the server MUST insert the element so that it
is the position-th element amongst all siblings whose name matches is the position-th element amongst all siblings whose name matches
NameorAny. NameorAny.
It is possible that the element cannot be inserted such that the It is possible that the element cannot be inserted such that the
request URI, when evaluated, returns the content provided in the request URI, when evaluated, returns the content provided in the
request. Such a request is not idempotent, and is not allowed for request. Such a request is not allowed for PUT. This happens when
PUT. This happens when the element in the body is not described by the element in the body is not described by the expression in the
the expression in the target selector. An example of this case is target selector. An example of this case is described in Section
described in Section 7.4. If this happens the server MUST NOT 7.4. If this happens the server MUST NOT perform the insertion, and
perform the insertion, and MUST reject the request with a 409 MUST reject the request with a 409 response. The body of the
response. The body of the response SHOULD contain a detailed response SHOULD contain a detailed conflict report containing the
conflict report containing the <cannot-insert> element. It is <cannot-insert> element. It is important to note that schema
important to note that schema compliance does not play a role while compliance does not play a role while performing the insertion. That
performing the insertion. That is, the decision of where the element is, the decision of where the element gets inserted is dictated
gets inserted is dictated entirely by the structure of the entirely by the structure of the request-URI, the current document,
request-URI, the current document, and the rules in this and the rules in this specification.
specification.
If the PUT request is for an attribute, the server inserts the 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 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 of the attribute is equal to the att-name from the attribute-selector
in the target selector. in the target selector.
Assuming that the insertion can be accomplished, the server verifies Assuming that the insertion can be accomplished, the server verifies
that the insertion results in a document that meets the constraints that the insertion results in a document that meets the constraints
of the application usage. This is dicussed in Section 8.2.5. of the application usage. This is dicussed in Section 8.2.5.
skipping to change at page 34, line 17 skipping to change at page 34, line 26
do anything to meet this requirement, since those other resources do anything to meet this requirement, since those other resources
would normally be resolved dynamically when requests are made against would normally be resolved dynamically when requests are made against
them. them.
However, the application usage can specify other resource However, the application usage can specify other resource
inter-dependencies. The server MUST create or modify the resources inter-dependencies. The server MUST create or modify the resources
specified by the application usage. specified by the application usage.
If the creation or insertion was successful, and the resource If the creation or insertion was successful, and the resource
interdependencies are resolved, the server returns a 200 OK or 201 interdependencies are resolved, the server returns a 200 OK or 201
Created, as appropriate. If the client included "application/ Created, as appropriate. If the client included
xcap-diff+xml" in an Accept header in the PUT request, and the "application/xcap-diff+xml" in an Accept header in the PUT request,
request was an insertion resulting in a 201 response, the server and the request was an insertion resulting in a 201 response, the
SHOULD include an XCAP diff document in the response [4]. The XCAP server SHOULD include an XCAP diff document in the response [4]. The
diff document SHOULD contain a single <document> element. It SHOULD XCAP diff document SHOULD contain a single <document> element. It
indicate the entity tag for the document resource prior to the SHOULD indicate the entity tag for the document resource prior to the
insertion in the "previous-etag" attribute, and the entity tag for insertion in the "previous-etag" attribute, and the entity tag for
the document after insertion in the "new-etag" attribute. A 200 OK the document after insertion in the "new-etag" attribute. A 200 OK
response to PUT MUST not contain any content. response to PUT MUST not contain any content.
8.3 GET Handling 8.3 GET Handling
The semantics of GET are as specified in RFC 2616. This section The semantics of GET are as specified in RFC 2616. This section
clarifies the specific content to be returned for a particular URL clarifies the specific content to be returned for a particular URL
that represents an XCAP resource. that represents an XCAP resource.
skipping to change at page 34, line 49 skipping to change at page 35, line 9
If the request URI contains a node selector, the server obtains the If the request URI contains a node selector, the server obtains the
document specified by the document selector, and if it is found, document specified by the document selector, and if it is found,
evaluates the node-selector within that document. If no document is 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 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 returns a 404 response. Otherwise, the server returns a 200 OK
response. If the node selector identifies an XML element, that response. If the node selector identifies an XML element, that
element is returned in the 200 OK response as an XML fragment body element is returned in the 200 OK response as an XML fragment body
containing the selected element. The MIME type of the response MUST containing the selected element. The MIME type of the response MUST
be "application/xcap-el+xml". If the node selector identifies an XML 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 attribute, the value of that attribute is returned in the body of the
response. The MIME type of the response MUST be "application/ response. The MIME type of the response MUST be
xcap-att+xml". "application/xcap-att+xml".
8.4 DELETE Handling 8.4 DELETE Handling
The semantics of DELETE are as specified in RFC 2616. This section The semantics of DELETE are as specified in RFC 2616. This section
clarifies the specific content to be deleted for a particular URL clarifies the specific content to be deleted for a particular URL
that represents an XCAP resource. that represents an XCAP resource.
If the request URL contains only a document selector, the server If the request URL contains only a document selector, the server
deletes the document specified by the URL if it exists and returns a deletes the document specified by the URL if it exists and returns a
200 OK, else returns a 404 response. 200 OK, else returns a 404 response.
skipping to change at page 37, line 29 skipping to change at page 37, line 34
escape encoded. escape encoded.
<schema-validation-error>: This element indicates that the document <schema-validation-error>: This element indicates that the document
was not compliant to the schema after the requested operation was was not compliant to the schema after the requested operation was
performed. performed.
<not-xml-att-value>: This indicates that the request was supposed to <not-xml-att-value>: This indicates that the request was supposed to
contain a valid XML attribute value, but did not. contain a valid XML attribute value, but did not.
<cannot-insert>: This indicates that the requested PUT operation <cannot-insert>: This indicates that the requested PUT operation
could not be performed because it would not be idempotent. could not be performed because a GET of that resource after the
PUT would not yield the content of the PUT request.
<cannot-delete>: This indicates that the requested DELETE operation <cannot-delete>: This indicates that the requested DELETE operation
could not be performed because it would not be idempotent. could not be performed because it would not be idempotent.
<uniqueness-failure>: This indicates that the requested operation <uniqueness-failure>: This indicates that the requested operation
would result in a document that did not meet a uniqueness would result in a document that did not meet a uniqueness
constraint defined by the application usage. For each URL, constraint defined by the application usage. For each URL,
element or attribute specified by the client which is not unique, element or attribute specified by the client which is not unique,
an <exists> element is present as the content of the error an <exists> element is present as the content of the error
element. Each <exists> element has a "field" attribute that element. Each <exists> element has a "field" attribute that
skipping to change at page 39, line 35 skipping to change at page 39, line 43
element which is the closest ancestor that does exist.</xs:documentation> element which is the closest ancestor that does exist.</xs:documentation>
</xs:annotation> </xs:annotation>
</xs:element> </xs:element>
</xs:sequence> </xs:sequence>
<xs:attribute name="phrase" type="xs:string" use="optional"/> <xs:attribute name="phrase" type="xs:string" use="optional"/>
</xs:complexType> </xs:complexType>
</xs:element> </xs:element>
<xs:element name="cannot-insert" substitutionGroup="error-element"> <xs:element name="cannot-insert" substitutionGroup="error-element">
<xs:annotation> <xs:annotation>
<xs:documentation>This indicates that the requested <xs:documentation>This indicates that the requested
PUT operation could not be performed because it would not be PUT operation could not be performed because a GET of that resource
idempotent.</xs:documentation> after the PUT would not yield the content of the PUT request.
</xs:documentation>
</xs:annotation> </xs:annotation>
<xs:complexType> <xs:complexType>
<xs:attribute name="phrase" type="xs:string" use="optional"/> <xs:attribute name="phrase" type="xs:string" use="optional"/>
</xs:complexType> </xs:complexType>
</xs:element> </xs:element>
<xs:element name="not-xml-att-value" substitutionGroup="error-element"> <xs:element name="not-xml-att-value" substitutionGroup="error-element">
<xs:annotation> <xs:annotation>
<xs:documentation>This indicates that the <xs:documentation>This indicates that the
request was supposed to contain a valid XML attribute value, but did request was supposed to contain a valid XML attribute value, but did
not.</xs:documentation> not.</xs:documentation>
skipping to change at page 47, line 27 skipping to change at page 48, line 4
Application Unique Description Document Application Unique Description Document
ID (AUID) ID (AUID)
----------------------------------------------------------- -----------------------------------------------------------
xcap-caps Capabilities of an RFC XXXX xcap-caps Capabilities of an RFC XXXX
XCAP server XCAP server
[[NOTE TO IANA/RFC-EDITOR: Please replace XXXX with the RFC number of [[NOTE TO IANA/RFC-EDITOR: Please replace XXXX with the RFC number of
this specification.]] this specification.]]
XCAP AUIDs are registered by the IANA when they are published in XCAP AUIDs are registered by the IANA when they are published in
standards track RFCs. The IANA Considerations section of the RFC standards track RFCs. The IANA Considerations section of the RFC
must include the following information, which appears in the IANA must include the following information, which appears in the IANA
registry along with the RFC number of the publication. registry along with the RFC number of the publication.
Name of the AUID. The name MAY be of any length, but SHOULD be no Name of the AUID. The name MAY be of any length, but SHOULD be no
more than twenty characters long. The name MUST consist of more than twenty characters long. The name MUST consist of
alphanum [15] characters only. alphanum and mark [15] characters only.
Descriptive text that describes the application usage. Descriptive text that describes the application usage.
14.2 MIME Types 14.2 MIME Types
This specification requests the registration of several new MIME This specification requests the registration of several new MIME
types according to the procedures of RFC 2048 [7] and guidelines in types according to the procedures of RFC 2048 [7] and guidelines in
RFC 3023 [8]. RFC 3023 [8].
14.2.1 application/xcap-el+xml MIME Type 14.2.1 application/xcap-el+xml MIME Type
 End of changes. 31 change blocks. 
102 lines changed or deleted 108 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/