Subject: Re: AD Evaluation of draft-ietf-atompub-protocol-11

From: "Joe Gregorio" <[email-masked]>
Date: Thu, 7 Dec 2006 11:36:45 -0500

Lisa,
   Thanks for the very detailed review of this draft. More comments in-line.

On 10/17/06, Lisa Dusseault <[email-masked]> wrote:
>
>
> It would probably not be useful at this point for me to suggest a resolution
> to absolutely everything, especially if that involves specific wording.
> It's much more likely the WG/editors would choose different wording and
> organization anyway.  But when I get back from vacation (1st day of
> November) and catch up on the mailing list traffic, I will see if there's
> any place where I can suggest wording to capture what I meant in a way that
> the WG can agree.  I understand there's often a balance between leaving
> options open for different implementations and extensions, and closing
> options down so that specific behavior can be depended on, and sometimes
> there are ways you can have a little of both.
>
> High-level comments,  summarizing comments
>
>  - The mechanism for creating a media resource and a media link entry in
> response to a single POST conflicts with at least one statement elsewhere in
> the draft, and has no example.  This is one of those cases where I
> personally had some assumptions
> (that not every media resource had its own
> media link entry if the media resource had been created manually)

There may be 'other' media resources, but if they don't have an associated
Media Link Entry then they are not 'in' the collection.

> that
> weren't ever quite cleared up by the spec. If the client CAN create a media
> resource without also creating a media link entry, that should be a separate
> example.

>  - Overall, the responsibility model needs to be slightly better defined.
> E.g. we know the server is responsible for choosing a URL for new entries;
> it's not clear who's responsible for cleaning up linked entries if a user
> ever needs to clean up historical entries.  Atom sometimes seems to split
> the responsibility, and those are the most complicated cases.  More examples
> below as it's probably more useful to discuss specifics.

That used to be in the spec:

http://bitworking.org/projects/atom/draft-ietf-atompub-protocol-06.html#entry-constraints

It should go back in.

>  - To an outsider or newcomer -- including me even though I've been
> following discussions closely for a while -- there's a part of the Atom
> model that's subtle but important to understand.  Consumers of Atom feeds
> are supposed to look at the regular feed document, whereas publishers of
> Atom feeds are supposed to look at other, different resources to see how to
> edit or create posts.  Publishers effectively look at a different feed than
> users do, one with extra metadata (the rel="edit" links).  It's a different
> model than that of WebDAV or IMAP, because rather than have the client
> specify which metadata it's interested in, the server offers two choices
> with different addresses.  I believe it would be useful to cover that part
> of the model upfront in addition to the other useful stuff already there.

Agreed.

>
> Creating resources
>
> Explicit result of POST, section 4.
>
> Are there zero, one or more resources created with a POST? There's a line at
> the top of section 4 which says that "POST is used to create a new,
> dynamically-named, resource".  However, that implies ONE, whereas with media
> entries, a POST could create TWO resources.  I believe a successful POST
> request as described here MUST either result in one or two resources, never
> zero, and never 3 or more (in the absence of extensions).

A POST can create any number of resources. In the case of an
entry collection it will be at least one. In the case of a media
entries it will be at least two. Many other resources could be created
but this spec should only concern itself with the ones of interest
for the operation of the protocol, otherwise the protocol
isn't of much use. For example, if we say that POSTing an entry
MUST only create one resource then how does the associated weblog
HTML page get created?

> What is the expected behavior of seeing a POST to an entry URL (rather than
> a collection URL)?  I see that this is currently undefined;

Yes, it is undefined. So is the effect of sending it a PROPPATCH, COPY, LOCK,
PATCH or MEGAFOO.

Agreed, a note to the effect that anything not defined in the
spec is, well, un-defined. I.e. we aren't holding any other
methods on the resources 'in reserve'.

> it may be worth
> stating that to warn clients.  (I'm pretty indifferent on this one, as in
> this case I can't see any obvious harm in different server behaviors
> existing,  if un-warned clients try it intentionally without knowing the
> results.  The only possible harm is if clients got confused, did a POST to
> an entry URL when a collection URL was intended, and the server does a
> success response which creates new resources or modifies existing resources
> in a way the client did not expect.  An error response would certainly be
> harmless for this undefined case but a success response could be real
> interesting.)
>
> Creating entries with multiple media resources
>
> It's never explained how a client would go about creating a feed entry with
> a number of media resources.  I imagine that it could be iterative; a client
> could create any of the resources at any time, and at any time after
> creating the feed entry, use PUT to update the feed entry to link to new
> media resources.  I assume -- though I didn't see it stated in the document
> -- that it's the client's responsibility in almost all cases to put links in
> the feed entry to point to the media resources, otherwise the media
> resources are unlinked (effectively hidden to readers).

Agreed, that's how it should work and the text and examples should
be bolstered to make that clear.

>
> The exception to this general process is if the client first uses POST to
> create both the media resource and the "Media Link Entry" in one go.  In
> this case, can the "Media Link Entry" (MLE) be transformed to a regular
> "Member Entry Resource" (MER)?  I thought it would be possible, but
> discussed just a bit with Tim today and he says no, so there you have two
> different readings of the spec.

I'll agree with Tim on that.

>  I guess a related question is what would
> happen if a client does a PUT of media content to an entry resource, or
> entry content to a media resource.

I think that falls in the "un-defined" territory.

> It's not clear to me whether a linked media entry is always listed in the
> metadata or not.
>   - When one or more "edit-media" link relations appear, who has been
> responsible for putting them there?

The server.

>  - When a media resource is deleted, who is responsible for removing the
> media resource link from the MLE?

The MLE itself should be removed, and this is done by the server.

>  - Section 4 says that the MLE contains the metadata for a Media Resource,
> but that seems to only assume a single Media Resource.  In the case of
> multiple Media Resources which the user intends to link into a single post,
> it's unclear to me whether there's one MLE for every Media Resource, or one
> MER for all the Media Resources created, or some other situation.  Again, in
> quick discussion with Tim, he says there is one Media Link Entry per Media
> Resource.  I can see how that would work but that was not at all my
> understanding before the discussion!

Tim is right, it's a 1-1 relationship. Obviously more
text and examples are needed.

> This document would benefit greatly from further examples:
>  1.  An example of creating a MLE and MR in a single POST; the request,
> response and the result (resource URLs) described.
>  2.  An example of modifying a MER to contain a new image or other media
> resource link: the request(s), possibly the responses (if it's interesting,
> it may not be), and definitely the result.
>  3.  An example of modifying a MER to change metadata (e.g. category or
> adding a new link relation element or both); possibly a failed request
> example would be even more interesting than a successful one.

