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

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

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