This proposal adds a single attribute top-level="true|false" to an Atom <entry> element, and removes the current semantics of the type="multipart/related" attribute of <content>, with the aim of providing a simpler, more general, and more Web-friendly way of dealing with multipart and compound posts.




The [WWW]Atom Syndication Format 0.3 pre-draft provides for the atom:content element to have @type="multipart/alternative", creating a simple two-level hierarchy. No existing syndication format offers such a content hierarchy. The use-case for this is said to be multimedia entries which include non-textual objects (e.g. pictures or video).

This notion of a compound entry accords not only adds complexity to the Atom format and protocol, it accords poorly with [WWW]Web Architecture; on the Web, everything either has a URI and is a Resource, or it doesn't exist. While there is the possibility of alternative representations of a resource via content-negotiation, it is fairly poorly supported and fails to meet many real needs. Put simply, the Web doesn't know about compound objects.

A common pattern in online publications for which feeds will be generated is for HTML-encoded narrative to embed pointers to graphics or other multimedia objects. The HTML and the other objects are all first-class Web resources, but normally only one of them (usually the HTML) will have its URI published to the world.

Atom can provide good support for this pattern, and simplify its publishing protocol, with the adoption of a single attribute top-level="true|false" for each <entry>, which if given as "false", requests that this entry not appear as a standalone item in publication or its syndication feed.

This will have two benefits. First, when posting a photo to a weblog, you will often want to point to it from a textual entry rather than having it show up by itself; but you still might like to use Atom to post it. Second, if you want the content which appears in the feed to include such a photograph, the easy way is to post it separately first but with top-level="no", then insert its URI into your (presumably HTML> <content>.


Replace the body of [WWW]4.13.10 with: "The "atom:content" element is a Content construct that conveys the content of the entry. An atom:entry element MAY contain zero or one atom:content elements"

Add section 4.13.11 as follows:

4.13.11 "top-level" Attribute

The atom:entry element MAY have an attribute named top-level whose allowable values are "true" and "false". If the attribute is absent, applications MUST behave as though it were present with a value of "true".

If the value is "false", this represents a request from the producer of the entry that this entry not be included as a separately-visible top-leve entry in the publication, nor appear in syndication feeds (presumably because it will be referenced indirectly from other entries). Software which encounters an atom:entry with top-level="false" SHOULD NOT display the entry as an independent item.


The structure of an atom:entry is simplified, and the design patterns for posting compound entries change.


See also: PaceObjectModule


[AsbjornUlsberg] Tim, could you create an example feed that shows how the @syndicate attribute impacts the format of the feed in situations where @type="multipart/alternative" were earlier used?

[TimBray] The original idea (I think) was to handle multiple different versions of the same thing, kind of replicating the functionality of content-negotiation. I objected that this seemed like a frill that the world of syndication has been getting by without. The come-back was that if we didn't have multipart, there'd be no way to post an entry with images & so on. This proposal feels like a better way to handle the entry-with-whatever problem, and I just don't think the different-versions problem is worth addressing in v1.0 of Atom.

[AntoneRoundy] Disclaimer: This is my first time editing a wiki, so if I format badly, feel free to fix it for me!

So, 1) You want to be able to use the Atom API to publish images and other such media. 2) You want these media items to have their own URI. 3) You want to avoid multipart/alternative. Another approach would be to have two Atom feeds. In one (which you don't intend for people to subscribe to), you post media items only. In the other, you post everything you want to show up in the feed everyone subscribes to. That one can refer to the media items in the other one by their entry URIs, just as they would in this proposal, but you don't have to add an extra attribute to keep them from showing up as separate items in the feed that everyone is supposed to subscribe to.

[TimBray] Yep. So it's a trade-off, which is easier/smoother: maintain two feeds, or support this extra attribute. I would lean to the attribute but it's not a no-brainer, I can see the other side.

[AsbjornUlsberg] But with the @syndicate attribute, how do you specify the relation between one <content> element and another? I still would very much like to see an example feed with the @syndicate attribute in action. :-)

[RobertSayre] Can we take this to the mailing list, please?

[MarkNottingham] This doesn't feel right; it's publishing-specific (i.e., you'd never see it in a feed), which makes me suspect there's a better way to do it. It also has some very implementation-specific semantics; if we try to specify this generically, we'll end up constraining the behaviour of other Web resources when we upload a resource with this attribute.

I'd much rather have a different kind of interaction that allows this; i.e., if you want to upload a movie or picture, PUT or POST to a different URI. It would be simple to come up with a new link type that pointed at an acceptable place to do so. If we based the API on WebDAV, this would be exceptionally easy to do.

That said, I thought the purpose of multipart/alternative was to allow different representations of a resource to be included in a feed; e.g., plain text vs. XHTML. I agree that multipart is a horrible way to do this, when we could just have multiple content elements, each with a different media type.