+1

> Can a client modify an entry to contain a link relation element in the
> following cases:
>  - To result in an "edit" or "edit-media" link relation, where the resource
> represented does not meet the requirements in section 11.1 or 11.2?

No.

>  - To result in an "edit" link relation that actually points to a media
> resource, or a "edit-media" link relation that actually points to a MER?
>  - To point to a resource on a different server entirely?

There is no reason to believe that any of these resource are on
the same machine to begin with. I could POST to media to machine A
and have the MLE could be created on machine B and the editable media
resource itself created on machine C.

>  - To point to a valid media resource or MER that happen to be in a
> different collection than the one normally used for this feed?
>  - Will some servers forbid adding a link relation element entirely?  Is it
> important for the client to know that that will always be forbidden for that
> server -- can it detect the "always forbidden" case separately from the
> "this particular edit is forbidden" case?
> Which of these are errors, and if so how is the error handled?  Which of
> these MUST the server allow and handle?  I understand there may be some need
> for flexibility here.  Perhaps it's just standardized error messages
> required here.  For example, if there are some servers which allow a given
> link relation to point to another server, and some servers which do not
> allow, how would the servers which do not allow respond with a sufficiently
> specific error, so that the client can avoid trying the same thing again?

I think some text explaining up front that for all intents and purposes the
server is in charge and could reject/modify entries as it sees fit is in order.

> Multiple formats/langs for media resources
>
> Multiple formats are not sufficiently defined -- e.g. JPG and PNG versions
> of an image resource.
> Format negotiation is hard.

I will agree with that last statement and would like to punt on
stating anything concrete about creating variants beyond
saying it's "un-defined".

> I found guidance for how
> to select among different "edit-media" link relations depending on format
> and language, but I found no guidance on how to create multiple versions.
> If there's no guidance to clients or servers how to do it (would the client
> create multiple resources in different formats? could the server
> automatically do it as variants? could the server automatically do it as
> multiple resources, and would all formats be therefore listed?), it's
> probably worth considering whether there's possible interoperability harm
> here.  I can imagine clients creating alternate-format versions quite
> successfully because the operations would be explicit, but when I imagine
> how servers would go about it, I can easily see ways it could go wrong (e.g.
> creating new URLs for resources that are invisible to the media collection,
> having multiple URLs in locations where clients expect only one).
>
> I think there may be a very basic confusion here -- in my head or in the
> document or both -- about what the "edit-media" link relation does and is
> for.  When I read the text it seems to offer the possibility for multiple
> formats for a single media resource, as suggested by the text: "If a client
> encounters multiple "edit-media" link relations in an entry then it SHOULD
> choose a link based on the client preferences for type and hreflang".
> However, when I try to think about how a client would create a post with a
> totally independent set of JPG images (e.g. one of the Eiffel Tower, one of
> the Louvre and one of the Arche de Triomphe), the "edit-media" link relation
> also seems to have relevance. Which is it or both? (and as always, who is
> responsible for filling it in or removing it when new media resources are
> created or destroyed?)

Media to MLE is a 1-1 relationship. Other variants, such as
PNG, JPEG and GIF of an image might be created for an image
at the whim of a server.

> Thomas Broyer said in email July 24 that  "Having the Content-Location value
> equal to the Location one tells the client that the response body is a
> representation of the newly created resource".   This is a subtle reading of
> HTTP and, if it's true,  I want to make sure that implementors understand
> this without having to read the mailing list.  The spec reads " the response
> from the server SHOULD contain a Content-Location header that contains the
> same character-by-character value as the Location header."  If the response
> from the server does not contain both headers identical, what should the
> client conclude?  I think this is one of those SHOULD recommendations where
> the consequence of it not being a MUST need to be considered.  Possibly the
> spec needs to say under what conditions the server would do otherwise;
> possibly the spec should say what the client knows, or does not know, or
> must do, if the server does otherwise.

Personally I'd rather drop all that verbage about Content-Location and just
point to RFC 2616 and the definition of Location and Content-Location.

> Deleting Resources
>
> In the case of an entry that points to multiple media resources, can the
> server delete all those media resources and their MLEs?  (I think not).  If
> a client issues a DELETE to a media resource, is its MLE deleted? (The spec
> covers the opposite case already when a client issues a DELETE to an MLE.)

This is covered by M<->MLE 1-1.

> Can collections be DELETEd?  It's fine for servers to allow or no, but if
> servers don't support, what error to use.

"un-defined"

> Editing resources
>
> Overall, the process for editing a resource is not entirely clear.  I find
> the description of creating a resource (POST), and what the server can
> accept, ignore or reject, more clear than the description of editing a
> resource (PUT) .  For example, there's normative text in section 9.2.1 (an
> example) relative to creating resources and handling metadata, but that text
> isn't duplicated for editing resources or obviously apply to editing
> resources. Thus:
>  - Can the client change the category?  (probably yes; MUST the server
> allow?)
>  - Can the client change the atom:id?  (probably never)
>  - Can the client change the "updated" value to be some time in the future?
> Some time long ago?  Or are there only two non-error changes -- "now" or
> "the previous value"?  MUST the server accept the value if it's the same as
> the previous value?  Or can there be servers that always ignore "updated"
> values from clients? (and if so, is it important for the client to know that
> the server does this)
>  - Can the client change the set of link relations? (probably yes; but does
> that include "edit" and "edit-media" link relations only or also
> first/previous/next/last link relations?)
> In general the possible edits need to be covered to consider whether the
> server MUST allow these kinds of edits, or MAY, and if refused, what error
> for what reason.

Agreed, like I said, this was in previous versions and should be
updated and restored:

http://bitworking.org/projects/atom/draft-ietf-atompub-protocol-06.html#entry-constraints

>
> I already threw in a request for an example of modifying a resource above,
> because one of the cases for editing a resource is to add a media resource
> to it.
>
> The spec says "The value of atom:updated is only changed when the change to
> a member resource is considered significant. "  The use of passive voice
> obscures who does what here.  When the client doesn't suggest a value for
> "atom:updated", does the server provide one, and if so, how does the server
> know what is "significant"?   I thought it would always be the client
> suggesting values, but Tim says that the server controls atom:updated which
> could imply that the client doesn't even need to suggest values.  See above
> about whether the server MUST accept certain values for "updated", or more
> likely, MUST NOT accept suggested values for "updated" when they're clearly
> wrong (e.g. this entry was last updated on October 16, 1906).
>
> Can a server ever ignore part of an edit and successfully process the rest?

Yes. Think of a client that throws in a slew of random link elements with
relations my server implementation doesn't understand. Same with foreign
markup. The server is in charge.

