UserPreferences

PaceCollectionControl


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

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

3. Non-entry collections MUST support control data.

3. Control information MUST be able to be set separately from updating

4. Control information MUST be extensible.

5. Control information MUST be in an XML document.

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

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

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>

Impacts

Notes


CategoryProposals