Proposed extension: Describing how collections are ordered

[tpluscode]

I propose to pick up where HydraCG/Specifications#172 left off and make an auxiliary vocabulary for describing collection, which goes beyond Hydra Core

[tpluscode]

cc @pietercolpaert

[pietercolpaert]

Hi @tpluscode,

In the meantime I created the TREE specification which is an extension of Hydra’s Collection design to create search-tree-like hypermedia structures. A 1-dimensional pagination can also be seen as a very simple search tree, and thus the TREE specification also supports describing ordering in Hydra collection. It does not describe the ordering of the members in the page itself, it only qualifies a hydra:next link into a tree:Relation object that explains what the next link precisely means, which could be that all members may have a dcterms:created that’s later in time.

Links:

• The specification: https://w3id.org/tree/specification
• The website of TREE: https://tree.linkeddatafragments.org/
• The Github repo: https://github.com/treecg
• Compatibility description with Hydra: https://treecg.github.io/specification/#hydra

[pietercolpaert]

And needless to say: I’m open to discuss how TREE can become an official Hydra extension!

[alien-mcl]

Please, keep in mind that extensions should not create alternative reality compared to what's doable with raw hydra vocab. Whenever possible, hydra constructs should be provided and then an extension can be applied. I envision clients falling back to raw hydra descriptions in case the client does not understand an extension.

[tpluscode]

What do you call an "alternate reality"? The whole point of extensions is to provide information which is otherwise not possible with Core (and when we intend to keep it that way).

In the example of ordered collections, there could be multiple ways, so there could be multiple extensions varying in expressivity. What if a client does not understand a given description? Worst case they will display collection members in random order as they come from a parser 🤷‍♂️

[alien-mcl]

Just please bare in mind that when hydra says it is a collection of users, don't make the extension say its a collection of cars. Extension should well, give an extended description of the collection. Providing sort order falls into this scheme.

The sentence beyond hydra just sounded side by side to hydra to me. If it is not the case - there won't be an issue

[tpluscode]

Just please bare in mind that when hydra says it is a collection of users, don't make the extension say its a collection of cars.

Please be serious 🤣

Where Hydra Core is not enough the extension would go "beyond" and add the additional details

[alien-mcl]

It's just a matter of experience - I know you're keen to make shortcuts sometimes ;)

[pietercolpaert]

Please, keep in mind that extensions should not create alternative reality compared to what's doable with raw hydra vocab. Whenever possible, hydra constructs should be provided and then an extension can be applied. I envision clients falling back to raw hydra descriptions in case the client does not understand an extension.

In the TREE spec, this is exactly what we tried to do with this chapter on Hydra compatibility: https://treecg.github.io/specification/#hydra - Happy to hear your thoughts!

[tpluscode]

You would know best how to approach TREE from the other end. The least we could build is again a "best practices" document showing how to use TREE to augment Hydra APIs.

[pietercolpaert]

I’m thinking about 2 parts:

1. Qualifying a hydra:next link

Instead of just saying next, we will make this link an entity in itself describing a Relation to another node

I have two examples currently in the repo based on a hydra:Collection

• https://github.com/TREEcg/specification/blob/master/examples/geospatially-ordered-public-transport/first.ttl
• https://github.com/TREEcg/specification/blob/master/examples/paged-collection-with-order/first.ttl

2. Extending hydra search forms indicating how the collection is searched through

Using a property path to indicate what the search form property is querying exactly

https://github.com/TREEcg/specification/blob/master/examples/timeseries/airQualityObservations.ttl#L81

[tpluscode]

For (2), would you consider SHACL Paths?

[pietercolpaert]

Yup: https://treecg.github.io/specification/#traversing

[alien-mcl]

I'm not sure I understand correctly - both of the examples @pietercolpaert are not providing any page relations in terms of hydra. Indeed there is some order description using tree, but hydra powered client would only discover that there is a collection with some members.

[pietercolpaert]

There is an equivalence:

<view1> hydra:next <next> .

Is equivalent to:

<view1> tree:relation <rel1> .
<rel1> a tree:Relation ;
           tree:node <next> .

So, you can also add hydra:next if you also want hydra-core agents to follow the next page without having to understand the “qualified” relation that then would be ignored.

