- From: Kévin Dunglas <dunglas@gmail.com>
- Date: Thu, 22 Jun 2017 15:08:06 +0200
- To: Markus Lanthaler <markus.lanthaler@gmx.net>
- Cc: Hydra <public-hydra@w3.org>
- Message-ID: <CAOv1iQYKw76gNPn50Gq9qsbggqWBWBK6KxpF9VGQ25_YeuPfpg@mail.gmail.com>
> This is valid too but why would you use a collection for this instead of
a direct link?
After a second look, there is a reason.
Our properties holding relations don't contain "hydra:Collection"s but a
single IRI or an array of IRIs. Example:
{
// ...
"companies": ["/companies/1", "/companies/2"], // to-many
"company": "/companies/1" // to-one
}
We need to guess if its an array of hydra:Link or just a single one
directly from the Hydra documentation.
Currently, the docs looks the following:
to-many:
{
"@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"
},
to-one:
{
"@type": "hydra:SupportedProperty",
"hydra:property": {
"@id": "#User/company",
"@type": "hydra:Link",
"rdfs:label": "company",
"domain": "#User",
"range": "#Company"
},
"hydra:title": "company",
"hydra:required": false,
"hydra:readable": true,
"hydra:writable": false
}
As you can see, currently it's not possible to distinguish to-one and
to-many just by parsing the docs.
If we add the owl property to the documentation of the to-one property like
this:
{
"@type": "hydra:SupportedProperty",
"hydra:property": {
"@id": "#User/company",
"@type": "hydra:Link",
"rdfs:label": "company",
"owl:maxCardinality": 1
"domain": "#User",
"range": "#Company"
},
"hydra:title": "company",
"hydra:required": false,
"hydra:readable": true,
"hydra:writable": false
}
We can now guess that it's a link to a single resource (or zero). If
the "owl:maxCardinality"
isn't present, we assume that this property can contain a list of links to
resources.
Is it a valid usage?
Cheers,
2017-06-22 14:46 GMT+02:00 Kévin Dunglas <dunglas@gmail.com>:
> Thanks for your reply Markus! It helps a lot.
>
> > It would be great if you could file PR
>
> I'll do it.
>
> > Eventually I'd probably like to support this natively in Hydra.
>
> It would be great. Vocabularies proliferation make the learning curve
> harder for web developers.
>
> > This is valid too but why would you use a collection for this instead
> of a direct link?
>
> Indeed, my bad we are already using a direct link, I get mixed up.
>
> > 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
>
> Nice initiative. Is there a document presenting the goals of this tool?
> I've already published a library to parse the Hydra documentation (it
> powers our admin system and the CRUD generator): https://github.
> com/dunglas/api-doc-parser
>
> It's written in ES6 + Flow (not TypeScript) but we will be very happy to
> move it to the Hydra org, or merge it with the new client.
> Maybe it's a better idea to separate the docs parser and the client (the
> client can use the docs parser).
>
> Let me know if I can help.
>
> Best regards.
>
> 2017-06-21 20:37 GMT+02:00 Markus Lanthaler <markus.lanthaler@gmx.net>:
>
>> 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
>>
>>
>>
>>
>>
>
>
> --
> Kévin Dunglas
>
> https://dunglas.fr
> Twitter: @dunglas <https://twitter.com/dunglas>
> Phone: +33 6 60 91 20 20 <+33%206%2060%2091%2020%2020>
>
--
Kévin Dunglas
https://dunglas.fr
Twitter: @dunglas <https://twitter.com/dunglas>
Phone: +33 6 60 91 20 20
Received on Thursday, 22 June 2017 13:09:00 UTC