Supported Operations on properties
angelo-v opened this issue · 9 comments
It is proplematic to define supported operations on a hydra:property, when re-using vocabularies, like on http://schema.org/events below:
"supportedProperty": [
{
"property": {
"@id": "schema:events",
"supportedOperation": [
{
"@id": "_:some_operation"
}
]
}
}
]This now states that schema:events does support _:some_operation, which is not true in general but only specific to this API.
It would be better to move anything API specific to the level of supportedProperty:
"supportedProperty": [
{
"property": {
"@id": "schema:events"
},
"supportedOperation": [
{
"@id": "_:some_operation"
}
]
}
]This is e.g. already the case for required, readable and writable.
Hmm. I think there is some misunderstanding of the spec. Your second snipped is exactly as the vocab says. Take a look at the raw JSON-LD vocabulary and you'll see that mentioned predicates (required, readable, and writable) are pointing as their domains 'SupportedProperty'.
As for the 'supportedOperation' - it points to 'Class' as it's domain and while SupportedOperation is of type Class you can safely use supportedOperation with it.
This is exactly to avoid adding unnecessary statements to the property itself.
Correct syntax would be:
"supportedProperty": [
{
"property": {
"@id": "schema:events"
},
"required": true,
"supportedOperation": [
{
"@id": "_:some_operation"
}
]
}
]Clearly, this is not obvious. Even the ApiDoc of the issue tracker demo does it "wrong": http://www.markus-lanthaler.com/hydra/event-api/vocab
We definitely have to make this clear in the spec
So wich on would get the @type: Link then? the supported property, or the property?
Clearly, this is not obvious.
Well, there is also an image that shows it on top of the spec, but it seems that indeed it should be stated more precisely.
It seems that my last correct example is not quite correct.
Indeed, hydra:supportedOperation is used in some of the examples directly on the property rather than the supported property and the spec does not touch that matter directly. Also the raw RDF representation of the vocabulary is not that clear about it.
During last call at 2018.05.28 we decided we won't change that approach with having a supported operation attached on the property, but we will add a note to the spec regarding the fact, that such statement should be considered as API specific and aggregators should use a limited trust policy to such statements. It's due to fact that attaching a supported operation to a shared vocavulary's term would mean that all occurances of such a property would have that operation available, which is clearly untrue.
The more I look at it, the less I like the idea of leaving this topic with a mere paragraph in the spec.
From the raw RDF of the vocabulary it is clear thath hydra:supportedOperation shouldn't be applied to neither resources of type hydra:SupportedProperty nor rdf:Property.
I'd love to make to formal and either extend current definition of the hydra:supportedOperation's schema:domainIncludes list with either the rdf:Property or hydra:SupportedProperty.
The former will make existing examples somehow legal, but leaving the issue of attaching features to predicates taken from external vocabularies.
The latter feels to me a bit cleaner. It makes those examples broken (well, they are broken now), but there will be no semantic issues with hydra predicates attached to external terms.
Both will enable hydra to be more CQRS ready - I saw the discussion on one of the slack channels that touched it (API with patching and CQRS-like approach).
I'll prepare a PR for this - we'll see how it will end up
Why do you think hydra:supportedOperation should not be used with hydra:SupportedProperty?
And what does any of it have to do with CQRS?
Just take a look at how the vocab defines it's domains and ranges (my post above).
As for CQRS - it is quite common to expose separate commands to update single properties (or set of properties) that partially updates aggregates. Having a formal way of attaching operations to properties would enable it