RE: Documenting the type of collections and cardinalities with OWL

Hi Kévin,

On Wednesday, June 21, 2017 3:05 PM, Kévin Dunglas wrote:
> A common need of API Platform's [1] users is to be able to retrieve
> from the Hydra documentation the type of collections (the type of
> resources contained in hydra:member when it cannot be mixed) as well
> as the cardinality of relations (to-one or to-many).

It would be great if you could file PR adding a use case for this to 

  https://github.com/HydraCG/Specifications/tree/master/drafts/use-cases

 
> There are several issues on our bug tracker about this, and fixing
> them will also allow to improve our dynamic Hydra-based React admin
> [2] and our React/Redux app scaffolder [3].
> 
> Markus pointed out [4] that we could use OWL to define more specific
> types. I've ended up with the following proposals, but I don't know
> OWL well.

Yes, OWL definitely works. Eventually I'd probably like to support this natively in Hydra.


> I would like to have the confirmation that my proposal is
> valid according to Hydra and OWL.
> 
> Can someone give a look to the following snippets ?
> 
> Documentation of the /users URL in the entrypoint (will return a
> hydra:PagedCollection of #User instances - all keys starting by owl
> have been added) :
> 
> ```
>   {
>       "@id": "#Entrypoint",
>       "@type": "hydra:Class",
>       "hydra:title": "The API entrypoint",
>       "hydra:supportedProperty": [
>           {
>               "@type": "hydra:SupportedProperty",
>               "hydra:property": {
>                   "@id": "#Entrypoint/user",
>                   "@type": "hydra:Link",
>                   "domain": "#Entrypoint",
>                   "rdfs:label": "The collection of User resources",
>                   "rdfs:range": [
>                     "hydra:PagedCollection",
>                     {
>                       "owl:equivalentClass": {
>                         "owl:onProperty": "hydra:member",
>                         "owl:allValuesFrom": "#User"
>                       }
>                     }

This is fine. The easiest way to check such things in general is to simply fire up a reasoner and see whether it makes the desired inferences.


> Documentation of a to-one relation (owl:maxCardinality key added):

This is valid too but why would you use a collection for this instead of a direct link?


Btw. in case you haven't seen it yet, we just started (1st PR under discussion) developing a reference client in TypeScript. Given your work, I assume you could contribute quite some experience. Would be great if you could help us over at

  https://github.com/HydraCG/Heracles.ts


Cheers,
Markus

 
> [1] https://github.com/api-platform/api-platform
> [2] https://github.com/api-platform/admin
> [3] https://github.com/api-platform/generate-crud
> [4] https://github.com/api-platform/core/issues/912#issuecomment-273296233


--
Markus Lanthaler
@markuslanthaler

Received on Wednesday, 21 June 2017 18:38:34 UTC