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

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


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


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


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

Received on Wednesday, 13 November 2013 19:34:01 UTC