Posted PaceCollectionsAcceptedMediaTypes

["Thomas Broyer" <t.broyer@xxxxxxxxxxx>]

http://intertwingly.net/wiki/pie/PaceCollectionsAcceptedMediaTypes

== Abstract ==

Adds a mean of identifying a collection's allowed resource media types
from within the Introspection Document.

== Status ==

New

== Rationale ==

Within the current protocol draft (04), you can't know whether you can
POST a resource of a given media type to a Collection Resource: you must
try and see if you get an error (415 Unsupported Media Type).
[[BR]]
In an APP client, such an information could prevents the user from
selecting an unaccepted file. E.g. if a collection only accepts image/*
resources, the APP client can prevent the user from selecting an Office
document.
[[BR]]
In comparison, HTML4 forms and XForms both provide that information for
file uploads (see the References section below), respectively through
their {{{accept}}} (on the {{{form}}} and {{{input type="file"}}}
elements) and {{{mediatype}}} (on the {{{upload}}} element) attributes.

With this information, an APP client can also avoid fetching a collection
or its members if it doesn't support any of the listed media types.
[[BR]]
In this case, the information is similar to the one carried by the
XHTML2's attributes of type {{{ContentTypes}}} (see the References section
below). The difference between these attributes and the HTML and Atom
{{{type}}} attributes on link elements is that HTML and Atom attributes
are advisory while the XHTML2 attributes are authoritative.

== Proposal ==

Add a {{{mediatype}}} attribute to the {{{app:collection}}} element in
Introspection Documents.

In section 8.1.1.3 The 'app:collection' Element, update the RNC:
{{{
   appCollection = element app:collection {
         attribute title { text },
         attribute contents { text },
         attribute href { text },
         attribute mediatype { text },
         anyElement*
      }
}}}

Add a new section:
{{{
8.1.1.3.2  The 'mediatype' Attribute

   The 'mediatype' attribute identifies the allowable content type(s)
   of the collection's member resources. Its value is a comma-separated
   list of media ranges with optional accept parameters, as defined in
   section 14.1 of [RFC2616] as the field value of the accept request
   header.

   During an HTTP POST, the Collection Resource MUST accept any resource
   whose media type matches the 'mediatype' value specified in the
   Introspection Document and therefore MUST NOT respond with a 415
   Unsupported Media Type status code. It MAY however reject a resource
   whose media type is allowed for other reasons, e.g. if it is not
   well-formed or otherwise doesn't match other prerequisits.

   If the 'contents' attribute has a value of "entry", the collection
   MUST allow editing of "application/atom+xml" resources, i.e. the
   value of the 'mediatype' attribute MUST match the "application/atom+xml"
   media type, either using the media type directly or through a media
   range such as "application/*" or "*/*".
}}}


== Impacts ==

APP clients can avoid POSTing resources to a Collection Resource if they
know it doesn't accept resources of that media type. They can also avoid
GETting collections or their members if they don't support the
collection's member media types.
[[BR]]
By extension, APP clients can prevent users from selecting resources of an
unaccepted media type for POSting to a Collection Resource; or they can
warn the user before GETting a collection or its members if they don't
support the collection's member media types.

== Notes ==

This proposal doesn't cover the identification of a member resource's
media type from within a Collection Document. If there's a need for such
an information, it'll reside in a distinct Pace.

There might also be a need to differentiate between GETting and POSTing:
e.g. an Entry Collection might provide readonly access (GET and DELETE
actually) to resources served as text/html or application/xhtml+xml but
read/write access (POST to the COllection Resource, and GET, PUT and
DELETE on the Member Resource) to resources served as
application/atom+xml. An APP client which wouldn't accept
application/atom+xml could "browse" the collection retrieving member
resources as text/html or application/xhtml+xml.
[[BR]]
This is not dealt within the current Pace.

== References ==

 * HTML4 forms' {{{accept}}} attribute:
[http://www.w3.org/TR/html4/interact/forms.html#adef-accept]
 * XForms {{{upload}}}'s {{{mediatype}}} attribute:
[http://www.w3.org/TR/xforms/slice8.html#ui-upload]
 * XHTML2 {{{ContentTypes}}} attribute values:
[http://www.w3.org/TR/xhtml2/abstraction.html#dt_ContentTypes]

-- 
Thomas Broyer