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

On Mon, Nov 18, 2013 at 2:59 AM, Markus Lanthaler
<markus.lanthaler@gmx.net>wrote:

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

Yep, I think you are right. Here, I updated the spec to include "expects"
(which takes SupportedProperty, replaces
"optionalProperty/requiredProperty") as well as "returns" (replaces
"hasPayload").

http://www.w3.org/wiki/images/b/b9/Actionsinschema.org.pdf



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