View source for Collection Design

The discussions related to [http://github.com/HydraCG/Specifications/issues/41 ISSUE-41] and [http://github.com/HydraCG/Specifications/issues/42 ISSUE-42] led to [[Avoid that collections break relationships|several]] [[Pagination|proposals]]. The group reached consensus on the overall design of collections, but there are still a couple of open questions. To help finalizing the design of collections, this page summarizes these open issues and the proposals to address them.

= Proposed Collection Design =

The following snippets in JSON-LD and Turtle format illustrate the design the group reached consensus on.

 {
   "@id": "/alice",
   "collection": {
     "@id": "/alice/friends",
     "@type": "Collection",
     "manages": {
       "property": "schema:knows",
       "subject": "/alice"
     }
   }
 }

 </alice> hydra:collection </alice/friends> .
 </alice/friends> a hydra:Collection ;
     hydra:manages [
         hydra:property schema:knows ;
         hydra:subject </alice> .
     ] .

== Inverse Relationship ==

Let's take an example of collection of events alice attends. Schema.org follows the model ''Event --[ attendee ]--> Person'' so we use ''object'' instead of ''subject'' inside of ''manages'' block:

 {
   "@id": "/alice",
   "collection": {
     "@id": "/alice/events",
     "@type": "Collection",
     "manages": {
       "property": "schema:attendee",
       "object": "/alice"
     }
   }
 }

[http://lists.w3.org/Archives/Public/public-hydra/2014Aug/0192.html section based on this email]

== Pagination ==

The main idea of the chosen design is to look at pages of a collection as specific ''views'' on a single underlying collection instead of thinking of the collection as the sum of its pages. A representation of a specific view would look as follows:

 {
   "@id": "http://api.example.com/an-issue/comments",
   "@type": "Collection",
   "member": [ ... ],
   "view": {
     "@id": "/an-issue/comments?page=3",
     "@type": "PartialCollectionView",
     "first": "/an-issue/comments?page=1",
     "previous": "/an-issue/comments?page=2",
     "next": "/an-issue/comments?page=4",
     "last": "/an-issue/comments?page=498",
   }
 }

== Open questions ==

# <del>Strictly speaking, the "collection" property  isn't necessary as the collection is already connected to the resource it belongs to via the "manages block". This, however, requires traversing a link in the reverse order which people might find confusing or counterintuitive and might also have performance implications. The question thus is: do we want to introduce "collection" (or a similar term) or not?</del>
# <del>The term "manages" is very generic, which makes it possible to reuse it for other features in the future without having to extend the vocabulary. The downside of it is that it is not very explicit, i.e., a client needs, e.g., to know that it is used on a collection and not something else in order to interpret it correctly. Do we want to use another term instead of "manages"?</del>
# <del>Should the terms rdf:subject/predicate/object be reused or should Hydra introduce the properties hydra:subject/property/object (note: property, not predicate)? Reusing rdf's properties keeps Hydra smaller but means that the "manages block" becomes an rdf:Statement, i.e., a triple (even though only one or two components of the triple will be there).</del>
# The term "manages block" is hardly descriptive. How should we call this thing (keep in mind that "manages" might be renamed)?


== Proposals ==

=== Alternatives for "collection" ===

* hasCollection (Hydra doesn't use the hasXY pattern till now)


=== Alternatives for "manages" ===

* collects
* collectionTemplate
* hasCollectionTemplate
* contains
* containsTemplate
* consistsOf
* provides
* lists
* organizes
* handles
* covers
* binding
* holds
* constraint
* memberConstraint
* memberTemplate
* relationshipTemplate

Some pro's and cons for these terms can be found on the mailing list: [http://lists.w3.org/Archives/Public/public-hydra/2014Jun/ (1)], [http://lists.w3.org/Archives/Public/public-hydra/2014Jun/0049.html (2)], [http://lists.w3.org/Archives/Public/public-hydra/2014Jun/0050.html (3)]

=== Names for the "manages block" ===

* TripleTemplate
* Relationship
* RelationshipTemplate