Abstract
Put the only agreed upon control flag into the entry in it's own namespaced element. It is updated by 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. 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
pubControl = element pub:control { atomCommonAttributes, pubDraft? & extensionElement } pubDraft = element pub:draft { "yes" | "no" }
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 exactly one pub:draft element and MAY contain zero or more extension elements as outlined in the Atom Syndication Format, Section 6. Both clients and servers MUST ignore foreign markup present in the pub:control element that they do not know.
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>