Operation linked to class and property

[bergos]

At the moment it is not possible to define different operations for the same property, but different classes. Maybe it's a design choice, but it make the API design a little bit more difficult for some use cases.

For example the Data Cube points for DataSet to a Slice using the slice property. The expects looks different for each dataset, but always the slice property should be used to point to the dynamically filtered data. It's solved now by using different custom slice properties. With OWL it would be possible to link from the custom slice properties to the original one. But that requires a client to understand OWL. One option would be moving the supportedOperation to the supportedProperty level.

Is this a use case which should be covered or was it a design choice that properties must always support the same operations?

Example with custom slice property:

[
  {
    "@id": "http://example.org/dataset-1",
    "@type": "Class",
    "supportedProperty": {
      "property": {
        "@id": "http://example.org/dataset-1#slice",
        "supportedOperation": {
          "@id": "http://example.org/dataset-1#slice-get",
          "@type": "Operation",
          "method": "GET",
          "expects": "http://example.org/dataset-1#slice-input",
          "returns": "http://purl.org/linked-data/cube#Slice"
        }
      }
    }
  },
  {
    "@id": "http://example.org/dataset-2",
    "@type": "Class",
    "supportedProperty": {
      "property": {
        "@id": "http://example.org/dataset-2#slice",
        "supportedOperation": {
          "@id": "http://example.org/dataset-2#slice-get",
          "@type": "Operation",
          "method": "GET",
          "expects": "http://example.org/dataset-2#slice-input",
          "returns": "http://purl.org/linked-data/cube#Slice"
        }
      }
    }
  }
]

Example with supportedOperation on the supportedProperty level:

[
  {
    "@id": "http://example.org/dataset-1",
    "@type": "Class",
    "supportedProperty": {
      "property": "http://purl.org/linked-data/cube#slice",
      "supportedOperation": {
        "@id": "http://example.org/dataset-1#slice-get",
        "@type": "Operation",
        "method": "GET",
        "expects": "http://example.org/dataset-1#slice-input",
        "returns": "http://purl.org/linked-data/cube#Slice"
      }
    }
  },
  {
    "@id": "http://example.org/dataset-2",
    "@type": "Class",
    "supportedProperty": {
      "property": "http://purl.org/linked-data/cube#slice",
      "supportedOperation": {
        "@id": "http://example.org/dataset-2#slice-get",
        "@type": "Operation",
        "method": "GET",
        "expects": "http://example.org/dataset-2#slice-input",
        "returns": "http://purl.org/linked-data/cube#Slice"
      }
    }
  }
]

[lanthaler]

@bergos, any update on the clarification of this issue?

[bergos]

Here is a complete example, which should be easier to understand without knowing the ontology. There are two classes Thing and RateableThing. Both have the comment property, both have a POST operation, but they expect different classes (Comment, RatingComment). In this JSON-LD representation it looks like there is a connection from the class to the operation, but the actual triples look like this:

<comment> <supportedOperation>  _:b1 .
<comment> <supportedOperation>  _:b2 .

Different properties could be used, but that's not always possible if a third party ontology is used and no custom properties should be used.

{
  "@context": "http://www.w3.org/ns/hydra/context.jsonld",
  "@graph": [{
    "@id": "http://example.org/Thing",
    "@type": "Class",
    "supportedProperty": {
      "property": {
        "@id": "http://example.org/comment",
        "supportedOperation": {
          "@type": "Operation",
          "method": "POST",
          "expects": "http://example.org/Comment"
        }
      }
    }
  }, {
    "@id": "http://example.org/RateableThing",
    "@type": "Class",
    "supportedProperty": {
      "property": {
        "@id": "http://example.org/comment",
        "supportedOperation": {
          "@type": "Operation",
          "method": "POST",
          "expects": "http://example.org/RatingComment"
        }
      }
    }
  }, {
    "@id": "http://example.org/Comment",
    "supportedProperty": {
      "property": {
        "@id": "http://example.org/message"
      }
    }
  }, {
    "@id": "http://example.org/RatingComment",
    "supportedProperty": {
      "property": [{
        "@id": "http://example.org/message"
      }, {
        "@id": "http://example.org/rating"
      }]
    }
  }]
}

[elf-pavlik]

@bergos does this issue only stay relevant for hydra:supportedOperation in hydra:ApiDocumentation?
For hypermedia controls included in representations of resources themselves it seems like no problem to reference particular operations with hydra:operation which would include hydra:expects appropriate for that specific resource.

[bergos]

@elf-pavlik you are right, it should work outside hydra:ApiDocumentation.

Are there any examples for hypermedia controls in the resources itself? Which clients support that feature? I'm not aware that this feature is mentioned explicitly in the spec or other documents. If that's the solution, than the feature should be more official.

[elf-pavlik]

One example here: https://www.hydra-cg.com/spec/latest/triple-pattern-fragments/#controls

Some background: https://ruben.verborgh.org/blog/2015/10/06/turtles-all-the-way-down/

Also use cases we recently work on start having hypermedia controls inline, see manages and memberTemplate included in the same graph in https://github.com/HydraCG/Specifications/blob/master/drafts/use-cases/5.1.creating-event-with-put.md#details
Even this EntryPoint makes something inbetween ApiDocumentation and controls in resources themselves: https://github.com/HydraCG/Specifications/blob/master/drafts/use-cases/1.entry-point.md

During last telecon we discussed if we should have ApiDocumentation and inline controls covering exactly the same set of use cases. While we found this possibility attractive we also stay open that inline controls may cover some cases which ApiDocumentation can't. Your use case might turn out one of those.