Re: CFC: Getting rid of 'extras'

To address your main point, extras as documented in the draft are not
necessarily optional; they are merely data that is sent in addition to the
core data sent with the intent.  Sometime they are required, and sometimes
they are optional.

This brings up another issue though: perhaps the optionality (I looked it
up, and that's actually a word) should be documented clearly in the intent
documentation.  To take it a step further, would it make sense to add a
best practices that intent documentation should be in WebIDL form?  This
way any extras could be marked as 'optional', though there are of course
many other solutions.

James

On Thu, Aug 23, 2012 at 4:10 AM, Friedger Müffke <friedger@gmail.com> wrote:

> I like the map idea so that you can add more semantics as data. However,
> removing the extras could lead to confusion about what is data and what is
> just extra (optional) accessory.
>  On Aug 23, 2012 1:16 AM, "James Hawkins" <jhawkins@google.com> wrote:
>
>> Sounds good to me.
>>
>> Any other folks have opinions on the change?
>>
>> James
>>
>> 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
>>> >>
>>> >
>>>
>>
>>