Collections API Proposal Notes

There are two "types", collections and resources. They differ only in that resources specify a list of file URIs keyed by type and collections specify a list of members. I've tried to prune back on possibly redundant properties and unpack some of the nested properties. For example, instead of labeling a collection "static", we can assign it a version number that should change if the collection changes. Some collections are "intrinsically" ordered, i.e. they have a natural order (Aeneid 2 comes after Aen. 1 and is followed by Aen. 3). Those that are will have members with "previous" and "next" values. Note that natural order and sort order are two different things.

I've re-thought "capabilities" as functions the API implementation may or may not expose, such as sorting, searching, filtering. These would be URL parameters (?sort=dc:date, for example, where dc:date is a metadata property).

The notation below is JSON-ish. I'd expect to use JSON-LD, with things like dts:id declared in the context, and so represented as @id in the actual record. I can imagine a very minimal version where all you'd do is give the API a Git repo with texts in it.

top level collection (e.g. /collections/papyri.info/)

dts:id: <id>
rdfs:label: <string>
dts:version: (should change if collection is updated)
dts:members: [{dts:id, ...}, ...] (these are not guaranteed to be complete records—they may only contain ids)
dts:size: <integer> (number of items in collection)
dts:nextPage: "<integer>-<integer>" (if members are paged)
dts:metadata: {
  <other descriptive data, title, citation, etc.>
}
dts:capabilities: {
  dts:sortable: {<paramName>:[<dts:metadata/property label>, ...]}
  dts:searchable {<paramName>:[<dts:metadata/property label>, ...]}
}

sub-collection (e.g. /collections/papyri.info;bgu;1/)

(/collections/papyri.info;bgu;1 redirects to /collections/papyri.info;bgu/)

dts:id: <id>
rdfs:label: <string>
dts:version: (should change if collection is updated)
dts:parents: [{dts:id:<id>, ...}, ...]
dts:previous: {dts:id:<id>, ...} (this and next are "intrinsic" order, e.g. Aen. 1 -> Aen. 2, not sort order, and are optional)
dts:next: {dts:id:<id>, ...}dts:previous: <id> 
dts:members: [{dts:id, ...}, ...]
dts:size: <integer> (number of items in collection)
dts:nextPage: "21-40" (e.g.)
dts:metadata: {
  <other descriptive data, title, citation, etc.>
}

paging collections: (e.g. /collections/papyri.info;bgu;1/21-40)

Same as above, with the addition of:

dts:prevPage: "1-20"

first item, e.g. /collections/papyri.info:bgu;1/first

Returns the first member collection or resource in the identified collection

last item, e.g. /collections/papyri.info:bgu;1/last

Returns the last member collection or resource

resource (e.g. /collections/papyri.info;bgu;1;2/)

dts:id: <id>
rdfs:label: <string>
dts:version: (should change if item is updated)
dts:parents: [{dts:id:<id>, ...}, ...]
dts:previous: {dts:id:<id>, ...}
dts:next: {dts:id:<id>, ...}
dts:metadata:
  rdfs:label
  [other descriptive data, title, citation, etc.]
dts:formats: {
  <type>: <uri>, ...
}