Collection Design

From Hydra Community Group

The discussions related to ISSUE-41 and ISSUE-42 led to several 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"
    }
  }
}

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

  1. 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?
  2. 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"?
  3. 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).
  4. 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: (1), (2), (3)

Names for the "manages block"

  • TripleTemplate
  • Relationship
  • RelationshipTemplate