Re: Schema.org Actions - an update and call for review

On Thu, Nov 14, 2013 at 4:24 PM, Sam Goto <goto@google.com> wrote:

>
>
>
> On Wed, Nov 13, 2013 at 11:33 AM, Markus Lanthaler <
> markus.lanthaler@gmx.net> wrote:
>
>> Sam,
>>
>> It would be incredibly helpful if you could send text-only mails and
>> indent
>> the parts you didn't write with ">"s. That would make it much easier to
>> see
>> what you wrote and what I wrote. Thanks!
>>
>>
>> On Wednesday, November 13, 2013 6:48 PM, Sam Goto wrote:
>> > Just backtracking a little bit on my recursion tree here :) We've
>> talked a
>> > bit about point (2), but let me ask you a few more questions about point
>> > (1).
>> >
>> > On Thu, Oct 17, 2013 at 12:20 PM, Markus Lanthaler wrote:
>> > > On Thursday, October 17, 2013 8:39 PM, Sam Goto wrote:
>> > > > Couple of questions:
>> > > >
>> > > > (1) How much benefit are you expecting from the flexibility of
>> > > > supportedProperties? don't you think that that will eventually
>> corner
>> > > > yourself into a fragmented ecosystem of APIs (each having a
>> different
>> > > > set of supportedProperties?)?
>> >
>> > > As always it depends I would say. Since the supportedProperties are
>> > > bound to a class, I don't expect too much fragmentation as I would
>> > > expect that people simply reuse the class as a whole in most instance.
>> >
>> > > As you know, in RDF there's generally no way to tell which properties
>> > > apply to instances of a certain class since the right answer is
>> normally
>> > > "any" (rdf:domain doesn't restrict it). That's why I designed
>> > > supportedProperties in the first place. It mimics the behavior most
>> > > programmers are familiar with.
>> >
>> > Right. We are running into a similar problem too. I'm having two
>> > philosophical debates:
>> >
>> > (I) is this a good idea? will it corner ourselves in the future?
>>
>> From a linked data perspective (follow your nose) I think it's the only
>> reasonable choice - at least the only I've found. How could it corner
>> ourselves in the future? I very deliberately called it
>> "supportedProperties"
>> to signal that this are not *all* properties that might exist for a class
>> but just the ones known to be supported.
>>
>>
>> > (II) assuming this is a good idea, which constructs do we use to model
>> > it?
>> >
>> > A few points on topic (I):
>> >
>> > (a) will this cause API fragmentation?
>>
>> Hydra's supportedProperties describe the properties known to be supported
>> for a specific class.
>
>
> Right. Gmail got to a similar conclusion, but a slightly different syntax.
>
> https://developers.google.com/schemas/reference/types/ActionHandler
>
> So instead of a Type SupportedProperty, there are two "lists of
> http://schema.org/Property"s: optionalProperty and requiredProperty.
>
> Any strong thoughts on the differences between these approaches (approach
> (a) is to have a list of SupportedProperty versus (b) N=2 lists of Property
> for optional and required fields)?
>

Thinking this a bit more, I'm liking "expects" and "SupportedProperty" a
lot more than "optionalProperty" and "requiredProperty. It is a lot closer
to resource shapes<http://events.linkeddata.org/ldow2013/papers/ldow2013-paper-02.pdf>,
which I like.

I'm circulating this with the folks (Yaar/Alex, CC-ed) that previously
proposed "optionalProperty", "requiredProperty" and "hasPayload" to check
with them if it "expects" and "returns" works for them.

If it does, with your consent, I'd like to adopt that (they fit well into
the ActionHandler class)!


> The other difference is that gmail allows you to specify requirements for
> "sub-properties": you can say that "review.reviewRating.ratingValue" is a
> required property in the Action instance (example<https://developers.google.com/gmail/actions/reference/review-action>).
> Thoughts?
>
>
>
>> Operations etc. use classes to describe the expected
>> data as well as to hint what data it might return. It is very beneficial
>> to
>> reuse already existing classes instead of minting new ones. Of course, it
>> can't prohibit people to create new classes to define their own set of
>> properties but then at least it has the advantage that those properties
>> etc.
>> can be discovered.
>>
>
> Quick Question: in hydra, do new Class requirements get defined per
> operation? Or cross referenced? If the latter, doesn't that imply that a
> "SupportedProperty requirement" applies to multiple operations?
>
>
>>
>> > (b) how do we deal with backwards compatibility ? e.g. once you
>> published
>> > an ApiDocumentation, and clients are using it, you can not add a
>> > SupportedProperty that is *required* without breaking existing clients
>> > prior to an API migration.
>>
>> That's true but not specific to Hydra. As long as you keep supporting the
>> old action anyway, you could just mark it as optional.
>
>
> Exactly. And you *always* have to support the old action, unless you want
> to make a backwards incompatible change (i.e. you can't ever add a new
> required property, after your initial API push).
>
>
>
>> If you phase out the
>> old API, old clients obviously break - unless they already had the data
>> you
>> need but just didn't send it (which in a lot of cases is quite possible).
>
>
>>
>> > (c) how do you keep your clients in sync with your ApiDocumentation?
>> When
>> > you make "SupportedProperty requirements" changes to your
>> > ApiDocumentation, how do clients become aware?
>>
>> The ApiDocumentation is not static but should be retrieve and processed at
>> runtime in order to avoid tight coupling. Thus, the client will notice the
>> changes as soon as the cached version expires. Just serve it with sensible
>> caching headers, HTTP gives you everything you need for free.
>>
>
> Got it.
>
>
>>
>>
>> > A few questions on point (II):
>> >
>> > (a) have you looked into resource shapes?
>>
>> Yes, it's basically a an extended version of Hydra's supported property
>> stuff. The only notable difference is that Hydra directly associates this
>> information to a class whereas OSLC adds an additional indirection via
>> oslc:ResourceShape. We have been discussing exactly this indirection in
>> the
>> Hydra CG as well. The reason why there's no such indirection in Hydra at
>> the
>> moment is because in the context of an API, classes are normally used
>> consistently. Requirements on properties however may be different
>> depending
>> on the class they apply to.
>>
>
> I'd expect that requirements on Class properties depend on which
> "operations" applied too, doesn't it?
>
>
>>
>>
>> > (b) have you considered SPARQL ASK queries?
>>
>> For what? The result of such a query wouldn't be helpful for a client at
>> all. The server on the other hand, can of course use SPARQL ASK queries to
>> validate incoming data but there's no need to communicate those queries
>> to a
>> client IMO.
>>
>> > (c) have you tried concepts from prototype languages?
>>
>> I don't know what this means.
>>
>>
>>
>> --
>> Markus Lanthaler
>> @markuslanthaler
>>
>>
>