Here is another example, a server could take in an entry with content
that was HTML and clean it up and the next time the entry
is accessed the content could be XHTML.

> For example, the server receives a PUT request that tries to edit the text
> of a MER and includes a new category value, the server accepts the new text
> but silently ignores the category value.  I suggest the answer would be MUST
> NOT silently ignore suggested changes, particularly since there's no way in
> a PUT response to say "here's what the server actually stored".   It may be
> my opinion differs here from that of the WG.  I find silently ignoring input
> to be scary.

The client can always do a follow-up GET.

I believe it's unavoidable and trying to specify it would either
become a rat-hole or would end up making the spec impossible
to implement.

>
> Synchronization
>
> I predict that some AtomPub authoring clients will attempt to synchronize:
> to maintain an offline copy of the feed including all its MERs and media
> resources, and to keep that offline copy up-to-date.  Some will probably
> even allow offline authoring of new posts, and offer to synchronize when the
> client next goes online -- because of the possibility of multiple authors,
> this may mean at times that the client would download new entries created by
> other authors, upload new entries created offline, and reconcile its offline
> copy of feed documents.
>
> Because authoring clients will attempt to do this based on Last-Modified and
> ETag -- after all, the functionality is all there in some form or another --
> the spec needs a little more clarity on how the client can rely on this
> working.  Otherwise, some servers may omit features that these authoring
> clients require, or implement them oddly.  While I would never suggest
> repeating all the requirements from other specs (in this case HTTP), there
> are cases where clarity and interoperability are greatly improved by at
> least referencing explicitly requirements from HTTP.  It's also possible to
> add new requirements based on features in HTTP, that apply to Atom servers
> alone.

Agreed, a little verbage and a link to http://www.w3.org/1999/04/Editing/
would be good.

>
> You can see that I lean more towards the "explain confusing things" side and
> "add more stringent requirements" than to the "it's already written
> elsewhere side" by peeking at section 8.2 of CalDAV
> <http://www.ietf.org/internet-drafts/draft-dusseault-caldav-15.txt>.
>  A mostly-explanatory guidelines section helps clients quickly understand a
> clear path towards synchronization, and new requirements for supporting
> ETags make things easier for what is, after all, a more limited use case of
> HTTP (calendaring) than the general case.  If HTTP synchronization in
> authoring cases were clearly defined and had not lead to years of arguments
> since the last HTTP update, I would probably feel differently about just
> silently relying on the mechanisms in HTTP.
>
> In any case, I have very specific brief suggestions to cover synchronization
> so that it's implemented more successfully than not.

Hey, we used to have that in there too:

http://bitworking.org/projects/atom/draft-ietf-atompub-protocol-04.html#collections_model_usage

>  - Consider adding a brief section offering clients non-normative guidelines
> on synchronization.  It doesn't have to limit server behavior so much as
> point out with green and red lights where the fairway is (mixing
> transportation and golfing metaphors in my head)
>  - Make a few requirements of servers to avoid some of those HTTP
> ambiguities.  For example:
>  "The ETag or Last-Modified values for a member resource MUST change when
> any metadata in the resource changes, as well as text/content, and this
> includes "next" and "last" link relation values.  The ETag or Last-Modified
> values of a member resource MUST NOT change solely because an associated
> other resource (e.g. the media resource being an associated resource to the
> media link entry resource) changed.  "
>
> More open questions that might be related to synch or might have relevance
> even for clients that don't do full synch:
>  - What is the relationship, if any, between the "atom:updated" value and
> the HTTP "Last-Modified" value.  Can the "atom:updated" value ever be later
> (greater) than the "Last-Modified" value?  I believe it can be the same or
> earlier, but the spec doesn't disallow the broken case.
>  - Is it clear whether the client MUST GET the entry after modifying it in
> order to have an accurate offline cache?  (this was mentioned in a post by
> Broyer Jul 13, but not in the document).  I believe this is made clear
> already for the cases of getting the feed and also for POST/create, but not
> for PUT/modify.
>  - Am I correct that the general assumption is that id's are there to see
> what entries are new, and URLs are there to see where to get them?  That may
> mean that URLs could change, for a given ID -- Perhaps a feature to change
> the slug name of a image after attaching it.  Is that theoretically
> possible?

Yes.

