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

On Friday, November 15, 2013 7:26 PM, Sam Goto wrote:
> On Thu, Nov 14, 2013 at 4:24 PM, Sam Goto wrote:
> > On Wed, Nov 13, 2013 at 11:33 AM, Markus Lanthaler wrote:
> > > On Wednesday, November 13, 2013 6:48 PM, Sam Goto wrote:
> > > > 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)?

I think the approach of using SupportProperty is more scalable as it allows
you to easily add more information to each property.
optionalProperty/requiredProperty optimizes for the case where there's just
a single attribute, i.e., "required". As you may have seen, in Hydra we
already have two more attributes: readonly, writeonly. This would become
difficult with GMail's approach.


> 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, which I like.

Yeah.


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

Of course.. we still need to talk about this ActionHandler thingy though :-)


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

That's a bit underspecified in Hydra at the moment I think. Currently the
idea is to use a property's range which again is a class that specifies it's
supportedProperties. That way you get your overall structure. I don't
particularly like micro-syntaxes such as "review.reviewRating.ratingValue"
because they tend to work well just in a few very-well defined cases. In
this case, e.g., I see problems if you need to mix multiple vocabularies
(granted, not something schema.org typically cares much about).


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

They are defined on a class level in the context of a specific API. Within
an  API the class requirements are consistent and apply to multiple
operations. That's similar to what most developers are familiar with from
their object-oriented programming languages. From my experience it is
typically much easier for developers to understand how to use multiple
specialized classes than to deal with multiple resource shapes (even though
they are very similar) - especially considering that properties are global
in RDF.


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

Typically not within an API. If you consider that most APIs are implemented
using some sort of object-oriented programming language I think this becomes
obvious. Developers think in classes that stay the same in the context of an
API - for all operations. If an operation requires some more properties,
it's trivial enough to define a sub class and specify its
supportedProperties separately. Effectively, there isn't much difference
between resource shapes and using specialized classes. The biggest
difference I think is what is send to the server. You don't inform the
server which resource shape you used but you would normally type the entity.
It becomes much easier to program against such data if there's a single
token you can use to distinguish between different "shapes". Furthermore, I
think oslc:describes goes a bit too far as it is defined as follows

    oslc:describes: This shape describes resources that are of any of
      these types. Formally, a shape S applies to a resource R if there
      is a triple R rdf:type T and there is a triple S oslc:describes T.

I don't want it to apply to both classes if I combine two. I want a new
single class which unites them.


Cheers,
Markus


--
Markus Lanthaler
@markuslanthaler

Received on Monday, 18 November 2013 11:00:06 UTC