Added support for strongly typed collections

[alien-mcl]

Summary

This pull request add some changes to the spec that should enable hydra powered APIs to describe strongly typed collections.

More details

There is an issue #233 that should be addressed by this pull request. While the changes are somehow small in numbers, there is another possibly a breaking change as one of the terms has it's domain changed.

[tpluscode]

Awesome, like it overall. Just suggested some editiorial changes

[tpluscode]

Something just occurred to me. I think it we should add a paragraph describing that an instance of a strongly type can have its own member assertions. In that scenario all those assertions should be combined, right?

[tpluscode]

Ah, and one more, similar case. We should clarify the behaviour when there are multiple (sub)classes which may have member assertions. I'd say that clients and server should walk up the rdfs:subClassOf hierarchy and combine them all.

To sum up with an example

:ArticleCollection
  rdfs:subClassOf hydra:Collection ;
  hydra:memberAssertion [
    hydra:property rdf:type ;
    hydra:object :Article ;
  ] ;
.

:DraftArticleCollection
  rdfs:subClassOf :ArticleCollection ;
  hydra:memberAssertion [
    hydra:property :status ;
    hydra:object :Draft ;
  ] ;
.

:KarolsDraftsCollection
  rdfs:subClassOf :DraftArticleCollection ;
  hydra:memberAssertion [
    hydra:property acl:owner ;
    hydra:object </person/Karol> ;
  ] ;
.

</person/Karol/drafts> a :KarolsDraftsCollection .

By combining all the member assertions above we could generate a query like below to find all members of the resource </person/Karol/drafts>.

SELECT ?member {
  </person/Karol/drafts> hydra:member ?member .

  # asserted by :ArticleCollection 
  ?member a :Article .

  # asserted by :DraftArticleCollection
  ?member :status :Draft .

  # asserted by :KarolsDraftsCollection
  ?member acl:owner </person/Karol> .
}

[alien-mcl]

I've added both paragraphs, but I think clients should not be overweighed with such a complex tasks as class hierarchy traversing.

[alien-mcl]

@tpluscode could you please review changes you've requested? I've got another bunch of changes made on this branch I'd like to proceed with (brand new diagram and made the terms stable rather than testing)

[tpluscode]

I don't think this makes the much sense. Even if an API duplicates all assertions on all levels of a class hierarchy, the client does not have a way of knowing that. Thus, they will have to traverse the hierarchy nonetheless.

I think I would change this paragraph and require only that a client inspects explicit rdf:type of a collection resource. In the example below the client would only discover the hydra:manages of PersonCollection

# resource
</people> a api:PersonCollection, hydra:Collection .

# api docs
api:PersonCollection
  rdfs:subClassOf api:AgentCollection ;
  hydra:manages [ hydra:property rdf:type ; hydra:object foaf:Person ] ;
.

api:AgentCollection
  rdfs:subClassOf hydra:Collection ;
  hydra:manages [ hydra:property rdf:type ; hydra:object foaf:Agent ] ;
.

Technically, a client could perform RDFS reasoning but in practice I would suggest that the server did that and served all materialised RDF types instead, to relieve the clients from performing additional processing

[alien-mcl]

Hmm - I see your point. I've softened this required from SHOULD to MAY. Strong recommendation for the server to provide all the details is still in force, but I do not see a way of forcing developers to do so. The client still can do the traversing though.