> There are also efficiency considerations.
>  - The spec could require that servers MUST return either the ETag, or the
> Last-Modified value, in any successful POST or PUT response.  I personally
> favour this so that clients can rely on it, though obviously other opinions
> are valid here.
>  - I really liked the idea of putting ETag in the author's feed, as
> discussed on the list but not appearing in the document, again for
> efficiency.
> Certainly, the spec could ignore these considerations for now.  However, I
> have noted that many client implementations choose a single way to implement
> their logic that can be relied upon if a reliable approach is available,
> rather than respond differently to different implementations.  Thus, I
> predict that if some servers implement more-efficient synchronization and
> others don't, clients will behave as if they're always talking to the
> less-efficient servers. The more-efficient servers will find it difficult to
> achieve better scalability through synch efficiency improvements because
> clients have already implemented reliable but inefficient synchronization
> and don't have reason to add a second logic path for the more-efficient
> servers.
>
> Internationalization
>
> How are categories compared? Case-sensitive, insensitive, according to which
> language? Would the categories "donné" and "donne" map to the same category
> as "Donne" and "DONNE"? I believe it's currently up to the server, which
> means unpredictable behavior from the point of view of clients. See
> http://www.ietf.org/internet-drafts/draft-newman-i18n-comparator-14.txt,
> which has passed IESG Evaluation except for some IANA actions.   This is a
> danger area for any draft going before the IESG which looks carefully at
> i18n these days.
>
> How do lang tags inside the document relate to Content-Language information
> in headers? Does the most granular override the other possible values?  What
> about when client provides to server? Does the server ignore or handle?
>
> Other
>
> The requirements for the link relations "next", "previous", "first" and
> "last" aren't as rigorous as for "edit" and "edit-media" link relations.
> Also they're defined quite separately -- I kind of thought that all the link
> relation types could be usefully defined in one section but if the editors
> prefer a different organization that's fine.  But; is it OK if the resource
> pointed to by one of these link relations is on another server, in another
> feed, is a different kind of resource than you might normally expect, etc...
> ?  I think the normal cases for these link relations are well-understood but
> not necessarily what a client should do if it encounters abnormal cases.
>
> Discovering feed reading URL
>
> A very minor feature request for the introspection document: it SHOULD
> contain the public or published read-only feed URL of the blog (Tim suggests
> using link rel="alternate" type="application/atom+xml", although I'm not
> sure that makes it sufficiently clear what it's for).   This so that my blog
> editing tool can show me not only all the entries and media resources (all
> discoverable from the introspection doc already) but also where the blog is
> published, so that I can copy that link to my friends when telling them
> about my blog.
>
> Extensions
>
> When the client puts extension elements in a MER, MUST the server store
> those unrecognized extension elements?

No.

>  I think the answer to this is
> actually that servers often do not and should not be required to do so.
> That makes it hard for clients to extend AtomPub's syntax in ways that other
> clients will understand but servers don't care about.  Consider the
> consequences: when some enterprising client developer decides to do
> something cool and useful and encounters servers that don't store their
> metadata in the obvious place, the client developer is going to quickly work
> around that by storing in some unobvious place.  For example in HTML
> comments in the atom entry content, or microformats, etc.  Is that all cool?
>
>
> (Aside: an example of clients working around servers like this is that some
> WebDAV servers in the very early days didn't actually allow clients to
> PROPPATCH custom properties as the authors clearly intended.  Some client
> wanted to put extra structured information on a resource when it was locked.
>  Instead of putting it in properties, since that didn't work reliably, the
> client instead put it in the LOCK entry's "owner" element!  Of course that
> didn't reliably interoperate either because some servers overwrote the
> "owner" element with authoritative information -- the lock's actual owner as
> known by the server.  So the workaround solution was also harmful to
> interoperability, only it was discovered after the client had shipped.)
>
> Workspaces
>
> What are workspaces?  I would like to see a definition.  I believe I
> understand that basically, a workspace corresponds to a single published
> feed; that a workspace contains the collections with the content authored
> for that feed.  I know the WG discussed this so maybe I can suggest wording
> at some point or simply register my vote for saying what it *is*.

I'll make you a deal, you define what a "web site" is and then
I'll define a workspace :) I think this is murky sematic territory best
handled by the W3C TAG.

> Besides the definition, I also wonder about workspace titles.  That seems
> redundant with the title of the entry collection and possibly also the title
> of the feed (inside the main feed document).  Is there any understanding of
> some of these values being identical, or any understanding of what different
> purpose they serve if they're not identical?
>
> OPTIONS response
>
> HTTP is unclear about where PUT and POST show up in Allow headers.  WebDAV
> ran into this as an interoperability problem -- some clients assumed that if
> they didn't see PUT in the Allow header for a collection, they couldn't
> write to that collection (the client might be checking for permissions or
> policy, having already established that the server was a WebDAV server but
> not certain if PUT would be allowed to this particular place).  Some servers
> had PUT in the Allow header value for a collection, some servers didn't,
> based on the literal reading that you couldn't actually PUT straight to a
> collection URL.  Clients had to end up with the OPTIONS Allow: header
> response being useless in this case.  With somebody else's hindsight, Atom
> doesn't have to leave this ambiguous for the special kinds of resources it
> defines...
>
> Cookie support, sessions, authentication
>
> Is there an assumption that clients MUST support cookies?  without such a
> requirement explicitly stated, some clients won't, for reasonable security
> concerns.  Instead, is there an assumption that clients MUST repeat
> authentication headers with each request?  Or will servers effectively end
> up constantly "reminding" clients (through 401 errors) to authenticate?
> This might seem obvious but it definitely differs from regular HTTP practice
> where clients authenticate once and then stop sending authentication
> information automatically and it just works because of cookies.  Also we'd
> experienced this as an interoperability problem in WebDAV interoperability
> tests where some server implementors insisted that certain WebDAV clients
> were completely broken in not supporting cookies.
>
> Are there assumptions that sessions will be maintained through persistent
> connections?  I believe there should be none.  That is, if you're a client
> implementor thinking that the first request will contain authorization and
> subsequent requests on the same connection have no authorization, think
> again.

I've stated my piece on authentication and the IETF requirements.
Just let me know the boiler plate that needs to be put in there
and i'll do it. I have no more energy for the subject.

> ANCHOR sections
>
> It's not clear to me that the RFC Editor will know what to do with all the
> [[anchor... ]] sections.  Most difficult of all, "anchor37" says "incomplete
> section".  For the rest, sometimes the RFC Editor may need to know what to
> replace with what on publication.  I'm sure the doc editors know what they
> meant but I personally was left guessing.

Agreed, will clean up.

> Lisa

Thanks again for the close reading.

   -joe

-- 
Joe Gregorio        http://bitworking.org

---

From: Lisa Dusseault <[email-masked]>
Date: Thu, 14 Dec 2006 12:16:54 -0800

Thanks for responding to my review.  I look forward to seeing a  
revised draft.  Below I've excerpted the stuff that is still giving  
me serious problems.

> resource itself created on machine C.

This requirement has to be stated explicitly, at least as a SHOULD.   
This is the kind of thing that clients come to completely rely on,  
and then you find some special-purpose server that decides this  
doesn't fit in its model.  "Well, the spec doesn't require me to  
accept link relations which point to other servers."   Finger- 
pointing rather than interoperability.

If that's completely unacceptable, the only alternative that would  
allow good interoperability is to have an error code or  feature  
advertisement that allows the client to detect that the server won't  
allow this.  A generic "Forbidden" error (or other choice that could  
be made by the server) is not enough to know what is disallowed and  
whether it is always disallowed.  "What did I do wrong?" the client  
plaintively asks.

> markup. The server is in charge.

I completely disagree with this.  It is way too unpredictable for  
clients to deal with.  Clients are left with the illusion of  
flexibility -- it *seems* you can use Atom syntax extensions and do  
creative things that other extended clients can understand -- but in  
fact the server can alter this at will leaving the client without any  
control over what it's really publishing.  In many cases, the client  
won't even want the server to store some stripped version of what it  
POSTed, because it can really change the meaning of some entry to  
have the server strip some of the content and markup.  Imagine  
removing the start time and location when I'm trying to publish an  
event entry to what I believe ought to be a calendar feed.

Some server changes to submitted documents is of course going to be  
allowable (edit dates, server-provided IDs, changes which are  
effectively XML canonicalization) but I believe these need to be  
limited.  The general case, which is how servers deal with  
unrecognized elements, needs to be severely limited so that the  
server can either reject the whole request or store as provided.

Lisa

---

From: Sylvain Hellegouarch <[email-masked]>
Date: Thu, 14 Dec 2006 20:29:03 +0000

> This is the kind of thing that clients come to completely rely on, and
> then you find some special-purpose server that decides this doesn't fit
> in its model.  "Well, the spec doesn't require me to accept link
> relations which point to other servers."   Finger-pointing rather than
> interoperability.

I didn't quite understand your statement here. You make things more
complicated than what Joe actually said.

> 
> If that's completely unacceptable, the only alternative that would allow
> good interoperability is to have an error code or  feature advertisement
> that allows the client to detect that the server won't allow this.  A
> generic "Forbidden" error (or other choice that could be made by the
> server) is not enough to know what is disallowed and whether it is
> always disallowed.  "What did I do wrong?" the client plaintively asks.

A generic error code would mean there was an error in the first place.
Why is this the case?

> clients to deal with.  Clients are left with the illusion of flexibility
> -- it *seems* you can use Atom syntax extensions and do creative things
> that other extended clients can understand -- but in fact the server can
> alter this at will leaving the client without any control over what it's
> really publishing.  In many cases, the client won't even want the server
> to store some stripped version of what it POSTed, because it can really
> change the meaning of some entry to have the server strip some of the
> content and markup.  Imagine removing the start time and location when
> I'm trying to publish an event entry to what I believe ought to be a
> calendar feed.
> 
> limited.  The general case, which is how servers deal with unrecognized
> elements, needs to be severely limited so that the server can either
> reject the whole request or store as provided.

This is a fundamental change to what has been said over and over on this
mailing-list. Allowing the client to have more power than the current
draft allows on the Atom member would mean we have to detail all those
cases within the draft itself and would strongly limit its simplicity IMO.

Besides, if you want to do fancy thing with a member, simply post a
media resource which is an atom entry. This won't be modified by the
server and will solely be treated a media resource. Then the client will
have full control on it. The server must keep full control of the member
 resource.

- Sylvain

---

From: Sam Ruby <[email-masked]>
Date: Thu, 14 Dec 2006 16:37:54 -0500

> reject the whole request or store as provided.  

I believe I first saw this in a response made by Roy Fielding to an 
assertion that servers must treat HTTP PUT as a bit-for-bit copy, but I 
can't immediately find the reference.  In any case: clients must always 
consider the possibility that the server processes other requests (even 
internally generated ones) between the time the one the client issued 
and the next request the server choses to process.  Such requests could 
partially or completely change the representation of the resource.

- Sam Ruby

---

From: Sylvain Hellegouarch <[email-masked]>
Date: Thu, 14 Dec 2006 21:47:39 +0000

> can't immediately find the reference.  
> 

Could it be?

http://lists.w3.org/Archives/Public/ietf-http-wg/2006OctDec/0228.html

- Sylvain

---

From: Eric Scheid <[email-masked]>
Date: Fri, 15 Dec 2006 11:04:40 +1100

On 15/12/06 7:29 AM, "Sylvain Hellegouarch" <[email-masked]> wrote:

> server and will solely be treated a media resource.

promise? does the spec support this assertion? or is this another case of
"the server is in charge and can accept or change whatever it wants"?

e.

---

From: "Joe Gregorio" <[email-masked]>
Date: Thu, 14 Dec 2006 23:56:20 -0500

> can't immediately find the reference.

http://www.imc.org/atom-protocol/mail-archive/msg05425.html

> In any case: clients must always

---

From: "Joe Gregorio" <[email-masked]>
Date: Fri, 15 Dec 2006 00:23:48 -0500

On 12/14/06, Lisa Dusseault <[email-masked]> wrote:
> This requirement has to be stated explicitly, at least as a SHOULD.  This is
> the kind of thing that clients come to completely rely on, and then you find
> some special-purpose server that decides this doesn't fit in its model.
> "Well, the spec doesn't require me to accept link relations which point to
> other servers."   Finger-pointing rather than interoperability.

Older versions of the spec had this wording:

http://bitworking.org/projects/atom/draft-gregorio-09.html#rfc.section.4.3

"This RFC does not specify the form of the URIs that are used. The URI
space of each server is controlled, as defined by HTTP, by the server
alone. What this RFC does specify are the formats of the files that
are exchanged and the actions that can be performed on the URIs
embedded in those files."

Something along those lines could be added back in.

> I completely disagree with this.
> It is way too unpredictable for clients to
> deal with.  Clients are left with the illusion of flexibility -- it *seems*
> you can use Atom syntax extensions and do creative things that other
> extended clients can understand -- but in fact the server can alter this at
> will leaving the client without any control over what it's really
> publishing.

This happens *all the time* in the real world. Many blog
comment systems have 'Preview' buttons. Why? Because you never
know how the server is going to handle your text.

Yes, it might be nice, in the future, to add a way for a server
to advertise its capabilities, but we do not have the real world
experience with the protocol to know what that should look like.

> In many cases, the client won't even want the server to store
> some stripped version of what it POSTed, because it can really change the
> meaning of some entry to have the server strip some of the content and
> markup.  Imagine removing the start time and location when I'm trying to
> publish an event entry to what I believe ought to be a calendar feed.
>
> allowable (edit dates, server-provided IDs, changes which are effectively
> XML canonicalization) but I believe these need to be limited.  The general
> case, which is how servers deal with unrecognized elements, needs to be
> severely limited so that the server can either reject the whole request or
> store as provided.

I'm sorry but we've already argued this to death on the list and there
is nothing in HTTP which supports that view [1]. We've even reviewed
the scenario you are talking about and came to the opposite conclusion:

  http://www.imc.org/atom-protocol/mail-archive/msg05415.html

This is the documented consensus of the WG. The next draft will have
verbage that makes this position clearer. If some implementations
find that too loose and want octet-for-octet storage they can use
always WebDAV.

[1] http://www.imc.org/atom-protocol/mail-archive/msg05415.html

    Thanks,
    -joe

---

From: Sylvain Hellegouarch <[email-masked]>
Date: Fri, 15 Dec 2006 07:25:48 +0000

> "the server is in charge and can accept or change whatever it wants"?

No you are right, this is a gratuitous assertion here. However APP
currently describes what a server is allowed to do on a member resource
and not on the media resource.

It could be interesting to see how extensions to APP could allow the
server and the UA to agree on what level of modification each party is
entitled to expect.

- Sylvain

---

From: Julian Reschke <[email-masked]>
Date: Fri, 15 Dec 2006 09:42:04 +0100

Joe Gregorio schrieb:
> ...

WebDAV doesn't make any promises about what servers do upon PUT. It just 
relies on RFC2616.

Best regards, Julian

---

From: Sam Ruby <[email-masked]>
Date: Fri, 15 Dec 2006 06:06:15 -0500

> http://www.imc.org/atom-protocol/mail-archive/msg05425.html

That's the one!

- Sam Ruby

---

From: Tim Bray <[email-masked]>
Date: Fri, 15 Dec 2006 08:13:48 -0800

> This requirement has to be stated explicitly, at least as a SHOULD.

Hmm.  One particular operation in the APP is defined as creating two 
resources; we specify how this is requested and the mechanism by which 
the server communicates the URIs that identify the newly-created 
resources.  It would feel really weird to me to specify anything about 
what servers the resources might be on.  That's not how URIs work or how 
the Web works.  You can't tell by looking at a URI what server the 
resource is on, anyhow.  The URI might not be an HTTP URI. Two URIs that 
look very much the same might reference data on different continents. 
That's the whole point of how URIs work.

Having said that, Lisa has already pointed out shortcomings in the 
number and placement of examples concerning this particular case.  I 
think it'd be a good idea to have the example showing the Media resource 
showing up at http://media.example.com and the MLE showing up at 
http://app.example.com.

But I'd be very much against side-tripping the protocol definition into 
any discussion of "servers".

 > I completely disagree with this.  It is way too unpredictable for 
clients to deal with.

Well, except there are several examples of APP clients that seem to do 
just fine.

Example: After extensive discussion, the WG achieved consensus that APP 
servers are *not* required to retain foreign markup.

Example: It is perfectly possible to imagine a server that morphs or 
prunes incoming entries for reasons of political censorship, security 
policies, markup standards, spelling-correction, automatic translation, 
or lots of other things we can't possibly imagine.

Example: my Ape protocol exerciser posts entries with a separate 
<content> and <summary> fields.  At least one of the servers I've tested 
against accepts posts but discards my summary and generates its own, 
algorithmically.

The range of things a server can usefully choose to do currently exceeds 
our ability to specify or constrain.  Fortunately, in HTTP, we have a 
protocol the semantics of whose state-changing verbs PUT and POST are 
remarkably well-matched for these interactions whereby a client says 
"please take this and publish it and tell me what you did" and the 
server says "OK, here's what I made of it."

The current WG consensus, way better than "rough", is that this level of 
interoperation is useful.  That consensus seems to be supported by 
implementation experience.

Lisa, perhaps the problem is that I'm reacting to a fairly general 
statement of concern.  Do you have some specific suggestions as to how 
server behavior could be limited or formally described?

  -Tim

---

From: Lisa Dusseault <[email-masked]>
Date: Fri, 15 Dec 2006 17:00:16 -0800

I guess I'm assuming that one would want clients to be able to extend  
Atom unilaterally.  The choices that I highlighted as problematic  
make it harder for clients to reliably add extensions to Atom  
documents.  (It remains easy for servers to add extensions to Atom  
feeds and entries using prescribed mechanisms like adding new  
elements in custom namespaces.  )

Since clients post Atom entries and other clients retrieve them, it  
seemed reasonable to want to extend Atom client-to-client.  If I used  
"AtomFu" client that was able to annotate my entries automatically  
with what music I was listening to (track name, album and artist in  
XML elements) while I wrote a blog posting, I thought AtomFu should  
just store that as XML markup in the entry.  Other users running  
"AtomFu" will see that information and nobody else needs to upgrade  
-- not servers, not other clients.  Eventually if other clients see  
this as a useful feature they'll make the additional markup visible.   
Servers probably would never need to upgrade to use or touch that  
markup.

A model where servers aren't required to keep such information won't,  
in practice, allow that kind of extension. If clients can't rely on  
their markup getting stored, then clients can't extend Atom  
unilaterally using XML markup.

But implementors of client software are innovative, too.  You can't  
stop them from putting cool information in entries -- they'll just  
put it in a place where the server decides it's just natural-language  
or some other component that it does allow the client to create  
unmodified.  So maybe instead of seeing track name, album and artist  
in XML elements, we'll see them in square brackets or some other  
format in the blog entry "text".  This will hurt interoperability to  
a certain extent, as there is no standard way of extending the  
machine-parsable information within the *text* of an entry.

We won't see this today -- with new protocols, servers typically lead  
adoption, implementing the protocol before many clients emerge.  But  
in the long run, server deployments get old and yet as long as  
they're still running, admins avoid changing software or even  
upgrading.  Yet people who've gotten used to the new functionality  
start expecting more from it and seek out clients that do cool new  
things and still interoperate with their servers.  Bare bones clients  
are the first generation of a new technology, and innovative  
(whatever the barriers) clients come much later.

It may be that I'm just having trouble accepting that the WG fully  
understands this and has still come to consensus that this is a great  
way to proceed.  Is that the case?

thx,
Lisa

On Dec 15, 2006, at 8:13 AM, Tim Bray wrote:
>
> The current WG consensus, way better than "rough", is that this  
> level of interoperation is useful.  That consensus seems to be  
> supported by implementation experience.
>
> statement of concern.  Do you have some specific suggestions as to  
> how server behavior could be limited or formally described?

---

From: Tim Bray <[email-masked]>
Date: Sat, 16 Dec 2006 07:20:01 -0800

On Dec 15, 2006, at 5:00 PM, Lisa Dusseault wrote:

> I guess I'm assuming that one would want clients to be able to  
> extend Atom unilaterally.

That doesn't seem to have been a design goal for the WG.  To the  
extent that the issue never came up in the discussion.

> The choices that I highlighted as problematic make it harder for  
> clients to reliably add extensions to Atom documents.

You're being tactful with "harder".  I'd say "impossible".

Here's my take on the WG thinking:  The set of software  
implementations which could reasonably act as APP servers is  
incredibly large and heterogeneous.  A lot of them already exist.   
The requirement that they reliably round-trip arbitrary XML from  
clients is actually pretty onerous, since many (all?) of them will  
have internal data-storage models which will look very little like  
the Atom XML representation.

We think that APP as specified allows very good interoperability for  
basic Web-centric publish/edit operations with low overhead, and low  
demands for complexity in the client and sever implementations.    
Adding the requirement for client-side extensibility would reduce the  
number of server implementations that would be able to advertise  
conformance with APP, even though they are perfectly capable of the  
highly-useful function possible under APP as of the current draft.

> (It remains easy for servers to add extensions to Atom feeds and  
> entries using prescribed mechanisms like adding new elements in  
> custom namespaces.  )

Right.  Phrased another way, the APP is highly extensible; but the  
current version requires co-operation from both client and server.   
This seems reasonable to me.

> understands this and has still come to consensus that this is a  
> great way to proceed.  Is that the case?

Sort of.  Frankly, there seems to have been very little hunger for  
unilateral client-side extension, and a very strong aversion from the  
server-side people to accepting the round-trip-any-XML requirement.

   -Tim

---

From: James M Snell <[email-masked]>
Date: Sat, 16 Dec 2006 09:38:12 -0800

Tim Bray wrote:
> [snip]
> demands for complexity in the client and sever implementations.   Adding
> the requirement for client-side extensibility would reduce the number of
> server implementations that would be able to advertise conformance with
> APP, even though they are perfectly capable of the highly-useful
> function possible under APP as of the current draft.
> 

+1

>> entries using prescribed mechanisms like adding new elements in custom
>> namespaces.  )
> 
> current version requires co-operation from both client and server.  This
> seems reasonable to me.
> 

