Subject: [Simple] Revised XCAP I-D posted

From: Jonathan Rosenberg <[email-masked]>
Date: Mon, 24 Oct 2005 00:59:24 -0400

Folks,

I've revised the xcap spec per discussion over the last few weeks and 
submitted to the I-D editor. At a high level, I made the following changes:

* fixed bugs and unclear things reported since approval
* added extensibility to the URI and described server behavior in the 
face of unknown URI
* added the ability to select namespaces and GET them, returning a 
simple document format that defines the namespaces for an element
* RECOMMEND conventions for the xcap root services URI, XUI and 
directory structures to avoid the need to configure these
* Significant new text discussing where elements get inserted exactly, 
especially as it relates to white space, comments, etc.

Until the document appears, you can pick it up at:

http://www.jdrosen.net/papers/draft-ietf-simple-xcap-08.txt

I think there is more discussion to be had here; I'll post a few notes 
momentarily.

Here are the detailed changes I made to the document:

* Added extensibility for the URI. This was done by adding two hooks
into the grammar for the URI. Added language that requires a server to
reject a request with a 404 if it doesnt understand one of the
extensions. Mentioned that a xcap-caps document lists an extension
token for extensions that extend the selector capabilities of xcap.

* Added the ability to query for namespaces, using namespace::* from
xpath. Specify this only for GET - returns a 405 if in PUT or
DELETE. It returns a document of form xcap-ns+xml, which is an xml
fragment containing a single element, which is the element whose
namespace bindings are desired. That element has xmlns and
xmlns:prefix declarations for all in-scope namespaces. Gave an example
of how this works. Added MIME type definitions for it.

* Fixed faulty XML document example in section 6.4, which should have
had a namespace binding declared with xmlns:ns3 and not xmlns:hi as
written.

* Example in section 6.3 didn't respect whitespace in the value
returned by the xcap query. Fixed this.

* Example namespace binding declarations with xmlns() in section 6.4
included quotes in them, but those are not allowed URI characters ane
need to be escaped. Fixed them to be escaped with %22

* Section 7.4 said, " The "*" indicates that all children of 
<watcher-info> are to be
    considered when computing the position for insertion.  If, instead
of ..." when it really mean, "..indicates that all element
children...". So, added the word element in there.

* There was some discussion on the list in early September around
confusion on when to send a 200 or 201. Specifically, Dean had asked
this:

Here's the question as it was asked me: "Problem Summary: In the
document: "The Extensible Markup Language (XML)Configuration Access
Protocol, (XCAP), draft-ietf-simple-xcap-07" section 8.2.6 is unclear
regarding a server response to a PUT request.  Problem Text: In the
document: "The Extensible Markup Language (XML)Configuration Access
Protocol, (XCAP), draft-ietf-simple-xcap-07" section 8.2.6 states "If
the creation or insertion was successful, and the resource
interdependencies are resolved, the server returns a 200 OK or 201
Created, as appropriate."

This text is faulty. In particular, the sentence, "If the creation or
insertion..." is problematic, since both creation and insertion result
in a 201. The text needs to say creation or replacement, to match up
with the operations defined in Section 8.2.3 and 8.2.4
respectively. There was also some confusion about whether 201 applies
to element or attribute insertions. The answer is
ABSOLUTELY. REmember, the big idea with xcap is that elements and
attributes are just resources like any other http resource, and rules
for handling them apply as defined in rfc2616.

So, the new text I put in the last paragraph of 8.2.6 now reads:

<t> If the creation or replacement was successful, and the resource
interdependencies are resolved, the server returns a 201 Created or OK
or 200, respectively. Note that a 201 Created is generated for
creation of new documents, elements, or attributes. If the client
included "application/xcap-diff+xml" in an Accept header in the PUT

* Updated URI reference from 2396 to 3986 per Ted's recommendation in
the discussoin on quoting of ~~

* Clarified the escaping of ~~ in the beginning of section 6. Text now
reads:

..identifies a document within the XCAP root. The path separator is a
path segment with a value of double tilde ("~~"), and SHOULD NOT be
percent-encoded, as advised in Section 2.3 of RFC 3986 <xref
target="RFC3986"/>.  URIs containing %7E%7E should be normalized to ~~
for comparison; they are equivalent. The path separator is piece of
syntactic sugar that separates the document selector from the node
selector. The node selector is an expression that identifies an XML
element within a document.  </t>

