Re: [Specifications] API documentation limitations (#183)

> We could say that the object of hydra:returns should always be some kind of Specification instead of a class.

This is how it is from the beginning. Changing it would break existing implementations, that's why I've created a specification that is also a collection. Actually, when I think about it - maybe it would be OK to drop that `hydra:Collection` typing for `hydra:CollectionSpecification` and assume that using the latter means the former is returned.

>Describing now, how a collection looks like, that is returned by an operation can get quite complicated,
> I see that, but possible:

This looks interesting - I think it touches constraints that were mentioned somewhere earlier. That approach could actually make construct introduced in PR #186 - the specification could contain media type rather than RDF statements.

Shall we go in that direction?

> And perhaps we need something like SHACL?

We need, but not directly. I was thinking about making a soft suggestion in the spec to either use SHACL for describing data structures, but still plain RDF or OWL should be somehow supported. I'd love to see Heracles.ts to work with SHACL as it nicely describes CWA structures in OWA way.

-- 
GitHub Notification of comment by alien-mcl
Please view or discuss this issue at https://github.com/HydraCG/Specifications/pull/183#issuecomment-463763376 using your GitHub account

Received on Thursday, 14 February 2019 19:39:09 UTC