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

> How do I use hydra:CollectionSpecification?
> What can I do with it what I cannot do with a hydra:Collection?

Well, `hydra:Collection` is a type, thus you can tell that a resource, i.e. `http://some.uri/api/orders` is of that type. But in API documentation you say that an operation returns a collection, but you do not provide that very instance. Without a specific instance, you are not able to say anything about that collection other than it is a collection.

> How can a Specification of a Collection be a Collection itself (subClass of Collection)?> Those are different concepts to me. Is it meant to be used as the object of a "hydra:returns"?
> But an Operation will not return a hydra:CollectionSpecification,
> but a Collection that matches this specification...

Indeed - same thing with `hydra:Class`. Na operation does not return a class of that IRI, but a resource that is of that type (that IRI). Same here, operation returns a collection that matches specification.
As for the CollectionSpecification being a Collection, it was to match domain of the `hydra:manages`. Is there any better way of achieving same thing without breaking anything that works on hydra as it is now?

> I would prefer to have prose specification and usage examples in addition to the plain jsonld changes.

I'll try to provide, probably with Heracles.ts tests.

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

Received on Wednesday, 13 February 2019 19:48:42 UTC