Brainstorming about resources states and al.

[Thomas Broyer <t.broyer@xxxxxxxxxxx>]

First: should states (draft/published) be applicable to every resource 
or to Atom entries only?

Next, let's see what we need and sum up some possible solutions.

Rationale
====================

We want to manage the state of resources with a rich and ideally 
extensible set of states (not limited to draft/published).
We also want to define properties on entries to allow/disallow comments, 
trackback/pingback, etc. we may however need more than "allow/disallow" 
values.
Finally, we also need a way to tell the APP server whether and which URI 
to trackback/pingback when creating or editing a resource (entries only?).

Solutions
====================

There are three distinct problems (resource states, entry properties and 
trackbacks/pingbacks) which can be discussed and addressed separately. 
The first two need a set of accepted values and a way to set/update the 
state/property value.

Resource States
------------------------------

We have two solutions here: restrict the set of resource states to a 
fixed number of values or allow it to be extended.
The first is not a great deal, we'll just have to find the way to 
set/update the state of a resource (see below). If an APP server is 
allowed to implement only a subset of these states, we'll also have to 
define the behavior of the server if the client tries to use an 
unsupported state (e.g. a "review" state to make the resource accessible 
to "reviewers" but not fully public; on a "single user" system, it 
should be interpreted as "fully private").

If we want to allow every APP server to extend the set of states (or 
actually, define the states it's supporting), we'll need a way for the 
server to send to the client its list of supported states. The client 
would then have to choose among those possible values or the server 
would respond with an error "unsupported resource state".
One solution here would be to augment the Introspection Document format 
to also contain a list of available states for each collection.

Setting a ressource's state
------------------------------

If we answer "entries only" to the very first question inside this 
message, then an entry's state is just the value of its "state" property 
and you'd set/update an entry's state the same way you'd set/update one 
of its properties' value (see below).

Even if we answer "every resource", the solution might as well be the same.

In the "entries only" case, we'll have to answer another question: is 
the state independent or part of the entry? In the first case, we'll 
probably have to add a new document format and a new "sub-protocol" (see 
PacePubStatusResource [1]). In the second case, the state is just a 
metadata property that can be implemented with a simple extension 
element (format-08 [2], section 6.4.1) which you'd add to your Atom 
entry when you GET, POST or PUT it.

Entry properties
------------------------------

As pointed out last November by Brent Simmons [3], properties may behave 
very differently from one another: they have different data types 
(booleans, dates, text, enumerated values (values taken from a fixed 
set)), different cardinality (single value, list of values (ordered or 
unordered), range of values, list of ranges or values), etc.

One thing however characterizes every property: a property is always 
present and always have a default value (which means it might be omitted 
in a "representation"). Even categories default to "no category" when 
not defined.

Setting a property's value
------------------------------

The easiest way of setting a property is to add a simple extension 
element (format-08 [2], section 6.4.1) into the entry.

However, it might be needed to change property values without having the 
entry to be considered updated (e.g. updating the atom:modified (has it 
been accepted for format-09?)).

Sending trackback/pingback
------------------------------

Trackbacked/pingbacked URIs are not really metadata about an entry but 
rather a message sent by the client to the server to instruct it to do 
some RPC stuff with the specified URIs; the server should ideally also 
be able to instruct the client which URIs have already been 
trackbacked/pingbacked while previously editing the entry.
I think that the way PacePubHeaders [4] dealt with that was pretty good 
(except Allow-Annotation and Allow-Remote-Annotation are actually 
properties of the entry; ...except if we want to allow 
trackback/pingback on any kind of resource, not only entries). To answer 
David Czarnecki's matter [5], we could define the Annotate header as 
"Annotate: <type>; <URI>" instead of just "Annotate: <URI>", with <type> 
being either "pingback", "trackback" or "discover" (if you want the 
server to sniff the remote resource) and defaulting to "discover" if it 
is an unrecognized value (this allows for later new values and it seems 
to be the way things are done in IETF RFCs).


[1] http://intertwingly.net/wiki/pie/PacePubStatusResource
[2] http://www.ietf.org/internet-drafts/draft-ietf-atompub-format-08.txt
[3] http://inessential.com/2004/11/18.php
[4] http://intertwingly.net/wiki/pie/PacePubHeaders
[5] http://www.imc.org/atom-protocol/mail-archive/msg00463.html

--
Thomas Broyer