+1

> server-side people to accepting the round-trip-any-XML requirement.

From this implementors point of view client-side extension simply is not
a requirement.

- James

---

From: "Joe Gregorio" <[email-masked]>
Date: Sat, 16 Dec 2006 15:25:18 -0500

On 12/15/06, Lisa Dusseault <[email-masked]> wrote:
>
> I guess I'm assuming that one would want clients to be able to extend Atom
> unilaterally.  The choices that I highlighted as problematic make it harder
> for clients to reliably add extensions to Atom documents.  (It remains easy
> for servers to add extensions to Atom feeds and entries using prescribed
> mechanisms like adding new elements in custom namespaces.  )
>
> Since clients post Atom entries and other clients retrieve them, it seemed
> reasonable to want to extend Atom client-to-client.  If I used "AtomFu"
> client that was able to annotate my entries automatically with what music I
> was listening to (track name, album and artist in XML elements) while I
> wrote a blog posting, I thought AtomFu should just store that as XML markup
> in the entry.  Other users running "AtomFu" will see that information and
> nobody else needs to upgrade -- not servers, not other clients.  Eventually
> if other clients see this as a useful feature they'll make the additional
> markup visible.  Servers probably would never need to upgrade to use or
> touch that markup.
>
> A model where servers aren't required to keep such information won't, in
> practice, allow that kind of extension. If clients can't rely on their
> markup getting stored, then clients can't extend Atom unilaterally using XML
> markup.

