Documenting the type of collections and cardinalities with OWL

Hello,

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).

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. 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"
                      }
                    }
                  ],
                  "hydra:supportedOperation": [
                      {
                          "@type": "hydra:Operation",
                          "hydra:method": "GET",
                          "hydra:title": "Retrieves the collection of User
resources.",
                          "rdfs:label": "Retrieves the collection of User
resources.",
                          "hydra:returns": "hydra:PagedCollection"
                      },
                      {
                          "@type": "hydra:CreateResourceOperation",
                          "hydra:expects": "#User",
                          "hydra:method": "POST",
                          "hydra:title": "Creates a User resource.",
                          "rdfs:label": "Creates a User resource.",
                          "hydra:returns": "#User"
                      }
                  ]
              },
              "hydra:title": "The collection of User resources",
              "hydra:readable": true,
              "hydra:writable": false
          }
      ],
      "hydra:supportedOperation": {
          "@type": "hydra:Operation",
          "hydra:method": "GET",
          "rdfs:label": "The API entrypoint.",
          "hydra:returns": "#EntryPoint"
      }
  }
```

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

```
{
  "hydra:supportedClass": [
      {
          "@id": "#User",
          "@type": "hydra:Class",
          "rdfs:label": "User",
          "hydra:title": "User",
          "hydra:supportedProperty": [
              {
                  "@type": "hydra:SupportedProperty",
                  "hydra:property": {
                      "@id": "#User/company",
                      "@type": "hydra:Link",
                      "rdfs:label": "company",
                      "domain": "#User",
                      "range": "#Company",
                      "owl:maxCardinality": 1
                  },
                  "hydra:title": "companies",
                  "hydra:required": false,
                  "hydra:readable": true,
                  "hydra:writable": false,
                  "hydra:description": "the company managed bythis user"
              }
          ]
      }
    ]
}
```

Documentation of a to-many relation (no owl:maxCardinality key means
unbounded, so to-many) :

```
{
  "hydra:supportedClass": [
      {
          "@id": "#User",
          "@type": "hydra:Class",
          "rdfs:label": "User",
          "hydra:title": "User",
          "hydra:supportedProperty": [
              {
                  "@type": "hydra:SupportedProperty",
                  "hydra:property": {
                      "@id": "#User/companies",
                      "@type": "hydra:Link",
                      "rdfs:label": "companies",
                      "domain": "#User",
                      "range": "#Company"
                  },
                  "hydra:title": "companies",
                  "hydra:required": false,
                  "hydra:readable": true,
                  "hydra:writable": false,
                  "hydra:description": "the companies managed by this
user\nMany Users have Many Companies"
              }
          ]
      }
    ]
}
```

Do you think it's a valid way to handle this?

Thank you in advance and have a nice day!

[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
-- 
Kévin Dunglas

https://dunglas.fr
Twitter: @dunglas <https://twitter.com/dunglas>
Phone: +33 6 60 91 20 20