W3C home > Mailing lists > Public > public-vocabs@w3.org > January 2014

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

From: Sam Goto <goto@google.com>
Date: Mon, 27 Jan 2014 21:08:33 -0800
Message-ID: <CAMtUnc7fkHMCz=MYwbuNnO2BUxUiyFjc_Q-AuQS07ap=uORraw@mail.gmail.com>
To: Markus Lanthaler <markus.lanthaler@gmx.net>
Cc: W3C Web Schemas Task Force <public-vocabs@w3.org>, public-hydra@w3.org
On Mon, Jan 27, 2014 at 9:01 PM, Sam Goto <goto@google.com> wrote:

>
>
>
> On Wed, Nov 27, 2013 at 6:37 AM, Markus Lanthaler <
> markus.lanthaler@gmx.net> wrote:
>
>> 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.
>>
>>
> Here is another challenge with this approach: how do you set up the
> expectations on the properties of the Action class? That is, most of the
> invocations take more than one parameter and they map to one of the Action
> properties (e.g. RsvpAction takes an "agent" as well as an "attendance" --
> whether the agent is going or not).
>
> If you had to declare that as a SupportedClass, that would require the
> handler to take a SupportedClass that is subClassOf a RsvpAction, which is
> a lot verbose [1].
>
> Option [2] is an attempt to cut down a bit the verbosity by allowing the
> "expects" property to take "Property", "SupportedProperty" (which refers to
> the Action-level properties) as well as "SupportedClass".
>
> Option [3] is what gmail lanched with, which, apart from strict
> preciseness, it is quite concise and clean.
>
> Markus, have you run into problems describing nested objects on "expects"
> (e.g. a bug needs an author which in turn needs to have at a minimum an
> id?)?
>
> [1]
>
> {
>   "@context": "http://schema.org",
>   "@type": "Event",
>   "@id": "http://code.sgo.to/events/123",
>   "name": "Taco Night",
>   "startDate": "2015-04-18T15:30:00Z",
>   "endDate": "2015-04-18T16:30:00Z",
>   "operation": {
>     "@type": "RsvpAction",
>     "expects": {
>         "@type": "SupportedClass",
>         "subClassOf": "http://schema.org/RsvpAction",
>         supportedProperty: [
>           {"@type": "SupportedProperty", "property": "
> http://schema.org/rsvpAttendance"}
>           {
>             "@type": "SupportedProperty",
>              "property": "http://schema.org/agent",
>              "rangeIncludes": {
>                "@type": "SupportedClass",
>                "subClassOf": "Person",
>                "supportedProperty": [
>                   {"@type": "SupportedProperty", "property": "
> http://schema.org/name"}
>               ]
>           }
>       ]
>     }
> }
>
> [2]
>
> {
>   "@context": "http://schema.org",
>   "@type": "Event",
>   "@id": "http://code.sgo.to/events/123",
>   "name": "Taco Night",
>   "startDate": "2015-04-18T15:30:00Z",
>   "endDate": "2015-04-18T16:30:00Z",
>   "operation": {
>     "@type": "RsvpAction",
>     "expects": [
>       "http://schema.org/rsvpAttendance" // this is a property that
> refers to the top level action
>        {
>             "@type": "SupportedProperty",
>              "property": "http://schema.org/agent",
>              "rangeIncludes": {
>                "@type": "SupportedClass",
>                "subClassOf": "Person",
>                "supportedProperty": [
>                  "http://schema.org/name"
>               ]
>           }
>       ]
>     }
> }
>
> [3]
>
> {
>   "@context": "http://schema.org",
>   "@type": "Event",
>   "@id": "http://code.sgo.to/events/123",
>   "name": "Taco Night",
>   "startDate": "2015-04-18T15:30:00Z",
>   "endDate": "2015-04-18T16:30:00Z",
>   "operation": {
>     "@type": "RsvpAction",
>     "optionalProperty": [
>       "rsvpAttendance" // this is a property that refers to the top level
> action
>       "agent.name" // this is a property that refers to the agent name
>

I forgot to mention, but these pathes are JsonPaths, which is based on
XPath.

http://goessner.net/articles/JsonPath/

These are quite simple, but with a xpath-like language, you can easily
express things like "all http://schema.org/Person nodes must have a 'name'
in my "expects"".

      ]
>     }
> }
>
>
>
>
>> > 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.orgproperties
>> > 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 Tuesday, 28 January 2014 05:09:01 UTC

This archive was generated by hypermail 2.4.0 : Friday, 17 January 2020 17:49:21 UTC