Re: CFC: Getting rid of 'extras'

On Fri, Aug 31, 2012 at 5:22 AM, Jungkee Song <jungkee.song@samsung.com> wrote:
> +1 for changes as well.
>
>
>
> I think we have two cases to handle since the payload that Web Intents
> deliver is not confined to MIME type.
>
>
>
> #1. MIME type
>
> As discussed and agreed, it would be good to create a consistent vocabulary
> as Greg suggested. For example,
>
>
>
> var intent = new Intent({
>
>     action: "http://intents.w3.org/pick",
>
>     type: "image/png",
>
>     data: { blob: getImageDataBlob(...),
>
>     url: “http://example.com/path/to/image/file.png”,
>
>     fileName: “iAmFromMIME” }
>
> });
>
>
>
> blob, url, fileName, etc. could be generic dictionary members in MIME type
> service context.
>
>
>
> #2. Service object type
>
> Web Intents allows us to define specific *Intent* services. Examples are
> Pick Media Intent [1] and Pick Contacts Intent [2]. (There should be more to
> come as Web Intents mitigates security and privacy concerns.)
>
>
>
> I think the type of such Intent should be of its own type simply because
> both ends expect to exchange data in that *Intent* type. (like we use MIME
> type to get MIME data in the payload.) For example,

Yes. JS maps have good extensibility properties and fit well with our
return value semantics.

Something I'd like to discuss in this same thread is getting some more
formalism around return types. Currently in the wiki pages containing
examples for MIME and schema.org types, the recommendation is that the
return type is the same schema as the argument type.

I still think that's a good plan, but I think we need some more
generic semi-reserved keys for UA-level errors that get propagated
back to the client. I propose error schemas look like this:

{
  "errorName" : "WebIntentsServiceCancelledError",
  "errorMessage" : "The service handling this intent was closed by the user."
}

All system errors would have a reserved prefix for "errorName", and
message schemas using intents would be encouraged to use the same
error keys with different names to communicate intent-specific error
conditions.

Since these errors would be sent through postFailure, not postResult,
there isn't really a namespace collision, but it would be recommended
that services not return objects with these error keys as part of
non-error cases.


>
>
>
> [client] - expects to get “http://intents.w3.org/type/media” typed object.
>
> var intent = new Intent({
>
> action: "http://intents.w3.org/pick",
>
> type: "http://intents.w3.org/type/media"
>
> });
>
>
>
> [service]
>
> var mediaObject = {
>
> content: { uri: "http://example.com/path/to/image/file.png" },
>
> description: "I did Seoul, Korea",
>
> title: "My trip",
>
> type: "image/jpeg",
>
> author: "JS",
>
> fileName: “iAmFromPickMediaIntent”,
>
> location: { coords: { latitude: 37.56056, longitude: 126.97569 }},
>
> tags: ["Han river", "Seoul"],
>
> thumbnail: { blob: getThumbnailDataBlob(…) },
>
> publishedDate: "16-01-2010" };
>
>
>
> window.intent.postResult(mediaObject);
>
>
>
> Namely, both client developer and service provider would expect to get the
> *data* in the structured clone object of the type that the related document
> ([1] in this example) specifies.
>
>
>
> Also, it would be useful if picker provides some decent UX where those
> Intent services coexist.
>
>
>
> WDYT?
>
>
>
> [1] http://w3c-test.org/dap/gallery/#idl-def-Media
>
> [2] http://w3c-test.org/dap/contacts/#idl-def-Contact
>
>
>
>
>
> Jungkee
>
>
>
>
>
> From: James Hawkins [mailto:jhawkins@google.com]
> Sent: Friday, August 24, 2012 3:34 AM
> To: ⅔ Steve McKay
> Cc: Greg Billock; WebIntents
> Subject: 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[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
>>>
>>
>
>
>
>

Received on Saturday, 1 September 2012 05:26:40 UTC