Re: CFC: Getting rid of 'extras'

The mapping is between action and payload, not type and payload.  Each
action specifies which data should be present or optional in the payload.

James

On Thu, Aug 23, 2012 at 10:30 AM, ⅔ Steve McKay <smckay@google.com> wrote:

> I absolutely agree that we should push extras down into a structured
> payload object. I have one concern with the proposal. The type in your
> examples are the MIME-type of the value embedded in the structured payload,
> rather than a type describing the structured payload  itself. Don't we want
> to document the literal type of the structured payload object?
>
> Some alternatives:
>
> *MIME-type in payload:*
>
>   type: fancy.org/types/mimedata
>   date: {  // mimedata instance
>     mimetype: image/png,
>     blob: blob image contents,
>     url: url of image contents,
>     filename: representative filename,
>   }
>
> *MIME-type as parameter to structured payload type:*
>
> One problem with including the MIME-type in the payload is that a service
> is presumed to be registered against a single type value AND we provide
> special handling of MIME-types (wildcards). We can address this issue with
> type parameters (similar to those supported by the MIME standard itself).
> Basically embed the MIME-type in the type field as a parameter to the real
> type.
>
>   type: fancy.org/types/mimedata[ <http://fancy.org/types/mimedata%5B>
> image/png]
>   data: {  // mimedata instance
>     blob: blob image contents,
>     url: url of image contents,
>     filename: representative filename,
>   }
>
> With the MIME-type embedded in the type field service registrations could
> still be made using a single type value.
>
> Any way we slice this up, I think we want to keep the mapping between type
> and value direct and literal.
> Less black magic == easier to document, use, and understand == happier
> developers and healthier ecosystem.
>
> Steve
>
>
>
> On Wed, Aug 22, 2012 at 4:07 PM, Greg Billock <gbillock@google.com> wrote:
>
>>
>> Definitely. The big driver for extras was MIME types, so here's a MIME
>> type before:
>>
>> type: image/png
>> data: blob = image contents
>> extras: { "url" : image url,
>>             "filename" : representative filename,
>>           }
>>
>> and a proposal for a format with no extras:
>>
>> type: image/png
>> data: { "blob" : blob image contents,
>>           "url" : url of image contents,
>>           "filename" : representative filename,
>>         }
>>
>> Using a map as a recommended base type for data provides a lot of
>> flexibility. It provides an open namespace into which new optional
>> features can be placed to satisfy new use cases as usage evolves. A
>> goal will be to create a consistent vocabulary across types, so for
>> example "url" means "a url pointing to the content" for all MIME
>> types.
>>
>>
>> On Wed, Aug 22, 2012 at 3:44 PM, James Hawkins <jhawkins@google.com>
>> wrote:
>> > Can you provide an example to show before and after?  A few disparate
>> cases
>> > would be helpful to see the impact of the change.
>> >
>> > Thanks,
>> > James
>> >
>> >
>> > On Wed, Aug 22, 2012 at 2:09 PM, Greg Billock <gbillock@google.com>
>> wrote:
>> >>
>> >> In June, we discussed getting rid of getExtra() in favor of an extras
>> >> attribute (i.e. [1]). I'm increasingly persuaded that we should just
>> >> get rid of extras altogether. When this was proposed [2], it was
>> >> because we knew we needed to be able to attach metadata to the payload
>> >> data for pre-existing types (such as MIME types). But a better scheme
>> >> to deal with that is to create extensible payload formats to begin
>> >> with. Such formats have to be documented anyway (see e.g. [3]), and so
>> >> it is better to just use the existing structured-clone payload to
>> >> describe the type. Any extra header information can just be included
>> >> there.
>> >>
>> >> So the proposal is to strike |getExtra()| from the API, and add a best
>> >> practices recommendation that any documented payload type passed
>> >> through |data| be a Javascript Object type so that fields may be added
>> >> to it as necessity arises.
>> >>
>> >> This would mean a revision to documents such as [3], but going forward
>> >> it puts data passing on a firmer footing where types get designed with
>> >> extensibility in mind from the beginning. I don't think we even really
>> >> lose any generality -- web developers need to consult documentation to
>> >> figure out which extras keys mean what, anyway, and as we've learned
>> >> from trying to pass MIME types, there end up being reasons to want to
>> >> pass, say, both URLs and Blobs through the type anyway, not to mention
>> >> even better future constructs, such as Stream [4], so there isn't much
>> >> intuitive power in the type anyway. If you have to consult the
>> >> documentation, it's easier to document the type as one object, rather
>> >> than as the object and then extras data.
>> >>
>> >>
>> >> [1]
>> >>
>> http://lists.w3.org/Archives/Public/public-web-intents/2012Jun/0118.html
>> >> [2]
>> >>
>> http://lists.w3.org/Archives/Public/public-web-intents/2012Mar/0003.html
>> >> [3] http://www.w3.org/wiki/WebIntents/MIME_Types
>> >> [4]
>> http://dvcs.w3.org/hg/streams-api/raw-file/a3858f3ef0ae/Overview.htm
>> >>
>> >
>>
>>
>