RE: Review of ordering draft, version 05

Lisa,

thanks for the review of the document. My comments are inline.

> From: w3c-dist-auth-request@w3.org
> [mailto:w3c-dist-auth-request@w3.org]On Behalf Of Lisa Dusseault
> Sent: Saturday, February 08, 2003 6:46 PM
> To: 'Julian Reschke'
> Cc: Webdav WG
> Subject: 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"

Fixed.

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

Well, the simple answer is, there *are* not pre/postconditions a server can
ignore. Quoting from RFC3253, section 1.6:

---> A "precondition" of a method describes the state of the server that
must be true for that method to be performed. A "postcondition" of a method
describes the state of the server that must be true after that method has
been completed. If a method precondition or postcondition for a request is
not satisfied, the response status of the request MUST be either 403
(Forbidden) if the request should not be repeated because it will always
fail, or 409 (Conflict) if it is expected that the user might be able to
resolve the conflict and resubmit the request.<---

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

Actually the goal was to do that by normatively referring to RFC3253.

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

All of them are MUSTs. Thinking of it (and remembering the WG discussion),
the ACL spec may want to clarify that it's using the terminology in a way
that is not fully compatible to RFC3253.

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

That's a good question. Is there any specific behaviour we want to mandate?
Are there use cases where a server may want to default to a specific
ordering type when none was given?

> 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?

Correct.

All we want to say that the ordering type was set as given:

(DAV:ordering-type-set): the collection was created with the specified
ordering type.


>   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?

Again, all conditons are MUSTs.

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

No, we don't. We just inherit. It means whatever RFC2396 wants it to mean.

> " 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."

Rewritten as:

"When the Position header is present, the server MUST insert the new member
into the ordering at the specified location."

> " (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.

It's what the spec has been saying for a long time.

I also don't see why that's a problem. It will only be a problem if

- the collection was ordered at time x
- a client does a PUT at time y and specifies a location header (if it
doesn't care, it can let it default to "last") *and*
- between x and y the collection was set to unordered by somebody else.

Seems like a case where I really *want* the request to fail. The client can
always use a sequence of PUT (without Position) and ORDERPATCH if this is
really an issue.

> "    (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?

Yes.

> "     (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?

Yes, it's a MUST.

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

However it also leads to text duplication. People can use both the TOC and
the index to locate the relevant section.

> 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

No, it doesn't. It uses DTD fragments in *exactly* the same way as RFC2518
and RFC3253, that is the standard WebDAV extensibility rules apply.

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

Correct.

Section 7 changed to say: "The ordering of internal member URIs in the
collection identified by the Request-URI is changed based on instructions in
the order-member XML elements in the order they appear in the request."

Also the explanations for example 7.1 were still assuming the old "href"
based syntax, I've updated that as well.

> "      (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?

That would be a server error (it's MUST).

> 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?

The URI that identifies the member that could not be repositioned. As per

"Since multiple changes can be requested in a single ORDERPATCH request, if
any problems are encountered, the server MUST return a 207 (Multi-Status)
response (defined in [RFC2518]), containing DAV:response elements for either
the request-URI (when the DAV:ordering-type could not be modified) or URIs
of collection members to be repositioned (when an individual positioning
request expressed as DAV:order-member could not be fulfilled)."

> "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.

That's because MOVE in RFC2518 is not atomic.

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

How would that help? A client can rely on the request being atomic.

> 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 is only defined for
collection versions. So yes, this only applies to servers that support
versioned collections.

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

Why would it mean that? A working collection doesn't have that property.

What indeed is missing here is some words about how the ordering in
DAV:version-controlled-binding-set affects UPDATE and CHECKOUT of collection
versions.

> 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

Yes.

> 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."

Well, in that case it supports RFC3253 features (namely these two live
properties). I'd say that normatively referring to a specific part of
another RFC should really be clear enough.

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

Done.

Again,

thanks for the review!

Julian

--
<green/>bytes GmbH -- http://www.greenbytes.de -- tel:+492512807760

Received on Saturday, 8 February 2003 14:56:17 UTC