RE: Potentials Actions - We Think We're Done

OK, so here's the review of

  https://www.w3.org/wiki/images/2/2d/Potential_Actions_-_Final_Review.pdf

that I've promised yesterday.


-- Part 1: Action status --

There's a "start_date" property in the example which has probably been forgotten there. Anyway, I think it might be better to infer whether an action is active/completed and/or "potential" by things like startTime/endTime and the presence of "action entrypoints" than having an actionStatus property. That being said, I really don't have a strong opinion about this though. I can certainly live with actionStatus.


-- Part 2: Connecting Actions to Things --

+1 I'm completely fine with this


-- Part 3: Action Entrypoints --

This section is extremely vague and I find that some things are even contradictory. For instance, the introduction

  "Potential actions are initiated by requesting the URL of an Action"

suggests that the action is always "initiated" by doing an HTTP GET. Later however, the draft says

  "For HTTP specifically, the method used for a Entrypoint will depend
   on the Action type."

The thing I find most confusing though is the reuse of the "url" property as I already said yesterday:

On Wednesday, April 09, 2014 8:25 AM, Sam Goto wrote:
> On Tue, Apr 8, 2014 at 12:40 PM, Markus Lanthaler wrote:
> > Why is schema:url use for the target of an operation? It is defined as
> > "URL of the item." which is quite ambiguous but I think generally it
> > is used as some kind of identifier.
> 
> IMHO, "URL of the item" seems like a reasonable description of what
> the Entrypoint is. Whether an entity/resource is in a webpage URL, a
> mobile app URL or an API url (whose distinction really just is either
> the url scheme - e.g. android-app:// - or the content-type - e.g.
> text/html vs application/ld+json- between the two), the pointer to the
> entity/resource always goes through the "url" property.

The thing is exactly that it is *not* the "URL of the item", i.e., the Action in this case. I think this becomes most apparent with completed actions:

  {
    "@context": "http://schema.org",
    "@type": "Movie",
    "name": "Footloose",
    "action" : {
      "@type": "WatchAction",
      "actionStatus": "CompletedAction",
      "url": "http://example.com/markus-watched-footloose"
    }
  }

How would you interpret such data? What if it would be a BuyAction, i.e., a POST action?

Jumping to part 4 for a second, I also find it quite problematic to set the value of "url" directly to a URL template (which by definition isn't a URL). How does a client know whether it is a URL template or not? By looking at the parameters? Why not introduce either a class "UrlTemplate" with a "template" property or something like a "templatedTarget" analogue to the "target" property I proposed yesterday?

I also don't particularly like how Entrypoint is used here (even though I like the concept and term in general and was actually advocating it). As currently used, it kind of implies that the URL is just the starting point of a multi-step sequence (which in a lot of cases I think it won't be).

IMHO it also doesn't make much sense to specify the encodingType/contentType/application of an "entrypoint" (still talking about the naming of entrypoint here) or to classify it as a "protocol element". A protocol defines how different parties talk to each other, like HTTP or the Atom Publishing Protocol for example do. What is a "protocol element"? It isn't defined in the draft. Couldn't we simply remove it till we really need it?

The draft seems to mix HTTP (accept[-patch/post/..], content-type) and HTML (enctype, type) terminology. Since [@]type is already taken, why not simply use "accept" and "contentType"?

Finally, the note

  "For HTTP specifically, the method used for a Entrypoint will depend
   on the Action type. Safe actions [...] will use GET, everything else
   will use POST except the actions that are subclasses of other HTTP
   methods (e.g., DeleteAction)."

comes back to something that has been discussed a while ago. I don't think this is something that will work. You can't (or at least you shouldn't) fix the HTTP methods. This is an implementation detail. Let me try to illustrate it based on a simple example.
Let's assume we have a ShortenUrlAction. What HTTP method would it use? POST? PUT? GET? All of them are completely valid:

  POST  indicates that every time I shorten the URL, I get a different
        short URL as result (multiple requests, multiple results)

  PUT   indicates that I can safely retry failed requests as all of
        them will return exactly the same short URL
        (multiple requests, same result)

  GET   is basically the same as the PUT but with the advantage that the
        result can be cached. You obviously need URI templates though.


-- Part 4: Input and Output constraints --

This is something we have discussed several times now (it is a tricky problem). Unfortunately, I have to say that I find this solution quite problematic. These "annotations" will work only for schema.org. As soon as you have to use another vocabulary your are completely on your own. I know, this is not something schema.org cares a lot about, but I think there would be quite a simple alternative which doesn't suffer from this limitation.

Using a slight variation of what Hydra currently does,

  "@type": "SearchAction",
  "query/input": {
    "@type": "PropertyValueSpecification",
    "valueRequired": true,
    "valueMaxlength": 100,
    "valueName": "q"
   }

could be transformed to

  "@type": "SearchAction",
  "expects": {
    "propertyPath": "query",  <--- expands to http://schema.org/query
    "valueRequired": true,
    "valueMaxlength": 100,
    "valueName": "q"
   }

If you need to define a property path such as reviewRating -> ratingValue, you simply say

  "property": [ "reviewRating", "ratingValue" ]


-- Example: Product purchase API call with /output --

Apparently there's a lot of information missing from the draft. For example, there's now suddenly a "result" property whose value is an "Order" with (required??) output annotations. So, you state that the not even yet invoked action's "result produced in the action" is an order. The POST (that the client apparently knew to invoke because that's just how BuyActions are invoked) however doesn't return an "Order" but a completed "BuyAction".

The "Movie review site API with /input and /output" example, has a completely different shape. The input parameters are now not on the action, but spread between the "object" and "resultReview" properties. The latter, btw., also has some required outputs.

Furthermore, that example's request POSTs a ReviewAction, why didn't the previous example POST a BuyAction then? In any cases, this feels very RPC-like and not webby at all.


On Wednesday, April 09, 2014 8:25 AM, Sam Goto wrote:
> I think the biggest delta in what we are landing today, is the idea of
> the target of the action not always necessarily being the resource
> that it is attached to. This is indeed a change, but I think it is a
> good one.

I think that is actually the smallest change in this draft, if it is one at all. It just uses the inverse of Hydra's "operation" property. That's all.

Sorry if this review sounds so negative and raises (again) a lot of issues. I simply care a lot about this work and we all know how difficult it is to change something as soon as it is out and being used. We obviously don't need to (and won't) get it 100% perfect but we at least need to achieve those magic 80%. I'm afraid we are still quite a few steps away from that.

I'm more than happy to help where I can (as you hopefully know by now) or collaborate more directly with all of you. I'm not sure, however, how we could speed this up... which, based on Jason's mail, seems to become quite important to you.


Cheers,
Markus


--
Markus Lanthaler
@markuslanthaler

Received on Thursday, 10 April 2014 00:21:02 UTC