A TREE client MUST be able to interpret a hydra:next though and handle it in the same way as the example above.

[alien-mcl]

This is what I meant - an extension should add features unavailable in pure Hydra, but server should provide all available details in pure hydra and optionally via the extension. It would be undesirable to have details provided via an extension but without hydra equivalent constructs when available.

[pietercolpaert]

@alien-mcl Fully agreed! I propose always adding the hydra-core properties in this repo as well, when you want to use TREE as a Hydra extension. However, I also see TREE as an extension on top of for instance activity streams 2.0, Linked Data Platform and Triple Pattern Fragments (ok, this one also uses hydra). So I will not include the Hydra-core fallbacks in the TREE specification in each example though.

[alien-mcl]

OK, my first thoughts were TREE is more rooted in hydra, but the only trace of it within the spec is IriTemplate used for tree:search. Having that in mind I'd go with separate extension that would introduce desired interoperability between hydra and TREE the same way as @tpluscode goes with SHACL.

[pietercolpaert]

Ok, I can certainly live with that. In TREE there is a compatibility section already on Hydra: https://treecg.github.io/specification/#hydra

[tpluscode]

@pietercolpaert finally looking again at a scenario where I want the information about collection order and I think that TREE solves a slightly different problem and another problem that is not really in need of addressing. Please, bare with me.

The latter is regarding tree:path used in an IRI Template mapping. It's not really about sorting but I'm curious why you need a second property. I typically just rely on hydra:property and that is exactly the property used to search the collection. It is also slightly irrelevant to the client in a pure REST API scenario but maybe I'm missing something

[tpluscode]

Now, regarding actually informing the client about collection sort, I have some thoughts.

First of all, this is not necessary limited to partial collections. Ie, the hydra:member property is itself not an RDF List, thus also non-paged collection will benefit from an order annotation, allowing clients to sort the members

Second, related to the last part of above statement, my goal from the beginning was only to inform the client how to sort. the members of a collection (or page) in memory. Nothing less nothing more. Annotating the next/previous relation is slightly weird because it will inherently keep the same order.

Indicating order of a paged collection

Here's a concrete and complete example of what I have in mind: a paged collection of people sorted by

1. birth date in descending order
2. birth location name
3. last name

In SPARQL this would be

SELECT ?res {
  ?res foaf:birthday ?bd .
  ?res ex:birthPlace/rdfs:label ?loc .
  ?res foaf:givenName ?gn .
}
ORDER BY desc(?bd) ?loc ?gn

The client need the exact same information to perform an equivalent sort operation on hydra:members of a partial collection view. I like the idea of attaching this information to the view itself. Thus, we'd have something like

</people>
  hydra:member ... ;
  hydra:view </people?page=10> .

</people?page=10>
  a hydra:PartialCollectionView ;
  hex:orderedBy (
    [ hex:descending foaf:birthday ]
    ( ex:birthPlace rdfs:label )
    foaf:givenName
  ) .

1. hex:orderedBy is a list just as ORDER BY clause is ordered
2. Its list members are SHACL Paths or blank node with hex:descending property
3. There must be exactly on value of hex:descending, a valid SHACL Path itself

Indicating order of a non-paged collation

A collection without pages would not typically have hydra:view, I think. However, the server. might still want to communicate how to sort the collection members. I think we have two options.

My preference could be to require a view to have the model most similar to a paged collection. This is nice, because potentially multiple views could be offered with different possible ways to order that collection.

</people> 
  hydra:member [], [], [] ;
  hydra:view </people#byLastName> .

</people#orderedByLastName>
  a hex:OrderedCollectionView ;
  rdfs:label "Ordered by last name" ;
  hex:orderedBy ( foaf:lastName ) ;
] .

</people#orderedByBirthPlace>
  a hex:OrderedCollectionView ;
  rdfs:label "Ordered by place of birth" ;
  hex:orderedBy ( ( ex:birthPlace rdfs:label ) ) ;
.

At this point I'm not even considering using hex:orderedBy with the collection resource itself :)

[tpluscode]

Final thought, we could consider always using hex:OrderedView also alongside hydra:PartialCollectionView. In such case offering multiple does not make sense since a client would not want to order partial results in a different way than ordered by the server. However, it would provide a unified way for accessing that information