Re: An updated draft of the schema.org/Action proposal

On Tue, Jan 28, 2014 at 6:22 AM, Markus Lanthaler
<markus.lanthaler@gmx.net>wrote:

> On Tuesday, January 28, 2014 6:02 AM, Sam Goto wrote:
> >
> > Here is another challenge with this approach: how do you set up the
> > expectations on the properties of the Action class? That is, most of
> > the invocations take more than one parameter and they map to one of
> > the Action properties (e.g. RsvpAction takes an "agent" as well as an
> > "attendance" -- whether the agent is going or not).
>
> It depends. If the agent, e.g., is fixed as it is in most cases when you
> send an invitation by email I would encode it in the URL the response is
> sent to. If it isn't, I would create an RsvpResponse class defining those
> two properties as you do below.
>

Right. Agreed that authentication/authorization has different transport
mechanisms (e.g. cookies or oauth tokens). That wasn't a great example on
second though.

Reviews might be a good one. As you are making a review, services take
"reviewBody" as well as "ratingValue" (which is nested inside a
"reviewRating" property of type "Rating", hence the nested object).

https://developers.google.com/gmail/actions/reference/review-action


>
>
> > If you had to declare that as a SupportedClass, that would require the
> > handler to take a SupportedClass that is subClassOf a RsvpAction,
> > which is a lot verbose [1].
>
> It always depends a lot on how you format these things. If the range of
> something is clear, there's also no need to specify it explicitly. Thus,
> [1] could be written as
>
> {
>   "@context": "http://schema.org",
>   "@type": "Event",
>   "@id": "http://code.sgo.to/events/123",
>   "name": "Taco Night",
>   "startDate": "2015-04-18T15:30:00Z",
>   "endDate": "2015-04-18T16:30:00Z",
>   "operation": {
>     "@type": "RsvpAction",
>     "expects": {
>       supportedProperty: [
>         { "property": "rsvpAttendance" },
>         { "property": "http://schema.org/agent",
>            "rangeIncludes": {
>              "subClassOf": "Person",
>              "supportedProperty": { "property": "name" }
>            }
>         }
>       ]
>     }
>   }
> }
>
> Which I don't find that verbose
>
>
> > Option [2] is an attempt to cut down a bit the verbosity by allowing
> > the "expects" property to take "Property", "SupportedProperty" (which
> > refers to the Action-level properties) as well as "SupportedClass".
>
> I still have troubles seeing how an application without further knowledge
> will be able to tell whether "http://schema.org/rsvpAttendance" in that
> example is a Property or a SupportedProperty. It would have to go and
> dereference that URL to look up its definition to find that out.
>
>
> > Option [3] is what gmail lanched with, which, apart from strict
> > preciseness, it is quite concise and clean.
>
> Yeah, it is concise and clean but the "agent.name" string doesn't mean
> anything without out of band knowledge. For me, that's a deal breaker. It
> works for something like Gmail because Google is big and important enough
> to enforce these things but looking at the bigger, decentralized Web it
> won't work at all IMHO.
>
>
> > Markus, have you run into problems describing nested objects on
> > "expects" (e.g. a bug needs an author which in turn needs to have at a
> > minimum an id?)?
>
> Yeah, I have been thinking about this but wasn't able to find an elegant
> solution yet. If you start relying on Linked Data principles, i.e.,
> dereferenceable URLs to look up definitions (of course all concepts can be
> defined in a single document) a lot of these deeply nested structures go
> away as you simply reference the various concepts. In many other cases, it
> is possible to eliminate the nesting by creating a new specialized type or
> by encoding some of the information in the URL the data is sent to.
>
>
As I mentioned to you before, we really need a solution to this. A non
trivial number of my actions take nested objects and we need to deal with
this requirement from day one.

Here are a few examples that could inform/help us come up with something
better:

hotel reservations
http://code.sgo.to/crawler/yaap.html#url=http://code.sgo.to/hotels/123
events rsvp-ing
http://code.sgo.to/crawler/yaap.html#url=http://code.sgo.to/events/123
taxistand reservations
http://code.sgo.to/crawler/yaap.html#url=http://code.sgo.to/taxistands/123/reservations
restaurant orders
http://code.sgo.to/crawler/yaap.html#url=http://code.sgo.to/restaurants/123/orders
product reviews
http://code.sgo.to/crawler/yaap.html#url=http://code.sgo.to/products/123



>
> > [1]
> >
> > {
> >   "@context": "http://schema.org",
> >   "@type": "Event",
> >   "@id": "http://code.sgo.to/events/123",
> >   "name": "Taco Night",
> >   "startDate": "2015-04-18T15:30:00Z",
> >   "endDate": "2015-04-18T16:30:00Z",
> >   "operation": {
> >     "@type": "RsvpAction",
> >     "expects": {
> >         "@type": "SupportedClass",
> >         "subClassOf": "http://schema.org/RsvpAction",
> >         supportedProperty: [
> >           {"@type": "SupportedProperty",
> >           "property": "http://schema.org/rsvpAttendance"}
> >           {
> >             "@type": "SupportedProperty",
> >              "property": "http://schema.org/agent",
> >              "rangeIncludes": {
> >                "@type": "SupportedClass",
> >                "subClassOf": "Person",
> >                "supportedProperty": [
> >                   {"@type": "SupportedProperty",
> >                    "property": "http://schema.org/name"}
> >               ]
> >           }
> >       ]
> >     }
> > }
> >
> > [2]
> >
> > {
> >   "@context": "http://schema.org",
> >   "@type": "Event",
> >   "@id": "http://code.sgo.to/events/123",
> >   "name": "Taco Night",
> >   "startDate": "2015-04-18T15:30:00Z",
> >   "endDate": "2015-04-18T16:30:00Z",
> >   "operation": {
> >     "@type": "RsvpAction",
> >     "expects": [
> >        // this is a property that refers to the top level action
> >       "http://schema.org/rsvpAttendance"
> >        {
> >             "@type": "SupportedProperty",
> >              "property": "http://schema.org/agent",
> >              "rangeIncludes": {
> >                "@type": "SupportedClass",
> >                "subClassOf": "Person",
> >                "supportedProperty": [
> >                  "http://schema.org/name"
> >               ]
> >           }
> >       ]
> >     }
> > }
> >
> > [3]
> >
> > {
> >   "@context": "http://schema.org",
> >   "@type": "Event",
> >   "@id": "http://code.sgo.to/events/123",
> >   "name": "Taco Night",
> >   "startDate": "2015-04-18T15:30:00Z",
> >   "endDate": "2015-04-18T16:30:00Z",
> >   "operation": {
> >     "@type": "RsvpAction",
> >     "optionalProperty": [
> >       // this is a property that refers to the top level action
> >       "rsvpAttendance"
> >       // this is a property that refers to the agent name
> >       "agent.name"
> >       ]
> >     }
> > }
>
>
>
> --
> Markus Lanthaler
> @markuslanthaler
>
>
>
>
>
>