RE: An updated draft of the schema.org/Action proposal

On Monday, February 10, 2014 9:00 PM, Sam Goto wrote:
> On Mon, Feb 3, 2014 at 8:03 AM, Markus Lanthaler wrote:
>> Sam,
>> 
>> It becomes increasingly difficult to parse your mails as they get
>> longer. It would help me a lot I you could remove the stuff you don't
>> comment on and somehow highlight the stuff you've said (simplest thing
>> is probably to just prepend a "> " to the lines you reply to). Thanks.
>>
>> 
>> On Tuesday, January 28, 2014 4:33 PM, Sam Goto wrote:
>> On Tue, Jan 28, 2014 at 5:45 AM, Markus Lanthaler wrote:
>> > On Monday, January 27, 2014 6:16 PM, Sam Goto wrote:
>> >>>> In our latest thinking (which I still need to put down on paper
>> >>>> and publish), we think that the "expects" and "returns"
>> >>>> constructs should go into the Action-level properties, because
>> >>>> it may apply to multiple action handlers (example: if you have
>> >>>> an android app as well as a web API, you don't want to repeat
>> >>>> yourself what your API looks like).
>> >>
>> >> Definitely makes sense. Can't we get rid of actionHandler then at
>> >> the same time by moving that information to the operation itself
>> >> as already proposed above. In other words, an operation would not
>> >> only be an HttpOperation but also, e.g., an AndroidOperation at
>> >> the same time. The application which invokes it extracts the
>> >> necessary information directly from the operation.
>> >>
>> >>   {
>> >>     "@type": ["SearchAction", "HttpOperation", "AndroidOperation" ],
>> >>     "httpMethod": "POST",
>> >>     "androidIntent": ...  <-- or something similar, you get the idea
>> >>   }
>> >
>> > Let me try to understand what you are trying to say. So, to put in
>> > terms of the current proposal, you'd get something like the following:
>> >
>> > {
>> >     "@type": ["SearchAction", "AndroidIntentActionHandler" ],
>> >     "packageName": "com.netflix"
>> > }
>> >
>> > rather than
>> >
>> > {
>> >     "@type": "SearchAction",
>> >     "actionHandler": {
>> >        "@type": "AndroidIntentActionHandler"
>> >       "packageName": "com.netflix"
>> >     }
>> > }
>> >
>> > Does that reflect what you are proposing? If so, what is the added
>> > benefit?
>> 
>> Kind of. What I was trying to do is to remove the whole ActionHandler
>> stuff. I don't want there to be "endpoints" which I can use to invoke
>> the operation. In my world view, operations are executed on the
>> resource. In other words, operations describe the things you can do
>> with a resource, not where you can send the resource to. In the
>> optimal case, there wouldn't be a need to describe Android intent
>> handlers as Android would be able to recognize the resource and its
>> operations and then figure out which locally installed app can handle
>> that combination. That's, however, too ambitious at the moment. Thus
>> we probably need an alternative for the time being. One option would
>> be (as I mentioned to you in another mail) to separately describe Web
>> resources and "app resources".
>> 
>> To be a bit clearer: What I have in mind is to link from the Web
>> resource to the app, similar to how App Indexing for Google Search
>> works:
>> 
>> https://developers.google.com/app-indexing/webmasters/details
>> 
>> So, a simple example would look like this:
>> 
>> {
>>   "@context": "http://schema.org",
>>   "@id": "http://example.com/web/resource",
>>   "operation": ... operations supported by the web resource ...
>>   ...
>>   "alternate": {
>>     "@id": "android-app://com.package/android/resource",
>>     "@type": "AndroidAppLink",
>>      ...
>>      "operation": ... possible but not necessary IMO ...
>>   }
>> }
> 
> 
> Humm, that's an interesting idea ... let me try to think this through.
> So you are saying we would have things like the following, describing
> the "operations" that can be taken in this resource as well as "where
> else" this resource is found :
> 
> {
>   "@context": "http://schema.org",
>   "@id": "http://example.com/web/resource",
>   "operation": ... operations supported by resource ...
> 
>   ...
>   "alternate": [{
>     "@id": "android-app://com.package/android/resource",
>     "@type": "AndroidAppLink",
>   }, {
>     "@id": "msApplication://microsoft.build.App/resource?arg1=1,arg2=2,etc",
>     "@type": "WindowsAppLink",
>   }, {
>     "@id": "myapp.com://resource?arg1=1,arg2=2",
>     "@type": "iOSAppLink",
>   }, {
>     "@id": "https://www.googleapis.com/example/v3/examples/resourceid",
>     "@type": "ApiLink",
>   },]
> }

Right


> Do the links above make sense to you? AndroiAppLink (see def here)?
> WindowsAppLink (see def here)? iOSAppLink? ApiLink?

Yes


> If so, a few follow up questions:
> 
> 1) I wonder how it would map to APIs endpoints (see example below)?
> Does ApiLink make sense to you to make the connection between webpage
> resources to APIs?

There's no example below. I assume you meant example above, right? It depends on the relationship between the "website resource" and the "API resource" I'd say. In quite a number of cases it may not even be necessary to separate them. In the cases I think alternate is a quite reasonable choice (without having to do a sameAs). I wouldn't call it ApiLink though.. Maybe just WebResource or something similar? In Hydra we have hydra:Resource for that.


> 2) How does WebFormHandler fit into this? Without handlers, how do we
> deal with the yandex use case spec?

The operation you associate to the ApiLink/WebResource "expects" a SupportedClass (in your draft). You could further describe the operation with the expected serialization format. You would, however, need to describe how an abstract (RDF) representation is mapped to a form. Using Hydra's IRI template mechanism could help in that regard.


> 3) Without handlers, we loose the ability to allow developers to
> control things like "preferred encoding" (spec) or things like "POST
> vs GET" that gmail launched with. Not sure how I feel about this.

Why? You can associate an HTTP method to each operation (in Hydra at least). That could be extended with supported serialization formats. Hydra doesn't support that yet but we have been discussing it and it is certainly something that will be needed in practice.


Cheers,
Markus


--
Markus Lanthaler
@markuslanthaler

Received on Monday, 3 March 2014 17:29:57 UTC