Review of ordering draft, version 05

Since we're getting close to last call on the ordering draft, I reviewed
it all again (it's been years since I did so before).  Here are all my
comments.

Section 3:
"This document uses the terms "precondition" as "postcondition" as
   defined in [RFC3253]. "

Should be "and", not "as"

I don't think it's sufficient to just import the definitions of
precondition and postcondition. These are concepts that can clarify
what's going on, but unless it's accompanied by really plain English,
future readers of the specification won't be able to extract the
information they need. Long-timer WG participants may know the meaning,
but I'm learning more and more about people who never come to the
working groups, who may only read little pieces of our specifications
(e.g. a developer who doesn't usually do protocol implementation but is
assigned to fix a bug).  Server implementors won't bother verifying
whether some condition is one they have to enforce, or simply ignore it.
I strongly recommend including the standard MUST/MAY/SHOULD language
that specification readers are familiar with, particularly in the
postconditions which are not just error code definitions but also
specify behavior.

As an example, I'll jump ahead to the first precondition and
postcondition in section 5.1.  I'm not even sure what they mean, but
I'll try to guess in order to restate them. Here's what I'd like to see:

 Additional Preconditions:

      (DAV:ordered-collections-supported): Error used when the client
attempts to create an ordered collection, if the server does not support
the creation of ordered collections in this namespace.

  Additional Postconditions:

      (DAV:ordering-type-set): The server MUST set the ordering-type
property on the new resource to the value specified in the Ordering-Type
header by the client. If it cannot, this error should be used.

That's just a sample; all of the postconditions and preconditions need
to be full sentences explaining what must or may happen.

Section 5.1:
"If the Ordering-Type header is not present, the collection will be
unordered."

"Will be" is ambiguous standards language.  It implies MUST but doesn't
really require anything.  "... the server MUST create the collection as
unordered" is one possibility. However, it's fine to say "... the
collection MAY be created as unordered" if we want to give servers the
freedom to make new collections ordered by default.

Section 5.1: I don't see how the ordering-type-set postcondition can be
implemented. How can the server tell the difference between an ordering
type that it must support, or an ordering type that it's not supposed to
know about but just advertise?  
  Or is the server just supposed to set the value, period?  If that's
the case, then why isn't this simply a MUST requirement, rather than a
postcondition?
I suspect I don't really understand the ordering-type-set postcondition,
thus it probably just has to be explained more in the specification.
 

Section 6.1
The "segment" definition in BNF is imported from RFC2396.  But that
definition says that a segment can contain a "param":
	RFC2396
	  "segment       = *pchar *( ";" param )"

What would the param be or mean?  I suspect we'll have to define our own
here.

" The server MUST insert the new member into the ordering at the
      location specified in the Position header, if one is present (and
      if the collection is ordered)."

What does the "one" refer to in "if one is present"?  I think this means
"If the collection is ordered and a new member is inserted with the
Position header, the server MUST insert the new member into the ordering
at the location specified in the header."

" (DAV:collection-must-be-ordered): the target collection must be
      ordered."

Does this mean that the request to PUT a resource *fails* if the client
includes a Position header and the collection isn't ordered?  That's
expensive for a client to have fail.  I don't know if that's what client
implementors are going to want to happen.

"    (DAV:segment-must-identify-member): the referenced segment must
      identify a resource that exists and is different from the affected
      resource."

Again, does this mean the server MUST fail the PUT request if the
segment in the Position header doesn't exist?

"     (DAV:position-set): the newly created collection member was
      created at the specified position."

Shouldn't the server always create the new member at the specified
position (a MUST)? Under what circumstances would this ever not happen?

Specification organization: how about putting the Position and
Ordering-Type header definitions in their own sections, titled "Position
Header" and "Ordering-Type Header". That makes it easier for people to
use the specification as a reference.


Section 7.

"     <!ELEMENT orderpatch (ordering-type?, ordermember*) >"

This definition makes the orderpatch element (thus the ORDERPATCH
request body) non-extensible unless we say otherwise.  We could put in
the "elements not understood by the server MUST be ignored" language, or
redefine certain elements as

      <!ELEMENT orderpatch (ordering-type?, ordermember*, ANY) >

We need to say that the list of <ordermember> elements in the orderpatch
body is itself order-dependent -- I believe the server must process them
in the order they appear, first to last.  Actually, this is specified in
section 7.1 under the example, but it should be said in section 7.

"      (DAV:orderding-modified): if the request body contained
      DAV:ordermember elements, the ordering of internal member URIs in
      the collection identified by the request-URI has been changed
      based on instructions in the DAV:ordermember elements."

Isn't this a simple MUST rather than a postcondition?  "The server MUST
order internal member URIs in the collection identified by the
request-URI based on instructions in the DAV:ordermember elements in the
ORDERPATCH request body." Under what conditions would this
ordering-modified error be returned to the client?

Section 7.2.

This example shows what happens if the fourth <segment> element in the
request body does not name a valid segment.  By analogy, I can see what
would be returned if the second <segment> element were invalid. However,
I'm not clear what would happen if the first or third <segment> element
were invalid.  What would be returned in the <href> element in the error
response?

"Because ORDERPATCH is an atomic method, the request to
   reposition nunavut.desc (which would otherwise have succeeded) failed
   as well, but doesn't need to be expressed in the multistatus response
   body."

One of the things we've learned from RFC2518 interoperability is that's
not necessarily true. When a server does a MOVE on a collection, the
client has a hard time figuring out which things moved and which didn't.
Some responses have the failed dependency error, others don't.  Should
we consider being more specific here? The server could simply include a
424 Failed Dependency error for each ordering that failed because of the
atomicity of the method.

Section 9.1.

"The property DAV:version-controlled-binding-set ([RFC3253], section
   14.2.1) records the set of version-controlled bindings in the
   collection. For ordered collections, the DAV:version-controlled-
   binding elements MUST appear in the ordering defined for the checked-
   in ordered collection."

This is true only for working collections when versioned collections are
supported. At a minimum, change to:

"The property DAV:version-controlled-binding-set ([RFC3253], section
   14.2.1) records the set of version-controlled bindings in a
   working collection (part of the versioned collections feature). 
   For an ordered working collections, the 
   DAV:version-controlled-binding elements MUST appear in the ordering 
   defined for the associated checked-in ordered collection."

Doesn't that mean that the user can't reorder a collection that they've
checked out into a working collection?  

Section 10 (Discovery).

"  Furthermore, RFC 3253 [RFC3253] introduces the live properties
   DAV:supported-method-set (section 3.1.3) and DAV:supported-live-
   property-set (section 3.1.4). Servers MUST support these properties
   as defined in RFC 3253."

Do you mean that any server that supports this specification must
support these two RFC3253 properties as well? If so, that could be made
a little more clear like this:

"  Furthermore, RFC 3253 [RFC3253] introduces the live properties
   DAV:supported-method-set (section 3.1.3) and DAV:supported-live-
   property-set (section 3.1.4). Servers supporting ordered-collections
   MUST support these properties as defined in RFC 3253 even if the
   server does not support any RFC3253 features."

Section 16. Acknowledgements

"Lisa Lippert" was me, but my name is now "Lisa Dusseault" again...  I'd
much prefer to be listed as Dusseault!

Lisa

Received on Saturday, 8 February 2003 12:45:52 UTC