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

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.
Furthermore, SupportedProperty has no "property" property anymore but you
use "name" to specify it - which is a string and could be anything. 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/
  - 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. 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

Received on Wednesday, 20 November 2013 16:41:04 UTC