- From: Sam Goto <goto@google.com>
- Date: Mon, 27 Jan 2014 21:08:33 -0800
- To: Markus Lanthaler <markus.lanthaler@gmx.net>
- Cc: W3C Web Schemas Task Force <public-vocabs@w3.org>, public-hydra@w3.org
- Message-ID: <CAMtUnc7fkHMCz=MYwbuNnO2BUxUiyFjc_Q-AuQS07ap=uORraw@mail.gmail.com>
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:02 UTC