2006/6/19, Tim Bray <[EMAIL PROTECTED]>:
<co-chair-mode> [… ] So it's time for the co-editors to capture that consensus and produce a protocol-09 so we can do a level set. […] When can we have one?</co-chair-mode>
Last week, I talked about a personal version of PaceMediaEntriesX. I hoped to have it done for the week-end, but it took me more time than I initially thought (mainly because english is not my native language I guess). Add to that Father's Day, a short time-line at work and a couple of trips to clients offices… So I decided to post here a preview of my "PaceUnifiedEntryEditing". I'll continue to work on it and adapt it for protocol-09 when it's out. So here it is: 1. rename "Member" in the terminology to "Entry": an Entry is a resource with (at least) an Atom Entry Document representation. A Collection is then a resource which is a set of Entries, and has (at least) an Atom Feed Document representation. 2. Creating Entries (no distinction between "media" and other entries) Whatever you POST to a collection, the server creates a resource with (at least) an Atom Entry Document representation (I could live with a spec not tying the Atom representation and the created resource, i.e. they could be two distinct resources, as suggested by Tim and his "media resource" / "media link entry" wording). If the POSTed entity was an Atom Entry Document, the Atom Entry Document representation of the created resource MUST be derived from the POSTed entity, i.e. it MUST NOT become the content of the created Atom Entry Document. In other words, servers MUST NOT created entries whose atom:content is an Atom entry (except if that's what was POSTed by the client). If the POSTed entity was a non-Atom document (neither a entry nor feed), servers MAY create the Atom Entry Document representation "from scratch", but MUST then put the POSTed entity (or a derived form) in the atom:content (either inline or out-of-line). (note: the following phrase should probably not make it in the spec, but it better explains the previous sentence; also see app:accept below) Servers can also process the POSTed entity as an "alternate representation" of the entry and thus create the Atom Entry Document representation by "transforming" the POSTed entity (rationale: the same URI should be usable with other protocols: I could POST SOAP messages for a WS-* protocol, an RSS item for the 2WayRSS protocol, a multipart/form-data entity created by an HTML form, etc.) The spec does not define what's the result of POSTing an Atom Feed Document. Servers are free to reject such entities using 422 (Unprocessable Entity) or 400 (Bad Request) status codes. 3. The app:accept element in introspectin document As said above, a server may use a POSTed entity as the atom:content of the Atom Entry Document representation of the created resource. The app:accept element lists media types (eventually using media ranges to represent a whole set of media types with the same "main type") which will result in such entries. The other cases (where the Atom Entry is built by transforming the POSTed entity) MUST NOT be listed here (i.e. if the server also does 2WayRSS at the same URI, it must not list application/rss+xml of whatever the RSS media type, because an RSS Item POSTed to the collection URI won't result in an Atom Entry with an atom:[EMAIL PROTECTED]"application/rss+xml"], the Atom Entry will rather be an alternate representation of the RSS item). If a server accepts "CompoundEntries", it MUST NOT list multipart/related in the app:accept value (given that atom:content cannot have a multipart/* or message/* value, such media ranges cannot be specified in app:accept). Another example, if a server transforms MSWord, OpenDoc or DocBook/XML articles into Atom Entries, it must not list those media types in app:accept. An extension will have to be written for such uses of the APP. Corollary: as a server is forced to derive from an POSTed Atom Entry when creating the Atom Entry representation of the created resource (and must not use it as the entry content), application/atom+xml MUST NOT be listed in app:accept. As every member of a collection (every Entry, in my terminology) has an Atom Entry Document, and given that non-Atom entities POSTed to a collection will (in case their media type is listed in the app:accept element) result in Atom Entry Document representations using them (the POSTed entities) as the atom:content value, clients MAY POST such Atom Entry Document representations (i.e. one with an atom:[EMAIL PROTECTED]"image/png"] and an inlined base64-encoded PNG image), and servers SHOULD accept them. The app:accept value can also contain the special values "text", "html" and "xhtml" as defined by AtomFormat. These values don't correspond to a media type and such content can only be used when POSTing an Atom Entry Document. [@@TBD: maybe app:accept should be renamed into app:content-type@@] [@@TBD: eventually use a single value "entry", meaning "every possible value of atom:content/@type that's not a media type", if we want a server to be forced to accept text, html *and* xhtml atom:content; I'll probably put this option in the Pace, as there seems to be a consensus around it@@] Rationale for this change in the app:accept/app:content-type meaning: an app:accept à la HTTP Accept request-header does not tell you what will be done with your POSTed entity. CompoundEntries and "XXX-to-Atom translations" will have to be exposed using extensions (for example, an ext:accept-as-entry, which value defaults to application/atom+xml and can contain application/msword to expose an MSWord-to-Atom translation: you POST an MSWord doc and the server extracts metadata and content to build an Atom Entry whose content will *not* be the POSTed MSWord doc). The app:accept/app:content-type element is only a hint (clients might still try to sent something else, and servers might accept it, but the result is not guaranteed) for entry creation (POST). Once created, the server exposes the editable representations with rel="edit" links (see below) so this is not needed [@@TBD: it might be needed if we want clients to be able to replace, say, a PNG image with an MSWord document, but this seems out of scope to me@@] 4. Editing Entries / the "edit" link relation Links with an "edit" relation tells clients where they can retrieve and/or update representations of, and/or delete resources. A server exposes every editable representation of an entry using [EMAIL PROTECTED]"edit"] in the Atom Entry Document representation of the entry. There MUST NOT be more than one [EMAIL PROTECTED]"edit"] in a entry with the same @type and @hreflang attributes (same as rel="alternate", as they serve a similar purpose; see below about @hreflang). If not given, @type defaults to application/atom+xml. If not given, @hreflang defaults to the xml:lang/Content-Language value in scope at the atom:entry level. --> no more rel="edit-media" links, the "dispatch" is done using the @type attribute of rel="edit" links. This prevents editing of <atom:content type="application/atom+xml"> separately from the enclosing Atom Entry, but I think this hits the 80/20 mark, as such entries might never even exist. The role of [EMAIL PROTECTED]"edit"] at the feed level is not defined (James might want to use it to link to an entry representing the collection ;-) but this is out-of-scope) [@@TBD: maybe we could rather say "reserved for future use"?@@] In the Atom Feed representation of a Collection, entries might have a single [EMAIL PROTECTED]"edit"] pointing to the Atom Entry Document representation of the Entry, which in turn could provide much more rel="edit" links. I.e. Collections MAY NOT expose all rel="edit" links and clients should then follow the [EMAIL PROTECTED]"edit" and @type="application/atom+xml"] to discover the others. Note that rel="edit" is very similar to rel="alternate", except it adds the semantic of "this is where you can modify the representation" and "this is an alternate representation of the very same resource". 5. Deleting Entries The DELETE request MUST be sent to the URI given in the [EMAIL PROTECTED]"edit" and @type="application/atom+xml"]/@href. This means that if an Entry is "deletable" but not "updatable", it must still have a [EMAIL PROTECTED]"edit" and @type="application/atom+xml"] but the given URI will then reject PUT requests (using 403 (Forbidden) or 405 (Method Not Allowed)). 6. Explicitely deal with ConNeg Servers MAY use conneg and return different representations at the same URI (i.e. in an entry, [EMAIL PROTECTED]"edit"] all have the same @href). If they do so, those representations MUST be tightly tied to each other (i.e. if you update one representation, all other representations are potentially updated as well). For example, servers MUST NOT use conneg to deal with translations in different languages of an entry, except if this translation is done automatically; if you want those translations to be distinctly edited, you'll have to create as many entries as languages. Clients should be prepared to deal with such servers (using transparent conneg) and thus include the appropriate Accept-* headers. Servers should provide an URI for each representation of a resource, even if it uses conneg (rationale: http://bitworking.org/news/WebServicesAndContentNegotiation). This means every representation should be sent to the client (when conneg takes place) using a Content-Location header giving the "real" URI of the resource. I must have forgotten many things, but that's basically what I'd like to see in a future draft. -- Thomas Broyer