I do not see the ability of clients to unilaterally extend the APP
using XML as a requirement.

> But implementors of client software are innovative, too.  You can't stop
> them from putting cool information in entries -- they'll just put it in a
> place where the server decides it's just natural-language or some other
> component that it does allow the client to create unmodified.  So maybe
> instead of seeing track name, album and artist in XML elements, we'll see
> them in square brackets or some other format in the blog entry "text".

You say that as if it's a bad thing. Personally I like microformats.
And besides, just because *your* client stuffs a track name, album
and artist into some XML does not automatically make it interoperable;
every client can, and will, choose to encode that data differently.

> This will hurt interoperability to a certain extent, as there is no standard way
> of extending the machine-parsable information within the *text* of an entry.

See microformats.

> understands this and has still come to consensus that this is a great way to
> proceed.

Like I stated previously, this has been discussed ad infinitum on the list
and the consensus supports it.

   -joe

---

From: Antone Roundy <[email-masked]>
Date: Sat, 16 Dec 2006 15:41:26 -0600

I'm not subscribed to the APP mailing list, so hopefully this isn't  
all redundant:

> markup getting stored, then clients can't extend Atom unilaterally  

There are two different issues here, which I think has been  
mentioned, but which might bear being clearly stated:

1) Do servers have to keep all extension data?

