Re: [Specifications] Should we introduce a property to associate operations and their target directly to an entity?

In my comment I just wanted to propose that operation doesn't always have to specify *target* - an IRI, which we can think of as a resource with an `@id` (denoted by that IRI)
As @lanthaler suggested we don't need to define a new property for that but just rely on using `hydra:operation` in reverse direction - JSON-LD `@context` in spec non-normative appendix can include an alias for that.
In cases like `CreateAction` with PUT #141 sometimes client will not get IRI but Uri Template / `hydra:IriTemplate`, based on which clients constructs the IRI which denotes the resource on which to perform the operation. In that case I don't think we can use `hydra:operation` in reverse direction

The most common example of using `hydra:IriTemplate` comes with `hydra:search`, the only property which definition includes `hydra:search rdfs:range hydra:IriTemplate`. Also already widely deployed thanks to Triple Pattern Fragments http://www.hydra-cg.com/spec/latest/triple-pattern-fragments/#controls

What I don't like about trying to use similar approach to creating a new resource (something like `hydra:create`). It seems to result in two different ways of advertising the *create* operation

```json
    {
      "@id": "/api/events",
      "title": "List of events",
      "@type": "hydra:Collection",
      "manages": {
        "property": "rdf:type",
        "object": "schema:Event"
      },
      "operation": {
        "@type": ["hydra:Operation", "schema:CreateAction"],
        "title": "Create new event",
        "method": "POST",
        "expects": "schema:Event"
      }
    }
```
and following how `hydra:search` works, something like:
```json
    {
      "@id": "/api/events",
      "title": "List of events",
      "@type": "hydra:Collection",
      "manages": {
        "property": "rdf:type",
        "object": "schema:Event"
      },
      "hydra:create": {
        "@type": "hydra:IriTemplate",
        "hydra:template": "/api/events/{uuid}",
        "hydra:mapping": {
          "hydra:variable": "uuid",
          "hydra:property": "id:uuid",
          "hydra:required": true
        }
      }
    }
```

While I would like something aligned with the first example using `schema:CreateAction`

```json
    {
      "@id": "/api/events",
      "title": "List of events",
      "@type": "hydra:Collection",
      "manages": {
        "property": "rdf:type",
        "object": "schema:Event"
      },
      "operation": {
        "@type": ["hydra:Operation", "schema:CreateAction"],
        "title": "Create new event",
        "method": "PUT",
        "expects": "schema:Event",
        "targetTemplate": {
          "@type": "hydra:IriTemplate",
          "hydra:template": "/api/events/{?uuid}",
          "hydra:mapping": {
            "hydra:variable": "uuid",
            "hydra:property": "id:uuid",
            "hydra:required": true
        }
        }
      }
    }
```

But then if we consider (an alias) `@reverse` of `hydra:operation` as `target`, it seems to conflict with `targetTemplate` in a way.

> @lanthaler: Mostly. I envisioned the target property to be a simple inverse of the operation property. Thus you couldn’t use both at the same time. We would need another mechanism to link from resource to the operation. I was thinking about action. I would call the abstract thing that happens (becoming a friend of someone, ordering something) an Action and the bytes on the wire (HTTP or other request) an Operation. WDYT?

I also like this distinction and we also have related conversation in #2 in case above if we would state
```json
    {
      "@id": "/api/events",
      "action": {
        "@type": ["hydra:Operation", "schema:CreateAction"]
      }
    }
```
We would have to provide an explicit `target` or `targetTemplate`, in that case it might make sense to define `target` property and for simple cases use it in `@reverse` direction (possibly making `operation` an alias). This also would allow use of `schema:SearchAction` [UC#7 Searching events](https://github.com/HydraCG/Specifications/blob/master/drafts/use-cases/7.searching-events.md)

```json
{
    "@context": "/api/context.jsonld",
    "@id": "/api/events",
    "@type": "hydra:Collection",
    "manages": {
      "property": "rdf:type",
      "object": "schema:Event"
    },
    "totalItems": 100,
    "members": [ ... ],
     "action": [
        {
          "@type": ["hydra:Operation", "schema:CreateAction"],
          "title": "Create new event",
          "method": "POST",
          "expects": "schema:Event",
          "target": "/api/events"
       }, {
          "@type": ["hydra:Operation", "schema:SearchAction"],
          "title": "Search evenst",
          "method": "GET",
          "targetTemplate": {
            "@type": "IriTemplate",
            "hydra:template": "/api/events{?search}",
            "hydra:variableRepresentation": "hydra:BasicRepresentation",
            "hydra:mapping": {
              "@type": "hydra:IriTemplateMapping",
              "variable": "search",
              "property": "hydra:freetextQuery",
              "required": true
            }
         }
       }
     ]
}
```
At the same time it would mean breaking change to `hydra:search` which @RubenVerborgh may strongly object since TPF deployments rely on it.

-- 
GitHub Notification of comment by elf-pavlik
Please view or discuss this issue at https://github.com/HydraCG/Specifications/issues/3#issuecomment-336635276 using your GitHub account

Received on Saturday, 14 October 2017 13:33:09 UTC