[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

PaceCollectionControl



http://www.intertwingly.net/wiki/pie/PaceCollectionControl

== Abstract ==

Put the only agreed upon control flag into the entry in it's own
namespaced element. It is updated but PUTting the whole entry.

== Status ==

Open (JoeGregorio)

== Rationale ==

I took an informal survey and this is what I heard, or at least what I
was able to glean from the conversation. If I have misrepresented your
position please update this Wiki entry. I have added my own votes to
the final tally.

1. Control information MUST be sent with the initial POST to create an
entry.  (otherwise creating a draft is a two step process.)

   +1 from Tim Bray, Eric Scheid, Thomas Broyer, James Snell, Joe
Gregorio. (Other people had questions, but I saw no votes)

2. Control information MUST be sent with the initial POST to create
anon-entry member.

   +1 from Eric Scheid, James Snell. 
   -1 from Ezra Cooper, Thomas Broyer, Joe Gregorio.

3. Non-entry collections MUST support control data.

   +1 from Eric Scheid, James Snell
   -1 from Thomas Broyer, Ezra Cooper

3. Control information MUST be able to be set separately from updating
   an entry via PUT. (because the overhead of PUTing the complete entry
   is too much overhead)

   -1 from Tim Bray, Joe Gregorio
   +1 from Eric Scheid, James Snell

4. Control information MUST be extensible.

   +1 from Tim Bray, Eric Scheid, Thomas Broyer, James Snell
   +0 from Joe Gregorio

5. Control information MUST be in an XML document.

   +1 from Tim Bray, Eric Scheid, Thomas Broyer, James Snell, Joe Gregorio

6. Control information MUST be contained inside the entry document.

   +1 from Tim Bray, Eric Scheid, Thomas Broyer, Joe Gregorio
   +0 from James Snell


>From this I concluded that we only want to include control information
to members of Entry Collections and not Generic Collections. That's
nice because it simplifies things, such as allowing the control
information to be included in the entry itself. This lines up nicely
because an Entry in a 'resource', and the Atom entry that you GET and
PUT 'represents' the 'state' of that resource and that state includes
whether or not it is a draft.

My personal rationale for requiring the entry be PUT to update the
'draft' status is:
1. It is conceptually the simplest thing that could possibly work
(aside from not doing any control at all).
2. I believe it is a much more common use case the you are going to
edit your draft one last time before
   deciding to switch it from draft to published. That means the
requirement to PUT the entire entry is not
   onerous at all and in fact falls into the primary way 'draft' is used.

The astute will observe that this proposal is just Tim Bray's
proposal, just stripped
of any elements except 'draft'.

== Proposal ==

Add a new top-level section X to the protocol-04 draft:

=== X.1  The Atom Publishing Protocol Namespace ===

The namespace name for the Atom Publishing Protocol's XML markup vocabulary is 
http://example.net/appns/. 
For the purposes of this document, we will assume the use of the prefix "pub".

=== X.2 The "pub:control" Element ===

The "pub:control" element MAY appear as a child of an "atom:entry" which is
being created or updated via the Atom Publishing Protocol. The
"pub:control" element,
if it does appear in an entry, MUST only appear at most one time.

The "pub:control" element and it's children elements
MAY be included in Atom Feed or Entry Documents. The "pub:control"
element is considered "foreign markup" as defined in Section 6 
of the Atom Syndication Format.

The "pub:control" element may contain zero or more of the subelements
in the Atom
Publishing Control namespace described in this section. The "pub:control"
element follows the same rules for Extensions as 
outlined in the Atom Syndication Format, Section 6.

X.2.1 Control element values

This specification defines only one child element for "pub:control".

X.2.2 The "pub:draft" Element

The number of "pub:draft" elements in "pub:control" MUST be zero or one.
It's value MUST be one of "yes" or "no". A value of "no" means that
the entry may be made publicly visible.
If the "pub:draft" element is missing then the value is understood to
be "no". That is,
if "pub:control" and/or the "pub:draft" elements are missing from an entry then
the entry is considered not a draft and can be made publicly visible.

== Example ==

{{{
<entry>
 <title>Lorem Ipsum</title>
 <link href="http://example.org/lorem"; />
 <updated>2003-12-13T18:30:02Z</updated>
 <summary>Lorem ipsum dolor sit amet, consectetur adipisicing elit...</summary>
 <control xmlns="http://example.net/appns/";>
  <draft>yes</draft>
 </control>
</entry>}}}


== Impacts ==



== Notes ==


   Thanks,
   -joe

-- 
Joe Gregorio        http://bitworking.org