2) Can a server accept an entry while discarding some or all  
extension data, or do they have to reject the entry and return an  
error code?

I think the answer to the first question is clearly no--servers  
shouldn't be required to store all arbitrary data that is sent to  
them.  So the questions are:

1) Which hurts more--data loss or rejected entries?

2) Is there any way to reduce that pain?

The pain of data loss is obvious--the data is lost.  The pain of  
rejected entries is having to fix and repost them or decide not to  
try again.

In either case, it might be useful to be able to query the server  
somehow to find out what it will and won't preserve.  If data is  
discarded, you can figure that out after the fact by loading the  
resulting entry and checking whether the data is all there, but one  
might prefer to know ahead of time if something is going to be lost  
in order to be able to decide whether to post it or not.  If the  
entry is just going to be rejected, unless there's a way for the  
server to communicate exactly which data it had issues with, fixing  
the data to make it acceptable could be extremely difficult ("Hmm,  
I'll leave this data out and try again...nope, still rejected. I'll  
put that back in and leave this out...nope. I'll take both  
out...nope. I'll put both back in and take yet another piece of data  
out...").

So, how might a client query a server to see what it will preserve?   
A few possibilities:

1) Have some way to request some sort of description of what will and  
won't be preserved and what might be altered.  I don't know how one  
would go about responding to such an inquiry except to basically send  
back a list of what will be preserved, including some way to say  
"I'll preserve unknown attributes here", "I'll preserve unknown child  
elements (and their children) here", "I'll store up to 32767 bytes  
here", etc.  If there is any known extension markup that a server  
wants to explicitly state that it won't preserve, there may need to  
be a way to do that too.

2) Have a way to do a "test post", where one posts the data one is  
considering posting (or something structurally identical), but says  
"don't store this--just tell me what you WOULD store".  The response  
could include what would be returned if one were to load the data  
after it being stored, or it could be some sort of list of anything  
that would be discarded or altered.

3) (I get the impression this could be done without requiring  
changes--is this the sort of process that has already been  
selected?)  Post the data as a draft, reload it to see if it's all  
still there.  If so, or if what has been preserved is acceptable,  
change it's status to "published" or whatever it's called.  If not  
delete it and give up or take whatever other action is appropriate.

My impression is that data loss would be less painful and more easily  
dealt with than rejection of entries that won't be completely preserved.

...but I haven't followed the discussion, so what do I know.

---

From: James M Snell <[email-masked]>
Date: Sat, 16 Dec 2006 16:31:26 -0800

The moral of the story is simple: clients need to know what they're
getting into.

1. Servers can accept or reject whatever they want.
2. it's really nice if servers let client's know up front what they
   intend to accept or reject
3. at this point there's no need for any kind of handshake protocol to
   determine what a server will accept or reject.  What's most likely
   to happen (and most likely to actually be used and work effectively)
   is that server's will put up websites [1] that document exactly how
   their endpoints work and what clients should expect.

- James

[1] http://code.google.com/apis/gdata/

