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

On Tuesday, November 26, 2013 7:39 PM, Sam Goto wrote:
> On Wed, Nov 20, 2013 at 8:40 AM, Markus Lanthaler wrote:
> > 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>.

Right, but adding another object in between even if it has nothing else than
a supportedProperties member wouldn't hurt much IMO. It would also open the
door to, e.g., support binary data.


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

But it makes it more difficult and introduces a mismatch between Schema.org
and Hydra which I would like to avoid.


> > 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.

This doesn't make any sense to me as it makes it completely impossible to
reuse any of the existing Schema.org properties (or any property in another
vocabulary for that matter).


> > > 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 :)

Then your change surprises me even more as the documentation uses exactly
the structure I'm proposing. For example (citing [1]):

   Moments: insert
   ===============

   ## Request body ##
   
   In the request body, supply a **Moments resource** with the following
   properties:

   Property name | Value          | Description            | Notes
   --------------------------------------------------------------------
   Required Properties 
   --------------------------------------------------------------------
   target        | nested object  | The object on which... |   
   type          | string         | The Google schema....  | writable  
   --------------------------------------------------------------------
   Optional Properties 
   --------------------------------------------------------------------
   startDate     | datetime       | Time stamp of when...  | writable  


   ## Response ##

   If successful, this method returns a **Moments resource** in the
   response body.
 
Could be translated directly into (omitting range information):

  {
    "name": "Moments: insert",
    "@type": "Operation",
    "method": "POST",
    "expects": {
      "@id": "#Moments",
      "supportedProperties": [
        {
          "@id": "#target",
          "name": "The object on which...",
          "required": true
        },
        {
          "@id": "#type",
          "name": "The Google schema...",
          "required": true
        }
        {
          "@id": "#startDate",
          "name": "Time stamp of when...",
          "required": false
        }
      ]
    },
    "returns": "#Moments"
  }


> > 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.

And nothing would stop them doing so in the future.. regardless of "expects"
takes a class or not.


> 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.

I'm not proposing to change that -- even though I think it might make a lot
of sense for products such as Actions in GMail which will just accept
certain classes/properties anyway.


> 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.

I really don't understand the reasons for the deviation of the model Hydra
or (Resource Shapes) follow. Are you concerned about the complexity? I think
it makes things much easier to understand a allows reuse which is impossible
if a just a set of SupportedProperties is used.

Have you had the chance to take a look at [2]? Would love to hear your
opinions?

Thanks,
Markus


[1] https://developers.google.com/+/api/latest/moments/insert
[2] http://www.hydra-cg.com/spec/latest/schema.org/


--
Markus Lanthaler
@markuslanthaler

Received on Wednesday, 27 November 2013 14:38:23 UTC