API documentation limitations

[alien-mcl]

This is a derivative of a PR #182 that covers #167 :

• explicitly point a target of the operation (this should make obsolete PR #154 and address issue #160 )
• define a collection specification that can have manages predicate provided

[angelo-v]

How do I use hydra:CollectionSpecification? What can I do with it what I cannot do with a hydra: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...

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

[angelo-v]

Would be cool to rename this PR "API documentation limitations" is quite generic.

[alien-mcl]

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.

[alien-mcl]

Would be cool to rename this PR "API documentation limitations" is quite generic.

I've named the PR same way as the issue #167 (as I did with previous PRs)

[alien-mcl]

Isn't this duplicating what the manages block intends to address? We should properly document the latter first IMO

Somehow. CollectionSpecification is to enable API documentation to express how the items of the collections matches the manages block. It does not duplicate it - it just makes it possible to hook-up hydra:manges to API documentation - I don't thing this was doable before.

[tpluscode]

I've named the PR same way as the issue #167 (as I did with previous PRs)

167 is also quite vague ;)

[angelo-v]

Somehow. CollectionSpecification is to enable API documentation to express how the items of the collections matches the manages block. It does not duplicate it - it just makes it possible to hook-up hydra:manges to API documentation - I don't thing this was doable before.

Ok, I get the goal and support it. Nevertheless I am not fine with just saying a CollectionSpecification is a Collection. Again for me this comes down to the meaning of "hydra:returns". We could say that the object of hydra:returns should always be some kind of Specification instead of a class.

If I just want to say it returns instances of a class this could look like that:

{
  "hydra:returns": {
    "@type": "hydra:Specification",
    "hydra:specifies": {
      "property": "rdf:type",
      "object": "schema:Event"
    }
  }
}

"hydra:specifies" is inspired by "hydra:manages", as it serves a similar purpose - describing what an operation returns and describing what's in a collection is quite similar to me.

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

{
  "hydra:returns": {
    "@type": "hydra:Specification",
    "hydra:specifies": [
      {
        "property": "rdf:type",
        "object": "hydra:Collection"
      },
      {
        "property": "hydra:manages",
        "object": {
          "property": "rdf:type",
          "object": "schema:Event"
        }
      }
    ]
  }
}

It's just a quick scribble, I don't want to propose it that way. It just seems to me, that the topic is more complicated and needs further thinking and discussing :/ And perhaps we need something like SHACL?

[alien-mcl]

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.

[angelo-v]

Shall we go in that direction?

We could give it a try and play arround with the possibilities a bit. I would especially want to get a feeling for how this works out from a clients perspective and ensure it doesn't make things to complicated.