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