* removed schema-instance declarations from example documents per
Jaris comments

* On the whole insertion thing, I removed this paragraph entirely from the
bottom of section 7.4:

<t>
When the client does not explicitly indicate a position in which to
insert a new element, the server will insert that element as the last
child of that parent. If this is not the desired position, the client
should perform a positional insertion.
</t>

This is misleading, since even with an explicit position there is only
a certain amount of control on where the server inserts.

And indeed, where the server inserts was very much underspecified. The
logic I sent out on the list didnt quite work, since it led to various
inconsistent behaviors. I ended up adding the following text in
Section 8.2.3:

<t> 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 <xref target="sec:parent"/>. The insertion is done
such that, the 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 production (in other words, there is no position
indicated) the server MUST insert the element such that it is in the
"earliest last" position. "Earliest last" means that it MUST be
inserted so that there are no elements after it with the same element name,
and for all insertion positions where this is true, it is inserted
such that as many sibling elements appear after it as
possible. Furthermore, if there were comment, whitespace, or
processing instructions after the last element with the same name,
they MUST occur prior to the insertion of the new element. In other
words, it appears just after the last element with that name, but
before any comments, whitespace or processing instructions. If there
were no other sibling elements with the same element name, the new
element is inserted such that it is the last element amongst all
element siblings. Furthermore, if there were comment, whitespace, or
processing instructions after the former last element,
they MUST occur prior to the insertion of the new element.
</t>

<t> If a position is indicated, the server MUST insert the element so
that it is in the "earliest nth" position. Earliest nth position means
that it MUST be inserted so that there are n-1 elements before it with
the same element name, and for all insertion positions where this is
true, it is inserted such that as many sibling elements appear after
it as possible. Furthermore, if there were comment, whitespace, or
processing instructions after the previous element with the same name,
they MUST occur prior to the insertion of the new element. If there
were no other sibling elements with the same element name, a
positional insertion is only possible if the position was 1. In such a
case, the new element is inserted such that it is the last element
amongst all element siblings. Furthermore, if there were comment,
whitespace, or processing instructions after the former last element,
they MUST occur prior to the insertion of the new element.  </t>

<t>
For example, consider the following document:
</t>

<figure><artwork>
<![CDATA[
<root>
  <el1 att="first"/>
  <el1 att="second"/>
  <!--comment -->
  <el2 att="first/>
</root>
<figure><artwork>
]]></artwork></figure>

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

<figure><artwork>
<![CDATA[
<root>
  <el1 att="first"/>
  <el1 att="second"/>
  <!--comment -->
  <el1 att="third"><el2 att="first/>
</root>
<figure><artwork>
]]></artwork></figure>

<t>
Notice how it has been inserted as the third el1 element in the
document, and has been inserted right below it, but just after the
comments and whitespace. It would have been inserted in exactly the
same place if the node selector had been root/el1[3][@att="third"]. If
the content of request had been &lt;el3 att="first"/&gt; and the node
selector was root/el3, it would result in the following document:
</t>

<figure><artwork>
<![CDATA[
<root>
  <el1 att="first"/>
  <el1 att="second"/>
  <!--comment -->
  <el2 att="first/>
<el3 att="first"/></root>
<figure><artwork>
]]></artwork></figure>

* I added the following text in section 8.4 on whitespace handling:

Note that
this deletion does not include any white space around the element that
was deleted; the XCAP server MUST preserve surrounding whitespace.

* RECOMMEND that XUI = SIP AOR

* Added the following text in the section on naming conventions for
application usages:

<t>
For many application usages, users need only a single document. In
such a case, it is RECOMMENDED that the application usage require that
this document be called "index" and exist within the users home
directory.
</t>

URI construction talks about this as well, recommending that, when
there is a single document, its called "index". Explicitly say that
usage of subdirectories is NOT RECOMMENDED. MUST NOT have a document
and sub-directory with same name.

Thanks,
Jonathan R.
-- 
Jonathan D. Rosenberg, Ph.D.                   600 Lanidex Plaza
Director, Service Provider VoIP Architecture   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