Antone Roundy wrote:
> 
> I'm not subscribed to the APP mailing list, so hopefully this isn't all
> redundant:
> 
> There are two different issues here, which I think has been mentioned,
> but which might bear being clearly stated:
> 
> 2) Can a server accept an entry while discarding some or all extension
> data, or do they have to reject the entry and return an error code?
> 
> shouldn't be required to store all arbitrary data that is sent to them. 
> So the questions are:
> 
> rejected entries is having to fix and repost them or decide not to try
> again.
> 
> might prefer to know ahead of time if something is going to be lost in
> order to be able to decide whether to post it or not.  If the entry is
> just going to be rejected, unless there's a way for the server to
> communicate exactly which data it had issues with, fixing the data to
> make it acceptable could be extremely difficult ("Hmm, I'll leave this
> data out and try again...nope, still rejected. I'll put that back in and
> leave this out...nope. I'll take both out...nope. I'll put both back in
> and take yet another piece of data out...").
> 
> So, how might a client query a server to see what it will preserve?  A
> few possibilities:
> 
> back a list of what will be preserved, including some way to say "I'll
> preserve unknown attributes here", "I'll preserve unknown child elements
> (and their children) here", "I'll store up to 32767 bytes here", etc. 
> If there is any known extension markup that a server wants to explicitly
> state that it won't preserve, there may need to be a way to do that too.
> 
> could include what would be returned if one were to load the data after
> it being stored, or it could be some sort of list of anything that would
> be discarded or altered.
> 
> changes--is this the sort of process that has already been selected?) 
> Post the data as a draft, reload it to see if it's all still there.  If
> so, or if what has been preserved is acceptable, change it's status to
> "published" or whatever it's called.  If not delete it and give up or
> take whatever other action is appropriate.
> 
>

---

From: Eric Scheid <[email-masked]>
Date: Sun, 17 Dec 2006 12:24:48 +1100

> extent that the issue never came up in the discussion.

Not sure exactly, but I did raise the possibility of a client passing in XML
whose only purpose is for the benefit of other clients. Things like
editorial comments and such. These would have been shepherded in the
app:control element, and there was a great deal of discussion about the
contents of app:control not being "published" (whatever that meant).

It got hairy, and there wasn't much support for the idea.

e.

---

From: "A. Pagaltzis" <[email-masked]>
Date: Sun, 17 Dec 2006 03:13:05 +0100

* Lisa Dusseault <[email-masked]> [2006-12-16 02:15]:
> Since clients post Atom entries and other clients retrieve
> them, it seemed reasonable to want to extend Atom
> client-to-client. If I used "AtomFu" client that was able to
> annotate my entries automatically with what music I was
> listening to (track name, album and artist in XML elements)
> while I wrote a blog posting, I thought AtomFu should just
> store that as XML markup in the entry.

That is, IMO, a misconception about Atom – one that is frequently
seen. We just had a similar discussion tonight in #atom on the
Freenode IRC network. The track name, album and artist are data;
they should be part of the payload of an entry, not part of its
envelope. In practice, that means you use either microformats or
a more structured format than HTML. Extending the Atom envelope
is a strategy of last resort.

Regards,
-- 
Aristotle Pagaltzis // <http://plasmasturm.org/>

---

From: Eric Scheid <[email-masked]>
Date: Sun, 17 Dec 2006 19:56:33 +1100

On 17/12/06 1:13 PM, "A. Pagaltzis" <[email-masked]> wrote:

> That is, IMO, a misconception about Atom  one that is frequently

wha?

What music Lisa is listening to when she wrote a blog posting is meta data,
not content, unless of course she's writing a blog posting *about* that
particular bit of music. The music is contextual meta data, along the same
vein as geo location of circumstance, the atom:generator involved, and even
the atom:published date/time.

Since when are we calling atom entries "envelopes"?

e.

---

From: James M Snell <[email-masked]>
Date: Sun, 17 Dec 2006 01:13:57 -0800

Quite frankly it doesn't matter what we call anything right now. The
server gets to determine what pieces of data it's willing to handle.
Period.  If you want anything more than that, use webdav.

- James

---

From: Julian Reschke <[email-masked]>
Date: Sun, 17 Dec 2006 10:48:12 +0100

> Period.  If you want anything more than that, use webdav.

Again: WebDAV doesn't redefine PUT, so the situation is exactly the 
same. (Unless you were referring to PROPFIND/PROPPATCH).

Best regards, Julian

---

From: Jan Algermissen <[email-masked]>
Date: Sun, 17 Dec 2006 11:34:27 +0100

> Period.  If you want anything more than that, use webdav.

(Sorry if this has already been said or not on the point, but I  
cannot read through the thread right now).

- The server is free to 'mess' with the PUTed data at will before  
doing the update; so it can strip out whatever it wants.

- Clients should do a GET before doing a PUT so they get  some chance  
to see what the sever actually handles

Jan

---

From: "Bob Wyman" <[email-masked]>
Date: Sun, 17 Dec 2006 16:37:02 -0500

On 12/16/06, A. Pagaltzis <[email-masked]> wrote:
>
> Extending the Atom envelope is a strategy of last resort.
>

+1

It is important to remember that not all processors of Atom data will know
what to do with unexpected metadata in the envelope. Thus, unexpected
envelope fields will often simply be stripped off and thrown to the bit
bucket. If you want data to stay with your "content," it is best to put it
in the <content/>...  Sometimes, it may be appropriate to extend the
envelope, however, one should not do so without a really compelling case.

Envelope extensions typically require "fetching time" or database structure
modifications in consuming applications if those extensions are to be
supported. This is because many feed consumers have distinct fields in their
databases or internal structures for each of the envelope elements and then
just have a single field for content. Also, the code for manipulating
envelope fields is usually distinctly different from the code used to
manipulate and process <content/>. So, if you create a new envelope field,
you require a great deal of code to be modified for that field to be
supported. On the other hand, if something can be slipped into <content/>
you'll see it being stored immediately and have the opportunity for
downstream consumers (display routines, etc.) to provide support for the
additional data. (For instance, you might write a GreaseMonkey script to do
interesting things with stuff encoded in <content/> even though the
"backend" of the application knows nothing about it.)

My personal feeling is that many of the proposals (but not all) for envelope
extensions are derived from what I consider to be unfortunate precedent set
in the RSS world where all sorts of random stuff has been pushed into the
envelope since in RSS the <description/> field is so under-specified that it
isn't really possible to think of it as something which can be structured.
Fortunately, the field has moved forward since legacy RSS was defined and
we've got better methods that can be used with Atom. There are undoubtedly
still things that might go in the envelope, but not as many as some folk
might think.

bob wyman

---

From: Jan Algermissen <[email-masked]>
Date: Mon, 18 Dec 2006 01:28:04 -0800

>envelope, however, one should not do so without a really compelling case.

I think the distinction to make is whether the information in question is necessary for whatever process the entries participate in. Processes should be able to work with the entries without having to dig into the actual content.

Jan