Subject: [Simple] Re: WGLC : draft-ietf-simple-xcap-09.txt, some comments

From: Jonathan Rosenberg <[email-masked]>
Date: Thu, 04 May 2006 13:39:59 -0400

Thanks for the detailed comments. Responses inline.

Schmidt, Christian wrote:

> 
> 6.2 Document Selector:
> 
> Comment: The example
> "http://xcap.example.com/services/resource-lists" is in violation
> with the recommendation specified in section 6.1, stating that the
> XCAP Root is recommended to be "http://xcap.<domain>". Hence the
> example should be "http://xcap.example.com/resource-lists".

Right, this was pointed out by a few people. Fixed.

> 
> 6.3 Node Selector:
> 
> Text in Verion 09: "Unfortunately, the characters permitted by these
> productions include some that are not allowed for pchar, which is the
> production for the allowed set of characters in path segments in the
> URI.  The AttValue production allows many such characters within the
> US-ASCII set, including the space.  Those characters MUST be percent-
> encoded when placed in the URI.  Furthermore, QName and AttValue
> allow many Unicode characters, outside of US-ASCII.  When these
> characters need to be represented in the HTTP URI, they are percent-
> encoded.  To do this, the data should be encoded first as octets
> according to the UTF-8 character encoding [18] and then only those
> octets that do not correspond to characters in the unreserved set
> should be percent-encoded.  For example, the character A would be 
> represented as "A", the character LATIN CAPITAL LETTER A WITH GRAVE 
> would be represented as "%C3%80", and the character KATAKANA LETTER A
>  would be represented as "%E3%82%A2"."
> 
> Comment: As first stated, a path segments allows all characters that
> are part of the pchar set. Other characters need to be
> percent-encoded. Hence, the actual description of how to transform
> data into a valid path segment should state: Textproposal: "To do
> this, the data should be encoded first as octets according to the
> UTF-8 character encoding [18] and then only those octets that do not
> correspond to the pchar set should be percent-encoded."

Slight mod to this; it should be "..and only those octets that do not 
correspond to characters in the pchar set.." but otherwise, OK.

> 
> Editorial Comment: Page 21: Last Paragraph: Selection 8.2.3) >
> Selection 8.2.3

fixed.

> 
> 7.4. Create or Replace an Element, page 27, first paragraph
> 
> Text in Verion 09: "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."
> 
> Comment: A reference to Section 8.2.3 should be added here with
> respect to how insertions are done.

Added.

> 
> Text in Verion 09: "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 an
> request that would not have this property and therefore not be
> idempotent, consider the following PUT request (URIs are line-folded
> for readability):
> 
> PUT /rls-services/users/bill/index/~~/rls-services/ 
> service%5b@uri=%22sip:[email-masked]%5d HTTP/1.1 
> Content-Type:application/xcap-el+xml Host: xcap.example.com
> 
> <service uri="sip:[email-masked]"> 
> <resource-list>http://xcap.example.com/resource-lists/users/joe 
> /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:[email-masked]".  However, this will not match 
> the value of the "uri" attribute in the element in the body."
> 
> Comment: A note should be added to make the implications of the
> idempotent restriction clear. I.e. 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 using a request URI that contains a
> node selector that holds the current attribute value to identify the
> element (as presented in the example). The only way around it would
> be to specify the position instead of the attribute value in the node
> selector (i.e. for the example the following request URI would work
> taking that the element is the 2nd <service> element:
> /rls-services/users/bill/index/~~/rls-services/service%5b2%5d ).

I added text to explain this. Another option that I listed, besides 
positional, is to replace the whole parent.

> 
> 
> 7.7 Create or Replace an Attribute
> 
> Text in Verion 09: "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 not be idempotent, consider the
> following PUT request (URIs are line folded for readability):
> 
> PUT /rls-services/users/bill/index/~~/ 
> rls-services/service%5b@uri=%22sip:[email-masked]%5d/@uri 
> HTTP/1.1 Content-Type:application/xcap-att+xml Host: xcap.example.com
>  "sip:[email-masked]"
> 
> This request will fail with a 409."
> 
> Comment: A note should be added to make the implications of the
> idempotent restriction clear. I.e. is will not be possible to replace
> the attribute value of an attribute that is the sole unique element
> identifier using a request URI that contains a node selector that
> holds the current attribute value to identify the parent element (as
> presented in the example). The only way around it would be to specify
> the position instead of the attribute value in the node selector
> (i.e. for the example the following request URI would work taking
> that the parent element is the 2nd <service> element:
> /rls-services/users/bill/index/~~/rls-services/service%5b2%5d/@uri ).

OK, included text here too.

> 
> 
> 
> 8.2.1 Locating the Parent
> 
> "If the parent URI has no node selector separator, it is referring to
>  the directory into which the document should be inserted.  If this 
> directory does not exist, 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.4."
> 
> Comment: As the XCAP protocol does not provide the means to create a
> directory, it is not possible to have a directory structure in the
> document selector and thus all documents are present in either to
> global directory or the home directory (and never in a subdirectory
> of the global or home directory). The only way to have one or more
> subdirectories in the document selector is when the application usage
> requires the existence of such subdirectories, which is in my view
> very unlikely. This should be noted.

