Operation linked to class and property
bergos opened this issue · 5 comments
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"
}
}
}
]
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"
}]
}
}]
}
@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.
@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.
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.