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

On Wed, Nov 20, 2013 at 8:40 AM, Markus Lanthaler
<markus.lanthaler@gmx.net>wrote:

> On Monday, November 18, 2013 9:14 PM, Sam Goto wrote:
> > On Mon, Nov 18, 2013 at 2:19 AM, Markus Lanthaler wrote:
> > > You are right(ish). What I meant is that in previous proposals the
> > > action handler had requiredProperties/optionalProperties (just as GMail
> > > Actions have) where as the latest draft doesn't have that anymore.
> > > Instead it seems to suggest that the Action itself specifies which data
> > > is to be send to the server. In the previous drafts the properties on
> > > the action looked like they were describing the action in more details
> > > and not defining the interface to the server.
>  >
> > Yep, that's my fault, I dropped that unintentionally. We originally had
> > "ActionHandler.optionalProperty/requiredProperty" and
> > "ActionHandler.hasPayload" but I agree that "expects" and "returns" makes
> > a lot more sense: they are more powerful and cleaner.
> >
> > Here, I updated the spec to include those:
> > http://www.w3.org/wiki/images/b/b9/Actionsinschema.org.pdf
>
> Hmm... you changed "expects" to take a SupportedProperty instead of a Class
> which results in a asymmetry with "returns" which still takes a Class.
>

Right. That maps more closely to the API that gmail launched with and it
also maps better to the use cases we have with indexing <forms>.

But most importantly, this doesn't corner us to taking Class in case we
need to in the future.


> Furthermore, SupportedProperty has no "property" property anymore but you
> use "name" to specify it - which is a string and could be anything.


SupportedProperty extends from Property, so it doesn't need to take one.


> In most
> cases a human-readable label to be read in a dynamically generated UI or
> documentation.
>
> I'm not sure I like this design. The reason is that most developers think
> in
> terms of (resource) classes. This is pretty apparent even if you just look
> at three arbitrary Web APIs:
>
> Google+: https://developers.google.com/+/api/latest/


I am/was actively involved in most of these APIs :)


>
>   - People
>   - Activites
>   - Comments
>   - ...
>
> Facebook: https://developers.facebook.com/docs/graph-api/reference/
>   - Achievement
>   - Album
>   - Application
>   - ...
>
> Twilio: http://www.twilio.com/docs/api/rest
>   - Accounts
>   - Subaccounts
>   - AvailablePhoneNumbers
>   - ...
>
>
> I think it's important to have something that mimics that. That's why I
> introduced the supportedProperties property in the first place. If there's
> no existing class which specifies the supportedProperties you need, you
> subclass one (or more) and specify them yourself. Then you can easily reuse
> that new class consistently across your API.


That's certainly a possibility. Most of our existing users (e.g. gmail
actions, g+ actions, yandex islands) take the entire action as the
payload/request/parameters, rather than an individual noun/class. I
certainly agree that we could eventually find that we'd need to pass just
nouns/classes, but at the moment we've been fairly happy with the transfer
of the entire action between parties.

Most importantly, with "expects" and "returns" being schema.org properties
they can evolve incrementally over time to take other types (e.g. Class),
so hopefully we can cross this bridge when we get to it.


> Resource Shapes basically does
> the same.
>
> If you think about a typical Web API, you can at least create and modify a
> number of resources. Most of the time, the parameters used for creating
> them
> and then modifying them are exactly the same.
>
> I hope to have the proposal of how to integrate parts of Hydra into
> schema.org ready for tomorrow.
>
>
>
> --
> Markus Lanthaler
> @markuslanthaler
>
>