Text now reads:

<t>
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 users 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
&lt;no-parent&gt; element. Detailed conflict reports are discussed in
<xref target="sec:reports"/>. 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 <xref target="sec:replace"/>. If it does not exist, it is
the creation operation, discussed in <xref target="sec:creation-serv"/>.</t>

> 
> Comment: The last reference should be replaced by 8.2.3. The same, at
> first line in page 35.

Good catch - fixed.

> 
> 
> 8.2.7  Resource Interdependencies
> 
> Text in Verion 09: "If the creation or replacement was successful,
> and the resource interdependencies are resolved, the server returns a
> 201 Created or 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."
> 
> Comment: And what about the 201 Created? What should the content be
> of the 201 Created? Should it e.g. contain the XCAP URI identifying
> the just created document, element or attribute (in line with RFC
> 2616]?

We're not changing the guidelines here, so I just referenced 2616 for 
this. I don't think such information will be useful to the client though.

> 
> 
> 8.4 DELETE Handling
> 
> Text in Verion 09: "GET operations can be conditional, and follow the
> procedures defined in [6]."
> 
> Comment: Replace GET by DELETE

fixed.

> 
> 8.5  Managing Etags
> 
> Text in Verion 09: "In the case of a DELETE, the entity tag refers to
> the value of the entity tag for all other resources after the
> deletion of the specified resource has occurred. One way to think
> about this is that the server is, logically speaking,
> re-instantiating the resource for a brief instant, so that it can
> have an entity tag that can be reasonably returned in the response to
> DELETE."
> 
> Comment: This would be correct when deleting elements or attributes.
> But there is no sense in creating and returning an ETag when the
> whole document is deleted!

I added a caveat that this discussion all assumes the document still 
exists after the operation in question.

> 
> 
> 11.1  Document Structure
> 
> Proposal for a modified definition: <no-parent>: This indicates that
> an attempt to insert a document, element, or attribute failed because
> the directory, document or element into which the insertion was
> supposed to occur does not exist.  This error element can contain an
> optional <ancestor> element, which provides an HTTP URI of the xcap
> resource that identifies the closest ancestor that does exist.  This 
> HTTP URI MAY be a relative URI, relative to the document itself. 
> Because this is a valid HTTP URI, its node selector component MUST be
> percent-encoded.
> 
> Comment: Note that if the <ancestor> element must contain a HTTP URI
> identifying an xcap resource, then it can never indicate a directory
> (for e.g. the case in which the create of a document failed because
> the parent directory does not exist).

Good points. Taking your comment into account, I changed your text to:

<t hangText="&lt;no-parent&gt;:">This indicates that an attempt to
insert a document, element, or attribute failed because the directory,
document or element into which the insertion was supposed to occur
does not exist.  This error element can contain an optional <ancestor>
element, which provides an HTTP URI that represents the closest parent
that would be a valid point of insertion. This HTTP URI MAY be a
relative URI, relative to the document itself.  Because this is a
valid HTTP URI, its node selector component MUST be
percent-encoded.</t>

> 
> 
> 12.  XCAP Server Capabilities
> 
> Proposal for enhanced text: The structure of the document is simple.
> The root element is <xcap- caps>.  Its children are <auids>,
> <extensions>, and <namespaces>. Each of these contain a list of
> AUIDs, extensions and namespaces supported by the server.  Extensions
> are named by tokens defined by the extension, and typically define
> new selectors.  Namespaces are identified by their namespace URI.
> Since all XCAP servers support the "xcap-caps" AUID, it MUST be
> listed in the <auids> element and the
> "urn:ietf:params:xml:ns:xcap-caps" namespace MUST be listed in the
> <namespaces> element.

Added your suggestoin on nsamespaces.

> 
> Comment: It doesn't seem to be a good idea to list the supported
> namespaces unrelated to the AUIDs. When an XCAP server supports
> multiple application usages. All namespaces of all supported
> application usages are returned as just one list. From this one list,
> the XCAP client can not determine which namespaces are supported for
> which application usages.

"Supported" here really implies that the server can obtain the schema 
for elements from that namespace. Consequently, I don't think it really 
matters what application usage they are from.

> 
> 
> 13.  Examples
> 
> Comment: The '/services' is to be removed in line with the
> recommendation of section 6.1.

Fixed.

Thanks for your comments!

-Jonathan R.

-- 
Jonathan D. Rosenberg, Ph.D.                   600 Lanidex Plaza
Cisco Fellow                                   Parsippany, NJ 07054-2711
Cisco Systems
[email-masked]                              FAX:   (973) 952-5050
http://www.jdrosen.net                         PHONE: (973) 952-5000
http://www.cisco.com

_______________________________________________
Simple mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/simple